Build a Local Shared Memory for Multi‑Agent AI: Stop Losing Context Between Claude and Codex in 10 Minutes

Core question of this article: How do you stop each AI agent from forgetting everything the other just did when you switch between Claude Code and Codex? And how can you build a shared memory using nothing but a local folder?

I’ve been using Claude Code for a long time. Inside it, a whole ecosystem has grown organically: memory, skills, vault, hooks. These pieces weren’t built overnight—they accumulated over months of daily use. Claude remembers my preferences, my active tasks, my user profile.

But lately I’ve been using Codex more and more. For some scenarios, it’s genuinely stronger—faster code generation, deeper understanding of certain frameworks.

Problem is, every time I switch from Claude to Codex, Codex has no idea what Claude just decided, what tasks are currently active, or who I even am as a user. I have to re‑explain everything: who I am, what project I’m on, where we are today, which high‑priority tasks are still open.

The reverse is just as painful. After Codex runs a session, switching back to Claude leaves Claude completely blind to what Codex just accomplished.

The solution isn’t choosing one over the other. It’s building a shared layer between the two agents—a neutral, local directory where they exchange information.

This approach needs no MCP, no A2A protocol, no cloud orchestration. The file system itself is the sync mechanism. Every session simply re‑reads the files, and that gives you the latest state.

Below are seven steps that take about ten minutes to run through.

Step 1: Create the Directory Structure – Physical Isolation + Shared Boundary

Core question of this step: How should you design the shared directory so agents can exchange information without ever polluting each other’s private data?

Create ~/.agents/ in your home directory. This becomes the single hub for multi‑agent collaboration.

~/.agents/
    contracts/        # Protocols that both agents read
    shared/           # Neutral data projected by Claude, read‑only for Codex
    handoff/          # Handover information written by Codex back to Claude
    manifests/        # Defines what should be shared and what should stay private

One hard rule—learned from painful experience:

Claude never touches .codex/, and Codex never touches .claude/. All collaboration goes through ~/.agents/.

Why so strict? I once tried letting them read each other’s private directories. Claude overwrote a Codex config file, and Codex failed to start on the next run. Isolating private directories completely and using filesystem permissions to enforce boundaries is the simplest and most reliable approach.

What I learned: Don’t let agents cross the line. Each agent’s private directory is its “home”. The shared directory is the “meeting room”. They can talk in the meeting room, but they never go into each other’s houses.

Step 2: Write Contracts – Protocols That Both Agents Read

Core question of this step: How do you guarantee that both agents interpret the sharing rules identically? What exactly goes into the contracts files?

Place two files in the contracts/ directory. Every agent reads them on startup. These files define “how to share” and “how to hand over”.

claude-shared.md (Projection rules for Claude)

# Claude → Shared Layer Projection Rules

## Execute at session end
1. Update shared/profile.md (only when user profile actually changes)
2. Overwrite shared/tasks.json (active task list, full overwrite)
3. Overwrite shared/today-summary.md (daily progress, full overwrite)

## Projection rules
- Files in shared/ are condensed versions, not mirrors of internal .claude/ files
- Each shared file has exactly one source file
- Do not synthesise data from multiple sources during projection
- Use signal‑word matching for extraction, not semantic summarisation

codex-global.md (Startup and handover protocol for Codex)

# Codex Startup Protocol

## Execute at session start
1. Read ~/.agents/contracts/codex-global.md
2. Read ~/.agents/shared/profile.md
3. Read ~/.agents/shared/tasks.json
4. Read ~/.agents/shared/today-summary.md
5. Check ~/.agents/handoff/latest.md for any unprocessed handover

## Execute at session end
1. If there are matters for Claude, write them to ~/.agents/handoff/latest.md

How to think about it: Contracts are like diplomatic protocols between two countries. Each agent has its own copy, and the copies state clearly: when to write which files, when to read which files, what format the handover should use. Both sides agree on the same protocol, so there’s no “I said this, you heard that”.

Step 3: Write the Manifest – Define the Sharing Boundary

Core question of this step: What information should be shared, and what must never be shared? How do you define a clear boundary that stays clean as you add more shared items later?

manifests/must-share.json does one simple thing: defines what is shared and what is not.

