# Memory and context management for an Agent OS: state of the art, November 2026

Research done 2026-11-10 by web search and page fetches. "Verified" means I read the primary page today; "snippet" means I only saw it in a search result; "inference" is my own conclusion. Model names and prices are quoted from the vendor docs as fetched.

# 1. Context engineering inside one run

Context rot is real and starts early (verified).

Chroma's "Context Rot" (Hong, Troynikov, Huber, 2025-07-14) tested 18 models while holding task difficulty fixed and varying only input length. All degraded.
On LongMemEval, every model did markedly better on focused prompts of about 300 tokens than on full prompts of about 113k tokens.
Distractors hurt non-uniformly. Logically coherent haystacks scored worse than shuffled ones. Claude models tended to abstain, GPT models to hallucinate.
"Context Length Alone Hurts LLM Performance Despite Perfect Retrieval" (arXiv 2510.05381) reports 13.9%–85% drops across 5 models even when retrieval is perfect and distractors are whitespace or masked.
Anthropic's compaction docs state the consequence plainly: keep active context small "because response quality degrades as a conversation grows."

Anthropic API primitives (verified from docs).

Tool-result clearing: clear_tool_uses_20250919, beta header context-management-2025-06-27. Defaults are trigger 100k input tokens and keep 3 tool uses; options are clear_at_least, exclude_tools, clear_tool_inputs. It runs server-side, so the client keeps full history.
Clearing invalidates the cached prefix, so the docs advise clear_at_least to make each clear worth the cache rewrite.
Thinking clearing: clear_thinking_20251015, which must be listed first when both are used.
Compaction: two modes, both beta. Threshold mode is the compact_20260112 edit (header compact-2026-01-12, default trigger 150k, minimum 50k, instructions, pause_after_compaction). On-demand mode uses header compact-2026-09-04 and a top-level compaction parameter; it can keep recent turns verbatim, run in the background and take a custom summarisation prompt. The docs recommend on-demand where available.
Memory tool: memory_20250818, now stable with no beta header. It is client-side: six commands (view, create, str_replace, insert, delete, rename) over a /memories prefix that your handler maps to any store. The API auto-injects a protocol: view memory first, record progress, "ASSUME INTERRUPTION."
The docs' security list for the memory tool: path traversal, sensitive data, file size caps, expiry.
Measured gains (Anthropic, 2025-09-29, internal evals): memory plus context editing +39% over baseline, context editing alone +29%, and 84% fewer tokens on a 100-turn web-search eval.

OpenAI Responses API (verified).

Server-side compaction: context_management with compact_threshold. Standalone: POST /responses/compact.
The compaction item is encrypted and opaque ("not intended to be human-interpretable"). It works with store=false.
Chain with previous_response_id or a stateless input array. Do not prune the compact output.
Inference: opaque compaction is a lock-in and audit problem. For an OS that must be inspectable and cross-provider, own a readable summary and treat vendor compaction as an optimisation.

Caching economics constrain design (verified).

Anthropic: 5-minute write 1.25x, 1-hour write 2x. Reads are 0.1x by default, 0.05x on Opus 5.5 and Sonnet 5.5, and 0.025x on Fable/Mythos 5.1–5.2.
Hierarchy is tools → system → messages; any tool-definition change invalidates everything. Maximum 4 breakpoints, 20-block lookback, workspace-level isolation.
OpenAI: automatic prefix caching, 0.1x reads on GPT-5.6+, 30-minute default TTL (12 hours optional), and "Preserve tool definitions, ordering, and schemas."
Manus (Yichao "Peak" Ji, 2025-07-18) reports about a 100:1 input:output ratio and treats KV-cache hit rate as the key production metric. Its rules:
- stable prefix with no timestamps, append-only context, deterministic serialisation;
- mask tools via logits rather than removing them;
- file system as unlimited context, with restorable compression (drop the page, keep the URL);
- recite a todo.md at the tail;
- keep failures in the trace;
- vary serialisation to avoid self-few-shotting.

Retrieval, sub-agents, notes (verified).

