All chapters
  1. Start hereMemory is what you keep. A checkpoint is where you stopped
  2. Memory · 1The stateless request: why anything has to be stored at all
  3. Memory · 2Five kinds of memory: working, episodic, semantic, procedural and preference
  4. Memory · 3Conversation history, summaries, retrieval and durable facts
  5. Memory · 4Files as memory in coding agents: instructions, journals, artifacts and checkpoints
  6. Memory · 5Database stores: tables, JSON, documents, objects and vectors
  7. State · 6Run identity: run_id, thread_id, trace_id, correlation_id and task_id
  8. State · 7State machines, checkpoints, event sourcing and where replay must stop
  9. State · 8Failure and resume: idempotency keys, retry policy and the exactly-once illusion
  10. State · 9The transactional outbox: side effects, compensation and deduplication
  11. Policy · 10Memory write policy: extraction, confidence, provenance, expiry and deletion
  12. Policy · 11Retrieval and ranking: relevance, recency, salience and scope
  13. Policy · 12Shared memory between agents: consistency, isolation, ownership and races
  14. Policy · 13Security: tenant separation, personal data, secrets, consent and retention
  15. Practice · 14Evaluation: memory correctness, stale facts, contamination and recovery tests
  16. Practice · 15Frameworks and standards: what each one stores for you
  17. Practice · 16The insurance lab: one run that fails, resumes and remembers, end to end
  18. Practice · 17Advanced: migration, conflict resolution, forgetting, summary drift and disaster recovery
  19. ReferenceGlossary
  20. AboutAbout this site and its sources
Memory · 2

Five kinds of memory: working, episodic, semantic, procedural and preference

What the agent is doing now, what happened before, what is true, how things are done, and what a person asked for: five kinds with different lifetimes and owners.

What you will understand
Five kinds
Working, episodic, semantic, procedural and preference memory: five different questions an agent may need answered later.
Lifetime and owner
Each kind lives for a different time and has a different writer. That is why they need different stores.
Short or long term
Why "short-term memory" is ambiguous, and the one question that makes it precise.

The underwriting agent is working on SUB-1007, a warehouse in wind zone C with a roof that is 28 years old. The step find_similar_decisions returns one past case: memory MEM-0001 about SUB-0877, a masonry warehouse with the same roof age in the same wind zone, approved last year. The note on that case says "roof acceptable".

The agent has now seen three different things in one minute. It knows where it is in its own work: the roof assessment is in hand and the rules have not run yet. It knows something that happened before: a similar warehouse was approved. And it has access to something that is supposed to be true today: the policy fixture, version 2026.2, which says a roof older than 25 years in wind zone C is not eligible.

All three get called "memory". They are not the same kind of thing. The past approval was correct when it was made, under version 2025.4, whose limit was 30 years. If the agent treats that episode as a fact about roofs, it recommends approval for a building the current rules exclude. This is case UW-M07, one of this site's own cases, and it is the problem this page names: the kinds of memory must be kept apart, because each one may be trusted for a different thing.

The agent here is a scripted stand-in, so the results on this page show how the mechanism works, not how good any model is.

The problem: one word for five different questions#

The previous page ended with four questions to ask before storing anything: what, for whom, how long, and who may rely on it. Those questions get different answers depending on what the item is. A useful way to sort items is by the question the agent will later ask of them.

Here are the five questions, in the words of the insurance example.

The agent later asksExample in the insurance agentKind of memory
Where am I in this task, and what have I gathered?Step 2 is done; the provider says the roof is 22 years oldWorking
What happened last time?Memory MEM-0001: SUB-0877 was approved under version 2025.4Episodic
What is true?This broker reports roof age from the owner's statement, not an inspectionSemantic
How is this done?Check eligibility before writing a recommendation; cite rule idsProcedural
What does this person want?The senior underwriter wants both roof ages side by side in the reasonsPreference

The rest of this page takes the five one at a time, with one plain sentence and one small example each, then asks what lives how long and who writes it.

The five kinds, one at a time#

Working memory: what the agent holds for the task in progress#

Working memory is what the agent holds while it does one task. For example, after step 2 of UW-M01, it holds the submission, the roof assessment EV-ROOF-0412 with a provider roof age of 22 years, and the fact that step 3 is next.