{
  "shared": [
    {
      "file": "profile.md",
      "source": ".claude/memory/working-with-me.md",
      "update": "on-change",
      "description": "User profile, stable information"
    },
    {
      "file": "tasks.json",
      "source": ".claude/memory/active-tasks.json",
      "update": "every-session-end",
      "description": "Active tasks, hot data"
    },
    {
      "file": "today-summary.md",
      "source": ".claude/memory/today.md",
      "update": "every-session-end",
      "description": "Daily progress, overwritten each time"
    }
  ],
  "private": [
    ".claude/memory/personal-notes.md",
    ".claude/memory/private/",
    ".codex/sessions/"
  ]
}

If you later add a new shared file, add one entry here. Both agents recognise it. If a file should never be seen by the other agent, list it explicitly under private.

Why the manifest is necessary: Without an explicit boundary, it’s easy to accidentally drop something into the shared directory that shouldn’t be there. I once projected my personal notes by mistake. Codex wouldn’t have read it, but the act itself was a risk. The manifest works like a customs declaration – every new file has to pass through it.

Maintenance: Spend five minutes each week looking at must-share.json. Are there new sharing needs? Has anything that should be private leaked into the shared list? Everything else runs automatically.

Step 4: Build the Shared Layer – Claude Projects Neutral Data

Core question of this step: What exactly goes into the shared directory? What file formats work best so the other agent can read them reliably without misinterpretation?

The shared/ directory holds three files. Only Claude writes them; Codex only reads.

shared/profile.md (User profile)

# User Profile

## Identity
[Role, type of work]

## Long‑term preferences
- Write code for simplicity first, no premature optimisation
- When designing, define boundaries first, then expand
- Judgement over information gathering

## Knowledge areas
[What you’re good at, what you’re not]

## Current project
[Project name + one‑sentence goal]

This file updates only when the user profile actually changes. Not every session end – because profiles are relatively stable. Frequent overwrites just add noise.

shared/tasks.json (Active tasks)

{
  "updated": "2026-05-27T18:30:00+08:00",
  "tasks": [
    {
      "id": "1",
      "title": "Build dual‑agent collaboration layer",
      "status": "in-progress",
      "priority": "high",
      "deadline": "2026-05-30",
      "notes": "~/.agents/ directory created, contracts written, shared layer in progress"
    }
  ]
}

Full overwrite at every Claude session end. One important detail: deadline is written only when the source data contains an explicit, unambiguous date format – e.g. “2026-05-30” or “4/24”. Vague expressions like “end of month” or “next week” are not written. Why? Because if Codex reads an ambiguous date, it might make wrong assumptions. It’s better to provide no date than a misleading one.

shared/today-summary.md (Daily progress)

# Daily progress — 2026-05-27

## Completed
- Shared layer directory structure created
- Both contracts files written

## Needs attention
- manifests/must-share.json needs a field review next week

## Next steps
- Add shared‑layer reading logic to Codex’s codex-global.md

Full overwrite at every Claude session end. When extracting “needs attention” items, use only signal‑word matching:

“conclusion / confirmation / milestone / approved / decision / blocked / postponed”

No semantic summarisation. This layer is built for stability, not cleverness.

I learned this the hard way. I first tried letting Claude write “needs attention” in natural language. It produced vague, fluffy statements that Codex couldn’t parse. Switching to pure signal‑word matching – write only when one of those keywords appears – felt “dumber”, but Codex now reliably extracts actionable items every single time.

Concrete scenario: Suppose I fix a complex bug in Claude during the afternoon. Claude writes that fix into the “completed” section of today-summary.md. In the evening I switch to Codex to work on another task. Codex reads the “completed” list and knows not to touch that bug again. Meanwhile, if I marked a “blocked” item in Claude, Codex will see that and actively avoid the blocked task, picking up other high‑priority work instead.

Step 5: Make Both Agents Read the Shared Layer – Inject Startup Instructions

Core question of this step: What exact lines do you add to Claude’s and Codex’s configuration files so they automatically read the shared layer on startup?

On Claude’s side – add to `CLAUDE.md`

## Session Start
Read ~/.agents/contracts/claude-shared.md
Check ~/.agents/handoff/latest.md — if there is new handover info, process it before starting

