Contract
- Input: a session that needs state to survive a boundary (compaction, reset, handoff, model change).
- Output: a
MemoryState reporting what was recorded, recalled, promoted, or reconciled.
- Scope: memory holds the thread and durable facts. Specs, tickets, PR bodies, and review plans are artifacts, not memory; memory references them.
- Rule: every memory entry carries a provenance line (source session, date, artifact reference). An entry without provenance is deleted, not kept.
The two memory files
- NOW.md - the working thread: current task, decisions in flight, open questions, next step. Short by construction; it is re-entered every session and must fit in a few hundred tokens.
- MEMORY.md - durable facts: user preferences, repo invariants, recurring pitfalls, tool facts that are not in CONTEXT.md. Append-only with provenance; reconciled when stale.
Procedure
- Record. Before a compaction, reset, or handoff, write the working thread to NOW.md and promote anything durable to MEMORY.md or to an artifact.
- Recall. At session start, read NOW.md and MEMORY.md into the context pack (see
context-pack) with their provenance lines.
- Reconcile. When a fact changes, update the entry and its provenance; never leave contradictory entries. Mark stale entries and remove them at the next reconciliation.
- Promote. When a memory entry becomes a decision, promote it to an ADR (see
docs-adrs) and replace the memory entry with a reference.
Provenance
| Question |
Answer |
| What is the source of truth? |
The session thread, CONTEXT.md, ADRs, and the current task artifacts |
| What is in scope? |
Record, recall, reconcile, and promote memory entries with provenance |
| What is explicitly out of scope? |
Specs, tickets, and PR bodies: artifacts, referenced from memory, never copied |
| Who or what consumes this artifact afterward? |
The next session via context-pack, context-compaction, or handoff |
| What evidence proves it is done? |
MemoryState with recorded, recalled, promoted, and stale entries |
| What risk remains? |
Stale entries reconciled late, or repo vocabulary duplicated from CONTEXT.md |
Artifact
MemoryState with status, nowEntries, memoryEntries, promotedToArtifact, staleEntries, nextConsumer, and riskRemaining.
Reference
- The canonical prompt for this skill is versioned at
.agents/skills/prompts/agent-memory/v1.md (prompt version 1.0).
- Governing skills: see the dependencies in the frontmatter for the skills this one composes with.
Every execution is traced via record-execution.mjs. The trace includes traceId, spanId, model tier, duration, tool calls, and quality score.
Rationale
Compaction and resets destroy working state unless something outside the window holds it. External memory (NOW.md for the thread, MEMORY.md for durable facts) is what lets context compress while knowledge survives across sessions, models, and handoffs.
Completion
- NOW.md reflects the exact working thread; nothing in flight is memory-only.
- MEMORY.md entries are durable, provenance-carrying, and non-contradictory.
- Decisions live in ADRs; memory holds references, not copies.
- No approval is required for memory writes: NOW.md and MEMORY.md are repo-local Markdown files, reversible via git.
Failure modes
- Memory as a dumping ground: if an entry does not survive compaction usefully, it is not memory.
- Duplicating CONTEXT.md: repo-local vocabulary belongs in CONTEXT.md; memory holds session-spanning facts only.
- Unbounded growth: reconcile MEMORY.md on every recall; cap NOW.md at a few hundred tokens.
@include .agents/skills/platform/contract-base.xml
1---2name: "agent-memory"3category: "foundation"4maturity: "experimental"5version: "1"6description: "Maintain external agent memory: structured notes persisted outside the context window (NOW.md for the working thread, MEMORY.md for durable facts) so context can compact or reset while knowledge survives across sessions."7license: "MIT"8capabilities:9 - maintain a MEMORY.md of durable, cross-session facts10 - decide what belongs in memory versus in an artifact11 - recall memory into a fresh context pack with provenance12 - trace agent memory decisions across inputs, constraints, and failure paths13 - validate foundation outcomes with evidence, assumptions, and explicit next steps14inputs:15 - a session that needs state to survive compaction, reset, or handoff16 - the repository's CONTEXT.md and ADRs (the repo-local vocabulary)17 - the current task and its artifacts18outputs:19 - type: object20 name: MemoryState21 properties:22 status: { type: string, enum: [recorded, recalled, reconciled] }23 nowEntries: { type: "array", items: { type: "string" } }24 memoryEntries: { type: "array", items: { type: "string" } }25 promotedToArtifact: { type: "array", items: { type: "string" } }26 staleEntries: { type: "array", items: { type: "string" } }27 nextConsumer: { type: "string" }28 riskRemaining: { type: "string" }29 required: [status, nextConsumer]30sideEffects:31 - write-files32dependencies:33 - context-pack34 - context-compaction35 - handoff36 - docs-knowledge-base37stopCondition: "Memory files are current, stale entries are reconciled, and every durable fact has a provenance line."38risk: "low"39trustTier: "2"40maxIterations: "5"41promptVersion: "1.0"42artifactType: "memory-state"43modelTier: "fast"44evaluators: ["behavioral", "regression"]45fixturesPath: .agents/skills/platform/fixtures/behavioral/agent-memory.json46diataxis: "how-to"47tags: ["memory", "context-engineering", "continuity"]48compatibility: []49approvalRequired: "false"50approvalFor: []51metadata:52 source: https://skillmd.com/skills/quantumquirkxyz/agent-memory53---5455## Contract5657- Input: a session that needs state to survive a boundary (compaction, reset, handoff, model change).58- Output: a `MemoryState` reporting what was recorded, recalled, promoted, or reconciled.59- Scope: memory holds the thread and durable facts. Specs, tickets, PR bodies, and review plans are artifacts, not memory; memory references them.60- Rule: every memory entry carries a provenance line (source session, date, artifact reference). An entry without provenance is deleted, not kept.6162## The two memory files6364- **NOW.md** - the working thread: current task, decisions in flight, open questions, next step. Short by construction; it is re-entered every session and must fit in a few hundred tokens.65- **MEMORY.md** - durable facts: user preferences, repo invariants, recurring pitfalls, tool facts that are not in CONTEXT.md. Append-only with provenance; reconciled when stale.6667## Procedure68691. **Record.** Before a compaction, reset, or handoff, write the working thread to NOW.md and promote anything durable to MEMORY.md or to an artifact.702. **Recall.** At session start, read NOW.md and MEMORY.md into the context pack (see `context-pack`) with their provenance lines.713. **Reconcile.** When a fact changes, update the entry and its provenance; never leave contradictory entries. Mark stale entries and remove them at the next reconciliation.724. **Promote.** When a memory entry becomes a decision, promote it to an ADR (see `docs-adrs`) and replace the memory entry with a reference.7374## Provenance7576| Question | Answer |77|---|---|78| What is the source of truth? | The session thread, CONTEXT.md, ADRs, and the current task artifacts |79| What is in scope? | Record, recall, reconcile, and promote memory entries with provenance |80| What is explicitly out of scope? | Specs, tickets, and PR bodies: artifacts, referenced from memory, never copied |81| Who or what consumes this artifact afterward? | The next session via `context-pack`, `context-compaction`, or `handoff` |82| What evidence proves it is done? | MemoryState with recorded, recalled, promoted, and stale entries |83| What risk remains? | Stale entries reconciled late, or repo vocabulary duplicated from CONTEXT.md |8485## Artifact8687`MemoryState` with `status`, `nowEntries`, `memoryEntries`, `promotedToArtifact`, `staleEntries`, `nextConsumer`, and `riskRemaining`.8889## Reference9091- The canonical prompt for this skill is versioned at `.agents/skills/prompts/agent-memory/v1.md` (prompt version 1.0).92- Governing skills: see the dependencies in the frontmatter for the skills this one composes with.9394Every execution is traced via `record-execution.mjs`. The trace includes traceId, spanId, model tier, duration, tool calls, and quality score.9596## Rationale9798Compaction and resets destroy working state unless something outside the window holds it. External memory (NOW.md for the thread, MEMORY.md for durable facts) is what lets context compress while knowledge survives across sessions, models, and handoffs.99100## Completion101102- NOW.md reflects the exact working thread; nothing in flight is memory-only.103- MEMORY.md entries are durable, provenance-carrying, and non-contradictory.104- Decisions live in ADRs; memory holds references, not copies.105- No approval is required for memory writes: NOW.md and MEMORY.md are repo-local Markdown files, reversible via git.106107## Failure modes108109- Memory as a dumping ground: if an entry does not survive compaction usefully, it is not memory.110- Duplicating CONTEXT.md: repo-local vocabulary belongs in CONTEXT.md; memory holds session-spanning facts only.111- Unbounded growth: reconcile MEMORY.md on every recall; cap NOW.md at a few hundred tokens.112113---114@include .agents/skills/platform/contract-base.xml