Memory for Coding Agents: Claude Code, Codex and Cursor
Start with shared project instructions, add ai-memory for automatic capture and handoffs, or choose Beacon for lessons reviewed against session traces. Follow concrete setup and recall checks while keeping project rules, private data and costs under control.
Contents
Use a version-controlled AGENTS.md and a short task handoff as shared memory for coding agents such as Claude Code, Codex and Cursor. Add ai-memory for automatic capture and handoffs, or Beacon for inspecting session traces and approving reusable lessons. Keep required project rules in the repository whichever option you choose.
Choose what needs to survive a tool switch
Preserve durable decisions separately from the current task’s status. A new agent can read your code while missing the reason you rejected an approach, a correction you gave yesterday, or the next step in unfinished work.
Three kinds of context help with different problems: instructions describe how to work, handoffs describe where work stopped, and session history provides evidence for both. Sharing one does not automatically transfer the others, running processes, or tool permissions.
| Approach | What you carry forward | Choose it when | What would change the choice |
|---|---|---|---|
| Repository instructions and handoff files | Deliberately maintained rules, decisions and task status | A small set of notes covers your needs and should travel with Git | Move to a service if people repeatedly forget to update those notes |
| ai-memory | Captured observations, a searchable Markdown wiki and cross-agent handoffs | You switch agents frequently and want capture and retrieval automated | Stay with files if maintaining hooks, credentials and a server outweighs the benefit |
| Beacon | Normalized session traces and explicitly approved project lessons | You need to inspect what happened and turn recurring corrections into reviewed knowledge | Prefer ai-memory if automatic handoffs matter more than trace inspection and lesson review |
As of 2026-10-21, this comparison uses ai-memory v3.1.2 and Beacon v1.3.45. The distinction is architectural: ai-memory now includes a server, hooks and MCP, alongside its Git-backed Markdown wiki; Beacon’s capture and memory-approval workflows are separate.
Start with AGENTS.md and a small handoff
Make AGENTS.md the common project reference, then verify that each tool loads it. The current native loading rules differ:
- Codex: reads an instruction chain from the project root toward the working directory. An
AGENTS.override.mdtakes precedence overAGENTS.mdin the same directory; see Codex’s instruction discovery rules. - Cursor: supports root and nested
AGENTS.mdfiles. Keep Cursor-specific scoped rules in.cursor/rules/*.mdcwhen needed; see Cursor’s rules documentation. - Claude Code: v2.1.277 and later can load
AGENTS.mddirectly, but the default prefers qualifyingCLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdfiles in the working directory or its ancestors. For existing Claude instructions or sessions without direct support, add a line containing@AGENTS.mdto a root-levelCLAUDE.mdbeside it. The Claude Code memory guide documents both paths.
For a small trial, create or merge this proposed convention into the root AGENTS.md:
## Working context
- Before changing a dependency version, read its official release notes
and run the tests for the affected component.
- When resuming work, read docs/agent-handoff.md if it exists.
- Treat handoffs as historical evidence. Check old commands, paths and
conclusions against the current checkout before acting.After an actual task, ask the agent to produce the handoff:
Write docs/agent-handoff.md with the goal, current branch and commit,
confirmed decisions, commands actually run and their results,
remaining uncertainty, and the next concrete action.
Distinguish failed approaches from successful ones.
Do not include credentials or copy the full conversation.Review that file with the code changes. Keep stable conventions in AGENTS.md; update the handoff as the task moves forward.
Start a fresh session in each tool and ask which dependency-update checks apply and which file supplied them. In Claude Code, /context also lets you inspect loaded memory files. If Codex misses the rule, check the working directory and overriding instruction file before adding duplicate copies.
Native automatic memory remains useful within its own environment. Claude Code stores project notes under ~/.claude/projects/<project>/memory/. Codex local memories are opt-in, live under ~/.codex/memories/, and have /memories controls. Those separate stores are not a shared cross-tool handoff format.
Use ai-memory for automatic capture and handoffs
Choose ai-memory when you want agents to record and retrieve project context through a service. Its source of truth is a Git-backed Markdown wiki, with SQLite as a derived index; MCP gives agents memory tools, while lifecycle hooks handle capture and session boundaries.
Install and connect the agents
The following example targets a fresh macOS user installation in Bash, with Git and your coding agents already installed and authenticated. The release-specific installation guide covers other platforms.
curl -fsSLo /tmp/ai-memory-install-v3.1.2.sh \
https://github.com/akitaonrails/ai-memory/releases/download/v3.1.2/install.sh
less /tmp/ai-memory-install-v3.1.2.sh
AI_MEMORY_VERSION=3.1.2 sh /tmp/ai-memory-install-v3.1.2.sh
export PATH="$HOME/.local/bin:$PATH"
ai-memory --version
ai-memory setup --plan --agent claude-code --agent codex --agent cursor
ai-memory setup --agent claude-code --agent codex --agent cursor
ai-memory statusExpect version 3.1.2. Review the setup plan before accepting it: setup creates a background service and changes MCP, hook and skill configuration at user scope. Capture can therefore include the selected agents’ other projects. The release’s Codex configuration writer also sets default_tools_approval_mode = "approve" for ai-memory’s tools, so review that permission if you want memory mutations to require confirmation.
For this release’s native Codex registration, load the generated bearer token into the launch environment. With the default macOS data directory, these Bash commands do not print it:
AI_MEMORY_AUTH_TOKEN="$(cat "$HOME/Library/Application Support/ai-memory/auth-tokens/default")"
export AI_MEMORY_AUTH_TOKEN
codexThe registration references AI_MEMORY_AUTH_TOKEN; the MCP installation guide explains this Codex-specific requirement. Use the actual data directory reported by ai-memory status if yours differs.
Inside Codex, run /hooks and trust the installed ai-memory hooks. Restart Claude Code and Cursor after setup. An installer exit code alone does not prove that Codex will execute untrusted hooks.
Verify stored knowledge and handoffs separately
Use one checkout and an explicit project scope for the first check. From its root, run ai-memory project init and accept or select the workspace and project names. It writes .ai-memory.toml; keep both names consistent across the agents.
In Claude Code, use this prompt:
Read .ai-memory.toml and use its workspace and project for ai-memory calls.
Call memory_status.
Use memory_write_page to save decisions/shared-memory-demo.md with:
"Memory trial: before a dependency upgrade, check the official release
notes and run the affected component's tests."
Read the page back with memory_read_page and report its stored path.Open Codex or Cursor in the same checkout. Ask it to call memory_query for Memory trial, then memory_read_page on the matching result. Success means an actual tool result returns the saved path and decision; a plausible answer without retrieval is insufficient. These operations are documented in the programmatic memory reference.
Next, check the automatic handoff using a real, small task: stop with one clearly unfinished action, exit normally, and open the next agent in the same directory. Its startup context should identify the pending action. A durable page remains searchable; a handoff is a next-session transfer that can be claimed once.
If retrieval fails, run ai-memory doctor, inspect MCP connection status, and check the workspace/project pair. A Codex authentication failure calls for checking its launch environment; a missing handoff calls for checking hook trust and session capture. Do not treat those as the same failure.
Use Beacon for inspected traces and approved lessons
Choose Beacon when you want to review the evidence behind a reusable lesson. It combines collection methods such as OpenTelemetry, hooks and local session-file recovery, with coverage varying by tool. Capturing a session does not automatically turn its contents into approved memory.
Install a local collector
For a fresh macOS installation in Bash with Homebrew, configure only the three agents used here:
brew update
brew trust asymptote-labs/tap
brew tap asymptote-labs/tap
brew install beacon
beacon version
BEACON_ONBOARDING=0 beacon endpoint install \
--harness claude,codex,cursor --no-backfill
beacon endpoint statusThe Homebrew formula provides 1.3.45 as of the verification date. This example skips historical-session backfill and the interactive onboarding wizard. It installs user-level capture for the selected agents, so their work in other repositories can also enter the log.
That choice matters: the normal wizard preselects Beacon Cloud. On a fresh installation, skipping it and omitting --connect avoids Cloud enrollment. It does not disconnect an existing installation; use beacon endpoint disconnect for that. The onboarding documentation describes the destination choices.
Restart the agents after configuration, and use Codex’s /hooks to review and trust Beacon’s hooks. Run a small session in your trial repository, explicitly stating the dependency-review convention above.
Create, approve and retrieve one lesson
Inspect the recorded session before creating a lesson. From the repository root:
beacon endpoint traces list --limit 10
read -r -p "Trace ID from the trial session: " BEACON_TRACE_ID
beacon endpoint traces show "$BEACON_TRACE_ID" --limit 150Choose the real ID returned by the list and confirm that its events contain the stated convention. Then create a candidate:
beacon memory candidates create \
--trace "$BEACON_TRACE_ID" \
--kind convention \
--title "Dependency upgrades require release-note review" \
--applicability "Before changing a dependency version in this repository" \
--body "Check the dependency's official release notes and run the affected component's tests before proposing the upgrade."
read -r -p "Candidate ID returned above: " BEACON_CANDIDATE_ID
beacon memory candidates show "$BEACON_CANDIDATE_ID"Review the candidate and its source evidence. Only after accepting the actual lesson, approve it:
beacon memory candidates approve "$BEACON_CANDIDATE_ID" \
--reason "Reviewed against the source trace"This authored-candidate path calls no evaluator. Beacon’s optional evaluator scores traces; it does not supply the completed lesson text. Both routes are described in the memory command reference.
Now ask a different agent, operating in the same repository, to run:
beacon memory list -q "dependency upgrades" --jsonHave it pass the returned memory ID to beacon memory show and explain when the convention applies. The expected result is the approved lesson associated with this project. If the result is empty, check approval state, project scope and query words; Beacon’s local query requires every search term to match.
This CLI route does not require MCP. For tool-based retrieval, Beacon’s separate local MCP server exposes search_memory, get_memory and get_memory_context. It reads approved local memory. Beacon Cloud uses a separate store; connecting a device does not synchronize those two memory stores.
Keep bad lessons, private data and costs under control
Promote narrow conclusions with evidence, and treat recalled text as historical input. A failed attempt can reflect a temporary outage or the wrong branch rather than a permanent project rule. Store the applicable situation, source task or commit, verification result and review date; correct or retire the note when the underlying behavior changes.
Approval is a workflow, not proof that a human checked the content. Keep the person reviewing a Beacon candidate separate from the agent proposing it, and prevent remembered instructions from overriding current requirements or permissions.
Capture also changes where private material persists. ai-memory’s [capture] ignore_paths rules in .ai-memory.toml can exclude supported path-based events, but its usage documentation explicitly says this is not a general prompt/output data-loss filter. Keep credentials and customer data out of reusable notes; deleting the current Markdown page may leave older Git versions.
For Beacon Cloud, check the current privacy policy before forwarding work sessions. As of 2026-10-21, research and model-training uses are on by default with an opt-out; metadata-only forwarding still includes information such as paths and command lines. Local storage also does not make a cloud coding model local: material retrieved into that model’s context becomes model input.
Budget for the complete workflow. ai-memory’s default memory path needs no generative-model API key, although its default local embedding model may download on first start. Beacon’s authored-lesson route avoids evaluator calls. Your coding agent’s normal usage, extra recalled input, optional cloud processing, storage and review time still matter; neither architecture alone proves lower total cost.
Before adopting a layer across all projects, complete one real tool switch: retrieve the correct decision, identify the unfinished action, inspect its evidence and continue against the current checkout. If that fails, fix loading, scope or capture before accumulating more memory.
