What should an AI agent remember?
Save the small set of durable facts that will change a later decision—not a transcript of everything that happened.
Persistent memory sounds like a storage problem. In practice, it is an editorial problem: what deserves to survive a session, who may write it, when it becomes stale, and how a person can correct it.
Memory can put information into a later model context. It does not turn prose into an access-control rule. If an action must be blocked, enforce that boundary outside the model.
The four-question retention test
Before preserving a fact, ask four questions:
- Will it matter after this session? Temporary paths, one-off debugging output and conversational filler usually will not.
- Will it change a future choice? A build command, corrected preference or project convention can. A vague note such as “the user has a project” cannot.
- Can it be checked and revised? Useful memory needs a visible owner, scope and correction path. Time-sensitive facts benefit from a review date.
- Is it safe to retain? Do not turn credentials, private transcripts or large raw dumps into convenient memory. Store a safe pointer when the underlying system already owns the information.
Four buckets are clearer than one memory pile
Instructions
Human-authored rules and project conventions that should be present routinely. Keep them concise and scoped.
Learned notes
Corrections, preferences and hard-won facts that are likely to prevent a repeated mistake.
History
The fuller record of earlier work. Search it when needed instead of squeezing every detail into the startup context.
Ephemera
Tool output, temporary state and task-specific detail. Keep it in the working record, then let it expire.
This separation is not universal product terminology. It is a practical way to decide which mechanism should carry a fact. Two documented systems illustrate the distinction: Hermes uses bounded memory files plus separate session search, while Claude Code distinguishes human-written project instructions from agent-written auto memory.
Memory needs controls, not mystique
- Scope: identify whether a note belongs to a user, project, repository or agent profile.
- Review: make saved entries inspectable and editable. A hidden correction mechanism invites stale assumptions.
- Capacity: use a budget. A small store forces prioritization and reduces the amount injected into every session.
- Freshness: replace superseded decisions rather than preserving conflicting statements without dates.
- Permissions: separate permission to read memory, write memory and take external action.
A good memory entry is specific enough to affect behavior and short enough to review. “Run the test suite with npm test before handoff” is actionable. “We worked on tests” is not. A changed decision should replace or clearly supersede the old one.
What the primary sources establish
Anthropic: context is finite
Anthropic’s context-engineering article describes structured notes outside the context window and just-in-time retrieval as distinct techniques. Its guiding idea is to keep context high-signal rather than load everything.
Claude Code: instructions and learned notes differ
Claude Code’s memory documentation separates human-written instruction files from agent-written auto memory, says both enter model context, and explicitly notes that context is not enforced configuration.
Hermes: bounded notes and session search differ
Hermes Agent’s memory guide documents bounded persistent notes, profile scope, visible capacity, editing actions and a separate session-search mechanism.
This guide compares documented mechanisms. It does not claim that either system was installed or tested locally, and it does not recommend retaining sensitive information.