為 Claude Code 與 Codex 建立本機共享長期記憶：Hindsight 守護程式設定教學

這是一份從頭到尾的指南，教您如何在 Mac 上為 Claude Code 和 Codex CLI 建立完全本機運行的共享長期記憶。它使用 MIT 授權的代理記憶引擎 Hindsight，以本機守護程式模式運行。您的 ChatGPT 訂閱方案（模型 gpt-6-luna）負責記憶提取，資料庫儲存在您選擇的資料夾中，且只會記憶您列出的儲存庫。

這份指南是我為設定第二台筆記型電腦而編寫的執行手冊，請務必按照步驟依序操作。本文使用的版本（2026 年 10 月）包括：@vectorize-io/hindsight-coding-agents 0.8.2、hindsight-api 1.1.0、hindsight CLI 1.1.0，運行於 Apple Silicon 的 macOS 上，使用 zsh。新版本可能有所不同，請參閱 Coding Agents 文件。

完成設定後，您將擁有以下架構：Claude Code 和 Codex CLI 將透過 SessionStart、UserPromptSubmit、Stop 等掛鉤（hooks），連接到 Hindsight 守護程式（hindsight-embed），該程式運行於 http://127.0.0.1:9077。

Hindsight 守護程式內部包含嵌入式 PostgreSQL (pg0)，資料儲存在 ~/projects/hindsight-data，並使用 ChatGPT 提供者（gpt-6-luna 模型）作為大型語言模型。此外，Hindsight CLI 也將提供一個網頁控制介面（http://localhost:9999）。

兩個代理程式共用一個外掛。@vectorize-io/hindsight-coding-agents 會為每個代理程式安裝三個掛鉤、一個帶有 hindsight_* 工具的 MCP 伺服器，以及一個配套技能。每個儲存庫都有一個記憶庫，命名為 coding-agent::<repo>。

Claude Code 和 Codex 會讀取並寫入相同的記憶庫，因此在其中一個代理程式中做出的決策，在另一個代理程式中也會可見。

記憶的捕捉與回溯是自動化的。每個會話的第一個提示詞都會注入記憶綜合內容，且每個會話結束時都會寫回記憶庫。Git 歷史和簡短的程式碼庫調查會為每個新記憶庫提供初始資料，並且隨著程式碼的演進，調查會重新運行。每個儲存庫有五個知識頁面：元件圖、慣例與模式、核心概念、關鍵決策與原理，以及倡議與增強功能。此功能僅限選擇啟用，您未列出的儲存庫將永遠不會被觸及。

步驟一：先決條件。您需要安裝 Claude Code 和/或 Codex CLI，因為它們是將要連接的代理程式，可透過 claude --version 和 codex --version 檢查。Node.js (npx) 用於運行外掛安裝程式和掛鉤，請檢查 node --version。uv 用於啟動守護程式，可透過 uvx brew install uv 安裝。

最新的 Rust 工具鏈是必要的，因為 macOS 上的守護程式模式會建構一個沒有 macOS wheel 的依賴項 litellm，請執行 rustup update stable。您還需要一個允許在第三方應用程式中使用的 ChatGPT 訂閱方案，這將用於支付記憶提取費用而非 API 金鑰，並將在步驟三登入時確認。

建議安裝 hindsight CLI，以便檢查記憶庫、重新整理頁面和啟動網頁使用者介面，可透過 curl -fsSL https://hindsight.vectorize.io/get-cli 安裝。

步驟二：首先編寫設定檔。在安裝之前，請先建立 ~/.hindsight/coding-agent.json，這樣第一個會話就會遵循您的規則：{ "optInOnly" : true , "optInPaths" : [ "~/projects/my-repo" ], "pageTriggerCron" : "H * * * *" , "surveyRefreshCommits" : 20 }。

然後執行 chmod 600 ~/.hindsight/coding-agent.json。

