Memory: Persisting Context Across Sessions
Memory is just recalled context — so every memory anti-pattern is a context anti-pattern. Typing enables decay, the doc-vs-memory boundary is durable-shared vs fast-private, repo-as-memory is the cheap floor you outgrow. An openly unsolved design space.
On this page
The previous two chapters managed context within a session. This one persists it across sessions. It is the most openly unsolved topic in the book — the practices here are current best-practice scaffolding around a contested design space, not settled science, and the chapter says so plainly.
Memory is just recalled context
The unifying lens makes this chapter cohere with the two before it. A recalled memory enters the window as more text — the store is read back in. So a stale or wrong memory is a context-quality failure, and over-recall is a context-length failure. As one practitioner puts it, “incorrect memories are worse than no memories. Bad facts, once stored, pollute every future decision.” [Practitioner] Why your AI agent doesn't actually remember anything · Ed Huang (2026)T3-practitioner original
Typing enables decay
Should memory have structure, or be one flat blob? The architecture proposals all add structure: MemGPT’s “virtual context management, a technique drawing inspiration from hierarchical memory systems in traditional operating systems”; MemGPT: Towards LLMs as Operating Systems · Packer et al. (2023)T3-practitioner original Generative Agents’ memory stream the agent will “synthesize… into higher-level reflections, and retrieve… dynamically to plan behavior”; Generative Agents: Interactive Simulacra of Human Behavior · Park et al. (2023)T3-practitioner original and LangMem’s explicit episodic/semantic/procedural split, where the semantic type “stores key facts (and their relationships)… that ground an agent.” [Practitioner] LangMem SDK for agent long-term memory · The LangChain Team (2025)T2-release-notes original
The doc-vs-memory boundary
Given a fact, which medium does it belong in — a committed doc or ephemeral memory? The official docs draw the line on two axes: a committed doc is “instructions you write” [Official] How Claude remembers your project · AnthropicT1-official original and is “shared with your team through version control,” whereas auto-memory is “notes Claude writes itself” and is “machine-local… not shared across machines.” How Claude remembers your project · AnthropicT1-official original The API layer mirrors it as a read_only store “for reference material… the agent does not need to modify.” Using agent memory · AnthropicT1-official original
Repo-as-memory: the cheap floor
The filesystem is a real memory store — “the file system not just as storage, but as structured, externalized memory,” [Practitioner] Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original unbounded and persistent, so after a context reset the agent “reads its own notes and continues” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original long tasks. But it is the floor, not the ceiling: it has no decay, no typing, no retrieval ranking; files “get unmanageable >5MB,” AI Agent Memory Management: When Markdown Files Are All You Need? · Yaohua Chen (ImagineX) (2025)T3-practitioner original and a flat scratchpad is “scoped to a single thread” while a real store “persists across threads and can be recalled at any time.” Long-term memory · LangChainT2-release-notes original
The landscape, and the safe bet
The proposals this chapter draws on optimize for different things — which is why “openly unsolved” is a starting point, not a verdict.
Patterns
Type your memory. Sketch: split memory by kind (episodic/semantic/procedural) or tier it. When to use: anything beyond a scratchpad. LangMem SDK for agent long-term memory · The LangChain Team (2025)T2-release-notes original Mechanics: store facts apart from experiences apart from rules; address each distinctly. Remember: typing is the precondition for selective decay and correction.
Decay / invalidate. Sketch: give stored facts a validity path. When to use: any long-lived memory. Mechanics: invalidate on contradiction; prefer “no memory” over a confidently-wrong one. Why your AI agent doesn't actually remember anything · Ed Huang (2026)T3-practitioner original Remember: a stale fact is recalled with full confidence — pollution is worse than absence.
Choose the medium. Sketch: durable-shared → doc; fast-private → memory. When to use: every fact you persist. How Claude remembers your project · AnthropicT1-official original Mechanics: identity/constitution/standards → committed doc; session-accreted preferences → auto-memory. My .md files vs Claude's memory tool: a practitioner comparison · Andreas Belitz (2026)T3-practitioner original Remember: commit the durable + reviewable; leave the disposable to memory.
Repo-as-memory floor. Sketch: start with the filesystem; outgrow it on signal. When to use: cross-session state, day one. Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original Mechanics: a notes/progress file first; promote to a structured store when you need typing, decay, or ranking. Long-term memory · LangChainT2-release-notes original Remember: the floor has no decay/typing/ranking — and bloats past a few MB.
Quick reference
- Memory = recalled context — every memory anti-pattern is a context anti-pattern.
- Typing enables decay — you can’t invalidate what you can’t address.
- Decay/pollution: a stale fact is “confidently wrong”; incorrect memory is worse than none.
- Doc-vs-memory boundary: durable-shared-reviewable (doc) vs. fast-private-decaying (memory).
- Repo-as-memory: cheap floor; outgrow it for typing/decay/ranking; bloats past a few MB.
- Openly unsolved — scaffolding, not settled science; recheck.
Practice
Exercise solutions
Identity-defining (e.g., “this is a Rust workspace; all crates target stable”) → committed doc; it rarely changes, should be shared/reviewable, and belongs where the team sees it. Session preference (e.g., “explain changes before applying this session”) → auto-memory; private, fast, disposable. Will-go-stale (e.g., “the user is on team X”) → if kept at all, it needs an invalidation path — typed so it can be located and overwritten when the world changes; otherwise it becomes the confidently-wrong recall the chapter warns about. The split is the doc-vs-memory boundary plus the typing-enables-decay rule applied per fact.
Two failures: (1) no typing/decay (M1/M2) — the preference was stored as a flat note with no validity path, so it could not be located and invalidated when it changed; it became “confidently wrong.” (2) wrong medium / no review (M3) — a consequential, drift-prone fact lived in private auto-memory rather than a reviewable committed doc where staleness would be visible. Fix: type the memory so the specific fact is addressable and can be invalidated on contradiction; and move durable, consequential facts to the committed doc (reviewable), leaving only fast, disposable preferences to auto-memory. The throughline: the stale note is a context-quality failure (memory = recalled context), so the remedy is structural — typing, decay, and the medium boundary — not “remember harder.”