Skip to content

Knowledge base

Persistent agent memory

Persistent agent memory is state an agent writes outside its context window and reads back in a later session, as notes, memory files or knowledge graphs. The hard part is forgetting: memory that only grows ends up holding nothing useful.

Written by

Updated:

Agentic Engineering 5

Our position. We keep state out of the conversation: plans, progress and research live in files, and the external plan is the source of truth (opens in a new tab). A fix ships with its rule update in the same commit, because an incident is the cheapest moment (opens in a new tab) to write to the factory’s memory.

Beyond a notes file, richer forms add temporal knowledge graphs, stored reasoning traces and a human approval step before anything reaches the memory file.

How does an agent remember beyond one session?

Agents are stateless by default; memory has to be engineered in. The common taxonomy splits short-term memory, the context window itself, rebuilt on every call, from long-term memory in external stores, which specializes into semantic memory (facts: “user prefers Python”), episodic memory (past events, effectively real few-shot examples), and procedural memory (learned rules about how to perform tasks). Writes happen either explicitly in the interaction flow (immediate but adds latency and mixes memory logic into agent logic) or implicitly via background processes (no user-facing latency, but briefly stale). The hard problems are retrieval relevance, memory bloat (an agent that remembers everything eventually remembers nothing useful), and forgetting, designing eviction that discards noise without deleting crucial context, all made harder by the delayed feedback loop: a flawed memory strategy only surfaces over time (Memory in Agents, Make LLMs remember (opens in a new tab)).

What to store as episodic memory is not symmetric: feeding an agent its past failures helps it break out of local minima, while feeding it past successes tends to make it lazy, it pattern-matches the earlier answer and parrots it back instead of reasoning afresh (Chroma - Context Engineering for Engineers (opens in a new tab)), the same logic behind keeping failed actions in the live context rather than scrubbing them.

The simplest robust pattern is structured note-taking: the agent regularly writes notes outside the context window and pulls them back in later, whether a todo list or a NOTES.md, maintaining progress and dependencies across dozens of tool calls and surviving context resets; Anthropic ships this as a file-based memory tool, and its Pokémon-playing agent demonstrates multi-hour coherence purely from self-written notes (Anthropic - Effective Context Engineering for AI Agents (opens in a new tab)). Hook-based context bundles extend this to session replay: an append-only log of tool calls, trimmed to essential reads and writes, restores roughly 60-70% of a previous agent’s understanding in a fresh window (Elite Context Engineering with Claude Code (opens in a new tab), 8 September 2025).

Widely-copied harness prompts hard-code the pattern, persisting user preferences to a fixed memory file the agent creates and re-reads on every task (Beast Mode (opens in a new tab)). Procedural memory can also be weighted by outcome: a review agent raises the weight of suggestions humans accept and lowers those they ignore, so a fix rejected ten times stops surfacing (Qodo - Why More Context Makes Your Agent Dumber (opens in a new tab)).

For richer state than notes, the frontier is structured and temporal. Zep’s argument from production deployments: “agent memory” as facts extracted from chat history covers a fraction of what an organization knows about a user across touchpoints, so they model memory as temporal knowledge graphs that capture not just what is true but what was true when and how it changed. The engineering cost is real: entity resolution on messy data (“Netflix” vs “netflix” as distinct entities, or two references to a parent that resolve to different people) required reflection mechanisms and extensive pipeline work to reach production reliability (Zep - What is Context Engineering, Anyway? (opens in a new tab)). Zep also cautions that sub-agents working from fragmented context produce incoherent results (Cognition’s Flappy Bird example, where independently briefed agents built mismatched pieces), so context must be shared, or the task should not be split at all (Zep - What is Context Engineering, Anyway? (opens in a new tab)).

Production consumer memory does not have to mean a vector database. A reverse-engineering of ChatGPT’s memory (inferred from behavior, not official) describes no RAG over conversation history at all, but layered stores: durable user facts written only when the user says “remember this” or the model detects a qualifying fact, cross-chat continuity served by precomputed lightweight digests of the user’s own messages rather than retrieval, and an ephemeral per-session metadata layer (device, timezone, plan) that never persists, with the live window rolling off by token count rather than message count (I Reverse Engineered ChatGPT’s Memory System (opens in a new tab)). For teams that do want the graph, Zep and Cognee package the pattern as ingest-to-graph-to-query services adoptable without building the pipeline, Cognee framing its store as an auto-extracted ontology or world model over an organization’s data (Wizard of Graph – Graph RAG talk (opens in a new tab); Cognee (opens in a new tab), vendor).

