Skip to content

README.zh-TW.md

Latest commit

 

History

History
176 lines (132 loc) · 15.5 KB

README.zh-TW.md

File metadata and controls

176 lines (132 loc) · 15.5 KB
Raw

🌐 English | 繁體中文

MeMesh

讓 AI 寫程式代理在本機共用記憶並協作。
一個 SQLite 檔案。不用 Docker，不用雲端。

npm MIT Node MCP

它能做什麼

換了 session 或寫程式代理（agent）後，你可能得重述先前的決策、解釋同一套架構，或重新找出已修過的問題。

MeMesh 讓代理在本機共用記憶與交換訊息。主要用途是跨 session 保存你的偏好、決策與經驗；在代理間傳送派工、問題、進度與結果；留下工作交接，讓後續 session 有脈絡可查。Claude Code 和 Codex 是主要例子；Cursor 與其他 MCP 用戶端也能透過文件列出的整合方式使用。自動擷取與傳遞能力取決於下方的 host 整合。

   you work with the agent
            |
            v
   +------------------+      +------------------+
   |  Claude Code     |      |  Claude Code     |
   |  capture         |      |  recall          |
   |  sessions,       | ---> |  at session      |
   |  commits, fixes  |      |  start and       |
   |  (automatic)     |      |  before edits    |
   +------------------+      +------------------+
            |                         ^
            v                         |
   +----------------------------------------+
   |  ~/.memesh/knowledge-graph.db           |
   |  decisions, lessons, links between them |
   +----------------------------------------+
  • 在適當時機記錄、提醒與防護。 MeMesh 的 Claude Code 與 Codex 整合共提供 10 個 hook command：其中 9 個 Claude Code hook 分別在開新對話、改檔案前、git commit 後、計畫核准或你回答問題後、Claude 停下來時（兩次：記錄這次對話內容，以及在還有訊息未讀時擋下結束）、對話被壓縮前、你說「記下來」時（聽得懂 5 種語言），以及執行可能重犯已接受教訓的危險指令前運作。計畫/問題與「記下來」hook 只會提醒 agent 呼叫 remember；第 10 個 command 同時處理 Codex SessionStart 與 SessionEnd，註冊並退場符合資格的一般 Codex CLI session。
  • 所有工具共用一份記憶。 今天在 Claude Code 存的決定，明天 Codex 或 Cursor 也用得到。
  • agent 之間可以留言。 本機的耐久收件匣可跨重啟保存；在 macOS 或 Linux 上，裝有 MeMesh plugin 的一般 Codex CLI thread 可保留有界的回合後原生 queue 視窗，並在同一 thread 恢復時取用已被接受的訊息。
  • 留下工作交接。 Claude Code 可把最後一則有實質內容的回覆留給同一專案的下個 session。用 task_state 記錄已明確說出的目標、下一步、阻礙或完成項目，再用 message 將證據位置或待處理問題送給確切收件者。
  • 有儀表板 可以瀏覽全部內容：4 個分頁、11 種語言，在 http://localhost:3737/dashboard。

支援哪些平台

平台 怎麼接 說明
Claude Code plugin：hook、MCP 工具、/memesh skill 自動記錄與提醒都有
Codex CLI Plugin，或 MCP server（memesh-mcp） 零設定 plugin 安裝，或 codex mcp add memesh -- memesh-mcp
Gemini CLI MCP server（memesh-mcp） gemini mcp add -s user memesh memesh-mcp
Cursor、Cline 與其他 MCP 用戶端 MCP server（memesh-mcp） 把用戶端指向 memesh-mcp；若用戶端不回報 workspace root，還要設 MEMESH_PROJECT_ROOT
Hermes Agent 原生記憶 plugin docs/platforms/hermes-agent.md
OpenClaw 原生記憶 plugin 只有原始碼，尚未發佈或完成真實環境測試：docs/platforms/openclaw.md
你自己的程式或腳本 memesh serve 提供的 HTTP API docs/platforms/universal.md
ChatGPT、Gemini 網頁版等線上聊天 透過你自己架的本機橋接走 HTTP API docs/platforms/README.md

Claude Code 的 9 個 hook 提供自動記錄、回想、提醒與防護。Codex plugin 會載入同一份 hook 設定：在 Codex 允許執行這個 plugin 的 hook 之後，它的 SessionStart hook 會注入同樣的記憶區塊，並為符合資格的一般 CLI thread 啟動傳訊 companion。其他 hook 在 Codex 下是否會執行，目前尚未驗證。使用 Codex plugin 時，只有在沒看到這個區塊時才呼叫 briefing；只有 MCP 的用戶端請在 session 開始時呼叫 briefing。需要特定資訊時再呼叫 recall。

回想與擷取維持本機且可預測：SQLite FTS5 搜尋、明確的記憶工具與規則式 hooks。這個版本不設定也不呼叫 LLM、embedding 或 vector provider。舊版留下的 provider 設定仍保留在磁碟上但會被忽略；memesh doctor 只會列出頂層欄位名稱，不會讀取或印出它們的值。

