agent-shared-memory git:20260831.ca20117A

Immutable. This exact content never changes and is served at /api/v1/blob/013f73cc11950b0e.

---
name: agent-shared-memory
description: Use when a user asks to inspect coordination memory, propose a durable decision or resolution, review pending memory proposals, or apply an explicitly approved proposal as a new append-only event.
---

# 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.

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.