Two directions push memory past notes and facts. Because coding agents turn over fast, some practitioners keep instructions in a portable store, an MCP knowledge graph, rather than any one tool’s config, so switching agents does not lose learned behavior, and a single phrase such as “we are done” expands into a memorized multi-step release chain replayed at the start of each session (DevOps Toolkit - agent memory MCP workflow (opens in a new tab)). And where memory has held only facts, context graphs are being extended to hold the reasoning, policies, rules, and past decisions with their rationale, split across short-term, long-term, and a distinct reasoning tier, so an agent can weigh a choice against precedent and its cost of being wrong, one agent proposing options with pros and cons while a second decides whether it has authority to act or must escalate, writing the outcome back as precedent (Neo4j - Context Graphs for Agentic Decision-Making (opens in a new tab)).

The talk orders that decision into five stages under human oversight. Framing states the objective, the causal picture and what is at stake in the environment. Guidance pulls precedent and rules. Assessment weighs risk against value, reversibility and the cost of an error, and produces the proposal. Action runs the authority check by the second agent, which acts or escalates. Outcome records what was considered and what was not, so the record serves as precedent for the next decision (Neo4j - Context Graphs for Agentic Decision-Making (opens in a new tab)). Neo4j Labs publishes the three tiers as an Apache-2.0 library, neo4j-agent-memory. Short-term memory keeps conversations as ordered, searchable messages per session. Long-term memory keeps typed entities, facts and preferences as a graph that grows across sessions. Reasoning memory keeps traces of thoughts, tool calls with their arguments and results, and whether each path succeeded, so the agent can search for a similar past problem before solving a new one (Neo4j Labs - Understanding the three memory types (opens in a new tab), as of September 2026). Long-term memory is queried by graph traversal and semantic search, and one call, get_context(), assembles the stored memory into combined context for a prompt (neo4j-labs - agent-memory (opens in a new tab), as of September 2026).

An open-source agent product puts a human approval between the model and the memory file. In exxperts, built on a fork of pi, a room’s memory grows in three steps. Remember proposes a summary at the end of a conversation, Memorize folds the waiting conversations into notes, and Review tidies the notes topic by topic. The workers behind each step are tool-less model processes that can only propose a short list of changes. The person approves the proposal, and only the approval endpoint writes the memory file (EXXETA - exxperts memory documentation (opens in a new tab), version 0.14.1, October 2026). The stated goal is memory that gets denser, not merely larger: a new point updates or supersedes the note that already holds it, and a Review edit whose text outgrows what it replaced is rejected. Memorize and Review never delete a note. A note that leaves memory moves to an archive with the reason it left (EXXETA - How exxperts works (opens in a new tab), version 0.14.1). A per-room budget, 20,000 estimated tokens by default, decides which notes move there, and pinned notes and open items stay (EXXETA - exxperts memory documentation (opens in a new tab)).

Recall in that product is keyword search over the notes, the archive and the transcripts of memorized conversations, ranked with BM25. Words are folded before indexing so German and English spellings meet: “Überweisung” finds “Ueberweisung”, “1.6.2026” finds “2026-06-01”, and “55.000” finds “55,000” (EXXETA - exxperts memory search index (opens in a new tab)). The project leaves out search by meaning on purpose. Embeddings would need a second model or a downloaded index and cost tokens or disk on every save, and their misses are harder to explain than a word that was not there. The room is told to search again in other words before it says it does not know (EXXETA - exxperts memory documentation (opens in a new tab)).

The project measured the design on LongMemEval-S, a public benchmark of long chat histories, using a fixed sample of 50 questions. Each question comes with about 48 conversations and 115,000 tokens of history. Room memory answered 43 correctly, and the same model with the whole history pasted into the prompt answered 41. Room memory used about 33,000 tokens per question against about 168,000, after a one-time build of about 1.15 million tokens per history. Claude Sonnet 5 answered, memorized and judged. The project states the limits itself: at 50 questions, 43 against 41 is a tie, and the sample was also the one used during development. The same model answers and judges, and the benchmark is personal chat with a scripted user rather than project work (EXXETA - exxperts memory documentation (opens in a new tab), project self-claims, as of October 2026).

Memory files decay, and the agent does not clean them. One practitioner catalog lists the forms: the same fact recorded several times in different words, two entries that contradict each other, vague entries, and rules about a library removed months ago. Rule files and memory files overlap, so the same fact can sit in both, and the catalog grooms them together. The routine merges duplicates, decides each contradiction and deletes the loser. An obsolete entry is deleted without an archive once git history or an ADR records the decision, because an archive nobody maintains gets pulled back into context later. A contradiction between two files is acceptable where each file states its scope, as frontend and backend testing notes may (Augmented Coding Patterns - Memory Grooming (opens in a new tab)). The capture side has a ritual of its own. At the end of a session the agent lists what the session taught and proposes a destination for each item: a behaviour rule goes to the always-loaded rules, a project fact to a reference document, a recurring quality correction to a hook, a repeated process to a skill. The person approves the routing (Augmented Coding Patterns - Learning Loop (opens in a new tab)).

Resources

Governed memory

Memory libraries