agent-shared-memory

agent-shared-memory

Coordinate durable facts without letting an agent silently rewrite project memory. Read the event schema in references/coord_memory_schema.md before creating or applying a proposal.

Authority

Repository state, current evidence, and recorded human decisions outrank memory. Recall systems are optional caches.

All memory mutations start as proposals:

.coord/memory-proposals/<proposal-id>.json

Without an explicit human approve decision, do not add, supersede, archive, delete, overwrite, or compact canonical memory.

Modes

Read

Read canonical events and return:

• current decisions, following supersedes references
• unresolved questions
• relevant artifact/evidence pointers
• recent execution outcomes
• conflicts or stale claims

Do not load raw agent logs into the primary session. Follow their stable paths only when needed.

Propose

Create a proposal with:

{
  "schema_version": 1,
  "proposal_id": "<uuid>",
  "source_task": "<task id>",
  "action": {
    "operation": "add | supersede | archive | delete",
    "target_ref": null,
    "summary": "<compact proposed event>",
    "evidence_refs": ["<stable ref>"]
  },
  "state": "proposed",
  "created_at": "<ISO 8601>",
  "decision": null
}

Supersede, archive, and delete require a specific action.target_ref. A proposal with no action.evidence_refs remains pending and must not be applied. The action object is immutable. Its canonical JSON bytes, not the mutable proposal envelope, are the approval payload.

Decide

Only a human may approve, decline, or revise a proposal. Record:

• actor
• decision
• timestamp
• rationale
• affected proposal/action hash
• HMAC authorization from the trusted host

Decline and timeout remain non-success. A revise decision creates or updates a proposal; it is not approval.

Apply

Apply only a proposal whose recorded state is approved and whose immutable action bytes still match decision.affected_action_hash. Decision metadata and state are outside that hashed payload, so recording approval does not invalidate the approval hash. The decision uses the same hmac-sha256 authorization boundary as checkpoint human records. Do not expose the signing secret to a delegated executor.