怎麼安裝

Plugin 與 npm-global CLI 共用同一個資料庫。Claude Code 使用者通常同時安裝 Claude plugin 與 CLI；Codex 可使用自己的 plugin，或使用 CLI 提供的 MCP server。

   Claude Code chat                Terminal, Codex, Cursor
         |                                  |
         v                                  v
   +-----------------+              +------------------+
   | A: plugin       |              | B: npm global    |
   | /plugin install |              | npm install -g   |
   | hooks + tools   |              | memesh CLI       |
   | + /memesh skill |              | + memesh-mcp     |
   +-----------------+              +------------------+
         |                                  |
         +---------------+------------------+
                         v
            ~/.memesh/knowledge-graph.db
               (one file, both paths)

A. 在 Claude Code 裡裝（hook、工具和 /memesh skill 會自動設定好）：

/plugin marketplace add PCIRCLE-AI/memesh
/plugin install memesh@pcircle-memesh

重開 Claude Code。下次對話開頭會出現 ◉ MeMesh。

B. 在終端機裝（需要 Node 22.13 以上）：

npm install -g @pcircle/memesh
memesh doctor          # 檢查本機安裝健康狀態並列出修復方式
memesh install-hooks   # 沒裝 A 才需要：幫 Claude Code 接上 hook，不動你原本的設定

Codex 零設定安裝：執行 codex plugin marketplace add PCIRCLE-AI/memesh 與 codex plugin add memesh@pcircle-memesh。手動替代方案是 codex mcp add memesh -- memesh-mcp。Cursor：把 { "mcpServers": { "memesh": { "command": "memesh-mcp" } } } 加進 ~/.cursor/mcp.json。若用戶端不回報 workspace root，要在 server 的環境變數設 MEMESH_PROJECT_ROOT（專案的絕對路徑），或每次呼叫都帶 project 參數。Dashboard 的 doctor 提醒可執行它能驗證的兩種可復原本機修復；單純開啟頁面不會自動改檔案。

裝了 plugin 不等於有 memesh 指令。 /plugin install 之後，在終端機打 memesh 會出現 command not found，要再跑 npm install -g @pcircle/memesh 才會有。只在 Claude Code 對話裡用的話，裝 A 就夠了。

更新： Claude Code plugin 用 memesh upgrade-plugin（沒有 CLI 時可用 npx @pcircle/memesh upgrade-plugin）；Codex plugin 用 codex plugin marketplace upgrade pcircle-memesh && codex plugin add memesh@pcircle-memesh；npm-global CLI 用 memesh update。想讓 AI 幫你裝？ 把 llms-install.md 丟給它。

怎麼開始

memesh remember "登入功能用 OAuth 2.0 加 PKCE"
memesh recall "登入"
# -> 找到那則筆記

memesh briefing        # agent 對這個專案知道多少
memesh serve           # 啟動本機 server 並印出儀表板網址

讓 memesh serve 保持執行，再開啟它印出的網址。在 Claude Code 裡使用記憶工具時連終端機都不用開：在對話裡說「記下來」就好；有內容可看之後，開新對話時也會自動先收到摘要。

有了記憶之後，兩件值得知道的事：

  • forget 是把整筆記憶封存，不是刪掉。新的記憶可以蓋過舊的。
  • 執行中的 agent 可呼叫 work_package，準備一份日曆摘要，或從最新且符合資格的近期 Claude Code transcript 取得有界限的可見輪次。Transcript 模式要求 client 提供唯一符合的 MCP file root；root 缺失或不明確，以及有界掃描失敗時都會封閉失敗。提交會保留遮蔽後的來源輪次，且只暫存為待人工審核提案；agent 不能自行套用或拒絕，MeMesh 也不會呼叫 provider。確切的探索上限請見 API reference。

交接時，Claude Code 的 Stop hook 會把最後一則有實質內容的回覆存成可替換的專案筆記。近期且受信任的筆記會在下個 Claude Code session 和任何用戶端的 briefing 中排在其他記憶之前；它只是供核對的提示，不能保證工作自動接續。只用 task_state 記錄確實知道的工作狀態，並用 message 將證據位置或待處理問題送給確切收件者（代理訊息指南）。訊息可供後續補收，但傳遞、擷取或原生 queue 接受都不代表對方完成工作。

briefing 會優先顯示專案最近的決策，並另外選取最多五則專案教訓。交接筆記、顯示的任務狀態、排序後的記憶、full 層級的全域記憶，以及注入的索引，共用一個 4000 字元的記憶區塊上限。索引若提示還有未列出的記憶，請用 recall；memesh briefing --index 的獨立索引仍採用自己的 40 行／3072 位元組上限。

完整指令與工具說明：docs/api/API_REFERENCE.md。架構：docs/ARCHITECTURE.md。參與開發：CONTRIBUTING.md。

全部 12 個記憶與協作工具

