Introduction
Every coding agent session feels like Groundhog Day: you re-explain the codebase conventions, re-link the relevant tickets, re-paste the schema. The agent isn't stupid — its memory is, by design, ephemeral. The fix isn't a bigger context window; it's an external memory architecture that survives across sessions, projects, and model swaps.
Why this matters
- Coding agents that forget cost you the same setup tax on every interaction.
- Bigger context windows make the problem cheaper but don't solve it — irrelevant context is worse than no context.
- Real productivity gains come from agents that accumulate knowledge of your codebase, your team's conventions, and prior decisions.
- Memory architecture is the difference between a clever autocomplete and a genuine collaborator.
Core concepts
Three memory tiers
Short-term (current task context), working (this session's scratchpad and tool outputs), long-term (cross-session knowledge: codebase facts, team conventions, prior decisions). Each tier has different storage, retrieval, and decay characteristics.
Episodic vs. semantic memory
Episodic = "what happened" (this PR, this incident, this conversation). Semantic = "what's true" (this is how we name files, this is our auth pattern). Promote episodic to semantic only when the lesson generalises.
Retrieval over recall
Don't try to stuff everything into context. Build retrieval (vector + keyword + structural) so the agent fetches what it needs when it needs it.
Memory decay and contradiction
Old memories go stale. Newer signals should override older ones, contradictions should surface for human review, and confidence should drop with age.
Practical patterns
AGENTS.md / CLAUDE.md
A versioned, human-edited file at the repo root capturing conventions and "do this, not that" rules — the agent's onboarding doc.
Decision log retrieval
Capture ADRs (Architecture Decision Records) and retrieve relevant ones when the agent enters a related area of code.
Lesson capture
When you correct the agent, capture the correction as a structured lesson with confidence, scope, and expiry.
Memory eval suite
Run a memory eval: same questions across sessions, with and without memory enabled, to measure whether memory is actually helping.
Pitfalls to avoid
- Treating memory as a vector DB problem only — graph and relational structure matter too.
- Letting memory grow unbounded; old, wrong context is worse than no context.
- Mixing user-provided memory with model-generated memory without provenance.
- Optimising for recall metrics that don't correlate with task success.
Key takeaways
- 1Memory is an architecture, not a feature flag.
- 2Separate episodic from semantic, and promote deliberately.
- 3Retrieve, don't recall — keep the context window clean.
- 4Measure whether memory is helping; if it isn't, remove it.
Go deeper · external resources
Curated reading list to take you from primer to practitioner. All links are external and free to read.