Anthropic's "Effective context engineering" names three long-horizon techniques: compaction, structured note-taking, and sub-agents returning condensed summaries. It favours just-in-time retrieval over preloading.
Multi-agent research post: sub-agents are compression. Token usage explains 80% of BrowseComp variance, at a cost of about 15x chat tokens. It is a poor fit where agents need shared context.
"Effective harnesses for long-running agents" (2025-11-26): an initializer session writes init.sh, a progress log and a JSON feature list (JSON because models overwrite it less than Markdown). Each later session reads progress and the git log, does one feature, verifies end-to-end, commits and updates progress. Failure modes: one-shotting and premature "done."

# 2. Memory architectures across sessions

Taxonomy.

CoALA (Sumers et al., 2023): working memory plus long-term episodic, semantic and procedural memory. I confirmed the paper today but not the taxonomy text, which is not in the abstract.
MIRIX (2025-07) extends to six types (Core, Episodic, Semantic, Procedural, Resource, Knowledge Vault) and self-reports 85.4% on LoCoMo.
Anthropic's "The components of agent memory" (2026-11-06) uses a practical decomposition: transcripts (searchable event log), agent-written notes, representations such as wikis, a small injected layer, and offline "dreaming."

Systems (verified unless noted).

MemGPT → Letta: the trajectory is away from database memory tools. "Context Repositories" (2026-02-12) and MemFS put memory in git-backed markdown edited with ordinary file tools. Every edit is a commit. Sleep-time reflection works in a git worktree and merges back. Legacy core_memory_replace-style tools are being removed.
Mem0: the 2025 paper used extract-then-decide (ADD/UPDATE/DELETE/NOOP) and claimed +26% relative to OpenAI memory, 91% lower p95 latency and over 90% token savings against full context. The graph variant added only about 2%.
In April 2026 Mem0 moved to single-pass ADD-only extraction plus hybrid retrieval (semantic, BM25, entity match) and dropped the external graph store from the open-source version. Inference: LLM-driven destructive updates at write time proved the weak point.
Zep/Graphiti: a temporal knowledge graph. Facts are edges with validity windows; contradictions invalidate rather than delete; every fact traces to source episodes; retrieval is semantic plus BM25 plus graph traversal. The paper reports DMR 94.8% against 93.4% for MemGPT and up to +18.5% on LongMemEval. It needs a graph database and LLM extraction on every write.
A-MEM (NeurIPS 2025): Zettelkasten notes with keywords, tags and links; new notes can rewrite old ones.
HippoRAG 2 (ICML 2025): Personalized PageRank over a knowledge graph, +7% on associative memory over the best embedding model.
LangMem: "hot path" memory tools versus a background manager, on namespaced LangGraph stores.
Generative Agents (2023): memory stream plus reflection. The recency/importance/relevance scoring is in the paper body, not re-verified today.
Cognee: not examined in depth.

File memory in Claude Code (verified).

CLAUDE.md is human-written. Auto-memory is MEMORY.md, with only the first 200 lines or 25 KB injected as an index. Topic files are read on demand. Both survive compaction. Sub-agents do not inherit main auto-memory.
Boris Cherny (2026-02-01): "Early versions of Claude Code used RAG + a local vector db, but we found pretty quickly that agentic search generally works better", and it avoids "security, privacy, staleness, and reliability" issues.
Letta (2025-08): a plain filesystem agent with grep and file search on GPT-4o mini scored 74.0% on LoCoMo, against Mem0's reported 68.5% for its graph variant.

# 3. Learning from experience

Measured gains (verified from abstracts).

Reflexion: 91% pass@1 on HumanEval against 80% for GPT-4.
Voyager: executable skill library, 3.3x more unique items and up to 15.3x faster tech-tree progress.
ExpeL (AAAI-24): insight extraction plus experience recall.
Agent Workflow Memory: +24.6% relative on Mind2Web and +51.1% on WebArena.
Dynamic Cheatsheet (2025-04): GPT-4o on Game of 24 went from 10% to 99%; Claude 3.5 Sonnet's AIME score more than doubled.
ACE (arXiv 2510.04618): +10.6% on agent tasks and +8.6% on finance, using itemised delta updates (generate, reflect, curate) instead of rewriting the playbook.
Anthropic (2026-11-06): Opus 5 on CL-Bench went from 0.564 to 0.828 with memory. Wiki plus search scored 61% against 53% for search alone, saving about 20k tokens per question.