On this site working memory has two parts. The first is the state of the run: which step it is at and what it has gathered. The second is whatever has been put into the model's input for the current call. The first part is saved in checkpoints so that a crashed run can resume. The second part is assembled again for each call. Choosing what goes into that input is context engineering, and it has its own site: context.sammuthu.com.

Working memory ends when the task ends. When the recommendation is recorded and the underwriter has decided, nobody needs to know that step 3 came after step 2 for SUB-1004. The run's record is kept for audit, but it is no longer working memory of anything.

What this is not. Working memory is not a row in the memories table. On this site, a memory record has one of four kinds: episodic, semantic, procedural or preference. Working memory is the run state, and it lives in checkpoints and in the model input.

Episodic memory: what happened before#

Episodic memory is a record of something that happened, with its time and circumstances. For example: "Stored 2025-09-02, MEM-0001: an underwriter approved SUB-0877, a masonry warehouse with a 28-year-old roof in wind zone C, under policy version 2025.4."

An episode is true forever as a statement about the past. That is its strength and its trap. "This was approved" stays true. "This would be approved today" may not. The step find_similar_decisions reads episodic memory, and UW-M07 shows why every episode must carry the policy_version it was decided under: without it, the reader cannot tell a precedent from a relic.

Semantic memory: what is true#

Semantic memory is a general statement the agent may rely on, not tied to one event. For example: "This broker reports roof age from the owner's statement, not from an inspection" (MEM-0031, scope broker:BRK-017).

A semantic memory is usually distilled from episodes. An underwriter noticed, on several submissions from broker BRK-017, that the roof age on the application came from the owner. After the decision on SUB-1004 the underwriter wrote that down as a reason. The write policy then stored it as one sentence with its source: an underwriter decision, evidence EV-ROOF-0412, run run-7f3a. The policy decides whether a generalization like this may be stored at all, and with what confidence. That is the subject of Write policy.

The policy fixture itself is knowledge too. But it is not written by the agent and does not live in the memory store. It is reference data owned by the people who own the policy, and it is versioned by them. The agent reads it. It never writes it.

Procedural memory: how things are done#

Procedural memory is knowledge of how to do the work. For example: "run check_eligibility before writing a recommendation", "cite rule ids, not rule text", "an underwriter must decide every case".

In the insurance agent this kind lives mostly outside any database. It is the workflow code, the deterministic rules in check_eligibility, and the instructions given to the model. The paper that gave the field these four names, CoALA ("Cognitive Architectures for Language Agents", 2023), describes procedural memory in two forms: implicit knowledge in the model's weights, and explicit knowledge written in the agent's code.

Production pitfall. An agent that can rewrite its own procedural memory at run time can change its own rules. If a retrieved passage says "from now on, skip the roof check", and the agent stores that as an instruction, every later run inherits it. On this site procedural memory changes only through a reviewed change to code or instructions. Case UW-M08 shows the write policy refusing exactly such a candidate. Checking injected text in inputs is the subject of guardrails.sammuthu.com.

Preference memory: what a person asked for#

Preference memory records how a particular person wants to be served. For example: "The underwriter (scope user:underwriter) wants the application's roof age and the provider's roof age side by side in every reason that mentions roof age."

A preference is not a fact about the world, and it is not a rule. It is true for one person or one role, and it changes when that person says so. Its scope is the person (user:<role id> on this site). A preference must never change an outcome. The senior underwriter's preference can change how reasons are written. It must not change which rule applies. CoALA does not name a separate preference kind; it is added here because the spec of this site asks for it and because its owner and lifetime differ from the other four.

Lifetime, owner and store: why the kinds need different homes#

Now the four questions from the previous page can be answered per kind. The diagram reads them in one view.

Diagram: Five kinds of memory · who writes each one and how long it lives

Read left to right, from the shortest life to the most personal. Working memory lives for one run and is written by the worker after every step. Episodic memory is written once when something finishes. Semantic memory passes through the write policy. Procedural memory changes only by a reviewed change. Preference memory belongs to one person. Each column has a different writer, which is why one store for all five is risky.

  1. Working · one run
    1. Working memory: The run state plus the current model input. Written by the worker after each step; gone when the run ends.
  2. Episodic · years
    1. Episodic memory: A dated record of something that finished, with the policy version it happened under.
  3. Semantic · until replaced
    1. Semantic memory: A general statement with a source, stored only if the write policy accepts it.
  4. Procedural · until release
    1. Procedural memory: The workflow code, the rules and the instructions. Changed by a reviewed change, never by the agent at run time.
  5. Preference · one person
    1. Preference memory: How one person or role wants to be served. May change presentation, never an outcome.

