Memory Design

Memory design

Memory is the only part of an agent that keeps being wrong after you stop looking. A retrieval bug shows up in the next answer; a stale memory sits there being quietly confident for months. Design the retirement path before the write path.

When this fires

An agent needs a fact to survive past the current context — across turns, tasks or sessions — or an existing memory store has grown noisy, contradictory, or is surfacing one subject's data to another. It does not fire for retrieval over a document corpus (that is retrieval-rag), and not for keeping a transcript: a transcript is a log, not memory.

Procedure

1. Name the repeat failure first. What did the agent forget, how often, and what did it cost — a re-asked question, a redone decision, a wrong assumption. Memory added without a named repeat failure is speculative storage, and storage you cannot justify is storage you will not prune.
2. Classify what is actually worth keeping, because the class decides everything after it:
   • stable facts and preferences — this user's stack, conventions, how they want to be addressed
   • decisions and their rationale — true until explicitly reversed, and the rationale is the part that matters later
   • working state — what this task is mid-way through; it dies with the task
   • derived summaries — regenerable from the source; store only when regeneration is expensive Everything else is a log. Do not promote a log to memory.
3. Put each class in the shallowest layer that holds it. Working state belongs in a task file or thread state, not a long-term store. Stable facts and decisions belong in a durable record. If the store is a vector index, it is a retrieval system and inherits the retrieval-rag procedure, including the requirement to measure recall — unevaluated vector memory is a wish.
4. Scope every record explicitly at write time: the subject it is about (this user, this project, this repository, this organization) and who may read it. Default to the narrowest scope. Widening a memory's scope so it crosses users or tenants is a data boundary change — raise it and get an explicit decision, do not infer permission from convenience.
5. Write memories as assertions with provenance, not as free prose: the claim, when it was learned, what it was learned from (session, message, file, commit), and what would make it false. A memory with no source cannot be retired safely, because nothing can be checked against the thing it came from.
6. Choose the write trigger deliberately. Writing on every turn produces noise that buries the few records that matter. The triggers that earn a write: the user says to remember, a decision is settled, a correction is issued, or a fact was expensively discovered. A user correcting the agent is the highest-value write there is — never drop one.
7. Refuse to store secrets and sensitive personal data. Credentials, tokens, keys, payment and identity data do not go into memory, even when they appeared in the conversation. If one is already stored, stop and tell the user rather than quietly acting on it.
8. Check for staleness at read time, not only on a schedule. Three detectors, cheapest first: contradiction — a new statement conflicts with a stored one; expiry — the record was time-boxed at write (current sprint, active branch, "for now"); reference decay — it names a file, person, project or setting that no longer exists. Verify a load-bearing memory against the live source before acting on it.
9. Supersede rather than silently overwrite. The replacing record points at what it replaced and says why. History of a reversed decision is often more useful than the decision.
10. Treat deletion as destructive. Retiring or clearing memory the user gave you removes something they may be relying on. Propose the retirement with the list of what would go, and ask. Never bulk-delete a memory store to fix a formatting problem.
11. Bound the store and measure usefulness. Set a cap and an eviction rule based on when a record was last read, not when it was written. Track what fraction of stored memories have been read at all in the last N sessions; a large unread tail is cost with no return, and it is the signal to tighten the write trigger from step 6.
12. Exercise the full loop before calling it done: write a memory, start a genuinely fresh session, confirm it is retrieved and used. Then change the underlying fact and confirm the old record is superseded rather than duplicated, and that the new answer reflects the new fact.

Checklist

• The repeat failure this memory exists to fix is named
• Each stored class mapped to a layer, with working state kept out of the durable store
• Every record carries subject scope and read visibility
• Every record carries source, timestamp, and a falsification condition
• Write triggers are explicit; corrections are always captured
• Secrets and sensitive personal data excluded at the write path
• Contradiction, expiry and reference-decay checks run before a memory is acted on
• Supersession preserves what was replaced and why
• Deletion is proposed to the user, never performed silently
• Cross-session round trip exercised, including the changed-fact case

Failure handling

• Two memories contradict each other — do not pick by recency alone. Check both against the live source; if it cannot be resolved, surface the conflict to the user rather than acting on a coin flip.
• The agent recalls a fact that is no longer true — the defect is in the retirement path, not in retrieval. Fix the expiry or contradiction detector; deleting the one bad record leaves the next one to be found by the user.
• A memory from one subject surfaced under another — stop, treat it as a data exposure, report it with the scope that was wrong. Do not continue the feature work first.
• The store is large and nothing is measurably better — that is a result. Report the unread fraction and propose narrowing the write trigger.
• No durable store is available in this environment — say so, keep the fact in the task's own working state, and do not describe behaviour as persistent when it is not.

Evidence to report

The classes stored and the layer each lives in; a sample record showing scope, source, timestamp and falsification condition; the write triggers as implemented; the staleness checks that run and where they run; the cross-session round trip actually performed, including the changed-fact case, with what was recalled; and the read-rate of the store if it has been running long enough to have one. "It remembers now" without a fresh-session round trip is a claim, not evidence.