How to Switch Between Claude Code and Codex Without Losing Context (Using ai-memory)

Aug 27, 2026

Cowrie

Dev @ Bswen

The Problem: Your Context Is Trapped Inside the Agent

I spent an hour working with Claude Code on a real project. At that point Claude already knew:

the module structure of the repo
why I rejected a certain library
which files were just changed
one bug I found and fixed
the feature I was currently implementing
the TODOs that still remained

Then I decided to switch to Codex. The problem appeared immediately:

Codex knew nothing.

No module structure. No rejected library. No fixed bug. No current task state. Nothing. I was back to zero, and I had to choose between:

re-explaining the whole project to Codex
copying a summary of what Claude did
pasting long chat logs
hand-writing CLAUDE.md / AGENTS.md
or simply staying with Claude to avoid the cost

The real gap is not another prompt template. What is missing is:

A memory layer that belongs to the project, not to the AI agent.

This post shows how a tool called ai-memory fills that gap. The core answer is short: you keep a project-owned memory layer between your agents, so you can quit Claude mid-task and resume in Codex without re-explaining anything.

What Is ai-memory?

ai-memory is a local-first persistent memory layer for AI coding agents. It is not another coding agent, and it is not conversation history. It sits between your agents and your storage:

Claude Code / Codex / Cursor / OpenCode / Gemini CLI
                        │
                        ▼
                    ai-memory
                        │
                        ▼
        Markdown Wiki + SQLite / FTS5

All supported agents can share the same project memory. Its core abilities:

lifecycle hooks automatically capture each coding session
useful context is saved as human-readable Markdown
a SQLite database indexes everything for fast search
FTS5 (SQLite’s full-text search module) lets you search without an LLM
it supports cross-agent queries, managed workstreams, and agent handoff

One sentence that describes it best: ai-memory is continuously maintained project memory, not a chat log.

Why AGENTS.md and CLAUDE.md Are Not Enough

AGENTS.md and CLAUDE.md are great for permanent project instructions. They store:

coding conventions
build commands
architecture overview
permanent project rules

But they are a bad fit for transient, evolving knowledge:

why a piece of code changed today
which approaches were already tried for a bug
which paths failed
where the current task stands
temporary technical decisions
unresolved questions

Here is a concrete example. My AGENTS.md looks like this:

Use PostgreSQL.
Run tests with ./gradlew test.
Do not edit generated files.

But the context that actually gets lost between agents is this:

Tried upgrading Firebase Messaging to 25.x,
but it requires minSdk 23.

The project still supports minSdk 19.

Current workaround:
use an older compatible Firebase Messaging version.

Next:
verify ProEnRelease build.

That kind of context is exactly what disappears when you switch agents. So the distinction is:

AGENTS.md stores instructions. ai-memory stores evolving project knowledge.

They complement each other. One does not replace the other.

How ai-memory Works

The flow is simple:

Coding Session
      │
      ▼
Lifecycle Hooks
      │
      ▼
Extract / Record Useful Context
      │
      ▼
Markdown Memory ── human readable + git friendly
      │
      ▼
SQLite + FTS5 (full-text search)
      │
      ▼
Search / Recall → Claude / Codex / Other Agents

Why is the Markdown + SQLite design interesting?

Markdown:

I can open the memory files and read them directly
I can grep them
I can back them up
no dependency on a SaaS vendor
it is not a black-box memory that I cannot inspect

SQLite / FTS5:

FTS5 is the full-text search module built into SQLite
it means I can search old memory even with no LLM involved
no need to understand database theory to benefit from it

The key point: capture, store, search, and retrieve all work with plain local files. The LLM is an optional enhancement layer, not a requirement.

Installing ai-memory

I checked the official README before writing this, because installation commands change. The project is written in Rust, and the supported ways include a prebuilt binary (for example via the AUR package ai-memory-bin on Arch Linux), building from source, or a Windows Docker wrapper.

After installing, verify it:

ai-memory --version

If the exact command changed, follow the current README on the repository.

Setting It Up with Claude Code

Before ai-memory can capture sessions, I need to wire two things for each agent: the MCP server and the lifecycle hooks.

For Claude Code, from the repository root:

ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply

For Codex, the equivalent:

ai-memory install-hooks --agent codex --apply