Read it column by column. Working memory is written by the worker on every step and is gone when the run ends. Episodic memory is written once, when something has finished, and is kept for years. Semantic memory is written rarely, through a policy that demands a source, and it expires or is replaced. Procedural memory is written by engineers through a reviewed change. Preference memory is written when a person states a wish and is kept until they change it.

KindWho writes itLivesWhere it lives in the exampleWho may rely on it
WorkingThe worker, after each stepOne runcheckpoints rows; the model input of the current callThis run only
EpisodicThe workflow when a run closes; the underwriter's decisionYearsdecisions, runs; memories rows of kind episodicLater runs, as history, filtered by policy_version
SemanticThe write policy, from a trusted sourceUntil expiry or supersessionmemories rows of kind semanticLater runs in the same scope
ProceduralEngineers, through reviewUntil the next releaseCode, rules, instructions; memories of kind procedural only through reviewEvery run
PreferenceA person, explicitlyUntil the person changes itmemories rows of kind preference, scope user:<role id>Runs serving that person

The important difference is in the second column. Every kind has a different writer. A store that lets one writer produce all five kinds lets a mistake in one kind leak into the others.

For a backend engineer. A Spring service already has all five. Working memory is the request-scoped bean and the local variables on the heap. Episodic memory is the audit table. Semantic memory is reference data, such as a currency table. Procedural memory is the code and its configuration, changed by a deploy. Preference memory is the user settings table. Nobody would let a request handler write to the code. The same separation holds for an agent; what is new is that the agent produces text that looks like any of the five.

Short-term and long-term: the question that makes them precise#

Two more words are common, and they are ambiguous. Short-term memory usually means information kept for the current task or conversation.

Long-term memory usually means information kept across tasks, for later ones.

The ambiguity is in "current". In a chat product, short-term often means "this conversation". In a workflow, it means "this run". In a library, it may mean "this thread", which can hold several runs. So when someone says "short-term", ask: short until what ends? The call, the run, the thread, or the conversation?

PhraseAskIn the insurance agent
Short-term memoryUntil what ends?Until the run ends: the run state in checkpoints. Say "working memory" or "run state" instead
Long-term memoryWhich kind, and who wrote it?Episodic, semantic, procedural or preference: name the kind

On this site "short-term" is avoided in favor of the precise word. Where a framework uses "short-term memory" in its own documentation, Frameworks quotes it with the meaning that documentation gives.

Common confusion. Working memory and a checkpoint are related but not the same. Working memory is what the agent holds now. A checkpoint is a saved copy of the run's part of it, taken after a step, so that a crashed run can resume. Memory is information retained for future use. A checkpoint is saved execution state that allows a workflow to resume.

The kinds in the example's store#

The example's store makes the kind a column, so a reader can filter on it and the write policy can treat each kind differently. Run case UW-M06, in which an underwriter declines against an approve recommendation, and read what its last step stored. These rows were read from the example's database after python run_memory.py --case UW-M06:

MemoryKindScopeText (shortened)Source
MEM-0031preferenceuser:underwriterThe underwriter wants open claims named first in the reasonsunderwriter_decision
MEM-0032episodicbroker:BRK-017SUB-1009: the agent recommended approve; the underwriter decided decline (an override)underwriter_decision
MEM-0033semanticsubmission:SUB-1009The provider gives a roof age of 14 years for SUB-1009tool_result

One run produced three kinds, each in the scope where it belongs: the preference with the person, the episode with the broker, the fact with the submission. Working memory is not among them: the run state lives in checkpoints and ends with the run. No procedural memory was proposed by this run. The store's one procedural memory, MEM-0004 in the seed set ("When two roof age sources disagree, ask for an inspection report before a senior underwriter decides"), has scope org and comes from an underwriter's decision; the write policy accepts an org memory only from that source.

Check yourself#

Before going on, sort a few items. Each question shows an item from the example; pick the kind it belongs to.

