Persistent memory for Claude Code and Codex: your options

Claude Code and Codex both start a new session with an empty context window. A session is one saved conversation; the context window is the working text the model can see at once. Whatever the last session learned, decided or tried is gone unless something outside that window carries it. The options differ on four things: who writes the memory, where it lives, which tools can read it, and whether a person can correct it.

Checked against each tool's documentation on 26–27 October 2026.

The short answer#

• One agent, one machine, one project. Write a short CLAUDE.md for Claude Code or AGENTS.md for Codex. It loads without a tool call.
• One agent, many sessions on one machine. Add auto memory: Claude Code's own notes, written by the model and stored on that machine; Codex has local memories, off by default.
• GitHub Copilot CLI on several machines. Nothing local to sync: Copilot Memory follows the account. Keep rules that must always apply in AGENTS.md.
• Cursor, a standing preference. No memory store in the editor or CLI; put it in AGENTS.md or User Rules.
• Two agents, or two machines. Use a file both tools read, or a memory server both can reach.
• A person must review what the agent wrote. Use a store with a correction separate from the text, or build a review habit around the file.

Instruction files are not memory#

An instruction file is text saved where an agent looks at startup. CLAUDE.md and AGENTS.md are that kind of file. They are the right place for standing rules: the test command, the package manager, the folder layout. They are a poor log: every line costs context.

The same filename is not one behaviour across agents. The vendor comparison covers Codex, Cursor, Gemini CLI, Copilot and Devin, and the limits each vendor documents. This page covers the tools with a documented memory store — Claude Code, Codex, Gemini CLI, Qwen Code and, in public preview, Copilot CLI — plus OpenCode, and Cursor's editor and CLI, which have none.

How CLAUDE.md and rules load#

