agent-shared-memory

Coordinate durable facts without letting an agent silently rewrite project memory. Read the event schema in references/coordmemoryschema.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:

{ "schemaversion": 1, "proposalid": "<uuid>", "sourcetask": "<task id>", "action": { "operation": "add | supersede | archive | delete", "targetref": null, "summary": "<compact proposed event>", "evidencerefs": ["<stable ref>"] }, "state": "proposed", "createdat": "<ISO 8601>", "decision": null }

Supersede, archive, and delete require a specific action.targetref. A proposal with no action.evidencerefs 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.affectedactionhash. 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.

Application appends one immutable event to .coord/memory.yml. It does not edit the target event:

It never edits an existing event; a resolution, correction, or supersession is a new append-only event.

• Superseding a decision appends a new decision event with supersedes.
• Resolving a question appends a resolution event with resolves.
• Archiving or deleting appends a lifecycle event referencing target_ref.
• Canonical removal, compaction, or physical deletion requires a separate

repository-specific retention decision.

Coordination scope

Use this memory for agent coordination decisions, questions, artifact pointers, and execution outcomes. Research truth belongs in research evidence stores; paper claims belong in the paper's claim/evidence contract.

Artifact policy

.coord/ is scratch and gitignored by default. Do not commit every proposal or agent boundary. Promote only an explicitly selected checkpoint snapshot, shipping artifact, or acceptance record into a repository-owned evidence path.

Output

Always report:

• mode: read, propose, decide, or apply
• proposal/event id
• state
• evidence refs
• whether canonical memory changed
• human decision still required

Never report an unapproved proposal as a canonical decision.