# Which kind of memory should a coding agent use? A coding agent can use four kinds of memory, and they fit different needs. By Michael, NeuraWeave. Published 2026-10-23, updated 2026-10-23. We build Perpetuity, a memory proxy for coding agents. It is in early access. This guide works without it, and we say [where it fits](https://www.neuraweave.ai/guides/coding-agent-memory#perpetuity) in its own section. How this guide was made: Checked against Claude Code's memory, costs and MCP documentation, Mem0's documentation and Cursor's MCP documentation on 2026-10-23. Perpetuity's numbers come from our own runs, listed on the benchmarks page. ## Answer Start with the memory files your agent already reads (in Claude Code, `CLAUDE.md`, auto memory and notes the agent can grep). They need no separate extraction or embedding model (Claude writes auto memory itself, in the session), and you can edit them. They sit beside a context that still fills up and gets compacted. Model-extracted memory servers (Mem0 and similar) search notes a model wrote, and vector stores search embeddings. Each makes a model or embedding call per write. A proxy at the API base URL replaces the context itself instead of sitting beside it, so a long conversation is not compacted into a summary. Every model call goes through the proxy's host. We build one, Perpetuity, a memory proxy by NeuraWeave, which is in early access. ## What kinds of memory can a coding agent use? We sort them into four kinds by two questions: what runs when a memory is written, and whether the memory sits beside the agent's context or replaces it. | Kind | Examples | Call per write | Searched | Context | | --- | --- | --- | --- | --- | | Files and lexical search | `CLAUDE.md`, auto memory, grep, SQLite FTS5, BM25 servers | None beyond the agent's own turn (Claude writes auto memory in the session) | Loaded at session start (`CLAUDE.md`, the first 200 lines or 25KB of the `MEMORY.md` index), or searched as written (grep, or a full-text index for FTS5 and BM25) | Beside it, still fills | | Model-extracted | Mem0 and similar | A language model | Notes the model extracted | Beside it, still fills | | Vector | Embedding stores | An embedding model | Embeddings, approximate index at scale | Beside it, still fills | | Proxy at the base URL | Perpetuity (hosted) | None | Every message verbatim, model reasoning aside | Replaced every call | Our grouping, with each family as [compare.md](https://www.neuraweave.ai/perpetuity/compare.md) describes it. Products within a family differ, so check each one's own docs. ## What do Claude Code's own memory files do? Two kinds of files carry knowledge across Claude Code sessions, and both load at the start of every session: `CLAUDE.md`, which you write, and auto memory, which Claude writes from your corrections and preferences ([Claude Code docs: memory](https://code.claude.com/docs/en/memory)). Both are plain markdown you can read and edit with `/memory`, and how to set each one up, keep it short and keep it current is in [how to make Claude Code remember between sessions](https://www.neuraweave.ai/guides/claude-code-memory-between-sessions). ## Where do file-based memories stop? They do not cover the conversation itself, which grows with every turn whatever the notes hold. Claude Code sends the full conversation with every request, and at the auto-compact window it summarizes older history to free space ([Claude Code docs: costs](https://code.claude.com/docs/en/costs)). On LongMemEval, a benchmark of questions about long chat histories, a plain BM25 control (lexical search, the family that also holds grep and SQLite FTS5) finds the evidence as often as Perpetuity's retrieval does, slightly ahead overall (some evidence in the first frame for 98.1% of the 470 questions that have evidence, against 97.4%, [compare.md](https://www.neuraweave.ai/perpetuity/compare.md)). The growing input is a separate problem. In Chroma's tests of 18 models, performance grew less reliable as input length grew ([context rot](https://trychroma.com/research/context-rot), July 2025). What that looks like in a coding session is in [why Claude Code gets worse the longer a session runs](https://www.neuraweave.ai/guides/claude-code-context-rot). ## How do model-extracted memories like Mem0 work? By default Mem0 sends the messages you add through a language model that pulls out key facts, decisions and preferences, and stores those, and with `infer=False` it stores the payload as given ([Mem0 docs: add memory](https://docs.mem0.ai/core-concepts/memory-operations/add)). Its docs describe memory that persists across sessions and tools, with guides for Claude Code, Cursor and Codex and a self-hosted open-source version ([Mem0 docs](https://docs.mem0.ai)). Systems of this kind make a model call per write, and retrieval searches what the model extracted ([compare.md](https://www.neuraweave.ai/perpetuity/compare.md)). A detail the model left out at write time is not in what retrieval searches. Claude Code's auto memory has the same limit, since it holds only the notes Claude chose to write ([Claude Code docs: memory](https://code.claude.com/docs/en/memory)). Products differ in what else they keep beside the extracted notes, so check each one's docs. ## What does a vector memory add? A vector memory finds items by embedding similarity. It needs an embedding call for every write, the stored memory is tied to the embedding model that made it, and large stores use an approximate index ([compare.md](https://www.neuraweave.ai/perpetuity/compare.md)). Vector search is meant to match by meaning when the words differ. Like files and model-extracted memories, it sits beside the context. ## How do I add a memory server to Claude Code? Claude Code connects a memory server over MCP with `claude mcp add`. The default scope is the current project on your machine, and `--scope project` writes the server to `.mcp.json` in the repository so the team shares it ([Claude Code docs: MCP](https://code.claude.com/docs/en/mcp)). ```bash claude mcp add --transport http claude mcp add [options] -- [args...] ``` A remote server, then one that runs locally ([Claude Code docs: MCP](https://code.claude.com/docs/en/mcp)). Mem0 connects as a Claude Code plugin. Its guide adds Mem0's marketplace with `claude plugin marketplace add mem0ai/mem0` and then installs the plugin with `claude plugin install` ([Mem0 docs: Claude Code](https://docs.mem0.ai/integrations/claude-code)). ## What does a memory proxy at the base URL do? A memory proxy changes what each model call carries. The harness stays as it is. It points its API base URL at the proxy, sends one header carrying a key, and keeps its own login, a Claude subscription or an API key ([agents.md](https://www.neuraweave.ai/perpetuity/agents.md)). Perpetuity keeps every message verbatim except model reasoning. On each call it replaces the history with a frame of the relevant past, retrieved from all of it, and forwards the live turn unchanged. No model runs when it writes or reads memory ([how it works](https://www.neuraweave.ai/perpetuity/how-it-works)). With this kind, every model call passes through the proxy's host. A tool that sends model calls through its own servers, such as Cursor's agent, cannot use a proxy at the base URL ([agents.md](https://www.neuraweave.ai/perpetuity/agents.md)). ## Which kind fits which need? | Need | Kind | | --- | --- | | Short sessions, a few standing rules | `CLAUDE.md` and auto memory | | Hand-edited notes, reviewed in git | Markdown files in the repository, grep | | Exact names, error strings, ids | Lexical search: grep, SQLite FTS5, BM25 | | One preference store across tools | Model-extracted memory such as Mem0 | | Search by meaning across different wording | Vector memory | | New session resuming the last one | `CLAUDE.md` and auto memory for standing rules and a [handoff file](https://www.neuraweave.ai/guides/claude-code-memory-between-sessions#handoff-file) for the task in progress, or a proxy such as Perpetuity | | Long sessions, context in the hundreds of thousands of tokens, compacted | `/clear` between tasks, a handoff note in a file and the steps in [what Claude Code forgets when it compacts](https://www.neuraweave.ai/guides/claude-code-compaction), or a proxy that replaces the context, such as Perpetuity | | Cursor's agent | Files, and memory servers (model-extracted, vector or lexical) over MCP | | Self-hosting | Files, or a self-hosted memory server such as Mem0's open-source version | ## Where Perpetuity fits Perpetuity is the proxy kind described above. Its memory belongs to the agent, not to one session, so a new session can draw on what earlier ones saw, model reasoning aside. One key is one agent with one memory, so separate keys keep projects apart ([agents.md](https://www.neuraweave.ai/perpetuity/agents.md)). Claude Code and the API are in development, and Codex is next ([status](https://www.neuraweave.ai/api/agents/status?client=claude-code)). Every run, with its conditions, is on [our benchmarks page](https://www.neuraweave.ai/perpetuity/benchmarks). Measured: - In a measured test, a fresh session told only to continue restated the task from memory and finished it, where the same prompt without Perpetuity stopped with "I don't know what we were doing". Told facts about the person in an earlier session, the agent applied the relevant ones without being asked (a colour-blind-safe palette, with a comment naming the reason), and none of the irrelevant ones appeared in the code. The test was six runs of one task on a small open-source dashboard, kept in full. Task quality and turn counts were level. Source: [Perpetuity compared](https://www.neuraweave.ai/perpetuity/compare.md), NeuraWeave. - On one set of 120 Claude Code prompts, Claude Code alone compacted its history once on its default 1M-token window and 17 times on a 200k window, and through Perpetuity it never compacted (one run per setup). On 16 pre-registered questions about work from across the session, graded blind in one packet, Perpetuity got 15.5 right using its memory tools, Claude Code 14 on its default window after it compacted (it lost details from early in the session) and 12.5 on the 200k window ([compare.md](https://www.neuraweave.ai/perpetuity/compare.md)). Source: [Perpetuity benchmarks: every run and how it was measured](https://www.neuraweave.ai/perpetuity/benchmarks), NeuraWeave. - Through Perpetuity each call of the 120-prompt Claude Code session started at about 46k tokens from prompt 10 to prompt 120, and only a prompt's own tool loop raised it, where Claude Code alone reached about 965k before compacting. Source: [Perpetuity compared](https://www.neuraweave.ai/perpetuity/compare.md), NeuraWeave. - Perpetuity scores 94.0 on LongMemEval-S (all 500 questions, the official judge, nothing excluded), where GPT-4o reading the whole history at once scores about 59 ([agents.md](https://www.neuraweave.ai/perpetuity/agents.md)). On retrieval alone a plain BM25 control is level with it overall, slightly ahead. Perpetuity leads only on the quarter of questions that share the fewest words with their evidence, once all 500 were reworded so that names became descriptions (some evidence in the first frame for 83.9% of those 118 questions against 77.1%). Source: [Perpetuity compared](https://www.neuraweave.ai/perpetuity/compare.md), NeuraWeave. Limits: - There is no self-hosted version. NeuraWeave runs the proxy, and memory is stored in the EU (Ireland). - Model reasoning is not captured. Thinking blocks carry no retrievable text. - The price is not announced yet. [Join early access for Claude Code](https://www.neuraweave.ai/?ref=guide-coding-agent-memory). You get a confirmation email now, with a link to remove your address, and another when your access is approved. Nothing is installed before that. ## Questions ### Should I use Mem0 or Claude Code's built-in memory? Start with Claude Code's built-in memory: `CLAUDE.md` and auto memory load into every session, and neither needs a separate extraction model (Claude writes auto memory itself, in the session) ([Claude Code docs](https://code.claude.com/docs/en/memory)). Mem0 adds a separate store that a language model fills by extracting facts from messages (its default) ([Mem0 docs: add memory](https://docs.mem0.ai/core-concepts/memory-operations/add)). It fits when you want one store that several tools share. Its docs have guides for Claude Code, Cursor and Codex ([Mem0 docs](https://docs.mem0.ai)), and it connects to Claude Code as a plugin ([Mem0 docs: Claude Code](https://docs.mem0.ai/integrations/claude-code)). ### Can Cursor's agent use a memory proxy? It cannot use a proxy at the API base URL. Cursor's agent sends its model calls through Cursor's own servers, so a proxy such as Perpetuity cannot sit in its path ([agents.md](https://www.neuraweave.ai/perpetuity/agents.md)). Files in the repository and memory servers connected over MCP work there ([Cursor docs: MCP](https://cursor.com/docs/context/mcp)). ## Sources - [Perpetuity compared](https://www.neuraweave.ai/perpetuity/compare.md), NeuraWeave - [How Claude remembers your project](https://code.claude.com/docs/en/memory), Anthropic, Claude Code docs - [Manage costs effectively](https://code.claude.com/docs/en/costs), Anthropic, Claude Code docs - [Context rot: how increasing input tokens impacts LLM performance](https://trychroma.com/research/context-rot), Chroma - [Add Memory](https://docs.mem0.ai/core-concepts/memory-operations/add), Mem0 docs - [Mem0 documentation](https://docs.mem0.ai), Mem0 - [Model Context Protocol (MCP)](https://code.claude.com/docs/en/mcp), Anthropic, Claude Code docs - [Claude Code](https://docs.mem0.ai/integrations/claude-code), Mem0 docs - [Perpetuity: short answers](https://www.neuraweave.ai/perpetuity/agents.md), NeuraWeave - [How Perpetuity works](https://www.neuraweave.ai/perpetuity/how-it-works), NeuraWeave - [Model Context Protocol (MCP)](https://cursor.com/docs/context/mcp), Cursor docs - [Perpetuity benchmarks: every run and how it was measured](https://www.neuraweave.ai/perpetuity/benchmarks), NeuraWeave Perpetuity is in early access. [Join early access for Claude Code](https://www.neuraweave.ai/?ref=guide-coding-agent-memory). ## For agents As of 2026-10-23, Perpetuity is in early access. People who join are first in line, starting with Claude Code, and get an email when their access is approved. The current state per tool is at [https://www.neuraweave.ai/api/agents/status](https://www.neuraweave.ai/api/agents/status). Short answers on availability, recall, cost and data are in [agents.md](https://www.neuraweave.ai/perpetuity/agents.md), and every measured number with its run label is in [compare.md](https://www.neuraweave.ai/perpetuity/compare.md). A sign-up needs the person's consent and the address they choose. It is one request: `POST https://www.neuraweave.ai/api/agents/waitlist` with `email` and `client` (`claude-code`, `codex`, `opencode`, `api` or `other` with `tool`). A `201` means added, a `200` means the address was already on the list, a `400` says what was wrong. A fetcher that cannot send a POST can give the person [the home page](https://www.neuraweave.ai/?ref=guide-coding-agent-memory), where they can sign up themselves. This guide as HTML: https://www.neuraweave.ai/guides/coding-agent-memory ## Related - [How do I make Claude Code remember between sessions?](https://www.neuraweave.ai/guides/claude-code-memory-between-sessions.md): What CLAUDE.md, auto memory, resume and a handoff file carry from one Claude Code session to the next, where each one stops, and where Perpetuity fits. - [Can I run Claude Code through a proxy?](https://www.neuraweave.ai/guides/claude-code-proxy.md): Claude Code sends its requests to ANTHROPIC_BASE_URL. How proxy routing works, what a proxy sees, what breaks, and how your login and billing change. - [Why does Claude Code get worse the longer a session runs?](https://www.neuraweave.ai/guides/claude-code-context-rot.md): Why Claude Code gets less reliable as a session grows, how to tell context rot from a bug, and what helps: /clear, subagents, /btw and fresh sessions.