How the memory model works: session, workspace, episodic and procedural memory

When people say "agent memory", they often mean one thing: a vector index of past text. Real agents need more than that. They need context for the task in front of them, durable facts that outlive the session, a record of what happened on past attempts, and the habits that tend to work. Agent Memory models each of these separately and connects them with a single learning loop.

Two tiers: volatile session, durable memory

Memory starts out short-term. During a run, an agent appends entries that are grouped by runId, and those entries live in session memory in Redis. Session keys are scoped by tenant, workspace, application and run, and they expire after a time-to-live. Session memory is where the agent thinks out loud.

Durable memory lives in PostgreSQL with pgvector. You move knowledge from one tier to the other with consolidation, which you can call explicitly or let a background maintenance service run once a session has been idle long enough.

The four structures

Workspace memory: the facts

A workspace memory is a single distilled fact. Its type drives how the pipeline treats it, and there are five types:

• decision
• correction
• violation
• approved_pattern
• artifact_ref

Each entry carries an embedding, confidence and importance scores, a lifecycle state, provenance (its source kind, source reference, the model that produced it and the extraction method), and two time axes: when it was valid and when it was recorded.

Workspace memories are connected by typed relationships, for example REPLACES, CONTRADICTS, CONFIRMS, BUILDS_ON and DERIVED_FROM. Those edges are what let the system say "this correction overrides that decision". When a fact is superseded or deleted, a dependency check flags the memories derived from it as stale. Those memories are marked for review, never silently removed.

Episodic memory: what happened

Consolidation opens one episode per run, and every raw session entry becomes an episode event. An episode records the run's outcome and a success score, and it links to the previous episode, so runs form a chain. Sentence-level derivatives are produced for fine-grained retrieval. Agents can look up past episodes similar to their current goal and see how those attempts ended.

Procedural memory: what tends to work

A procedure is a learned how-to with a trigger, a goal, ordered steps and anti-patterns, along with success and failure counts and a confidence score. Procedures are created in two ways:

• Within a run: a run that scores well and involves an approved pattern can yield a procedure, with steps taken from the episode's event sequence.
• Across episodes: approved patterns and decisions with repeated evidence and high confidence are promoted to procedures.

When a later run applies a procedure and reports the outcome, the procedure is strengthened or weakened. Like other memories, procedures fade when they aren't used.

Memory blocks: what you curate by hand

Blocks are deliberately outside the learning loop. A block is a labeled piece of free text, such as a persona, the conventions or the architecture notes. You edit it line by line by adding, replacing or removing lines. Consolidation never touches blocks, so they work as the living documents you pin into an agent's context.

Promotion, step by step

Consolidating a run follows roughly this sequence:

1. Create the episode and save its events.
2. Load the workspace's semantic categories, which decide which types can be promoted.
3. Extract candidate facts from eligible session entries, using an LLM when one is configured and rule-based processing otherwise.
4. Deduplicate them and compress them into canonical facts in workspace memory.
5. Infer relationships and detect contradictions, so a newer correction can supersede an older decision.
6. Evaluate the episode's outcome, then derive or validate procedures.
7. Finalize the episode summary and embeddings, and run cross-episode abstraction.

Promotion can go one level further. A fact that is confirmed independently in at least two different workspaces of the same tenant can become a candidate for a tenant-wide convention. A tenant admin approves or rejects it, and approved conventions appear in every workspace's recall under their own heading. Memories flagged as PII are never promoted. Above tenants sit platform policies, which lower layers can't override, and platform defaults, which they can.

Relevance decays, but never quite to zero

Not every fact deserves equal weight forever. A memory's vividness combines its importance, a retention term that decays exponentially with age, and a bonus for being accessed. Stability increases when a memory is accessed at well-spaced intervals, which gives a spaced-repetition effect. Vividness has a floor, so an old fact can always be found again if the query calls for it.

Recall: from many sources to one context

When an agent asks a question, retrieval runs as a pipeline:

1. Classify the query, and split it into sub-queries if it is complex.
2. Search vector, full-text, structured, graph and episode sources in parallel.
3. Combine the results with reciprocal rank fusion, then expand to neighboring episode context.
4. Apply temporal filters if the query asks for them, and rerank.
5. Compile the result into a working-memory context within the requested token budget.

The resulting context keeps its sources separate. Platform policies come first, followed by tenant conventions, then workspace facts, episodes and procedures, so the agent can tell a binding rule from a remembered preference. Every recall also returns a receipt. Reporting an outcome or feedback against it credits the memories that were actually used and lowers confidence in the ones that misled. That is the learning loop: remember, recall, act, report, consolidate.

Why separate the types?

Each type answers a different question, and mixing them hurts all of them. Facts need to resolve contradictions. Episodes need to keep their order and outcome. Procedures need evidence counts. Curated blocks need to stay out of automated rewriting. Keeping the structures separate, and connecting them through consolidation, lets each one do its own job while your agent still makes a single call.

For the details, start with the memory model docs, or follow the quickstart and watch a session turn into an episode.