每個鍵值的用途如下：optInOnly: true 表示記憶功能預設在所有地方都是關閉的。不在 optInPaths 中的儲存庫將不會啟用記憶功能，不會建立記憶庫，也不會保留任何內容或進行初始化。optInPaths 是路徑前綴，其中 ~ 會被展開。

~/projects/my-repo 會批准該儲存庫及其 Git 工作樹。~/projects 將批准其下的所有儲存庫，每個儲存庫都有自己的記憶庫。若要稍後新增儲存庫，只需將其路徑附加到此處，無需重新安裝。

pageTriggerCron: "H * * * *" 表示每個知識頁面最多每小時重新整理一次。這是預設值，明確寫出方便修改。H 會被替換為從記憶庫和頁面名稱雜湊而來的值，因此頁面會在不同的分鐘重新整理，而非同時進行。如果沒有新內容，則會跳過重新整理。

每次重新整理都是每個頁面進行一次大型語言模型（LLM）綜合。由於使用本機守護程式，費用來自您的 ChatGPT 訂閱方案，因此每小時重新整理是可負擔的。如果您想節省方案用量，可以使用 "H H * * *"（每天一次）。

surveyRefreshCommits: 20 表示當自上次調查以來有 20 個新提交時，用於初始化新記憶庫結構知識的程式碼庫調查會重新運行。這是預設值。在 Claude Code 中，每次調查都是一個無頭的 claude -p --model haiku 運行，費用上限為 2 美元（surveyModel、surveyBudgetUsd）。

在 Codex 中，它透過 Codex 本身運行。將其設定為 0，則每個儲存庫只會在首次開啟時調查一次。否則，活躍的儲存庫將會持續重新調查。安裝程式會在步驟五將 "serverMode": "daemon" 加入此檔案。

在公司筆記型電腦上，請僅列出允許以這種方式處理的儲存庫。使用守護程式時，記憶會保留在本機磁碟上，但提取步驟仍會將文字記錄傳送給您的 LLM 提供者（OpenAI，透過您的 ChatGPT 訂閱方案）。每台筆記型電腦也有自己的記憶，兩個守護程式不會同步。

選擇啟用清單還是所有儲存庫？設定檔支援兩種模式，每台機器選擇一種：僅選擇啟用（白名單）模式，配置為 "optInOnly": true + "optInPaths": [...]，適用於工作筆記型電腦或任何只允許處理部分儲存庫的機器。所有儲存庫（黑名單）模式，則完全移除 optInOnly 和 optInPaths，並使用 banks.<id>.disabled 排除個別儲存庫，適用於您希望所有地方都有記憶功能的個人機器。

從選擇啟用模式切換到所有儲存庫模式，意味著刪除這兩個鍵：{ "serverMode" : "daemon" , "pageTriggerCron" : "H * * * *" , "surveyRefreshCommits" : 20 , "banks" : { "coding-agent::private-notes" : { "disabled" : true } } }。

此更改會在您下一個提示詞時生效，因為掛鉤會在每次呼叫時重新讀取檔案。MCP 工具會在下一個會話中讀取此更改。

從那時起，任何儲存庫的第一個會話都會建立其 coding-agent::<repo> 記憶庫，從 Git 歷史（預設為最近 300 個提交）初始化，並運行程式碼庫調查。調查會在每 surveyRefreshCommits（20）個新提交後再次運行。

在 Claude Code 中，每次調查都是一個 claude -p --model haiku 運行，預算上限為 2 美元。現在，每個儲存庫的文字記錄都會傳送給您的提取 LLM。雖然使用本機守護程式，儲存仍保留在您的 Mac 上，但提取仍發生在提供者端。

請停用無法接受此行為的儲存庫。可選的每個儲存庫控制項位於同一檔案中，以記憶庫 ID 為鍵：{ "banks" : { "coding-agent::some-repo" : { "disabled" : true }, "coding-agent::big-monorepo" : { "gitIngest" : "full" , "retainSessions" : false } } }。

