{"id":82321,"date":"2026-09-06T20:41:16","date_gmt":"2026-09-06T12:41:16","guid":{"rendered":"https:\/\/www.ahhhhfs.com\/?p=82321"},"modified":"2026-09-07T18:37:22","modified_gmt":"2026-09-07T10:37:22","slug":"ai-memory%ef%bc%9a%e8%ae%a9-claude-code-%e4%b8%8e-codex-%e5%85%b1%e4%ba%ab%e9%a1%b9%e7%9b%ae%e8%ae%b0%e5%bf%86","status":"publish","type":"post","link":"https:\/\/www.ahhhhfs.com\/en\/82321\/","title":{"rendered":"ai-memory: Share Project Memory Between Claude Code and Codex"},"content":{"rendered":"

When a Claude Code session hits a usage limit or a debugging path stops making progress, switching to Codex can provide another way forward. The new session, however, does not automatically know the project architecture, the errors already investigated, the approaches that failed, or the work that remains. ai-memory<\/strong> stores this project context so another AI coding agent can retrieve it later.<\/p>\n

\"ai-memory<\/a><\/p>\n

Overview:<\/strong> ai-memory is a shared project memory service for AI coding agents. It captures prompts, tool calls, and session progress through lifecycle hooks, then organizes the information into a Git-backed Markdown wiki. Claude Code, Codex, Cursor, and other supported clients can retrieve previous decisions, failed approaches, and open tasks. The project uses the MIT License, but it does not synchronize source files, dependencies, or development environments.<\/div>\n

How ai-memory differs from built-in agent memory<\/h2>\n

Claude Code already supports CLAUDE.md<\/code> files and automatic memory, while Cursor provides project rules and related context features. These built-in systems may be sufficient when all work stays inside one coding tool. Their debugging history, technical decisions, and unfinished tasks do not normally appear automatically after moving to a different agent.<\/p>\n

\"ai-memory<\/a><\/p>\n

ai-memory runs a shared memory service outside those individual tools. Lifecycle hooks capture prompts, tool calls, and session boundaries. The service turns those observations into Markdown pages that later sessions can search and use for handoffs.<\/p>\n

The Markdown wiki is the primary source of truth, with Git recording its history. SQLite provides derived indexes for full-text search, entities, relationships, and optional vectors. Those indexes can be rebuilt from the files, while the Markdown pages remain directly readable, editable, and portable.<\/p>\n

What carries over from Claude Code to Codex?<\/h2>\n

Once both clients are connected to the same ai-memory service and mapped to the same project, Claude Code can leave a Handoff containing task progress, attempted approaches, and unresolved questions. Codex can then retrieve that record instead of asking for the entire project history again.<\/p>\n

The basic hooks and Handoff system are enough when Codex only needs to know where the previous session stopped. The optional managed workstreams feature goes further: it records visible events and tool-call history across agents and links the native sessions maintained by Claude Code, Codex, and other supported clients.<\/p>\n

This gives the next agent a usable task history. It does not copy Claude Code\u2019s complete internal session state into Codex.<\/p>\n

Switching agents in the same project directory<\/h3>\n

When Claude Code and Codex open the same local project directory, Codex can inspect the files already present there, including uncommitted changes. Switching agents on the same computer does not require a Git commit or push first.<\/p>\n

ai-memory adds information that may not be obvious from the files: why a particular approach was chosen, which fixes were already attempted, how far an error investigation progressed, and what should happen next. The current checkout and project instructions still take priority over stored historical memory.<\/p>\n

Continuing the project on another computer<\/h3>\n

Running ai-memory on a Homelab server, LAN host, or remote server allows several computers to access the same project memory. Source files are handled separately. The second computer still needs the correct repository state, branch, dependencies, and environment variables.<\/p>\n

A cross-machine handoff therefore has two parts: retrieve the previous task history through ai-memory, then synchronize the code and development environment through Git or another file-management process. Local changes that never reached the second machine will not be transferred by ai-memory.<\/p>\n

Which AI coding tools does ai-memory support?<\/h2>\n

ai-memory supports several AI coding clients. The table below covers the tools most relevant to this article and shows why \u201csupported\u201d does not mean identical automation on every client.<\/p>\n

\n\n\n\n\n\n\n\n\n\n
ai-memory integration options for common AI coding clients<\/caption>\n
Client<\/th>\nIntegration<\/th>\nLimitations and setup notes<\/th>\n<\/tr>\n<\/thead>\n
Claude Code<\/th>\nMCP + lifecycle hooks<\/td>\nLifecycle events can be captured after setup, subject to capture rules and exclusions. Capturing the assistant\u2019s final response requires both --capture-assistant<\/code> during hook installation and capture_assistant<\/code> on the server. It is disabled by default.<\/td>\n<\/tr>\n
Codex<\/th>\nMCP + lifecycle hooks<\/td>\nCodex CLI 0.145.0 and later provide a native SessionEnd<\/code> event, allowing automatic end-of-session summaries and handoffs. Older Codex versions can use ai-memory finalize-session --agent codex<\/code> as a fallback. Assistant-final-response capture is not supported for Codex.<\/td>\n<\/tr>\n
Cursor<\/th>\nMCP + lifecycle hooks<\/td>\nSupports memory tool calls and lifecycle capture after the relevant MCP and hook configurations are installed. Captured events may change as Cursor updates its integration interfaces.<\/td>\n<\/tr>\n
Gemini CLI<\/th>\nMCP + lifecycle hooks<\/td>\nSupports memory tool calls and lifecycle capture. MCP and hook integrations need to be installed for Gemini CLI.<\/td>\n<\/tr>\n
VS Code Copilot<\/th>\nMCP only<\/td>\nCopilot Agent mode can call the memory tools exposed by ai-memory, but the integration currently has no lifecycle hooks and does not provide the same automatic capture flow as Claude Code.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/div>\n

Claude Code, recent Codex releases, Cursor, and Gemini CLI can combine memory tools with lifecycle capture. Older Codex releases require a manual fallback when a final summary or Handoff is needed. VS Code Copilot currently works through MCP without automatic lifecycle capture.<\/p>\n

Does ai-memory need an LLM?<\/h2>\n

Can ai-memory work without an external LLM?<\/h3>\n

Yes. Core ai-memory functions do not require a hosted LLM. Project memory is stored in a Git-backed Markdown wiki, while SQLite maintains derived indexes. Without a configured language model, the system can still search through FTS5, declared entities, and graph relationships, and it can produce rule-based session summaries and handoffs.<\/p>\n

\"ai-memory<\/a><\/p>\n

Since version 2.0, a fresh installation with no embedding provider configured attempts to enable in-process local embeddings automatically. The approximately 87MB model downloads in the background on first startup, and hybrid search normally becomes available after the next restart. If the model cannot be downloaded or the installed build lacks local embedding support, ai-memory continues with its non-vector search path.<\/p>\n

A separate LLM provider can be configured for richer session consolidation and related model-assisted features. Hosted embedding providers include OpenAI, Voyage, and Gemini, while compatible local or self-hosted endpoints include Ollama and LM Studio. Existing installations retain an explicitly configured embedding provider rather than being switched automatically.<\/p>\n

No external LLM calls does not mean the entire workflow has no cost.<\/strong> The server still consumes storage, memory, and compute resources, while backups, upgrades, and compatibility maintenance require time. Subscriptions or model usage for Claude Code, Codex, and other coding agents are separate expenses.<\/p>\n

Does project memory leave the machine when using cloud models?<\/h3>\n

It can. Self-hosting means that you control the ai-memory server and its data directory. The data path changes when a hosted model or embedding provider is enabled. Content used to generate summaries or embeddings is sent to the selected provider, so its retention and data-processing terms should be reviewed before use.<\/p>\n

Local models can keep the corresponding ai-memory summarization or embedding workload inside your own environment. This does not change how the coding agent itself connects to its model provider. Even when ai-memory makes no cloud model calls, Claude Code, Codex, or another coding assistant may still send code and project context to its own service.<\/p>\n

Should you run ai-memory locally, on a Homelab, or on a VPS?<\/h3>\n

For a single computer, ai-memory can run on the same machine as the coding agent. A Homelab server, LAN host, or remote VPS becomes useful when several computers or team members need to access the same project memory.<\/p>\n

\"project<\/a><\/p>\n

The official quick-start configuration binds the service to 127.0.0.1<\/code> without authentication, so other computers cannot connect directly. A LAN or internet-facing deployment requires an appropriate listening address, authentication, allowed-host configuration, and HTTPS.<\/p>\n

Remote deployment:<\/strong> a bearer token authenticates the client, while HTTPS protects data in transit; one does not replace the other. ai-memory provides multi-user authentication, attribution, and audit records, but its data model is single-tenant and does not provide per-page RBAC. It can serve a trusted team, but it should not be treated as a public multi-tenant knowledge platform for mutually untrusted users.<\/div>\n

For another approach to shared tools and project context, see our overview of the holaOS AI agent workspace<\/a> and compare a dedicated memory service with a unified workspace.<\/p>\n

Who should use ai-memory?<\/h2>\n

Whether ai-memory is worth running depends mainly on how often you switch agents, computers, or team members. It adds another service that needs configuration, updates, and backups.<\/p>\n

ai-memory may be useful if you:<\/h3>\n