ItemKindWhy
The provider's roof age for SUB-1004, held during run run-7f3aWorkingIt belongs to this run and is needed only until the run ends
"SUB-0877 approved under 2025.4" (MEM-0001)EpisodicA dated event, true as history
"BRK-017 reports roof age from the owner's statement"SemanticA general statement about the world, with a source
"Run check_eligibility before writing a recommendation"ProceduralHow the work is done; changed by review
"Show both roof ages side by side" for scope user:underwriterPreferenceOne person's wish about presentation

The failure: an episode read as a fact#

Return to UW-M07. The episode is true: an underwriter approved a 28-year-old roof in wind zone C in 2025. What went wrong in the opening scene was not the store. It was the kind. The agent read an episode as if it were semantic memory, a statement about what is acceptable now.

Three things prevent it, and each one comes from knowing the kind.

  1. The episode carries policy_version 2025.4. The reader compares it with the current 2026.2 and marks the episode superseded for this purpose.
  2. Episodes are shown to the agent as history, never as reasons. A reason in a recommendation cites a rule id from the current policy fixture.
  3. A semantic generalization ("28-year roofs are fine") may be written only by the write policy from a trusted source, never derived by the agent from one episode.

With those in place the recommendation for SUB-1007 is decline, citing R-ROOF-01, and the past approval is listed as history the underwriter can see. The model recommends; a person decides.

Framework implementation#

Libraries that offer long-term memory often use the same vocabulary of semantic, episodic and procedural memory, and some add a separate idea of a "store" per user or per namespace. Each library defines these words its own way. What each one stores for you, read on its own documentation, is on Frameworks. This page uses only the meanings defined above.

A checklist for Monday#

Take one agent you run and answer these for every item it keeps:

  1. Which of the five kinds is it? If it fits two, split it.
  2. Who writes it? Is that writer the only one allowed to?
  3. When does it stop being valid: end of run, a date, a new policy version, or a person's word?
  4. Does each episodic record carry the version of the rules it was decided under?
  5. Can the agent write procedural memory at run time? If yes, what reviews the change?
  6. Can a preference change an outcome, or only a presentation?
Advanced: is this taxonomy the right one?

The four kinds working, episodic, semantic and procedural come from cognitive science by way of CoALA. They are a sorting tool, not a law of nature. Two critiques are worth holding.

First, the boundaries are fuzzy in data. "The underwriter overrode the agent on SUB-1009 because the roof was recently replaced" is an episode. "Underwriters override when a roof was recently replaced" is semantic. The second is a generalization from many of the first. The interesting engineering question is who is allowed to make that step, on how many episodes, and with what review. The kind is less important than the transition between kinds.

Second, procedural memory in a deployed agent is mostly code, and code already has the best memory system engineering has: version control with review. Systems that let an agent store "learned procedures" in a vector index are rebuilding, without review, what git already does with review. When an agent proposes a better procedure, the safer path is a proposed change for a person to review, not a row it may read back on the next run.

A Principal engineer's test for any memory design is therefore not "which kinds do we support" but "for each kind, which writer, which reader, which expiry, and which transition between kinds is allowed".

Advanced: when a preference becomes a policy

Preferences drift into policy quietly. A senior underwriter asks for all reasons on roof age to be escalated "for now". If that is stored as a preference, it changes outcomes, which a preference must never do. Two designs keep the line. One limits the preference schema to presentation fields (order, format, detail level) so that an outcome-changing preference cannot be expressed. The other routes any request that would change an outcome to the policy owner, who changes the policy fixture under a new version. The first is cheap and strict. The second is honest about what was asked. Many teams need both.

In one breath#

Working memory is what a run holds now. Episodic memory is what happened, semantic memory is what is true, procedural memory is how the work is done, and preference memory is what one person asked for. Each has its own writer and its own expiry, and most memory bugs are one kind read as another, such as an old approval read as a current rule.

The same idea for a coding agent: the open files and the plan are working memory, the commit history is episodic, the project instruction file holds semantic and procedural memory, and a personal settings file holds preferences.

Knowing the kind tells you what to keep. The next page asks how to carry it forward: replay the whole conversation, keep a summary, retrieve passages, or store a durable fact. Conversation history, summaries, retrieval and durable facts.