agent-memory

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