Codex CLI 與 Claude Code 共用專案記憶：Git 為核心的同步策略

annie · August 11, 2026, 4:56pm

解決 Codex CLI 與 Claude Code 記憶不同步問題。以 Git 為 source of truth，搭配 .agent/ 共享 Markdown 記憶與 HANDOFF.md，並介紹 Memorix 等跨 Agent 記憶工具，實現無縫切換。

當你需要在同一個專案資料夾中頻繁切換 Codex CLI 與 Claude Code 進行開發，最令人困擾的問題莫過於兩者的記憶文件不同——Codex 讀取 AGENTS.md，Claude Code 則依賴 CLAUDE.md 或自動記憶系統。隨著任務交替，專案知識逐漸分叉，導致重複工作或遺漏關鍵決策。

解決這個問題的關鍵不在於「同步兩套記憶」，而是讓 Git 儲存庫本身成為專案記憶的唯一真相來源（source of truth）。以下提供一套經過驗證的架構與工具，讓你在不同 AI Agent 之間無縫交接。

核心架構：以 Git 為中心的共享記憶

不要將大量專案知識直接塞進 AGENTS.md 或 CLAUDE.md，而是讓它們只作為引導入口（bootstrap），指向一個共用的 .agent/ 目錄。

your-project/
│
├── AGENTS.md                  # Codex 入口
├── CLAUDE.md                  # Claude 入口
│
├── .agent/
│   ├── PROJECT.md             # 專案架構、技術棧、重要規則
│   ├── CURRENT.md             # 當前進度
│   ├── DECISIONS.md           # 架構決策記錄
│   ├── GOTCHAS.md             # 踩過的坑與注意事項
│   ├── TASKS.md               # 已完成 / 進行中 / 下一步任務
│   └── HANDOFF.md             # Agent 交接文件
│
└── src/

入口檔案的設定

AGENTS.md 與 CLAUDE.md 內容保持一致，只負責指示 Agent 讀取 .agent/ 下的檔案。例如：

# Agent Instructions

Before starting any task, read:

- .agent/PROJECT.md
- .agent/CURRENT.md
- .agent/DECISIONS.md
- .agent/GOTCHAS.md
- .agent/TASKS.md
- .agent/HANDOFF.md

The files under `.agent/` are the canonical shared project memory.

After completing meaningful work:

1. Update CURRENT.md.
2. Record architectural decisions in DECISIONS.md.
3. Record discovered pitfalls in GOTCHAS.md.
4. Update TASKS.md.
5. Write a concise HANDOFF.md for the next agent.

這樣一來，無論使用哪個 Agent，它都會先讀取同一組共享記憶檔案，確保知識一致。

HANDOFF.md：交接的關鍵

HANDOFF.md 是整個架構中最重要的檔案，它記錄上一個 Agent 的工作狀態，讓下一個 Agent 能無縫接續。建議固定格式如下：

# Current Handoff

## Last Agent
Claude Code

## Goal
Implement user authentication.

## Completed
- Added auth middleware
- Added JWT verification
- Added login endpoint
- Added integration tests

## Files Changed
- src/auth/middleware.ts
- src/auth/login.ts
- tests/auth.test.ts

## Important Decisions
- JWT instead of session cookies
- Access token lifetime: 15 minutes
- Refresh tokens stored in DB

## Failed Approaches
- Tried library X
- Abandoned because it conflicts with Edge Runtime

## Current Blocker
Refresh token rotation test fails intermittently.

## Next Action
Investigate: tests/auth.test.ts:182

## Verification
Run:

npm test -- auth
npm run typecheck

這個交接文件讓 Agent 切換時能快速掌握上下文，避免重複探索。

進階工具：Memorix 跨 Agent 記憶層

如果你需要更自動化的記憶管理，可以考慮使用專門的跨 Agent 記憶工具。目前最符合此需求的開源專案是 Memorix。

