Codex CLI 與 Claude Code 專案記憶同步終極指南

annie · August 11, 2026, 4:56pm

在同一專案同時使用 Codex CLI 與 Claude Code，卻因記憶不同步而困擾？本文深入解析三個記憶層級，提供從官方支援到第三方工具的完整解決方案，讓你告別任務中斷、提升開發效率。

當你在同一個專案資料夾同時運行 Codex CLI 與 Claude Code，最大的痛點莫過於兩者的記憶各自為政。這並非工具設計缺陷，而是因為它們的記憶機制分屬不同層級，且官方設計上本來就沒有跨 agent 同步的意圖。本文將拆解三個記憶層級，並提供從零依賴到第三方工具的完整落地策略。

釐清問題：記憶不同步的三個層級

在同一個資料夾操作時，記憶不同步其實是三種不同機制的混雜：

層級	Claude Code	Codex CLI	是否可共用
L1 靜態指令（人寫的規則）	`CLAUDE.md`、`.claude/rules`	`AGENTS.md`、`AGENTS.override.md`	可以，官方支援
L2 專案狀態／任務紀錄	無原生格式	無原生格式	需自建（repo 內檔案）
L3 自動生成記憶（agent 自己寫的）	Auto memory：`~/.claude/projects/<project>/memory/MEMORY.md`	Memories：`~/.codex/memories/`	不可共用

L3 是誤解的來源。Claude Code 的 auto memory 依 git repo 推導路徑、存在使用者 home 下，且官方明說是 machine-local、不跨機器共享（參見 Claude Code memory 文件）。Codex 的 memories 同樣寫在 ~/.codex/memories/，官方定義為「generated state」，並明確指出不要將手動編輯這些檔案當成主要控制面，該使用 AGENTS.md。Codex memories 預設是關閉的，需 [features] memories = true 才能啟用。

核心理念：不要試圖同步 L3。正確策略是將「必須共享的知識」從 L3 擠出來，強制落到 L1 + L2 的 repo 內檔案。

L1：收斂靜態指令為單一來源

以 `AGENTS.md` 為唯一真相，`CLAUDE.md` 只做橋接

Claude Code 官方文件明確只讀 CLAUDE.md、不讀 AGENTS.md，並直接給出建議寫法：

<!-- CLAUDE.md -->
@AGENTS.md

## Claude Code 專屬
- src/billing/ 底下的變更請先用 plan mode

@path import 在 session 啟動時展開，等同內嵌。若完全不需要 Claude 專屬段落，也可以使用 symlink：

ln -s AGENTS.md CLAUDE.md

注意 Windows 建立 symlink 需要 Administrator 或 Developer Mode，跨平台團隊一律用 @AGENTS.md import。另外若 import 的路徑解析到工作目錄之外（例如 @~/.claude/xxx.md），Claude Code 首次會跳出核准對話框。

Claude Code v2.1.213 之後還有 /import 指令，可把 Codex 的 AGENTS.md、MCP servers、commands、skills 一次性帶進來——但那是 one-time copy，不是持續同步，長期還是靠 @AGENTS.md。

反方向是陷阱：不要指望 Codex 讀 `CLAUDE.md`

Codex 確實有 project_doc_fallback_filenames 可以加入自訂檔名，但官方 AGENTS.md 指南說明其探索規則是：每個目錄依序檢查 AGENTS.override.md → AGENTS.md → fallback 名單，且每個目錄最多只納入一個檔案。只要 AGENTS.md 存在，CLAUDE.md 就永遠不會被讀到。這條路會製造「以為同步了、其實沒有」的假象。

同時要注意 Codex 的 project_doc_max_bytes 預設 32 KiB，超過就截斷；Claude Code 則建議單一 CLAUDE.md 控制在 200 行以內以維持遵循率。共用檔案要為兩邊的上限一起瘦身。

L2：共享任務日誌的真正解方

「它們做過什麼任務」這件事，任何一方的原生記憶都不會讓對方看到。唯一穩定做法是在 repo 中建立一個雙方都被指示要讀寫的目錄：

.agent/
├── STATE.md        # 現在正在做什麼、下一步、blocker（每次 session 結束覆寫）
├── JOURNAL.md      # append-only：日期 / agent 名 / 動作 / 結果
├── DECISIONS.md    # ADR 格式的決策紀錄，只增不改
└── GOTCHAS.md      # 踩過的坑

然後在 AGENTS.md 中寫成硬規則（Claude 端透過 @AGENTS.md 自動繼承）：

## Shared agent memory protocol
1. 開工前先讀 .agent/STATE.md 與 .agent/JOURNAL.md 最後 30 行。
2. 收工前必須 append 一筆 JOURNAL 條目，格式：
   ## YYYY-MM-DD HH:MM | <claude-code|codex> | <task>
   - Changed: <files>
   - Result: <pass/fail>
   - Next: <handoff note>