Documented failure modes.

Brevity bias and context collapse (ACE): iterative rewriting erodes detail. Fix: append or patch bullets, never regenerate wholesale.
Error reinforcement (Xiong et al., 2505.16067): agents follow retrieved experiences closely, so stored mistakes propagate, and even correct-looking runs can mislead. Use later task outcomes as free quality labels.
Over-prescriptive write rules (Anthropic): a "record only failures" rule cut memory gains by 0.234 on Opus 5. Tell the agent what memory is for.
Stale state: a 413-file state archive was costlier and worse than 10 files of plans and rules. Store what the environment won't show again.
Poisoning: AgentPoison and MINJA are query-only injection attacks; a secondary summary cites over 95% injection success, which I did not verify. Dash et al. (2606.04329) identify four write channels, nine structural vulnerabilities and six attack classes, and find that agents which write and retrieve more aggressively are more exploitable. They state that current prompt-injection defences do not fully cover this. The channel names (explicit instruction, system-prompt-driven, compaction-driven, experience-to-procedure) come from a search snippet of the full text.
Concurrent-write loss (Anthropic): agents writing one shared table kept 41 of 57 facts; one page per entity kept all 57.

# 4. Retrieval quality and evaluation

Hybrid retrieval.

Anthropic Contextual Retrieval (verified): top-20 retrieval failure fell from 5.7% to 3.7% with contextual embeddings, to 2.9% adding contextual BM25, and to 1.9% with a reranker (−67%).
Postgres options: built-in tsvector/ts_rank is not true BM25. Real BM25 needs ParadeDB pg_search or Tiger Data pg_textsearch. Fuse with reciprocal rank fusion (snippets from vendor blogs).

Embeddings (snippets, mostly vendor or third-party).

Voyage 4 family (2026-01-15) has a shared embedding space across voyage-4-large, -4, -4-lite and the open-weight voyage-4-nano (Apache 2.0, 32k context). Indexing with one and querying with another works without re-indexing.
voyage-code-4 and voyage-context-3 exist at $0.12 and $0.18 per million tokens.
Qwen3-Embedding (0.6B/4B/8B, Apache 2.0, 32k context) is the standard open family. I did not verify MLX availability or throughput.
Third-party comparisons from October 2026 still list text-embedding-3-large/small as OpenAI's embedding models. I found no newer OpenAI embedding model but did not check OpenAI's model page.
Inference: with BM25 plus a reranker in the pipeline, embedding choice is second-order. Evaluate on your own corpus.

Benchmarks and why to distrust them.

LoCoMo conversations are only about 16–26k tokens. In Mem0's own table the full-context baseline (about 73%) beat Mem0 (about 68%). Zep's corrected run scored 75.14%; Mem0's re-run of Zep reportedly gave 58.44% (snippet).
Penfield Labs' audit (2026): 6.4% of the LoCoMo answer key is wrong, and the gpt-4o-mini judge accepted 62.81% of intentionally wrong, topically adjacent answers. A thread on the LoCoMo repo shows grader agreement swinging from 60.8% to 87.9% on identical answers.
LongMemEval (ICLR 2025; 500 questions; about 115k-token histories) is more discriminating: long-context LLMs drop about 30%. A secondary source says Zep's paper reports full context at 60.2% against Zep at 71.2% on GPT-4o.
Vendor 2026 numbers (Mem0: LoCoMo 92.5, LongMemEval 94.4, BEAM-1M 64.1, BEAM-10M 48.6) are self-reported and unreplicated.
MemoryAgentBench (ICLR 2026 per its repo) finds no method masters all four competencies, selective forgetting least of all.
EvoMemBench (NeurIPS 2026) compares 15 memory methods: "long-context baselines remain highly competitive"; memory helps when context is insufficient or tasks are hard.
Inference: below roughly 50–100k tokens of relevant history, load it or grep it. Specialised memory pays off only beyond that, or for cost and latency.