The hook-based agents I have seen in the current docs are claude-code, codex, opencode, pi, omp, and kimi-code. Some clients are MCP-only, which means they can talk to ai-memory but do not get managed workstreams — for example Kiro CLI, VS Code Copilot, and Zed. I check the docs before assuming an agent supports hooks.

Now the setup is done. Claude Code sessions start writing project memory automatically.

Switching from Claude Code to Codex Mid-Task

Let me walk through a real handoff. The project layout:

my-app/
├── backend/
├── frontend/
├── database/
└── AGENTS.md

The task: Add rate limiting to the login API.

I started in Claude Code. Claude read the auth module, found the login endpoint, noticed Redis was already available, decided to reuse it, implemented the rate limiter, and then hit an issue during testing. I exited Claude Code before finishing the last fix.

ai-memory had already saved a snapshot like this:

Task: Add login API rate limiting

Decisions:
- Reuse existing Redis client
- Limit: 5 attempts / minute / IP

Changed:
- auth/login.rs
- middleware/rate_limit.rs

Issue:
- integration test fails when Redis is unavailable

Next:
- decide whether tests should mock Redis

Now I open Codex. Instead of re-explaining everything, I just continue the same workstream:

ai-memory run claude        # start a managed workstream in Claude Code
ai-memory run codex --yolo  # later, continue the same workstream in Codex

Codex can now pick up where Claude stopped. No chat-log pasting, no “I was working with Claude before, we changed these three files…” explanation. I can just say:

Let's continue the rate-limiting task.

The snapshot tells Codex the task, the decisions, the changed files, the open issue, and the next step. That is the whole point of the handoff: the memory belongs to the project, so the next agent can read it.

Managing Cross-Agent Workflows with ai-memory run

ai-memory run is not about remembering chat. It manages the things that matter for a real task:

the task itself
the workstream
current state
handoff
unresolved problems
next action

I verified the current command semantics from the docs:

ai-memory run claude        # start a managed workstream in Claude Code
ai-memory run codex --yolo  # continue the same workstream in Codex
ai-memory run               # resume the newest usable managed session here
ai-memory run --fresh codex # start a new Codex session in the same workstream

There is also ai-memory continue, which resumes the newest managed checkout without me changing directories:

ai-memory continue

A useful multi-agent pattern:

Claude Code
      ↓
architecture + implementation

Codex
      ↓
debugging + tests

Gemini CLI
      ↓
documentation / review

Three agents work on the same workstream. I only need the agent that fits the current step, and I never rebuild the context from scratch.

Can ai-memory Work Without an LLM?

Yes. Basic storage and search work without an LLM, because the core is:

Markdown
   +
SQLite
   +
FTS5

With only those pieces I can still:

capture a session
store the context
search my memory
retrieve the right notes

The LLM is an enhancement layer. It is used for summarization, deduplication (merging repeated memories), and memory consolidation over time, not for every single query. This is a real difference from many “AI memory” SaaS products that require a model call for even basic recall.

Where Is Your Memory Stored?

Everything is local by default. The default data locations I verified:

Linux:   ~/.local/share/ai-memory
macOS:   ~/Library/Application Support/ai-memory
Override: AI_MEMORY_DATA_DIR

Inside the data directory, the layout looks like this:

data/
├── wiki/    # markdown — back up with rsync or git push to a remote
├── raw/     # immutable session log archive
├── db/      # memory.sqlite (FTS5 + entities + page_embeddings)
├── logs/    # daily rolling tracing
└── models/  # reserved for future local embedders

So I can read the Markdown directly, back it up, and search the SQLite index. The default commit-to-Git behavior may change between versions, so I verify it against the current docs instead of assuming.

Should you commit AI memory to Git?

My practical take:

Safe to commit:

architecture decisions
public project knowledge
reusable debugging notes

Be cautious with:

API keys
credentials
customer data
internal URLs
private prompts
proprietary information

Treat memory files like any other repo content: commit the knowledge, keep the secrets out.

What Should an AI Coding Agent Remember?

This question matters more than the tooling, because automatic capture does not mean the captured content is right.

Good memories:

Architecture decisions
Failed approaches
Important bugs
Build quirks
Environment constraints
Current task state
Unresolved questions

Bad memories:

Every shell command
Huge logs
Temporary debug output
Secrets
Generated code
Trivial conversation