Memorix 是一個跨 Agent 的專案記憶層，明確支援 Claude Code、Codex、Cursor、Windsurf、Gemini CLI、OpenCode 等工具。它透過 MCP、Hooks、Skills 與專案規則整合到不同 Agent 中，記憶模型包含：

記憶類型	用途
Observation Memory	記錄 bug、gotcha、fix、實作筆記
Reasoning Memory	記錄設計原因、替代方案、取捨
Git Memory	記錄 commit 做了什麼
Code Memory	記錄檔案、符號、依賴關係
Compact Continuity	記錄上個 session 做到哪裡

安裝方式簡單：

npm install -g memorix
memorix setup --agent claude --global
memorix setup --agent codex --global

之後在專案目錄中，無論使用 claude 或 codex，都能查詢同一個專案記憶。

其他值得參考的方案

除了 Memorix，還有幾個專案也值得關注：

ai-memory：同樣支援 Claude Code 與 Codex，可透過 MCP 安裝，適合放在 LAN 或 homelab 伺服器上供不同客戶端使用。
agentmemory：支援多種 MCP/hook 客戶端，功能強大但架構較重。
project-memory：最簡單透明的方式，直接建立 bugs.md、decisions.md、key_facts.md 等 Markdown 檔案，並設定 CLAUDE.md 與 AGENTS.md 指向它們。
codex-agent-mem：以本地 SQLite + FTS5 + MCP 做持久化專案記憶，明確支援多種 MCP 客戶端。

最終配置建議：兩層架構

對於頻繁切換 Codex CLI 與 Claude Code 的工作流程，建議採用兩層架構：

第一層：Git 原生規範記憶（Canonical Memory）

repo/
├── AGENTS.md
├── CLAUDE.md
└── .agent/
    ├── PROJECT.md
    ├── CURRENT.md
    ├── TASKS.md
    ├── DECISIONS.md
    ├── GOTCHAS.md
    └── HANDOFF.md

這一層是規範真相，任何 Agent 都能直接讀取，不依賴特定工具、MCP、向量資料庫或 SaaS。Git 本身即可做版本控制。

第二層：Memorix（選用）

Memorix 負責自動捕捉、語意檢索、對話歷史、推理記錄、Git 歷史與交接。而 .agent/*.md 負責規範決策、當前狀態、關鍵限制與人類可讀的狀態。

重要區別：不要讓向量記憶成為唯一的真相來源。規範記憶應始終保持純文字、可版本控制。

多 Agent 交接協議

在 AGENTS.md 與 CLAUDE.md 中加入以下規則，確保交接順暢：

## Multi-Agent Handoff Protocol

This repository may be edited by Claude Code, Codex, OpenCode, or other coding agents.

Before starting work:

1. Read `.agent/CURRENT.md`.
2. Read `.agent/HANDOFF.md`.
3. Read relevant entries in `.agent/DECISIONS.md`.
4. Inspect `git status` and recent commits.
5. Do not assume the previous agent completed its task.

After meaningful work:

1. Update `.agent/CURRENT.md`.
2. Update `.agent/TASKS.md`.
3. Add durable architectural decisions to `.agent/DECISIONS.md`.
4. Add newly discovered traps to `.agent/GOTCHAS.md`.
5. Replace `.agent/HANDOFF.md` with:
   - completed
   - changed files
   - current blocker
   - next action
   - verification commands

Never store secrets, tokens, credentials, or temporary debugging output in project memory.

這條規則通常比再加十個 MCP 都重要。

結論

解決 Codex CLI 與 Claude Code 記憶不同步的最佳方法，不是嘗試同步 CLAUDE.md 與 AGENTS.md，而是建立一個以 Git 為核心的共享記憶架構。透過 .agent/ 目錄下的規範記憶檔案，加上明確的交接協議，任何 Agent 都能無縫接續工作。若需要更自動化的記憶管理，可選用 Memorix 等跨 Agent 記憶工具。

這樣的組合讓你在 Claude Code、Codex、OpenCode 之間切換時，專案記憶永遠跟著 Git 走，不再因 Agent 不同而遺失知識。