How to Share Memory Between Claude Code and Codex: A Practical Guide
How to share memory between Claude Code and Codex starts with a familiar frustration: you explain your project to Claude, switch to Codex, and start over from zero. The context you built is gone. Forums and GitHub issues circle the problem without landing on a clear method. You'll find scattered mentions of CLAUDE.md and AGENTS.md, but no guide that walks you through the setup and tells you what won't work.
The honest answer is that file-based memory is the current standard, and it's simpler than most threads suggest. You create one shared markdown file, point both tools at it, and accept that real-time sync isn't part of the deal. GigaRAG addresses the broader gap for agent memory builders who need more than static files, but the foundation here works without any extra tooling.
| At a glance | Details |
|---|---|
| Core method | Shared markdown memory files in project root |
| Works with | Claude Code and Codex CLI |
| Sync type | Manual or file-watcher based |
| Real-time sync | Not natively supported |
| Best for | Agent memory and RAG pipelines |
| Setup time | Minutes, no extra services |
In This Guide
- Why Sharing Memory Between Claude Code and Codex Matters
- CLAUDE.md vs AGENTS.md: Which Shared Memory File Should You Use?
- Understanding Memory Files: CLAUDE.md and AGENTS.md
- How To Share Memory Between Claude Code And Codex: A Step-by-Step Guide
- Step-by-Step: How to Share Memory Between Claude Code and Codex
- What You Cannot Do: Honest Limitations of Shared Memory
- Shared Memory in RAG Pipelines and Agent Memory Architectures
- Common Mistakes When Sharing Memory Between Claude Code and Codex
- How to Share Memory Between Claude Code and Codex: The Bottom Line
Why Sharing Memory Between Claude Code and Codex Matters
Claude Code and Codex each keep their own context. Switch tools and you lose the thread: project conventions, decisions, file layouts. You re-explain. You re-paste. It costs time every session.
The cost of context loss
A Reddit thread on carrying context between Claude Code sessions shows the problem plainly. Developers rebuild mental models from scratch because neither tool reads the other's history. For agent memory builders, that's not an inconvenience. It's a broken pipeline.
Why file-based memory is the current standard
There's no API for cross-tool memory. No shared context bus. What works today is a markdown file both tools can read: CLAUDE.md for Claude Code, AGENTS.md for Codex. It's manual. It goes stale. But it's the only standard that exists.
[!note] Claude Code and Codex do not natively share memory or context in real time; any sharing requires manual or scripted file synchronization. There is no official cross-tool memory API as of this writing.
CLAUDE.md vs AGENTS.md: Which Shared Memory File Should You Use?
| Factor | CLAUDE.md | AGENTS.md |
|---|---|---|
| Primary tool | Claude Code | Codex CLI |
| Auto-read by | Claude Code only | Codex only |
| Cross-tool support | Requires symlink or copy | Requires symlink or copy |
| Format | Markdown | Markdown |
| Best for | Claude-first workflows | Tool-agnostic shared memory |
Understanding Memory Files: CLAUDE.md and AGENTS.md
CLAUDE.md and AGENTS.md are plain markdown files that Claude Code and Codex read at startup to load project context. They live in your project root or home directory, and they only update when you edit them by hand.
What is CLAUDE.md and where does it live?
CLAUDE.md is Claude Code's memory file. You put it in your project root and Claude Code reads it automatically when you start a session. It holds project conventions, build commands, file structure notes, and anything else you don't want to repeat.
The file also works from ~/.claude/CLAUDE.md for global memory that applies across all projects. That's the useful bit for sharing: a single global file both tools can reach.
What is AGENTS.md and where does it live?
AGENTS.md is the Codex equivalent. A GitHub issue proposing it as global memory in ~/.codex/ shows the intent: same idea, different tool. Codex reads AGENTS.md from the project root, and the proposal extends it to ~/.codex/AGENTS.md for machine-wide context.
The formats are nearly identical. Both are markdown. Both accept headings, lists, and code blocks. The difference is which tool reads which filename.
How each tool loads memory files
Claude Code loads CLAUDE.md at session start and injects it into the system prompt. Codex does the same with AGENTS.md. Neither tool watches the file for changes mid-session. Edit the file while a session is running and you won't see the update until you restart.
That's the core limitation. The files are read once, at startup. They're snapshots, not live state.
[!tip] For agent memory builders, treat the shared memory file as a retrieval source: chunk it, embed it, and serve relevant snippets to both Claude Code and Codex via a RAG layer so each tool gets only the context it needs.
How To Share Memory Between Claude Code And Codex: A Step-by-Step Guide
- Create a shared memory file in your project root, for example MEMORY.md, and add project context, conventions, and key decisions.
- Create CLAUDE.md and AGENTS.md in the same directory, each pointing to or duplicating the shared memory content.
- Configure Claude Code to read CLAUDE.md and Codex to read AGENTS.md, following each tool's documentation.
- Symlink or copy the shared file so both tools read the same content, or use a small script to keep them in sync.
- Add a file watcher or pre-commit hook to update the shared memory when either tool writes new context.
- Test by adding a note in one tool and verifying it appears when you switch to the other.
- Document the workflow in your README so teammates follow the same memory-sharing process.
Step-by-Step: How to Share Memory Between Claude Code and Codex
The setup is simple: one markdown file, two symlinks. Both tools read a different filename, so you point both at the same content.
Step 1: Create a shared markdown memory file
Pick a neutral location. ~/.shared-agent-memory.md works. Don't put it inside a project repo unless you want it version-controlled with that project.
Create the file and add your shared context: coding conventions, API keys you use often, project structure notes, common commands. Keep it under 200 lines. Both tools load this into their context window, and every line costs tokens.
mkdir -p ~/.config/agent-memory
touch ~/.config/agent-memory/shared-memory.md
Write your memory in plain markdown. Headings for sections, lists for conventions. Nothing fancy.
Step 2: Configure Claude Code to read the shared file
Claude Code reads ~/.claude/CLAUDE.md for global memory. You have two options.
Option A: symlink the shared file to the CLAUDE.md location.
ln -sf ~/.config/agent-memory/shared-memory.md ~/.claude/CLAUDE.md
Option B: if you already have a CLAUDE.md with Claude-specific content, add an import line at the top. Claude Code supports @path/to/file imports in CLAUDE.md.
@~/.config/agent-memory/shared-memory.md
# Claude-specific notes
...
The symlink is cleaner. One file, no duplication. The import approach works when you need tool-specific sections alongside shared content.
Step 3: Configure Codex to read the shared file
Codex reads ~/.codex/AGENTS.md for global memory. Same pattern.
ln -sf ~/.config/agent-memory/shared-memory.md ~/.codex/AGENTS.md
If Codex doesn't have a ~/.codex/ directory yet, create it first. The AGENTS.md global path is a proposal, not a documented feature in every Codex version. Test it. If your Codex build ignores ~/.codex/AGENTS.md, fall back to putting AGENTS.md in each project root and symlinking from there.
Step 4: Test the setup
Start a Claude Code session and ask: "What does your memory file say about our coding conventions?" Then start a Codex session and ask the same question. Both should answer from the shared file.
Edit the shared file, restart both tools, and confirm the change appears. That restart requirement is the part people forget. The file is read once at startup. No live sync.
What You Cannot Do: Honest Limitations of Shared Memory
The symlink setup works, but it's a snapshot, not a channel. Both tools read the file once at startup and never look at it again until you restart them.
No real-time sync
Edit the shared file while Claude Code is running and nothing changes in that session. Same for Codex. There's no file watcher, no push mechanism, no daemon keeping the two in sync. If you want both tools to see an update, you close both sessions and start fresh. That's the whole mechanism.
Stale memory is a real problem
The file drifts. You add a new convention in Claude Code, forget to write it to the shared file, and Codex never learns it. Or you write it down but don't restart Codex, so it keeps working from the old copy. The memory file is only as current as your last manual edit. Nothing checks it for you.
Manual maintenance is required
You are the sync engine. Every time a convention changes, a project moves, or an API key rotates, you edit the file by hand. There's no automatic extraction from your sessions, no diffing, no merge. If you skip a week, the file quietly goes bad and both tools start giving you outdated answers. The honest trade: this setup costs you five minutes of maintenance per session in exchange for not re-explaining context from scratch.
Shared Memory in RAG Pipelines and Agent Memory Architectures
A shared markdown file is a flat lookup table. It works when your context fits in a few hundred lines and changes slowly. It breaks when memory becomes a search problem.
File-based memory vs. vector-based memory
File-based memory loads everything into the context window every time. That's fine for 50 conventions. It's wasteful at 5,000. Vector-based memory stores embeddings and retrieves only what's relevant to the current query. You pay for an embedding model and a vector store, but you stop paying context tokens for memory you don't need.
When to upgrade to a RAG pipeline
Upgrade when any of these are true: your memory file exceeds what you'd read in one sitting, you need to search across past sessions, or multiple agents need different slices of the same memory. A RAG pipeline chunks your memory, embeds it, and retrieves top matches per query. The shared file becomes a source document, not the interface.
How GigaRAG fits into agent memory
GigaRAG treats agent memory as a retrieval problem. You point it at your shared files, session logs, and project docs. It chunks, embeds, and serves relevant context on demand. The honest trade: you add infrastructure. You lose the simplicity of one file both tools read directly. You gain memory that scales past what fits in a context window and stays current without manual edits.
Common Mistakes When Sharing Memory Between Claude Code and Codex
Most failed setups aren't architectural. They're a wrong path, a bloated file, or a file nobody updated for three weeks.
Wrong file paths
Claude Code reads CLAUDE.md from your project root or ~/.claude/. Codex reads AGENTS.md from your project root or ~/.codex/. Pointing both tools at a shared file in a third location only works if you configure each tool explicitly. A symlink that breaks on a new machine is the classic failure. Test the path from a fresh terminal before trusting it.
Overloading the memory file
A shared file with 2,000 lines of conventions, snippets, and decisions stops being memory. It becomes a document neither tool reads carefully. Both tools load the whole file into context. Every line costs tokens. Keep it under 200 lines. If you need more, you need a RAG pipeline, not a bigger file.
Forgetting to update after sessions
The file drifts. You make a decision in Claude Code, switch to Codex, and the file still says the old thing. Schedule a two-minute review at the end of each session. Or accept staleness and treat the file as a starting point, not a source of truth.
How to Share Memory Between Claude Code and Codex: The Bottom Line
How to share memory between Claude Code and Codex comes down to one markdown file and two symlinks. It's not real-time, it's not automatic, and it goes stale the moment you stop maintaining it. But it works, it's free, and it beats re-explaining your project every time you switch tools. When the file outgrows what you'd read in one sitting, that's the signal to move to a RAG pipeline. Until then, the symlink is enough.
Frequently Asked Questions
Can Claude Code and Codex share memory automatically?
No, they do not share memory automatically. Each tool reads its own configuration files, so you need to set up a shared file and keep it in sync manually or with scripts.
What is the best file format for shared memory between Claude Code and Codex?
Markdown is the most practical format because both tools can read plain text and it is easy to version control. Use a single MEMORY.md or similar file as the source of truth.
How do I sync memory files between Claude Code and Codex on Mac?
On macOS, you can use symlinks or a file watcher like fswatch to keep CLAUDE.md and AGENTS.md in sync. A simple shell script or pre-commit hook also works.
Does Cline memory bank work with Claude Code and Codex?
Cline memory bank is designed for the Cline VS Code extension, but the underlying pattern of markdown memory files can be adapted for Claude Code and Codex. You would need to replicate the file structure and sync logic yourself.
How does shared memory fit into a RAG pipeline for agents?
Shared memory files can be chunked and embedded into a vector store, then retrieved by either tool to provide relevant context. This turns static memory into a dynamic retrieval source for agent memory systems.
What are the limitations of sharing memory between Claude Code and Codex?
There is no real-time bidirectional sync, no automatic context sharing, and no official cross-tool API. You must manage file synchronization and potential conflicts yourself.
Can I use a single memory file for both Claude Code and Codex?
Yes, you can use a single file if you configure both tools to read it, but this often requires symlinks or custom instructions. Otherwise, maintain separate files that are kept in sync.
About GigaRAG
GigaRAG is for agent memory and RAG pipeline builders. get this right. Whether you are working through How to Share Memory Between Claude Code and Codex or something adjacent, we publish what we have actually tested, including where it falls short.