# 5. Operational concerns

Write policy: writers and write triggers are the attack surface (Dash et al.). Untrusted tool output must never write directly to durable memory.
Provenance: Anthropic says to record whether a fact is verified and how. Graphiti links every fact to source episodes.
Versioning and rollback: Letta's answer is git, with a commit per edit, diffs of what the sleep-time agent changed, and revert.
Conflict resolution: invalidate with validity intervals (Zep) rather than LLM-driven deletion (dropped by Mem0).
Concurrency: per-writer worktrees merged back (Letta), and one page per entity instead of shared tables (Anthropic).
Consolidation cost: the Sleep-time Compute paper (2025-04) reports about 5x less test-time compute at equal accuracy and 2.5x lower cost per query when amortised over related queries. Anthropic advises focusing dreaming on information likely to change and tuning its cadence to access frequency. Letta triggers after N steps or on compaction.
Injected layer: keep it small. A wrong injected note propagates into every session, and long instruction files reduce adherence (Anthropic).

# Recommended memory architecture for a from-scratch Agent OS

Everything below is inference from the evidence above.

Principles

The transcript is the source of truth; every memory is a derived, re-buildable view.
Files for what agents read and write; Postgres for what the system indexes and audits.
Append and invalidate, never overwrite or delete.
Small stable injected prefix; everything else just-in-time.
Untrusted content never writes durable memory without a gate.

Layer 0: event log (Postgres, append-only).

runs(id, project_id, agent_id, parent_run_id, task, status, …).
events(id, run_id, seq, ts, role, kind, content jsonb, tokens, trust_level, blob_ref), partitioned by month, with a generated tsvector and GIN index.
Large tool outputs go to a content-addressed blob directory. The context keeps only a preview and the path (restorable compression).

Layer 1: in-run working context (short term).

Order: [tools, fixed and deterministically ordered] → [system] → [injected memory index, snapshotted at run start and frozen] → [append-only messages].
No timestamps or volatile IDs in the prefix. Canonical JSON. Cache breakpoints after system and index, plus a rolling one. 1-hour TTL for long idle gaps.
Gate tools by policy or tool_choice, never by editing the tool list.
Offload any tool result over about 2–4k tokens to a file.
Enable tool-result clearing with clear_at_least and exclude_tools: ["memory"].
Compact at about 50–60% of the window with your own structured, readable summary: goal, constraints and decisions, files touched, verified facts with event IDs, open problems, next steps, and verbatim user instructions, error strings, identifiers and paths. Keep recent turns verbatim.
Use vendor compaction (Anthropic on-demand, OpenAI compact_threshold) as the transport, but always persist your own summary to Layer 0.
Sub-agents get fresh context and return a summary of at most 1–2k tokens plus artefact paths.
Scratchpad files todo.md and notes.md in the run directory, with the todo recited at the tail.

Layer 2: task and project state (medium term, files in git).

Per project: PROGRESS.md, features.json (machine-checked status only), DECISIONS.md, init.sh.
Session protocol: read progress and git log → one unit of work → verify → commit → update progress.

Layer 3: durable memory (long term, markdown in a git repo per scope).

Scopes: global/ (owner preferences, environment facts), project/<id>/, agent/<role>/ (playbooks), and skills/ (procedural memory with progressive disclosure: name and description injected, body on demand).
Each scope has a MEMORY.md index of at most 200 lines, one line per topic file. Only global and current-project indexes are injected.
Topic files carry front matter: type (fact/preference/procedure/lesson), source_event_ids, verified, valid_from, invalid_at, confidence, author_agent.
Expose this through the Anthropic memory-tool interface (and an equivalent function tool for OpenAI), backed by one handler with path canonicalisation, size caps and a secret scrubber.
A Postgres mirror, memory_items(id, scope, path, type, body, valid_from, invalid_at, superseded_by, source_event_ids[], verified, trust, embedding vector, fts), is rebuilt from git by a hook. It is an index, never the authority.

Read path.

