Designing Memory for a Repeat-Visit Coding Agent
You're building a coding agent that works on the same handful of client repositories across many sessions over several weeks. Users report three complaints:
- It forgets project-specific conventions between sessions (build commands, "never touch this legacy directory") and has to be re-told every time.
- On a repo it has worked in before, it sometimes re-proposes a fix that was already tried and already failed, for the same bug class.
- On long single-session tasks, it occasionally loses track of the multi-step plan it made at the start, after many tool calls.
For each complaint, identify which memory layer is missing or misdesigned, what should be stored, and whether it should be loaded eagerly or retrieved on demand. Then explain how the three fixes are different from each other, not just "add more memory."
Complaint 1 — missing long-term memory
Project conventions (build commands, "don't touch /legacy") are
facts that are true independent of any one session, small, and
likely to matter every time work happens in this repo — they pass
all three durability criteria for long-term memory. Because they
apply to every session on this repo, they should be eagerly
loaded — an always-loaded, small, human-reviewable file read at
the start of every session on this project (the CLAUDE.md-shaped
pattern: authored, versioned, concatenated in, re-injected after
compaction). Retrieval-triggered storage would be the wrong choice
here — these facts are relevant to 100% of sessions on this repo, so
making them dependent on a similarity match adds risk (a miss) for
no benefit.
Complaint 2 — missing episodic memory
"We tried fix X for this bug class and it failed because Y" is not a stable fact — it's an event, scoped to a specific past task with a specific outcome and root cause. This is episodic memory, distinct from the long-term conventions in complaint 1: it should be stored as a record keyed by project plus a description of the task/bug (approach tried, outcome, root cause), and it should be retrieval-triggered — searched for relevance when a new task looks similar to a past one, not loaded on every session regardless of task (most sessions won't be touching this bug class, so eager loading would waste budget and bury unrelated episodes under it). The fix is not "store more facts" — it's adding a layer that captures causal history, which a facts-only long-term store structurally cannot represent well.
Complaint 3 — missing working memory
Losing track of a plan across many tool calls within one session is a working-memory problem, not a long-term or episodic one — the information (today's plan) has no reason to outlive this task. The fix is to have the agent write the plan to an external, structured artifact (a plan file or state block) at the start of the task and re-read it periodically, rather than relying on it staying salient in the model's own generated tokens across dozens of intervening tool calls. This should survive this session's context compaction (a stable file on disk, unlike raw chat), but it is not meant to persist once the task is verified done — unlike complaints 1 and 2, nothing here needs to be durable across tasks.
Why these are three different fixes
Complaint 1 is a durability problem (a fact that should survive sessions wasn't being persisted at all) solved with eager long-term memory. Complaint 2 is a causal-history problem (an event, not a fact) solved with retrieval-triggered episodic memory. Complaint 3 is a within-task attention problem, solved with an externalized scratchpad that doesn't need to survive past this task at all. "Add more memory" undersells the design — each complaint maps to a different layer with a different lifetime, a different store shape, and a different load trigger, and conflating them (e.g. shoving the plan into long-term memory, or the failed-fix history into the always-loaded conventions file) would either bloat the eager set or fail to capture the causal detail that made the information useful.
Share this question