/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. Trigger on "agent forgets everything between sessions", "agent keeps retrying the same failed approach". Do not use for trimming the current context window — see the context-engineering skill; for human-written project instructions, see the agent-instructions skill.
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.