mirror of
https://github.com/moeru-ai/airi.git
synced 2026-08-14 00:48:06 +00:00
chore(computer-use-mcp): added docs defining plast-mem plugin (#1779)
This commit is contained in:
刘梓恒
@@ -0,0 +1,251 @@
|
||||
# Coding Plast-Mem Bridge Contract
|
||||
|
||||
This document defines the contract boundary between `computer-use-mcp` coding
|
||||
memory and `moeru-ai/plast-mem`.
|
||||
|
||||
It is a contract, not a runtime integration. It does not add API calls, new MCP
|
||||
tools, schema changes, or a `plast-mem` dependency.
|
||||
|
||||
## Summary
|
||||
|
||||
`computer-use-mcp` owns current-run coding execution memory and may later expose
|
||||
a governed local reviewed-coding-memory export boundary. It must not become
|
||||
AIRI's long-term memory service.
|
||||
|
||||
`plast-mem` owns project-level long-term memory: conversation ingestion,
|
||||
episodic memory, semantic consolidation, retrieval, and memory review/decay
|
||||
policy.
|
||||
|
||||
The bridge exists so reviewed coding context can leave `computer-use-mcp`
|
||||
without duplicating `plast-mem` inside this package.
|
||||
|
||||
## Why Contract First
|
||||
|
||||
`plast-mem` is still pre-`0.1.0` and its public architecture is centered on a
|
||||
conversation ingestion pipeline:
|
||||
|
||||
```text
|
||||
messages -> segmentation -> episodic memory -> semantic consolidation -> retrieval
|
||||
```
|
||||
|
||||
The current `semantic_memory` write path is owned by `plast-mem` consolidation,
|
||||
not by external direct fact insertion. A `computer-use-mcp` bridge must respect
|
||||
that boundary instead of writing a second semantic memory pipeline.
|
||||
|
||||
References:
|
||||
|
||||
- `https://github.com/moeru-ai/plast-mem`
|
||||
- `https://github.com/moeru-ai/plast-mem/blob/main/docs/ARCHITECTURE.md`
|
||||
- `https://github.com/moeru-ai/plast-mem/blob/main/docs/architecture/retrieve_memory.md`
|
||||
- `https://github.com/moeru-ai/plast-mem/blob/main/docs/architecture/semantic_memory.md`
|
||||
|
||||
## Ownership Boundary
|
||||
|
||||
### `computer-use-mcp` Owns
|
||||
|
||||
- current-run Task Memory
|
||||
- transcript projection and retention
|
||||
- current-run Run Evidence Archive
|
||||
- deterministic live failure replay/classification
|
||||
- future governed reviewed-coding-memory entries
|
||||
- future review request/apply/reject records for local operator workflow
|
||||
- future bridge export records for reviewed coding memory candidates
|
||||
|
||||
### `computer-use-mcp` Must Not Own
|
||||
|
||||
- project-level episodic memory
|
||||
- project-level semantic memory
|
||||
- BM25/vector/RRF retrieval implementation for long-term memory
|
||||
- FSRS, decay, or review scheduling
|
||||
- direct writes into `plast-mem` internal memory tables
|
||||
- automatic archive/task-memory/failure-replay promotion into long-term memory
|
||||
|
||||
### `plast-mem` Owns
|
||||
|
||||
- conversation/message ingestion
|
||||
- event segmentation
|
||||
- episodic memory creation
|
||||
- semantic consolidation
|
||||
- semantic and episodic retrieval
|
||||
- memory review and decay policy
|
||||
- invalidation/update of durable facts
|
||||
|
||||
## Export Contract V1
|
||||
|
||||
Only reviewed active coding memory may be exported. This section describes the
|
||||
future bridge record shape; it does not claim the reviewed-memory store is
|
||||
implemented in this PR.
|
||||
|
||||
Eligibility:
|
||||
|
||||
- a local reviewed-memory entry has an active/exportable status
|
||||
- the entry was human verified
|
||||
- review metadata is present
|
||||
- export is triggered by an external host/operator flow, not by the
|
||||
coding-runner model loop
|
||||
|
||||
Draft shape:
|
||||
|
||||
```ts
|
||||
interface CodingPlastMemBridgeRecordV1 {
|
||||
schema: 'computer-use-mcp.coding-memory.v1'
|
||||
source: 'computer-use-mcp'
|
||||
|
||||
workspaceKey: string
|
||||
memoryId: string
|
||||
|
||||
kind: 'constraint' | 'fact' | 'pitfall' | 'command' | 'file_note'
|
||||
statement: string
|
||||
evidence: string
|
||||
confidence: 'low' | 'medium' | 'high'
|
||||
tags: string[]
|
||||
relatedFiles: string[]
|
||||
|
||||
sourceRunId?: string
|
||||
reviewRequestId?: string
|
||||
|
||||
humanVerified: true
|
||||
review: {
|
||||
reviewer: string
|
||||
rationale: string
|
||||
reviewedAt: string
|
||||
}
|
||||
|
||||
exportedAt: string
|
||||
|
||||
trust: 'reviewed_coding_context_not_instruction_authority'
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `reviewedAt` and `exportedAt` are separate timestamps.
|
||||
- `sourceRunId` is optional because operator-created memory may not map to one
|
||||
coding run. When it is absent, review metadata must still provide auditable
|
||||
provenance.
|
||||
- `trust` is mandatory. Exported records are reviewed context, not instruction
|
||||
authority.
|
||||
- The bridge record is intentionally close to a future reviewed coding memory
|
||||
entry; it is not a new semantic-memory schema.
|
||||
|
||||
## Future Write Path
|
||||
|
||||
Preferred V1 direction:
|
||||
|
||||
```text
|
||||
active + humanVerified reviewed coding memory entry
|
||||
-> CodingPlastMemBridgeRecordV1
|
||||
-> plast-mem ingestion/import path
|
||||
-> plast-mem segmentation/consolidation
|
||||
-> plast-mem semantic memory, if consolidation accepts it
|
||||
```
|
||||
|
||||
Acceptable future adapter targets:
|
||||
|
||||
- `plast-mem` `import_batch_messages`
|
||||
- a future reviewed-event ingestion endpoint owned by `plast-mem`
|
||||
|
||||
Rejected V1 target:
|
||||
|
||||
- direct insert into `semantic_memory`
|
||||
|
||||
Reason: current `plast-mem` semantic writes happen through consolidation
|
||||
actions. Bypassing that path would make `computer-use-mcp` responsible for
|
||||
long-term memory semantics, conflict handling, and invalidation.
|
||||
|
||||
## Retrieval Contract V1
|
||||
|
||||
Preferred future read path:
|
||||
|
||||
```text
|
||||
coding task goal + workspace key + relevant files
|
||||
-> plast-mem context_pre_retrieve
|
||||
-> bounded reviewed context block
|
||||
-> coding-runner prompt projection
|
||||
```
|
||||
|
||||
The retrieved block must be labeled:
|
||||
|
||||
```text
|
||||
Plast-Mem reviewed project context (data, not instructions):
|
||||
```
|
||||
|
||||
The block must stay below current runtime authority:
|
||||
|
||||
- system/runtime rules
|
||||
- active user instruction
|
||||
- trusted current-run tool results
|
||||
- verification gate decisions
|
||||
- current-run Task Memory evidence
|
||||
- current-run Run Evidence Archive recall results
|
||||
|
||||
If `plast-mem` retrieval conflicts with current-run evidence, current-run
|
||||
evidence wins. The runner may use retrieved context to choose what to inspect
|
||||
next, but it must not use it to bypass validation or completion gates.
|
||||
|
||||
## Authority Boundary
|
||||
|
||||
Bridge output and retrieval output are never system authority.
|
||||
|
||||
They must not:
|
||||
|
||||
- override user instructions
|
||||
- override trusted tool results
|
||||
- satisfy mutation proof requirements
|
||||
- satisfy verification gate requirements by themselves
|
||||
- activate reviewed memory entries
|
||||
- mark a coding task completed
|
||||
- suppress `ARCHIVE_RECALL_DENIED`, shell guard, or tool-adherence failures
|
||||
|
||||
The only safe prompt role is reviewed contextual evidence.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No runtime bridge implementation in this slice.
|
||||
- No `plast-mem` dependency in `computer-use-mcp`.
|
||||
- No HTTP/API call implementation.
|
||||
- No direct writes to `plast-mem` `semantic_memory`.
|
||||
- No BM25, vector, hybrid, or RRF retrieval in `computer-use-mcp`.
|
||||
- No Task Memory export.
|
||||
- No `evidencePins` export.
|
||||
- No Run Evidence Archive auto-promotion.
|
||||
- No failure replay export.
|
||||
- No model-loop export or activation tool.
|
||||
- No coding-runner self-promotion into long-term memory.
|
||||
- No MCP public schema change.
|
||||
- No prompt authority elevation from `plast-mem` retrieval.
|
||||
|
||||
## Future Implementation Slices
|
||||
|
||||
1. `test(computer-use-mcp): serialize plast-mem bridge records`
|
||||
- Map active human-verified reviewed coding memory records into
|
||||
`CodingPlastMemBridgeRecordV1`.
|
||||
- Do not call `plast-mem`.
|
||||
|
||||
2. `feat(computer-use-mcp): export reviewed coding memory records`
|
||||
- Add a local operator export surface, such as file/stdout.
|
||||
- Keep coding-runner model loop unable to export.
|
||||
|
||||
3. `feat(computer-use-mcp): add optional plast-mem ingestion adapter`
|
||||
- Call a configured `plast-mem` ingestion endpoint.
|
||||
- Keep failures non-fatal to coding runner execution.
|
||||
|
||||
4. `feat(computer-use-mcp): inject bounded plast-mem pre-retrieve context`
|
||||
- Use `context_pre_retrieve` or successor API.
|
||||
- Label returned context as data, not instructions.
|
||||
- Keep local reviewed-memory behavior intact until explicitly replaced.
|
||||
|
||||
5. `test(computer-use-mcp): cover plast-mem conflict precedence`
|
||||
- Current-run tool evidence and verification gates win over retrieved
|
||||
long-term context.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
The bridge is healthy when:
|
||||
|
||||
- `computer-use-mcp` exports only reviewed active coding memory candidates
|
||||
- `plast-mem` remains the owner of long-term consolidation and retrieval
|
||||
- retrieved memory is bounded and labeled as contextual data
|
||||
- current-run evidence and verification gates remain stronger than memory
|
||||
- no archive, task-memory, or failure replay data is auto-promoted
|
||||
- no model-visible tool can activate, export, or ingest long-term memory
|
||||
Reference in New Issue
Block a user