步驟三：將 Hindsight 登入您的 ChatGPT 訂閱方案。Hindsight 的 ChatGPT 提供者使用 OpenAI 官方的「使用 ChatGPT 登入」流程。Hindsight 會註冊為自己的 OAuth 用戶端，並儲存自己的憑證，這與 Codex CLI 的登入是分開的。

請執行 uvx --from hindsight-api-slim hindsight-admin chatgpt login。

此時會開啟一個瀏覽器視窗，請登入並批准方案使用。該命令會等待 127.0.0.1:1455 上的回呼，然後將 ~/.hindsight/chatgpt/credentials.json 儲存為 0600 模式。您可能會看到 sentence-transformers 未安裝的警告，這些警告來自於從 slim 套件運行管理工具，不會影響登入。

確認方式：執行 uvx --from hindsight-api-slim hindsight-admin chatgpt status，應顯示 # Signed in: yes 和 # Plan usage enabled: yes。

Token 會自動重新整理，用量會計入您的 ChatGPT 訂閱方案，並顯示在 https://chatgpt.com/settings/usage。

步驟四：在您的 shell 中固定提供者和模型。將以下內容添加到 ~/.zshrc：# Hindsight daemon: extract memories with the ChatGPT plan, model pinned export HINDSIGHT_API_LLM_PROVIDER = chatgpt export HINDSIGHT_API_LLM_MODEL = gpt-6-luna。

開啟一個新的終端機並檢查：echo " $HINDSIGHT_API_LLM_PROVIDER / $HINDSIGHT_API_LLM_MODEL "，應顯示 chatgpt / gpt-6-luna。

為何要明確設定兩者：提供者方面，當守護程式啟動時，外掛會依序選擇提供者：HINDSIGHT_API_LLM_PROVIDER，然後是 OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY、GROQ_API_KEY 中第一個設定的，如果 claude CLI 在 PATH 中，則選擇 claude-code。

明確設定可確保使用 chatgpt，即使您的環境中存在 API 金鑰。模型方面，gpt-6-luna 是目前 ChatGPT 提供者的預設模型。固定它可確保即使未來版本更改預設值，也能保持不變。運行時會每日自動更新。所有在啟動守護程式的環境中的 HINDSIGHT_API_* 變數都會傳遞給它。

若要僅針對提取使用不同的模型，請使用每個操作的變數（例如 HINDSIGHT_API_RETAIN_LLM_MODEL）。

步驟五：以守護程式模式安裝外掛。從新的終端機執行：npx @vectorize-io/hindsight-coding-agents install claude-code codex --server daemon。輸出應包含 local extraction will use chatgpt (from HINDSIGHT_API_LLM_PROVIDER)。

安裝程式會進行以下操作：對於 Claude Code，三個掛鉤會合併到 ~/.claude/settings.json 中，MCP 伺服器會透過 claude mcp add（使用者範圍）註冊，技能會安裝在 ~/.claude/skills/hindsight-coding-agent。

對於 Codex CLI，三個掛鉤會合併到 ~/.codex/hooks.json 中，[mcp_servers.hindsight] 會寫入 ~/.codex/config.toml，技能會安裝在 ~/.agents/skills/hindsight-coding-agent。

共享運行時會複製到 ~/.hindsight/coding-agents，並且 "serverMode": "daemon" 會寫入 ~/.hindsight/coding-agent.json。

Codex 還需要其掛鉤功能旗標。如果 ~/.codex/config.toml 沒有 [features] 部分，安裝程式會為您添加。如果該部分已存在，安裝程式會列印提醒，您需要自行添加 hooks = true 這行。安裝程式接受 hooks = true 或舊的拼寫 codex_hooks = true，某些文件仍在使用。

請注意：此外掛是透過 npx 安裝的，而非透過 Claude Code 市場，因此不會列在 /plugin 下。請使用 npx @vectorize-io/hindsight-coding-agents install | uninstall | update | stats 來管理它。