工具 做什麼
work_package 準備一份有界限且不受信任的日曆摘要，或從唯一符合的 MCP workspace root 準備 Claude Code transcript 套件；提交一份嚴格結果等待人工審核，或延後而不產生耐久變更。Transcript 提交會保留有界且已遮蔽的來源輪次；不會暴露檔案路徑、隱藏推理、provider、embedding 或 vector 資料。
remember 用觀察、關係和標籤儲存知識；也可以只給一段自由文字（note），標題、觀察和名稱會自動推導出來；replace 則是直接改掉既有的那一筆；新的決策（decision）一定要附 why（為什麼這樣決定，以及什麼情況下就不成立了）
recall 本機 FTS5 搜尋，包含多因素評分（相關性、近期性、頻率、信心、回憶影響）
forget 軟歸檔（永不刪除）或移除特定觀察
export 以 JSON 備份、搬遷記憶，或在相容代理之間轉移
import 匯入記憶，包含合併策略（跳過 / 覆寫 / 追加）
learn 記錄來自錯誤的結構化教訓（錯誤、根本原因、修復、預防）
task_state 讀取或記下工作進度——目標、下一步、卡住的地方、剛完成的事
briefing 提供給任何 MCP client 的工作拓撲——符合條件的專案交接筆記會在所有層級排在其他記憶之前；minimal 接著顯示本專案的決定、教訓、已知事實與近期活動，以及不屬於任何專案的記憶，standard 加上新鮮任務狀態和有界記憶索引，full 再加入其他專案與全域記憶；確切的 project + recipient 才會顯示該收件者尚未擷取的訊息
user_patterns 分析你的工作模式——時間表、工具、優勢、學習領域
improvement 將有證據來源的產品改善送交人類審核，或讀取其狀態；agent 不能自行接受或拒絕
message 先找出活動 agent，再交換確切收件者的不受信任訊息。Durable JSON payload 上限 64 KiB；完整 native envelope 上限 16 KiB，並區分 native_message_too_large 與 recipient_unavailable。原生接受、探索、輪詢與擷取都不代表 ACK 或 workflow disposition

細節

評分排序 — 結果依相關性（30%）+ 近期性（25%）+ 頻率（18%）+ 信心（17%）+ 回想影響（10%）排序。

agent 訊息的完整規則（完整說明：docs/platforms/agent-messaging.md）：

  • 今天就能做的：MCP、HTTP 或 CLI sender 可把一份 JSON 編碼後不超過 65,536 UTF-8 bytes（64 KiB）的不受信任 payload 耐久化送給一個指定的本機 recipient。接收端可另行擷取、在重啟後用 opaque cursor 補收，並把 intake、acknowledgement、workflow disposition 與 host activation 分開記錄。
  • 啟用 MeMesh Codex plugin 後，每個具有有效 thread identity 與現有工作目錄、並新啟動或恢復的一般 Codex CLI thread，都會自動以 thread-scoped identity 註冊，不需要手動執行 agent setup。SessionStart 會啟動 owner-private companion；SessionEnd 保留 45 秒的有限 idle queue 視窗，resume 會取代前一個 exact generation，逾時則移除 registration。在 idle 視窗內被 queue 接受的訊息，會在同一 thread resume 時以簡短通知出現，agent 再從 inbox 擷取正文；這不代表已停止的 UI 被自動喚醒。只有某個 workspace 需要穩定的命名 principal 時，才需選用 memesh agent setup codex-session。包含 routing metadata 與 payload 的完整 native envelope 另有 16,384 bytes（16 KiB）上限。exact-session send 只有在原生 queue 接受後才成功；完整 envelope 過大時回報 native_message_too_large，sender 無法連到本機 router 時回報 router_unreachable，其他無法使用或拒絕的 session 則回報 recipient_unavailable。不論 sender 或 recipient 失敗，scope 相符的 recovery data 仍會保留，Principal target 在無法原生傳遞時仍保有 durable store-and-forward。原生接受不代表 acknowledgement 或 workflow disposition，原生訊息不得包含 secrets。
  • 已停止、缺失或斷線的 Codex session 不會被喚醒，也不會被別的對話頂替；失敗的 exact-session 原生傳遞不會自動重播，sender 必須明確重試。scope 相符的 recovery data 仍會保留，memesh message storage report 可以看目前存了什麼。原生傳遞目前只支援 macOS 和 Linux。
  • 這條文件化的原生路徑涵蓋一般 Codex CLI。除非確切且正在執行的 session 出現在 message discover，否則不要假設 Codex Desktop 或未連接的 task 已註冊；這是證據邊界，不代表這些 host 一律不相容。
  • Claude Channel 與自動註冊的 Codex 配對時，不需要在兩邊之間複製 --project 值：各 host 從自己的工作目錄（Claude）或 --workspace（Codex）推得自己的 routing project，所以在同一個 repository 啟動兩者，就會自動落在同一個 project。

MIT 授權