The core principle: good agent memory should preserve decisions, not noise. If I record only decisions and state, the memory stays useful for months. If I record everything, the memory becomes noise that no agent wants to read.

ai-memory vs AGENTS.md vs Copy/Paste

Approach	Persistent	Cross-agent	Automatic capture	Human-readable	Local-first
Copy/paste summaries	Partial	Yes	No	Yes	Yes
AGENTS.md	Yes	Mostly	No	Yes	Yes
Claude Code native context	Session-dependent	No	Yes	Partial	Depends
SaaS memory service	Yes	Possible	Depends	Often No	Usually No
ai-memory	Yes	Yes	Yes	Yes	Yes

The table is the honest summary: copy/paste is lossy, AGENTS.md is static, native context dies with the session, and SaaS services are usually not local-first. ai-memory is the only row that is persistent, cross-agent, automatic, human-readable, and local-first.

A Practical Multi-Agent Workflow

Here is the setup I recommend:

AGENTS.md
      ↓
Permanent instructions (standards, build commands, repo rules)

ai-memory
      ↓
Evolving project knowledge (decisions, bugs, experiments, current state)

Git / Tests / Docs / Code
      ↓
Source of truth

Keep ai-memory honest in this stack: it is not the source of truth. The code, tests, and Git history are. ai-memory is:

a continuity layer between coding sessions and coding agents.

Where ai-memory May Not Be a Good Fit

I do not want to oversell it. There are real limits.

Solo developers and small teams (indie hackers, 2–5 person teams, multi-agent workflows) are the sweet spot. The tool is local, lightweight, and the capture workflow fits a single developer.

Enterprises need to think about tenant isolation, access control, secrets handling, audit, centralized management, retention policy, and compliance. ai-memory alone is probably not ready to replace a mature centralized knowledge infrastructure.

Memory quality is the engineering problem that does not go away. Automatic capture is not the same as correct capture. I can end up with obsolete decisions, incorrect assumptions, duplicated memories, or a temporary workaround recorded as a permanent decision. Persistent memory introduces a new problem: stale memory. Filtering and reviewing what gets recorded is part of the job.

FAQ

Does ai-memory work with Claude Code? Yes. Claude Code is a first-class supported agent with both MCP and lifecycle hooks via ai-memory install-mcp --client claude-code --apply and ai-memory install-hooks --agent claude-code --apply.

Does ai-memory work with OpenAI Codex CLI? Yes. Codex supports lifecycle hooks (ai-memory install-hooks --agent codex --apply) and can be used with ai-memory run codex.

Can Claude Code and Codex share the same memory? Yes. That is the core use case. Both agents read and write the same project memory, so a handoff mid-task keeps the task state.

Does ai-memory require an LLM? No. Search and recall work on Markdown + SQLite + FTS5. The LLM is an optional layer for summarization and consolidation.

Where does ai-memory store its data? Locally, by default at ~/.local/share/ai-memory on Linux and ~/Library/Application Support/ai-memory on macOS, overridable with AI_MEMORY_DATA_DIR.

Is ai-memory local? Is it open source? It is local-first and open source (the repository is akitaonrails/ai-memory).

Can I use it with Cursor or Gemini CLI? Cursor and Gemini CLI are supported clients. Check the current docs for whether they use hooks or MCP-only integration.

Is ai-memory a replacement for AGENTS.md? No. AGENTS.md stores permanent instructions; ai-memory stores evolving project knowledge. They complement each other.

Should I commit ai-memory files to Git? Commit knowledge (decisions, public notes, debugging notes). Keep secrets, credentials, and customer data out.

Final Thoughts

In this post, I showed how to stop a coding task in Claude Code and resume it in Codex without re-explaining the project, using ai-memory as a project-owned memory layer.

The before and after:

Before:  Claude → stop → Codex starts from zero
After:   Claude → project memory → Codex

The real change is simple: the context no longer belongs to Claude or Codex. It belongs to the project.

One honest caveat: if you always use a single agent, the benefit of ai-memory is limited. But if you switch between Claude Code, Codex, Cursor, OpenCode, and Gemini CLI, cross-agent continuity is often worth more than simply paying for a bigger context window. Try the handoff scenario above on one small task, and you will feel the difference immediately.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 ai-memory official repository (akitaonrails/ai-memory)
👨‍💻 ai-memory installation documentation
👨‍💻 ai-memory managed workstreams documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!