如果安裝了舊的每個代理程式 Hindsight 外掛（例如 hindsight-memory），請先將其解除安裝，以確保只有一組掛鉤運行。

步驟六：啟動並驗證守護程式。SessionStart 和 Stop 掛鉤會在埠號 9077 空閒時，自行在背景啟動守護程式。請手動啟動一次，以便在您觀察時完成緩慢的首次運行（下載、Rust 建構、模型載入）：node ~/.hindsight/coding-agents/dist/daemon-start.js --harness claude-code。

驗證方式：執行 lsof -iTCP :9077 -sTCP :LISTEN，應顯示 localhost:9077 上有一個 Python 程序。然後執行 PID = $( lsof -tiTCP :9077 -sTCP :LISTEN ) 和 `ps eww -p $PID | tr ' ' '

' | grep '^HINDSIGHT_API_LLM_'，應顯示 # HINDSIGHT_API_LLM_PROVIDER=chatgpt 和 # HINDSIGHT_API_LLM_MODEL=gpt-6-luna`。在底層，此外掛會要求 hindsight-embed 啟動伺服器。

hindsight-embed 會運行 hindsight-api --idle-timeout 0 --port 9077，並搭配一個由 pg0 管理的嵌入式 PostgreSQL 18 實例。

步驟七：在守護程式設定檔中固定提供者。守護程式還有一個每個設定檔的環境檔案 ~/.hindsight/profiles/coding-agent.env，它會在首次啟動時建立。請確保其內容與您的 shell 設定一致。這樣，即使是從不載入 ~/.zshrc 的環境（例如從 Dock 開啟的代理程式）啟動的守護程式，也能使用 ChatGPT 和 gpt-6-luna。

請執行 f = ~/.hindsight/profiles/coding-agent.env，然後 cp " $f " " $f .bak"，再執行 grep -n '^HINDSIGHT_API_LLM_' " $f " 以檢查其目前內容。

編輯該檔案，使其包含以下兩行，並移除任何 HINDSIGHT_API_LLM_API_KEY= 行：HINDSIGHT_API_LLM_PROVIDER = chatgpt 和 HINDSIGHT_API_LLM_MODEL = gpt-6-luna。最後執行 chmod 600 " $f " " $f .bak"。

步驟八：將記憶庫放置到您想要的位置。預設情況下，資料庫位於 ~/.pg0/instances/hindsight-embed-coding-agent/data。Hindsight 沒有設定此路徑的選項，但 pg0 會遵循符號連結。以下是如何將其移動到 ~/projects/hindsight-data 的方法。

首先停止守護程式及其 PostgreSQL。切勿複製正在運行的資料庫。執行 kill $( lsof -tiTCP :9077 -sTCP :LISTEN )，然後等待 PostgreSQL 退出且 postmaster.pid 消失，可透過 pgrep -f 'postgres -D .*hindsight-embed-coding-agent' || echo "postgres stopped" 和 ls ~/.pg0/instances/hindsight-embed-coding-agent/data/postmaster.pid 2>/dev/null || echo "clean shutdown" 確認。

接著複製、驗證，然後替換為符號連結：SRC = ~/.pg0/instances/hindsight-embed-coding-agent，DST = ~/projects/hindsight-data。執行 mkdir -p " $DST "，然後 cp -a " $SRC " " $DST /"（-a 會保留 PostgreSQL 所需的 0700 權限）。

執行 diff -rq " $SRC " " $DST /hindsight-embed-coding-agent" && echo "identical" 以驗證是否相同。最後執行 mv " $SRC " " $SRC .old" 和 ln -s " $DST /hindsight-embed-coding-agent" " $SRC "。

重新啟動並確認 PostgreSQL 現在從新資料夾運行：node ~/.hindsight/coding-agents/dist/dae。