## Session End
Update shared/ according to the projection rules in ~/.agents/contracts/claude-shared.md

On Codex’s side – add to `CODEX.md` or `codex-global.md`

## Session Start
Read ~/.agents/contracts/codex-global.md
Read ~/.agents/shared/profile.md
Read ~/.agents/shared/tasks.json
Read ~/.agents/shared/today-summary.md
Check ~/.agents/handoff/ — if there are unprocessed handover files, read them first

## Session End
If there are matters for Claude → write to ~/.agents/handoff/latest.md

Double safety: In Codex’s config.toml, add a model_instructions_file entry. That way, even if CODEX.md isn’t read for some reason, the shared‑layer instructions still load at startup.

Why put this explicitly in Session Start? I found that if reading instructions aren’t placed at startup, agents tend to “forget” to check shared files during conversation. Hard‑coding it into the startup flow makes it as automatic as brushing your teeth.

Step 6: Build Handoff – Codex Writes Back to Claude

Core question of this step: After Codex finishes a task, how does it “hand back” information that Claude needs to know? What’s the format and lifecycle of the handoff directory?

When Codex finishes a session and there’s something Claude should know, write it to the handoff directory.

handoff/latest.md

# Codex → Claude handover — 2026-05-27

## Completed
- Fixed empty deadline values in shared/tasks.json
- Updated startup reading logic in codex-global.md

## Needs Claude’s attention
- shared/tasks.json has a new task from a Codex execution result – please confirm whether to add it to the active list

## Blocked items
- None

Lifecycle of a handover:

Codex writes handoff/latest.md at session end.
Next time Claude starts, it reads this file.
Claude processes the handover, then moves the file to handoff/archive/ with a date‑stamped name (e.g. 2026-05-27-latest.md).
Next time Codex checks the handoff/ directory and sees it empty, it knows the previous handover has been handled.

Mental model: Handoff is like a sticky note left on a whiteboard when two people change shifts. Codex finishes the night shift, writes “what happened tonight, what to watch for in the morning” on the note, and sticks it on the whiteboard. Claude arrives in the morning, reads the note as the first thing, handles it, then files the note away. The next night, Codex sees a clean whiteboard and knows nothing is pending.

What I learned: My first design had agents writing directly into each other’s private directories. The problem was timing – writes often happened but the other agent wasn’t reading at the right moment. Switching to a dedicated handoff directory with an explicit “move to archive” mechanism solved it. The key is having a physical representation of “processed” – a file that is moved away.

Step 7: Validate – Three Tests to Confirm Everything Works

Core question of this step: How do you know the shared layer is actually working? What tests should you run to verify each part?

Test 1: Codex reads the shared layer

Start Codex in your home directory. Confirm it reads:

~/.agents/contracts/codex-global.md
~/.agents/shared/profile.md
~/.agents/shared/tasks.json
~/.agents/shared/today-summary.md

If any file is not read, check the path.

Test 2: Claude reads handoff

Start Claude in your vault directory. Confirm it reads handoff/latest.md. If Codex left something but Claude doesn’t detect it, check that the session start instructions in CLAUDE.md are in the correct place.

Test 3: Full round trip

Run through the full cycle:

Claude writes to shared/ (profile, tasks, today‑summary)
Codex reads shared/ and executes a task
Codex writes to handoff/ (latest.md)
Claude starts again, reads the handoff, processes it
Claude moves the handoff file to archive

Once this loop runs cleanly, your shared layer is live.

Daily Use – Switching Agents Becomes Automatic

Core question of this section: What does daily work look like with this system? What’s the experience of switching from Claude to Codex and back?

Switching from Claude to Codex

Codex starts, reads shared/profile.md – knows who you are, your long‑term preferences, your knowledge areas.
Reads shared/tasks.json – knows what tasks are active, their priorities, deadlines.
Reads shared/today-summary.md – knows where you are today, what needs attention.

Real experience: You no longer have to tell Codex “I’m a backend Go developer who prefers clean code, currently refactoring the order system, finished the database migration today, next step is writing the API layer”. Codex reads all of that on its own.

Switching from Codex back to Claude