Default is agentic: read the index, then grep or open files.
Add one memory_search tool over memory_items and events: BM25 or FTS plus pgvector, fused by reciprocal rank fusion, filtered by scope and invalid_at IS NULL, with a mild recency prior and an optional reranker. Return snippets with paths and provenance.
Contextualise chunks (prepend scope, file and heading) before embedding.
Code is not embedded; agents grep the working tree.

Write path.

Hot path: the agent may write notes freely into its run and project scratch areas.
Writes to global, agent playbooks and skills go to a proposals/ branch or worktree.
A consolidation job per project runs at run end, on compaction, or nightly. It reads new transcripts, verifies proposals against the event log, de-duplicates, marks contradicted items invalid_at with superseded_by, applies ACE-style delta edits to playbooks (add, patch or retire a bullet, with helpful/harmful counters fed by later run outcomes), commits with a message citing event IDs, and merges.
Global and skill changes need owner approval via a diff digest. Project-level changes auto-merge.

Safeguards.

Trust tagging on events (owner > agent reasoning > tool output > web content). Facts derived only from web or tool content are stored verified=false, never promoted to the injected layer or to skills without corroboration or approval, and rendered as quoted data.
Lessons require an outcome signal (test passed, owner confirmed).
git revert is the rollback. A weekly lint checks index size, broken links, stale unverified items and items never retrieved.
Regression evals: your own 30–50 question set per project, with a full-context or grep baseline that must be beaten before any new memory mechanism is added.

Deliberately defer.

Knowledge graph or Graphiti-style entity resolution. Adopt only the bi-temporal columns now; revisit for finance or research entities if multi-hop temporal queries fail the eval.
A-MEM-style auto-rewriting of old notes.
A learned importance score.
Shared cross-agent blackboards.
Fine-tuning from trajectories.
A dedicated vector database.
Embedding the full transcript. Start with FTS only and embed summaries.

# What I could not verify

Whether OpenAI has released an embedding model newer than text-embedding-3.
MLX performance of Qwen3-Embedding and voyage-4-nano.
Attack success rates in MINJA and MPBench.
Zep's LongMemEval per-model figures (secondary source only).
Cognee internals, and details of the OpenAI Conversations API.
BEAM and DolphinBench details beyond vendor descriptions.

# Sources