Claude Code loads CLAUDE.md from the working directory and every directory above it, root down; CLAUDE.local.md follows CLAUDE.md in the same directory. A nested CLAUDE.md or a rule with a paths: field loads on demand, when Claude touches a matching file. AGENTS.md is read only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md is in the working directory or above it, on v2.1.277 or later. The docs say a Bash cat or head counts as a read; the measured trigger is narrower. As of 26 October 2026 the two reports behind that are open (#90450, #88565). A mid-session edit to a root CLAUDE.md waits for /clear, /compact or a restart.

Mid-session edits and the "loaded, specific, conflicting, hard rule" ladder are in Why your nested CLAUDE.md or path-scoped rule never loaded. For where auto memory lives, what the 200-line/25KB index loads, and how to check it, see Claude Code auto memory.

Built-in memory: one is per repository, one is per Codex home#

Both agents keep notes of their own. Claude Code auto memory is on by default in local sessions; Codex memories are off by default. Both are per-tool and local to that tool's home, both are written by a model, and the other agent does not see them. They differ on the boundary that matters when you switch projects.

Claude Code keys auto memory to the git repository, so every worktree and subdirectory of one repository shares one directory, and another repository gets another. The Codex memories page describes one local store under the Codex home, with summaries, durable entries, recent inputs and supporting evidence. It does not divide that store by repository. A memory learned in one repository can therefore be injected into a chat in another. That is why the advice differs: put required project rules in AGENTS.md, and treat Codex memories as recall that may cross a boundary you did not draw. The scope guide has the isolation options.

"Enabled" is not one switch. In the Codex TUI or the ChatGPT desktop app, /memories has two per-chat decisions: may this chat read existing memories, and may it contribute to future ones. The feature flag and the desktop setting turn the store on; the chat controls decide what this chat does with it. Generation runs in the background and can be skipped when your remaining rate limit is low, so "it did not remember" is often "the background pass has not run yet." The docs also say Codex redacts secrets from generated memory fields, and still tell you not to store secrets and to review the files before sharing a Codex home directory.

For the checks, see how to check what your agent remembered. For a wrong memory, see how to correct it. For the file layout and the truncated summary, see how agents find things in memory. For the model calls behind generation, see memory without extra LLM calls.

Gemini CLI: the context file is the memory#

Run gemini --version first; this section describes v0.65.0 (20 October 2026). Gemini CLI has no memory database either. Its /memory command is a viewer and reloader for the context files the CLI puts in the prompt at startup; when the agent saves a fact, it edits one of those Markdown files with its normal write tools. The docs describe four places: GEMINI.md in the repository (shared and committed), a GEMINI.md in a subdirectory, a private per-project MEMORY.md index under ~/.gemini/tmp/<project>/memory/, and the global ~/.gemini/GEMINI.md, which loads in every project on the machine.

The private index is the part that surprises people. The agent can keep a short fact in MEMORY.md and a longer procedure in a sibling note; only MEMORY.md is loaded, and the sibling is read only if the index points at it. /memory show prints the concatenated text under the labels Global, Private Project Memory, Extension and Project. /memory list prints the paths. Neither command calls a model.

Auto Memory is separate and experimental. It is off by default; when experimental.autoMemory is on, a background pass mines old session transcripts and writes candidate patches under the project memory folder's .inbox, which you review with /memory inbox. Nothing is applied without approval, and it does not touch the repository GEMINI.md.

/memory add and the old save_memory tool are gone in this version, so a tutorial that tells you to use them is stale.

The check, correction and scope steps are in what the memory command shows in Gemini CLI.

Qwen Code: two instruction files and a model-written store#

Qwen Code keeps two instruction files and a model-written store — closer to Claude Code's memory model than to Gemini CLI's, despite the fork. It reads GEMINI.md only if you add it to context.fileName, and the Qwen memory docs describe the system as of Qwen Code 0.26.2 (27 October 2026).

QWEN.md is the instruction file you write, at three levels: ~/.qwen/QWEN.md for every project on the machine, a repository QWEN.md for the team, and .qwen/QWEN.local.md for you in one repository. AGENTS.md is a second default name, not an opt-in. The source sets the default list to QWEN.md and AGENTS.md, and context.fileName replaces that list rather than adding to it (memory constants). Discovery is the global file plus an upward walk from the working directory to the git root, so a QWEN.md in packages/api is not found unless you start there. The instruction-loading guide has the order and the checks.

Auto-memory is on by default and closer to Claude Code's than to Codex's. Qwen writes it, not you, under ~/.qwen/projects/<project>/memory/, with MEMORY.md as the index (200 lines and 25,000 UTF-16 code units) and one topic file per memory. There is also a user tier at ~/.qwen/memories/ for cross-project facts, and an opt-in team tier at .qwen/team-memory/ that is committed to the repository. Project memory is keyed to the git root, but each linked worktree gets its own folder, so a fact learned in one worktree is not in the next.

Four commands matter. /memory opens a panel with the auto-memory and cleanup switches and entries that open the user and project memory folders when managed auto-memory is on (the default); with it off, they open the two QWEN.md files. /remember <text> asks the model to save a fact, and the model chooses the user or project tier (or team, when it is enabled). /forget <text> removes matching entries from the user and project tiers. /dream runs consolidation. An older /memory show is not a subcommand in the current CLI; it returns a usage error.

For the checks, see how to check what your agent remembered. For the Qwen-specific routes, see the Qwen Code guides.

Copilot CLI remembers, but the store is on GitHub#

GitHub Copilot CLI has a memory feature, and it is a different shape from the file-based tools above. Copilot Memory is a GitHub-side store in public preview. It holds repository-level facts — conventions, build commands, architectural decisions — and user-level preferences. It is not a folder under ~/.copilot, and there is no memory file to open.

Copilot Memory is enabled per account, not per repository. On a paid individual plan it is on by default; on an organization- or enterprise-managed plan an administrator has to enable it first, and users can then opt out. When it is on, it applies in every repository where you use a supported Copilot feature. A repository fact is available to everyone with access to Copilot Memory in that repository; a user preference stays with the user.

The CLI's /memory show command reports the status, and the documentation links since 1.0.51. The facts themselves are in GitHub: repository Settings → Copilot → Memory for repository facts, and your personal Copilot settings → Memory for your preferences. /memory on and /memory off change the CLI switch; they do not delete what is already stored. Deleting is the GitHub action.

Two limits matter when you choose it. Only the root agent can store or vote on a memory; a subagent — a separate agent the main session starts, with its own context — can read memories but cannot write them. And in prompt mode (copilot -p) memory is off by default; --enable-memory turns it on. Repository facts are stored with citations and re-checked against the current branch before use, and an unused fact or preference is deleted after 28 days.

That makes Copilot Memory a recall layer for Copilot, not a rulebook and not a shared store for other agents. A convention that must always apply belongs in AGENTS.md or .github/copilot-instructions.md, where it loads as instruction text. A fact for Claude Code or Codex has to go somewhere they read. Status, 27 October 2026: a report says memories can appear in a similarly named repository (#3945, open, 26 June 2026); the docs say repository facts are used only in operations on the same repository.

Run copilot --version before relying on a command: /memory arrived in 1.0.49; /memory show gained the documentation links in 1.0.51, and the current release is 1.0.104 (27 October 2026).

OpenCode does not document a built-in memory store#

OpenCode does not document a built-in memory store. The V1 and V2 documentation checked on 27 October 2026 list no memory page, no memory setting in the configuration schema, and no memory command. Requests for native memory have been closed as not planned (#8043, #16077, #20322).

That is not a gap you can switch on. The replacements are the shapes above:

• AGENTS.md and instructions for durable rules. V2 loads the global AGENTS.md, then repository ancestors nearest-first, then the paths in instructions. V1 loads the global file and repository files, and falls back to CLAUDE.md when no AGENTS.md is on the path. These are instructions, not a log: every line costs context in every session. The OpenCode AGENTS.md guide covers the difference and the check.
• A handoff file for task state. Keep it in the repository and put a pointer in AGENTS.md. In V2, you can also add its path to instructions so it loads at startup and is treated as the current baseline after compaction. The handoff guide has the fields.
• A plugin or MCP server if you accept the extra moving part. A plugin is code that runs inside OpenCode; an MCP server is a separate process or service the agent calls. Either can add a memory-like tool, but neither is memory by default, and you still have to tell the agent to use it. The plugin and MCP pages are the starting points.

OpenCode saves sessions locally, so you can resume a conversation or export it (opencode session export in V2, opencode export in V1). That is a transcript, not memory: the next session does not inherit the context unless a file or a tool puts it there. The session guide covers where the transcript lives.

Cursor's editor and CLI have no current memory store#

Cursor's editor and CLI have no memory store today. The old Memories feature was retired in Cursor 2.1: a Cursor staff reply in the memories cleanup thread (7 January 2026) said the UI was removed starting in 2.1.x, and that stored memories could still be injected without a UI. The Agent SDK and Grok Bot are separate surfaces with their own memory; neither is the editor's.

Old data can outlive the feature. An open report on Cursor 3.24.12 says account rules from older versions can still be injected into every chat while Customize → Rules leaves them out. A staff reply on 26 October 2026 said this is most likely on accounts that used the old Memories feature and suggested opening a new window with no folder, then checking Customize → Rules; if the rules appear there, delete them (#174724). Try that before assuming a new memory feature is at work.

What Cursor does have is instruction text: AGENTS.md, a project rule, or User Rules in Customize → Rules. Chat history is a transcript, not memory; a new chat does not inherit it. The Cursor AGENTS.md guide covers what loads, and the rules guide covers which rule is running.

MCP memory servers#

MCP (Model Context Protocol) is a way for an agent to call tools on another server. It is not a store. A server exposes tools, and the agent chooses when to call them. A memory server does not load itself: you need a line in CLAUDE.md or AGENTS.md, or a session-start hook. ai-memory is the automatic, self-hosted option; Noteheld is the hosted, deliberate-note option. Both speak MCP and HTTP.

ai-memory, from our test#

ai-memory is an open-source, MIT-licensed memory server by Fabio Akita. One Rust binary serves MCP and HTTP. Hooks capture prompts, tool calls and session boundaries, then turn them into pages in a git-backed markdown wiki. The default path makes zero LLM calls, and one server can serve more than twenty harnesses.

We tested v3.2.5 in a sandbox with no LLM provider or API keys. We fed hand-written Claude Code and Codex hook events to the shipped scripts and made real MCP calls. No real session was run, so trust prompts and timeouts were not exercised.

• The default startup packet was empty. With no pending handoff and no [briefing] opt-in, a Codex SessionStart produced no output. The agent had to call memory_briefing, or memory_query and memory_read_page.
• An explicit handoff did arrive. A handoff from a Claude Code-shaped session printed at the next Codex SessionStart, and was consumed once. Status, 26 October 2026: #959 is closed. The default still claims. Set [handoff] claim_on_session_start = false in config.toml to show the handoff id instead of consuming it, then accept it explicitly. Our v3.2.5 test used the default and did not exercise the setting.
• A person's flag did not change the next read. memory_feedback with signal: wrong recorded a page-level flag and routed it to lint; a fresh query still got the old snippet. Editing the markdown worked: the watcher reindexed it, and the correction appeared in the body and search results. The title stayed wrong, and the opt-in brief listed titles only.
• Attribution was anonymous by default. Pages said generated.by: process:ai-memory/3.2.5, audit rows had author_id: None, and doctor said identity: anonymous (root). Setting [auth].root_username or creating users and API keys adds names.

Where ai-memory is better: automatic capture, a handoff across tools, one server for several machines, self-hosting, a team server with grants, and a markdown wiki you can grep or restore. Costs: a server to run, hooks to debug, provider choices, a manual correction loop.

Noteheld, from the same test#

Noteheld is the hosted notes service this site documents. It is not an automatic memory tool. An agent writes a note deliberately, with a summary (or a derived one) and a reason. The next agent can call overview for a map, then read the note by path. Every revision records the key's label, the time and the reason.

The workspace owner — a person signed in, or the master key — can add a correction above the note, on the whole note or a line range. Open corrections print before the note lines, and the overview lists them. The agent changes the note, then resolves the correction.

Noteheld does not record prompts or tool calls, and it has no hooks. Nothing loads for free: an agent needs a key and must ask. Notes are stored as plaintext; version 1 does not encrypt note bodies end to end. A folder key limits what a compromised agent can touch inside Noteheld, not tools elsewhere. A correction is still stored data, and a note can still steer an agent that reads it. There is no handoff tool.

Use it for a small curated record, where a person must correct a line and the next agent must see it first. The cost: somebody writes the notes, and the agent must be told to read them.

Which one fits#

Start small. Add a shared store when a second agent, machine or person needs the facts.

The guides#

• Hand off work between Claude Code and Codex — what to write and where.
• How to check what your coding agent actually remembered — capture, load and use.
• How to correct wrong or stale agent memory — fix the line and the index.
• Keep agent memory in the right project, machine or team — scope and who can read what.
• What agent memory tools capture, and how to keep secrets out — capture, sanitizers, private-repo checklist.
• Sync agent memory and project progress across machines and agents — machines, CI, backup and restore.
• How agents find things in memory — startup context, search and recall.
• Agent memory without extra LLM calls — what a summarizing model costs.

For Codex setup outside memory — AGENTS.md loading, config, sessions, approvals, hooks, undo — see the Codex guides. For OpenCode, the OpenCode guides cover instruction loading, sessions, permissions and the rest. For Gemini CLI outside memory — what loads at startup, sessions, permissions, hooks — see the Gemini CLI guides. For Qwen Code — instruction loading, permissions, sessions, local models, MCP, skills — see the Qwen Code guides. For Cursor — instruction loading, rules, skills, chat history, permissions, hooks and MCP — see the Cursor guides.