Claude starts, reads handoff/latest.md.
Knows what Codex did and what needs attention.
After processing, moves the handoff file away.

Real experience: Claude will proactively tell you “Codex just fixed the empty deadline values in tasks.json and added a new task for you to review.” You don’t need to manually sync anything.

A Final Note – This Is Not Cloud Multi‑Agent Orchestration

Core question of this section: How does this local directory approach differ from cloud‑based multi‑agent frameworks (like AutoGen or CrewAI)? When is it appropriate, and when is it not?

It doesn’t handle concurrency. It doesn’t handle distributed state. It doesn’t need MCP or A2A protocols.

The file system itself is the sync mechanism. Every session re‑reads the files, and that gives you the latest state.

What this means:

If you need two agents writing to the same file at the same time, this approach is not for you.
If you need millisecond‑level state synchronisation, this approach is not for you.
If you need a central orchestrator to dispatch tasks, this approach is not for you.

But it works very well for:

One person using multiple agents at different times (serial usage).
Wanting a simple, auditable, file‑level state sharing mechanism.
Avoiding extra dependencies and services.

What I learned: I initially tried Redis and SQLite for shared storage. Overkill. The file system provides enough atomicity (writing a file is atomic), and anyone can instantly cat a file to inspect state – debugging becomes trivial.

One‑Page Quick Reference: Action Checklist

Step	What to do	Key files	One‑line explanation
1	Create directories	`~/.agents/`	Single hub for sharing
2	Write protocols	`contracts/claude-shared.md` `contracts/codex-global.md`	Define projection and handover rules
3	Define boundaries	`manifests/must-share.json`	Explicitly list shared vs private
4	Build shared layer	`shared/profile.md` `shared/tasks.json` `shared/today-summary.md`	Claude projects, Codex reads
5	Inject startup instructions	`CLAUDE.md` `CODEX.md`	Auto read/write at session boundaries
6	Build handoff	`handoff/latest.md`	Codex writes back to Claude
7	Validate	Three tests	Ensure full round trip works

FAQ

Q1: Where are the private directories for Claude and Codex exactly?

Claude’s private directory is typically .claude/ inside your project folder. Codex’s private directory is .codex/. The shared layer lives in ~/.agents/, independent of both.

Q2: Is it okay if Claude doesn’t update profile.md at every session end?

Yes. must-share.json sets the update policy for profile.md to "on-change". Only write when the user profile actually changes – not at every session end.

Q3: If Codex sees the handoff directory is non‑empty, which file should it read first?

Sort by filename; the latest one has priority. latest.md is the agreed convention for the most recent handover. After processing, move it to archive/.

Q4: What if both agents try to write the same shared file at the same time?

This approach does not handle concurrent writes. It assumes serial usage – only one agent active at a time. If you need concurrency, this solution is not for you.

Q5: How exactly does signal‑word matching work? Give an example.

When Claude generates the “needs attention” section of today-summary.md, it scans .claude/memory/today.md for sentences containing any of the predefined keywords (blocked, decision, milestone, approved, etc.). It copies those sentences directly, with no summarisation or rephrasing.

Q6: I don’t use Claude Code or Codex. I use other agents. Can I still use this approach?

Yes. The core ideas are: shared directory + startup protocol + handover files + boundary manifest. As long as your agents support executing custom read/write instructions at session start and end, you can adapt this.

Q7: Does this approach leak my private information?

The private list in manifests/must-share.json explicitly declares which directories and files are never shared. As long as you don’t add private file paths to the shared list, nothing leaks.

Practical summary:

Use ~/.agents/ as the multi‑agent sharing hub.
contracts/ holds protocols that both agents read.
manifests/ defines the sharing boundary – maintain it when adding new files.
shared/ holds condensed Claude‑projected data; Codex only reads.
handoff/ holds handover information written by Codex back to Claude.
Add session start/end read/write instructions to CLAUDE.md and CODEX.md.
Run three tests to validate: Codex reads shared → Codex writes handoff → Claude reads handoff.
The filesystem is the sync mechanism – no cloud orchestration required.

Local Shared Memory for Multi-Agent AI: Stop Losing Context Between Claude and Codex in 10 Minutes