---
title: "Memory"
description: "The distinct types of agent memory, what each solves, and what to share versus isolate in a multi-agent system."
url: "https://agentsurface.dev/docs/agents/memory"
index: https://agentsurface.dev/llms.txt
lastVerified: 2026-10-29
lastModified: 2026-10-29T11:29:43.000Z
---

## Summary [#summary]

"Agent memory" covers at least five distinct mechanisms with different scope and persistence. A system that relies only on message history is capped at what fits in a context window. Start with none, and add a type only when the product need is concrete - see [Design Defaults](https://agentsurface.dev/docs/agents).

| Type            | Scope                   | Storage                  | Retrieval               |
| --------------- | ----------------------- | ------------------------ | ----------------------- |
| Message history | Current thread          | In-memory / checkpointer | Sequential, by position |
| Working memory  | Per-session, per-agent  | Structured store         | Direct key access       |
| Semantic recall | Cross-thread, long-term | Vector database          | Embedding similarity    |
| Observational   | Background compression  | Structured store         | Direct key access       |
| Procedural      | Learned behavior        | Instruction store        | Loaded into context     |

## Message History [#message-history]

The conversation context the model processes every turn - the only type guaranteed to influence output. Scoped to a `thread_id`; a checkpointer (Postgres, Redis) persists it across sessions. Manage length by trimming to a token budget, summarizing and compressing older turns, or - increasingly - letting the platform do it: OpenAI's server-side compaction on the Responses API and Anthropic's beta compaction API summarize prior turns inside the provider's own runtime, so the app neither resends nor re-summarizes the transcript. Platform compaction is lossy by design and is not a memory system or an audit log; keep your own record of what the agent did.

## Working Memory [#working-memory]

Persistent structured state that survives across turns within a session, and optionally across sessions - accessed directly by key rather than processed wholesale like message history. Use it for facts that should stay stable across a session: user preferences, confirmed decisions, established context. Frameworks that support it typically let you define a schema (Zod or equivalent) for what the agent tracks, inject the current values into the system prompt automatically, and persist model-driven updates alongside programmatic reads and writes.

## Semantic Recall [#semantic-recall]

Messages and other content stored as vector embeddings; the most similar past content is retrieved and injected into the current turn. This lets an agent "remember" a fact from months ago without keeping every message in the active window. Retrieval is scoped either to a thread or to a resource/entity ID that spans threads (a user, an organization, a project) - the latter is what makes cross-thread recall work: a fact recorded in January is retrievable from a session started in April against the same entity ID.

## Observational Memory [#observational-memory]

Background compression of aging message history: as messages age past a recency threshold, a process summarizes and stores them in structured form, freeing context space while preserving substance. This runs asynchronously - the agent keeps operating on recent messages verbatim while older ones compress in the background. Treat any specific compression-policy API as illustrative rather than a fixed constructor shape; the pattern (recent-verbatim plus older-summarized) is the portable part, and different systems expose it as a policy, a hook, or a custom job.

## Procedural Memory [#procedural-memory]

The first four types store what the agent _knows_; procedural memory stores what it has _learned to do_ - generalized instructions distilled from experience, not raw events. It is a growing category - Zep v4's docs cover skill capture, learning and admission, restoration, and sharing, and other memory products offer comparable instruction stores, so check each product's own API before assuming one - and its file-based cousin is the skill library: a `SKILL.md`-style document that captures a repeatable procedure once and loads it on demand.

**Write path.** Reflection, not direct capture: a background or end-of-task step reviews recent runs and promotes patterns that succeeded _repeatedly_ into standing instructions - deliberately slow and selective, since a single success should not become a rule.

**Read path.** Loaded into context at session start rather than retrieved per turn, because standing instructions apply broadly. High-volume instruction sets can be scoped by task type or tool to control token cost.

**Risk.** This is the one memory type that changes behavior, so a wrongly promoted instruction compounds as a bad habit across every future run. Require multiple supporting runs before promotion, expire instructions that stop being reconfirmed, and keep the store small and human-auditable.

## Context Failure Modes [#context-failure-modes]

Five named failure modes describe how a growing context degrades an agent before it runs out of room:

- **Poisoning** - an error enters context and gets treated as true for the rest of the run, compounding into further wrong steps.
- **Distraction** - so much history has accumulated that the model over-relies on it instead of reasoning fresh from the current task.
- **Confusion** - irrelevant tools or content in context steer the model toward the wrong action even though nothing in it is factually wrong.
- **Clash** - contradictory information sits in context at once, and the model has to pick a side without being told which one is current.
- **Rot** - output quality falls as context grows, measurably, well before the model's advertised context limit is reached.

These motivate keeping context lean by design rather than trusting the window's advertised size: message trimming, working-memory scoping, and semantic recall (above) all exist partly to keep an agent from accumulating the volume of context that triggers these failure modes.

## Memory Processors [#memory-processors]

A memory processor is a pluggable filter that sits between the memory store and the context window that gets sent to the model - it runs after retrieval and before the prompt is built. Common processors: a token limiter that caps total memory content to a budget, and a tool-call stripper that drops old tool calls and their results once they are no longer relevant to the current turn. Processors let the same underlying memory store feed different context shapes to different calls, without changing what is actually persisted.

## Sharing Memory Across Agents [#sharing-memory-across-agents]

Sharing requires explicit design; assuming a global memory store is the most common multi-agent memory mistake.

| Memory type       | Share between agents?           | Rationale                                                         |
| ----------------- | ------------------------------- | ----------------------------------------------------------------- |
| Message history   | Only through a shared thread ID | Workers do not need the supervisor's full internal reasoning      |
| Working memory    | Per-agent                       | Agent-specific preferences and state                              |
| Semantic recall   | Share via a resource/entity ID  | Cross-thread recall benefits from the full history of that entity |
| Procedural memory | Per-role, curated               | Each role learns its own procedures; sharing spreads bad habits   |
| Shared task store | Yes, namespaced                 | Sub-task outputs must reach the supervisor or downstream agents   |

Thread-level sharing (supervisor and workers on the same `thread_id`) works for tightly coupled delegation but leaks the supervisor's internal reasoning into worker context. Explicit namespaced store sharing - each agent reads and writes under `(project, task, key)` rather than a shared global object - scales better once workers should only see what they need.

## Related [#related]

- [Orchestration](https://agentsurface.dev/docs/agents/orchestration)
- [Design Defaults](https://agentsurface.dev/docs/agents)
- [Agent Retrieval](https://agentsurface.dev/docs/agent-retrieval) - the retrieval mechanics semantic recall builds on
- [Durable Execution](https://agentsurface.dev/docs/agents/durable-execution)