3. 架構或依賴決策一律寫進 .agent/DECISIONS.md，不要只留在對話裡。
4. .agent/ 內容優先於你自己的 memory；衝突時以 .agent/ 為準。

用 hooks 強制執行

關鍵補強：用 hooks 強制執行，而不是靠模型自律。Claude Code 官方文件強調 CLAUDE.md 是 context 而非強制設定，要保證某件事一定發生就要用 hook。兩邊都有 hook 系統可掛：

Claude Code hooks：可在 SessionStart 注入 .agent/STATE.md、在 Stop/SessionEnd 寫回 JOURNAL
Codex hooks：同樣支援 prompt 前注入與 session 結束後處理

同時建議把 .agent/JOURNAL.md 設計成 append-only，避免兩個 agent 同時跑時互相覆寫（last-write-wins 會吃掉紀錄）。

附加技巧：把 Claude Code 的 auto memory 搬進 repo

Claude Code 有 autoMemoryDirectory 設定，可以把 auto memory 目錄改到自訂位置：

// .claude/settings.local.json
{ "autoMemoryDirectory": "/absolute/path/to/repo/.agent/claude-memory" }

限制：值必須是絕對路徑或以 ~/ 開頭（不接受相對路徑，所以無法寫成可 commit 的通用設定），且寫在 project settings 時要先通過該資料夾的 workspace trust 對話框。這能讓 Codex 至少「讀得到」Claude 累積的筆記，但不是雙向同步——Codex 不會往裡面寫。當作單向可見性改善，不要當成解法主體。

L3：可使用的跨 agent 共享記憶服務

以下都同時明確支援 Claude Code 與 Codex CLI（透過 MCP + hooks）：

專案	語言	機制	適合情境
rohitg00/agentmemory	TypeScript	本地 memory server（:3111）+ MCP + hooks + 15 個 SKILL.md	目前生態最完整、最接近 turnkey 的選擇
basicmachines-co/basic-memory	Python	MCP server，知識以純 Markdown + knowledge graph 儲存	想要記憶是人類可讀 Markdown、可 Obsidian 開的
majiayu000/remem	Rust	單一 CLI + hooks + MCP，SQLite/SQLCipher	重視加密與稽核、想要單一 binary
jmeiracorbal/mnemo	Go	本地 SQLite + MCP tools + hooks	想要最小依賴、Go 單檔部署
MarceloCaporale/codex-agent-mem	Python	SQLite + FTS5 壓縮 context pack	Codex 為主、Claude 為輔的組合
Jessinra/Lorekeeper	Python	self-improving memory，MCP server	想要記憶會自我修剪／改寫
focaxisdev/deja-vu	TypeScript	repo-local Markdown memory，刻意不用 DB／向量庫／託管服務	與上面 L2 手作方案最接近，但已成套
DeusData/codebase-memory-mcp	Go	把 codebase 索引成 knowledge graph	解決「程式碼結構記憶」而非「任務記憶」
swarmclawai/swarmvault	TypeScript	local-first knowledge graph / RAG store	記憶量大、想長期沉澱成 wiki

補充參考清單：github.com/topics/codex-memory、github.com/topics/claude-code-memory。

選型提醒： 這類專案多為單人維護、star 數落差大（從 3 到 500+），版本推進很快。若你偏好可攜、不綁供應商的架構，MCP server 若需要常駐 daemon 就等於每台機器多一個要照顧的行程。建議先跑 L1 + L2（零依賴、純 repo 檔案、跟著 git 走），確認痛點仍在再引入 L3。

建議落地順序

今天就做：AGENTS.md 成為唯一真相 → CLAUDE.md 只放 @AGENTS.md + Claude 專屬段落。
今天就做：建 .agent/{STATE,JOURNAL,DECISIONS,GOTCHAS}.md，把讀寫協議寫進 AGENTS.md，commit 進 repo。
這週做：兩邊各掛一組 hook——session 開始注入 STATE.md，session 結束 append JOURNAL.md。這一步把「靠模型記得」換成「靠 harness 保證」。
視情況：若 .agent/ 長大到需要語意檢索，再從上表挑一個接 MCP；優先選記憶落地為 Markdown 的（basic-memory、deja-vu），保留可移植性。
不要做：不要試圖同步 ~/.claude/projects/.../memory/ 與 ~/.codex/memories/；不要用 project_doc_fallback_filenames 讓 Codex 讀 CLAUDE.md；不要把 secrets 放進任何一層記憶。

總結

同步 Codex CLI 與 Claude Code 的專案記憶，關鍵在於理解記憶的三個層級並對症下藥。L1 的靜態指令可透過 @AGENTS.md import 或 symlink 輕鬆共用；L2 的任務日誌需要自建 agent 目錄與 hooks 強制執行；L3 的自動生成記憶則不應強求同步。先從零依賴的 L1 + L2 方案開始，確實有需要再評估第三方工具，如此才能既解決痛點，又維持架構的簡潔與可攜性。