Chroma, "Context Rot", https://www.trychroma.com/research/context-rot — 2025-07-14
Du et al., "Context Length Alone Hurts LLM Performance Despite Perfect Retrieval", https://arxiv.org/abs/2510.05381 — 2025-10
Anthropic, "Effective context engineering for AI agents", https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents — 2025-09
Anthropic docs, Context editing, https://platform.claude.com/docs/en/build-with-claude/context-editing — fetched 2026-11-10
Anthropic docs, Compaction overview, https://platform.claude.com/docs/en/build-with-claude/compaction — fetched 2026-11-10
Claude Cookbook, "Context engineering: memory, compaction, and tool clearing", https://platform.claude.com/cookbook/tool-use-context-engineering-context-engineering-tools — 2026
Anthropic docs, Memory tool, https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool — fetched 2026-11-10
Anthropic docs, Prompt caching, https://platform.claude.com/docs/en/build-with-claude/prompt-caching — fetched 2026-11-10
Anthropic, "Managing context on the Claude Developer Platform", https://claude.com/blog/context-management — 2025-09-29
OpenAI, Compaction guide, https://developers.openai.com/api/docs/guides/compaction — fetched 2026-11-10
OpenAI, Prompt caching guide, https://developers.openai.com/api/docs/guides/prompt-caching — fetched 2026-11-10
Manus (Y. Ji), "Context Engineering for AI Agents: Lessons from Building Manus", https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus — 2025-07-18
Anthropic, "How we built our multi-agent research system", https://www.anthropic.com/engineering/multi-agent-research-system — 2025-06
Anthropic, "Effective harnesses for long-running agents", https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents — 2025-11-26
Anthropic, "The components of agent memory", https://www.anthropic.com/research/components-of-agent-memory — 2026-11-06
Claude Code docs, "How Claude remembers your project", https://code.claude.com/docs/en/memory — fetched 2026-11-10
B. Cherny, X post on agentic search vs RAG, https://x.com/bcherny/status/2017824286489383315 — 2026-02-01
Sumers et al., CoALA, https://arxiv.org/abs/2309.02427 — 2023-09
Letta, "Benchmarking AI Agent Memory: Is a Filesystem All You Need?", https://www.letta.com/blog/benchmarking-ai-agent-memory — 2025-08
Letta, "Introducing Context Repositories", https://www.letta.com/blog/context-repositories — 2026-02-12; MemFS docs, https://docs.letta.com/concepts/memfs; "Letta's Next Phase", https://www.letta.com/blog/our-next-phase
Lin et al., "Sleep-time Compute", https://arxiv.org/abs/2504.13171 — 2025-04-17
Mem0 paper, https://arxiv.org/abs/2504.19413 — 2025-04-28; migration docs, https://docs.mem0.ai/migration/oss-v2-to-v3; "State of AI Agent Memory 2026", https://mem0.ai/blog/state-of-ai-agent-memory-2026 (vendor)
Zep paper, https://arxiv.org/abs/2501.13956 — 2025-01-20; Graphiti, https://github.com/getzep/graphiti; Zep, "Is Mem0 Really SOTA in Agent Memory?", https://www.getzep.com/blog/lies-damn-lies-statistics-is-mem0-really-sota-in-agent-memory — 2025
A-MEM, https://arxiv.org/abs/2502.12110 — 2025-02 (NeurIPS 2025)
MIRIX, https://arxiv.org/abs/2507.07957 — 2025-07-10
HippoRAG 2, https://arxiv.org/abs/2502.14802 — 2025-02 (ICML 2025)
LangMem, https://langchain-ai.github.io/langmem and https://www.langchain.com/blog/langmem-sdk-launch — 2025
Park et al., Generative Agents, https://arxiv.org/abs/2304.03442 — 2023-04
Reflexion, https://arxiv.org/abs/2303.11366 — 2023-03; Voyager, https://arxiv.org/abs/2305.16291 — 2023-05; ExpeL, https://arxiv.org/abs/2308.10144 — 2023-08; Agent Workflow Memory, https://arxiv.org/abs/2409.07429 — 2024-09
Dynamic Cheatsheet, https://arxiv.org/abs/2504.07952 — 2025-04-10
ACE, https://arxiv.org/abs/2510.04618 — 2025-10
Xiong et al., "How Memory Management Impacts LLM Agents", https://arxiv.org/abs/2505.16067 — 2025-05
Dash et al., "From Untrusted Input to Trusted Memory", https://arxiv.org/abs/2606.04329 — 2026-06
"When Agents Remember Too Much", https://arxiv.org/html/2607.06595v1 — 2026-07 (snippet)
LongMemEval, https://arxiv.org/abs/2410.10813 — 2024-10 (ICLR 2025)
Penfield Labs, "We audited LoCoMo", https://penfieldlabs.substack.com/p/we-audited-locomo-64-of-the-answer — 2026; LoCoMo issue #23, https://github.com/snap-research/locomo/issues/23
MemoryAgentBench, https://arxiv.org/abs/2507.05257 and https://github.com/HUST-AI-HYZ/MemoryAgentBench — 2025-07
EvoMemBench, https://arxiv.org/abs/2605.18421 — 2026-05 (NeurIPS 2026)
Anthropic, "Contextual Retrieval", https://www.anthropic.com/news/contextual-retrieval — 2024-09
Voyage AI, "The Voyage 4 model family", https://blog.voyageai.com/2026/01/15/voyage-4 — 2026-01-15; model list and pricing, https://www.mongodb.com/docs/voyageai/models
Postgres hybrid search: ParadeDB, https://www.paradedb.com/blog/hybrid-search-in-postgresql-the-missing-manual; Tiger Data, https://www.tigerdata.com/blog/elasticsearchs-hybrid-search-now-in-postgres-bm25-vector-rrf (vendor)
Embedding comparisons (secondary): https://www.rapidfire.ai/learn/best-embedding-models-for-rag (2026-10), https://surrealdb.com/blog/embedding-models-comparison

spb agent-os