/agent-memory

name: agent-memory
description: Use when an agent needs state that survives a session or a context compaction. Covers what to persist, file-based memory, structuring notes for retrieval, and preventing memory from becoming stale.
metadata:
  category: agent-tooling
  version: 1.0.0
  tags: [memory, persistence, state, context, notes]

Agent Memory

Purpose

Give an agent state that outlives its context window. Anything the agent must not forget belongs in a file it can re-read — not in a conversation history that will be compacted away.

When to Use

• A task that spans more turns than the context window holds.
• Work that continues across sessions.
• An agent that repeatedly rediscovers the same fact or repeats the same failed approach.
• Accumulating knowledge about a codebase or a domain over time.

Capabilities

• Deciding what deserves persistence.
• File-based memory the agent reads and writes.
• Structuring notes for retrieval rather than for narrative.
• Staleness detection and pruning.

Inputs

• The task and its expected duration.
• What has been learned that would be expensive to rediscover.
• What has been tried and failed.

Outputs

• A memory file that survives compaction and session end.
• Notes structured so that the relevant part is findable.
• A pruning discipline so the memory does not become a stale swamp.

Workflow

1. **Write down what would be expensive to rediscover** — File locations, API shapes, the reason an approach was abandoned, a constraint the user stated once. Not the narrative of how you got there. 2. **Write it as facts, not as a story** — "The auth middleware is in `src/mw/auth.ts` and it does not run on `/health`." Not "I looked for the auth middleware and eventually found it." 3. **Record failures explicitly** — "Tried X. It does not work because Y." This is the highest-value memory content, because without it the agent will try X again. 4. **Re-read at the start of each session** — Memory that is not read is not memory. 5. **Prune what is stale** — A note that was true three refactors ago is now a trap. Date the entries and check them. 6. **Keep it small** — This file is loaded every session. It competes with the actual work for context.

Best Practices

• The most valuable memory is a record of what failed and why. Without it, an agent will confidently repeat a failed approach in a new session.
• Structure the file so the agent can find the relevant section without reading all of it. Headings, not prose.
• Do not persist the conversation. Persist the conclusions.
• A memory file that grows monotonically will eventually be mostly wrong. Pruning is part of the discipline, not an afterthought.
• Distinguish stable facts (architecture, conventions) from working state (what I am doing now). They have different lifetimes and belong in different sections or different files.
• Date the entries. A fact from six months ago about a fast-moving codebase is a hypothesis.

Examples

**A memory file structured for retrieval:**

# Working memory — orders service migration

_Last updated: 2026-06-14_

## Stable facts (verified, unlikely to change)
- Auth middleware: `src/middleware/auth.ts`. Runs on every route EXCEPT
  `/health` and `/metrics` (see the exclusion list at line 22).
- Money is `Money` (integer minor units) throughout. There is no float money
  anywhere and there must not be.
- The migration runner is `pnpm db:migrate`. It does NOT run automatically on
  deploy — this is deliberate; migrations are run manually before the deploy.

## Current task
Strangling `legacy/billing` into `src/features/billing`.
Done: invoice generation, proration.
Next: refunds.
Not started: dunning, tax.

## Tried and failed — do not repeat
- 2026-06-02: Tried to run the two billing paths in parallel and diff the
  outputs. Abandoned: the legacy path writes to the ledger as a side effect,
  so running both double-writes. Shadow mode requires a read-only ledger
  adapter, which does not exist yet.
- 2026-06-09: Tried extracting `PricingEngine` first. It depends on
  `LegacyCustomer`, which depends on half the legacy module. The dependency
  runs the wrong way; extract `Customer` first.

## Open questions for the user
- Should refunds issued before the migration remain visible in the new UI?
  (Asked 2026-06-11, not yet answered.)

The "tried and failed" section is what stops the next session from spending two hours rediscovering that shadow mode double-writes the ledger.

Notes

• Without a memory of failed approaches, an agent starting a fresh session will reason its way to the same plausible-but-wrong approach it already abandoned. This is the most common and most wasteful memory failure.
• Memory and context compaction serve the same goal from different directions: compaction summarizes what happened, memory records what was concluded. Both are needed.
• If a memory file exceeds a couple of hundred lines, it has stopped being memory and become a document. Prune it or split it.