@pcircle/memesh 4.5.1 → 4.6.0

package/README.md

@@ -1,9 +1,9 @@
-🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
+🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [Deutsch](README.de.md)
 
 <p align="center">
-  <h1 align="center">MeMesh LLM Memory</h1>
+  <h1 align="center">MeMesh</h1>
   <p align="center">
-    <strong>Local memory for Claude Code and MCP coding agents.</strong><br />
+    <strong>Agentic memory for coding agents.</strong><br />
     One SQLite file. No Docker. No cloud required.
   </p>
   <p align="center">
@@ -16,32 +16,40 @@
 
 ---
 
-**MeMesh** — the open-source **memory layer** for Claude Code & MCP agents. One SQLite file. No cloud. Plugs into any LLM.
+**MeMesh** — open-source **agentic memory** for Claude Code & MCP coding agents: captured from the agent's real work, injected at the moment it acts, kept honest when it contradicts itself. One SQLite file. No cloud.
 
-## 95.60% R@5 on LongMemEval-S — beats Mem0 by 46 points
+## Install
 
-MeMesh's retrieval is **FTS5 alone** — no LLM, no embeddings on the hot path. Measured against the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark (500 questions, MIT-licensed):
+**In Claude Code** — type these in the chat (hooks, memory tools and the `/memesh` skill are wired automatically):
 
-| System | R@5 | Source |
-|---|---|---|
-| **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
-| MemPalace | 96.6% | Vendor self-report |
-| Supermemory | ~82% | Vendor estimate |
-| Zep | 63.8% | LongMemEval paper |
-| Mem0 | 49.0% | LongMemEval paper |
+```
+/plugin marketplace add PCIRCLE-AI/memesh
+/plugin install memesh@pcircle-memesh
+```
 
-Re-runnable in ~10 seconds. Full instructions, dataset SHA256, raw per-question results, and known-failure analysis: [`benchmarks/longmemeval/REPRODUCE.md`](benchmarks/longmemeval/REPRODUCE.md).
+Restart Claude Code. A `◉ MeMesh` status line at the top of your next session means it is capturing.
 
----
+**In a terminal** — the `memesh` CLI, the dashboard, and the `memesh-mcp` server for Codex / Gemini / Cursor (needs [Node 22.13+](https://nodejs.org)):
+
+```bash
+npm install -g @pcircle/memesh
+memesh doctor        # verifies this install end to end
+```
+
+Most Claude Code users eventually want **both** — they share one database and never conflict. Details, other agents, and upgrades: [Get Started](#get-started-in-60-seconds).
+
+> **Installing via an AI agent?** Point it at [llms-install.md](llms-install.md) — deterministic steps with per-step verification. Once installed, [AGENTS.md](AGENTS.md) tells it how to use memesh well.
 
 ## The Problem
 
-Your coding agent forgets between sessions. Every architecture decision, bug fix, failed test, and hard-won lesson has to be re-explained. Claude Code starts fresh, re-discovers old constraints, and burns context on things it should already know.
+Your coding agent doesn't just forget facts between sessions — it **repeats work**. It re-proposes the approach you rejected last month, trips over the same failing test, re-discovers the constraint that broke production in March, and asks you to re-explain the architecture it helped design.
+
+That's not a chat-history problem; it's an agent-memory problem. What needs to survive between sessions is the *work*: decisions with their reasons, failures with their fixes, and the links between them.
 
-**MeMesh gives coding agents persistent, searchable, evolving local memory.** Install with npm, memory lives in `~/.memesh/knowledge-graph.db`, plug into Claude Code or any MCP-compatible client.
+**MeMesh is that memory.** Hooks capture it from what the agent actually does (sessions, commits, failures — not manual notes), recall injects it at the moment the agent acts (session start, before file edits), and the knowledge-graph layer keeps it honest over time (supersession, LLM-judged conflict detection). Install with npm, memory lives in `~/.memesh/knowledge-graph.db`, plug into Claude Code or any MCP-compatible client.
 
 > [!IMPORTANT]
-> Actively developed — features may change between releases. [Open an issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues) for bugs or feature requests.
+> Actively developed — features may change between releases. [Open an issue](https://github.com/PCIRCLE-AI/memesh/issues) for bugs or feature requests.
 
 ---
 
@@ -65,7 +73,7 @@ flowchart TB
     subgraph paths["Two install paths"]
       direction LR
       A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
-      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
     end
 
     DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
@@ -111,12 +119,14 @@ If you only use memesh through Claude Code chat (never type `memesh` in a termin
 If you use Claude Code, install MeMesh as a plugin from inside the CLI:
 
 ```
-/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin marketplace add PCIRCLE-AI/memesh
 /plugin install memesh@pcircle-memesh
 ```
 
 Claude Code wires hooks, skills, and the MCP server automatically. You get in-session auto-capture, proactive recall, the `/memesh` skill (remember / recall / learn / forget) inside the Claude Code conversation, and `remember` / `recall` / `forget` / `learn` available as MCP tools to the agent.
 
+**Verify it:** restart Claude Code and start any session. A status line like `◉ MeMesh ready · no memories for "your-project" yet` appears at the top — that line IS the plugin working; no separate command needed. (Once you have memories, it shows counts instead.)
+
 The MCP server runs directly from the plugin's bundled compiled output — no `npx` lookup, no build step, and nothing to compile. memesh stores its data through `node:sqlite`, which is part of Node itself (22.13+), so a Node upgrade cannot leave it with a binary built for the wrong runtime.
 
 > **This installs the plugin only.** You can run CLI commands via `npx @pcircle/memesh <command>` if you absolutely don't want a global install, but typing plain `memesh` in a terminal will report `command not found`. To get a real shell `memesh` command, also run **Option B** below — both paths coexist and share the same memory database. The "Install paths at a glance" diagram above covers this.
@@ -137,11 +147,17 @@ npm install -g @pcircle/memesh
 
 If you installed via **Option A** (`/plugin install memesh@pcircle-memesh`), skip this step — Claude Code wires plugin hooks automatically.
 
-If you installed via **Option B** (`npm install -g`), the CLI is on your PATH and the MCP server is registered, but the Claude Code session hooks are not auto-wired. Without them you can still use `memesh remember` / `recall` manually, but the **auto-capture loop** (sessions → lessons → recall on next session) is silent.
+If you installed via **Option B** (`npm install -g`), the CLI is on your PATH — but nothing is wired into Claude Code yet: the npm package deliberately runs no install scripts, and the plugin (Option A) is what registers the MCP server and hooks inside Claude Code. What the npm path can wire by itself is the session hooks. Without them you can still use `memesh remember` / `recall` manually, but the **auto-capture loop** (sessions → lessons → recall on next session) is silent.
+
+```bash
+memesh setup                 # detects Claude Code / Codex / Gemini, offers to wire each, verifies
+```
+
+Or the individual steps by hand:
 
 ```bash
 memesh install-hooks         # adds memesh's hooks to ~/.claude/settings.json
-memesh doctor                # verifies "Hooks wired into Claude Code" passes
+memesh setup --check         # machine-level verification: reads the hosts' own config, changes nothing
 ```
 
 The hooks coexist with any custom hooks you already have under `~/.claude/hooks/` — `install-hooks` writes additive entries and never overwrites yours. To remove later: `memesh uninstall-hooks`.
@@ -167,6 +183,18 @@ gemini mcp list      # memesh should show "Connected"
 
 > **Use `memesh-mcp`, not `npx -p @pcircle/memesh`, as the configured command.** `npx -p` resolves to the *local* package whenever the host's working directory is inside a checkout of this repository, silently running whatever state that working tree is in instead of the installed release.
 
+### Native integration: Hermes Agent
+
+**Hermes Agent** (NousResearch) has a first-party `MemoryProvider` plugin system — MeMesh integrates at the same tier as Hermes's own built-in memory backends (honcho, mem0, hindsight), not as an HTTP bridge. Unlike MCP mode where you manually call tools, Hermes's provider system runs `recall`/`remember` automatically on every turn.
+
+The integration maps Hermes's `prefetch()` and `sync_turn()` hooks directly onto MeMesh's HTTP API. Complete guide with provider code structure, config, and four real pitfalls from a live deployment: **[docs/platforms/hermes-agent.md](docs/platforms/hermes-agent.md)**
+
+### Native integration: OpenClaw
+
+**OpenClaw** has a first-party memory-capability plugin system — MeMesh integrates as a native memory provider at the same tier as OpenClaw's own built-in backends (LanceDB), not as an HTTP bridge. The plugin registers via `api.registerMemoryCapability()` and exposes `memory_recall`/`memory_store`/`memory_forget` tools plus automatic recall on the `before_prompt_build` hook.
+
+**Key difference from Hermes**: OpenClaw's auto-capture is threshold-gated (max 3 memories/turn when triggered), not every-turn. The integration maps onto MeMesh's HTTP API (`/v1/recall`, `/v1/remember`, `/v1/forget`). Full TypeScript plugin contract, config shape, and pitfalls: **[docs/platforms/openclaw.md](docs/platforms/openclaw.md)**
+
 ### Step 2: Store a decision
 
 > The bash examples below assume `memesh` is on your `PATH` (Option B). Option A (plugin-only) users have two equivalent paths: ask in the Claude Code conversation (the `/memesh` skill + MCP tools cover the same flows), or replace `memesh` with `npx @pcircle/memesh` in any shell — same flags, no global install needed.
@@ -214,6 +242,32 @@ memesh serve
   <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — interactive knowledge graph with type filters and ego mode" width="100%" />
 </p>
 
+### See what it remembered
+
+At any moment, one command prints what your agent knows about the current project — where work was left off, decisions, lessons, recent activity (wrapped as reference data):
+
+```bash
+memesh briefing
+```
+
+```text
+Where "your-project" was left off (today):
+- Goal: Ship the payment retry logic
+- Next: Open the PR once CI is green
+
+Decisions and direction for "your-project":
+- [decision] Use FTS5 as the retrieval baseline
+```
+
+This same block is what Claude Code receives automatically at session start, and what any other MCP client gets from the `briefing` tool — the agent starts oriented instead of re-reading the repository, and you stop re-explaining last week. The dashboard (`memesh serve`) is the full visual view.
+
+### Your data
+
+- **One local file.** Everything lives in `~/.memesh/knowledge-graph.db` — SQLite, on your disk. No cloud account; nothing leaves your machine unless you configure a cloud embedder or LLM yourself.
+- **Back up = copy that one file.** Restore = copy it back.
+- **Pause capture anytime**: `export MEMESH_AUTO_CAPTURE=false`.
+- **Delete everything**: remove `~/.memesh/`.
+
 ---
 
 ## Who Is This For?
@@ -282,6 +336,22 @@ Paste tools into any API call
 
 ---
 
+## Benchmarks — 95.60% R@5 on LongMemEval-S
+
+MeMesh's retrieval is **FTS5 alone** — no LLM, no embeddings on the hot path. Measured against the public [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) benchmark (500 questions, MIT-licensed):
+
+| System | R@5 | Source |
+|---|---|---|
+| **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | Vendor self-report |
+| Supermemory | ~82% | Vendor estimate |
+| Zep | 63.8% | LongMemEval paper |
+| Mem0 | 49.0% | LongMemEval paper |
+
+Re-runnable in ~10 seconds. Full instructions, dataset SHA256, raw per-question results, and known-failure analysis: [`benchmarks/longmemeval/REPRODUCE.md`](benchmarks/longmemeval/REPRODUCE.md).
+
+---
+
 ## What Happens Automatically In Claude Code
 
 You don't need to manually remember everything. MeMesh has **6 hooks** that capture and inject knowledge while you work:
@@ -347,7 +417,7 @@ When npm flags an installed version as deprecated (typically a security advisory
 
 **🔄 Knowledge Evolution** — Decisions change. `forget` archives old memories (never deletes). `supersedes` relations link old → new. Your AI always sees the latest version.
 
-**⚠️ Conflict Detection** — If you have two memories that contradict each other, MeMesh warns you.
+**⚠️ Conflict Detection** — `memesh dream conflicts` has the LLM judge your semantically-closest memory pairs for contradiction, supersession or duplication, and stages what it finds as proposals. Nothing applies itself: you review with `dream list` / `dream show`, and only an accepted proposal creates the relation — after which every `recall` touching either memory carries the warning. Causality is never inferred from timestamps; verdicts come from what the memories actually say.
 
 **🕸️ Knowledge Graph Connectivity** — `memesh kg backfill-relations --all-rules` links orphan entities using tag co-occurrence, project clustering, session context, and name similarity — no LLM required.
 
@@ -369,6 +439,58 @@ Imported bundles stay searchable, but MeMesh does not auto-inject imported memor
 
 ---
 
+## Recipes
+
+### Catch a contradiction before it bites
+
+Two decisions, made weeks apart, that cannot both be true — the failure mode
+a memory layer exists to catch:
+
+```bash
+memesh remember --name retry-policy --type decision \
+  --obs "All HTTP clients retry failed requests up to 5 times with exponential backoff."
+# ...weeks later, someone decides the opposite...
+memesh remember --name retry-policy-v2 --type decision \
+  --obs "HTTP clients must never retry automatically — fail fast and surface the error."
+
+memesh dream conflicts        # the judge flags the pair, with its reasoning
+memesh dream show 1           # read the verdict, the excerpts, what accepting creates
+memesh dream accept 1         # YOU decide — nothing is ever linked automatically
+memesh recall "retry policy"  # → Warning: Conflicts detected
+```
+
+From then on, any assistant that recalls either decision is told they
+conflict — instead of confidently quoting whichever one it found first.
+
+### One memory, three assistants
+
+MeMesh is an MCP server, so the same SQLite file serves every MCP client on
+the machine. Register it once per tool (exact commands in
+[Get Started](#get-started-in-60-seconds)) and a decision recorded in Claude
+Code is recalled by Codex or Gemini CLI mid-session — no re-explaining, no
+copy-pasting context between vendors.
+
+### Record decisions so they stay findable
+
+Auto-capture keeps session history, but the memories that pay rent are the
+deliberate ones:
+
+```bash
+memesh remember --name auth-approach --type decision \
+  --obs "JWT with RS256; PKCE over implicit flow because the client is public." \
+  --tags "project:myapp" "topic:auth"
+```
+
+Then link consequences to their causes as they happen — from any MCP client,
+in plain words: *"remember this incident as a lesson, influenced by
+auth-approach"*. The `remember` tool takes free-form relations, and `caused` /
+`influenced` are the documented causal vocabulary (cause → effect, stated
+explicitly — MeMesh never infers causality from timestamps). Weeks later,
+`memesh recall "why did we pick PKCE"` returns the decision with its recorded
+consequences attached — reasoning you can follow, not just text that matched.
+
+---
+
 ## Unlock Smart Mode (Optional)
 
 MeMesh works offline by default — recall stays strictly LLM-free (95.60% R@5 on LongMemEval-S out of the box). Add an LLM API key only if you want LLM-augmented analysis flows on top: smarter session extraction, auto-tagging of new memories, lesson generation from failures, and `dream` compression:
@@ -411,7 +533,7 @@ The embedder is configured **independently of the chat LLM** — changing `llm.p
 
 ---
 
-## All 7 Memory Tools
+## All 9 Memory Tools
 
 | Tool | What it does |
 |------|-------------|
@@ -421,6 +543,8 @@ The embedder is configured **independently of the chat LLM** — changing `llm.p
 | `export` | Share memories as JSON between projects or team members |
 | `import` | Import memories with merge strategies (skip / overwrite / append) |
 | `learn` | Record structured lessons from mistakes (error, root cause, fix, prevention) |
+| `task_state` | Read or record where the work stands — goal, next step, blocker, what was just finished |
+| `briefing` | The assembled work topology — the same block Claude Code gets at session start, for any MCP client |
 | `user_patterns` | Analyze your work patterns — schedule, tools, strengths, learning areas |
 
 ---
@@ -452,19 +576,22 @@ Claude Code's plugin marketplace pins versions at install time and does **not**
 
 **Option A — `/plugin` UI**: uninstall `memesh@pcircle-memesh`, then reinstall. Claude Code fetches the latest marketplace version.
 
-**Option B — one-line script** (no UI clicking, idempotent):
+**Option B — one command** (no UI clicking, idempotent; requires the npm CLI, `npm install -g @pcircle/memesh`):
+
+```bash
+memesh upgrade-plugin
+```
+
+It finds your installed plugin version, checks the prerequisites, and runs the bundled upgrade script for you. Prerequisites: `node`, `npm` and `rsync` on your PATH (macOS ships rsync; Debian/Ubuntu: `sudo apt install rsync`).
+
+Plugin-only users without the npm CLI can still run the script by hand — substitute your installed version into the path:
 
 ```bash
-# If your plugin install is v4.2.5 or newer, the script ships inside it:
 bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
 
-# If you installed before v4.2.5 (i.e. you're on v4.2.4 or v4.2.3),
-# the script isn't in your plugin yet. Use the npm-global copy instead:
+# Installs from before v4.2.5 don't contain the script yet; use the
+# npm-global copy instead (see "Install paths at a glance" above):
 bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
-
-# (That assumes you've also run `npm install -g @pcircle/memesh`. If you
-# haven't, this is also a good moment to — see the "Install paths at a
-# glance" section above for why most users want both paths.)
 ```
 
 The script fast-forwards the marketplace cache, stages the new version under `~/.claude/plugins/cache/`, installs runtime deps, and re-points `installed_plugins.json`. Restart Claude Code afterwards so the MCP server reconnects.
@@ -478,8 +605,8 @@ Session start surfaces a one-line banner (throttled to once per 24h per version)
 ## Contributing
 
 ```bash
-git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
-cd memesh-llm-memory && npm install && npm run build
+git clone https://github.com/PCIRCLE-AI/memesh
+cd memesh && npm install && npm run build
 npm test
 npm run test:e2e-dashboard
 ```

package/README.zh-TW.md

@@ -1,9 +1,9 @@
-🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [Tiếng Việt](README.vi.md) | [Español](README.es.md) | [ภาษาไทย](README.th.md)
+🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [Deutsch](README.de.md)
 
 <p align="center">
-  <h1 align="center">MeMesh LLM Memory</h1>
+  <h1 align="center">MeMesh</h1>
   <p align="center">
-    <strong>給 Claude Code 和 MCP 程式開發代理的在地記憶系統。</strong><br />
+    <strong>給程式開發代理的代理式記憶。</strong><br />
     一個 SQLite 檔案。不需要 Docker。不需要雲端。
   </p>
   <p align="center">
@@ -16,32 +16,38 @@
 
 ---
 
-> [!IMPORTANT]
-> **持續開發中的專案** — 功能會持續更新，版本之間可能會有變動。遇到問題或想要新功能，請[開 issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+**MeMesh** — 給 Claude Code 和 MCP 程式開發代理的開源**代理式記憶**：從代理的實際工作中擷取，在它行動的當下注入，記憶自相矛盾時保持誠實。一個 SQLite 檔案。不需要雲端。
 
-## 問題所在
+## 安裝
 
-你的程式開發代理在每次對話之間就會忘記一切。每個架構決策、每個修復的臭蟲、每個失敗的測試、每個代價不菲的教訓，都得重新跟它解釋一遍。Claude Code 每次都從零開始，重新發現舊的限制條件，浪費寶貴的上下文在它本應已知的事情上。
+**在 Claude Code 裡** — 在對話框輸入這兩行（hooks、記憶工具和 `/memesh` skill 會自動接好）：
 
-**MeMesh 讓程式開發代理擁有持久、可搜尋、不斷演進的在地記憶。**
+```
+/plugin marketplace add PCIRCLE-AI/memesh
+/plugin install memesh@pcircle-memesh
+```
 
-這個套件是 MeMesh 產品系列的在地記憶層。我們刻意保持它的精簡和開源：用 npm 安裝，把記憶保存在 `~/.memesh/knowledge-graph.db`，然後連接到 Claude Code 或任何支援 MCP 的用戶端。託管工作區和企業級作業系統產品應該與這個套件的 README 和路線圖分開。
+重開 Claude Code。下一個 session 開頭出現 `◉ MeMesh` 狀態列，就代表它在記了。
 
----
+**在終端機裡** — `memesh` CLI、儀表板，以及給 Codex / Gemini / Cursor 用的 `memesh-mcp` server（需要 [Node 22.13+](https://nodejs.org)）：
 
-## 實證 — 在 LongMemEval-S 上 R@5 達 95.60%
+```bash
+npm install -g @pcircle/memesh
+memesh doctor        # 端到端驗證這份安裝
+```
 
-MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌入），對照公開的 [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) 基準測試（500 題，MIT 授權）量測：
+大多數 Claude Code 使用者最後兩種都會裝 — 它們共用同一個資料庫、永不衝突。細節、其他代理、升級方式：見下方「60 秒快速開始」。
 
-| 系統 | R@5 | 來源 |
-|---|---|---|
-| **MeMesh（Mode A，經由 `recallEnhanced()`）** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
-| MemPalace | 96.6% | 廠商自行回報 |
-| Supermemory | ~82% | 廠商估計值 |
-| Zep | 63.8% | LongMemEval 論文 |
-| Mem0 | 49.0% | LongMemEval 論文 |
+## 問題所在
 
-重現指令、資料集 SHA256、原始逐題結果與已知失敗分析全部都在 [`benchmarks/longmemeval/`](benchmarks/longmemeval/)。約 10 秒可重跑一次。
+你的程式開發代理在對話之間不只是忘記事實 — 它會**重複做過的工作**。它會重新提出你上個月否決過的做法，被同一個失敗的測試絆倒，重新發現三月那次弄壞 production 的限制條件，還要你重新解釋那個它自己參與設計的架構。
+
+這不是聊天記錄的問題，而是代理記憶的問題。需要在對話之間留存下來的是*工作本身*：決策連同它的理由、失敗連同它的修法，以及它們之間的關聯。
+
+**MeMesh 就是那份記憶。** Hooks 從代理實際做的事情擷取記憶（session、commit、失敗 — 不是手動筆記），回憶在代理行動的當下注入記憶（session 開始時、編輯檔案前），知識圖譜層則讓記憶長期保持誠實（supersession 汰換、由 LLM 判定的衝突偵測）。用 npm 安裝，把記憶保存在 `~/.memesh/knowledge-graph.db`，然後連接到 Claude Code 或任何支援 MCP 的用戶端。
+
+> [!IMPORTANT]
+> **持續開發中的專案** — 功能會持續更新，版本之間可能會有變動。遇到問題或想要新功能，請[開 issue](https://github.com/PCIRCLE-AI/memesh/issues)。
 
 ---
 
@@ -65,7 +71,7 @@ flowchart TB
     subgraph paths["Two install paths"]
       direction LR
       A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
-      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
     end
 
     DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>Same data, both paths see it")]:::db
@@ -113,11 +119,13 @@ npm install -g @pcircle/memesh
 如果你使用 Claude Code，從 CLI 內把 MeMesh 當外掛安裝：
 
 ```
-/plugin marketplace add PCIRCLE-AI/memesh-llm-memory
+/plugin marketplace add PCIRCLE-AI/memesh
 /plugin install memesh@pcircle-memesh
 ```
 
-Claude Code 會自動接好 hooks、skills 和 MCP server。你會獲得對話內自動擷取、主動回憶、可在 Claude Code 對話中使用的 `/memesh` skill（remember / recall / learn / forget），以及代理可呼叫的 `remember` / `recall` / `forget` / `learn` MCP 工具。CLI 與本地儀表板無需任何額外的全域安裝就能完整使用 — `npx @pcircle/memesh <command>` 可執行所有 CLI 指令，`npx @pcircle/memesh` 可在 `localhost:3737` 啟動儀表板。MCP server 直接從外掛內建的編譯產物啟動 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地建置步驟。memesh 透過 Node 內建的 `node:sqlite`（22.13+）存放資料，所以升級 Node 不會留下一個為錯誤 runtime 編譯的二進位檔。
+Claude Code 會自動接好 hooks、skills 和 MCP server。你會獲得對話內自動擷取、主動回憶、可在 Claude Code 對話中使用的 `/memesh` skill（remember / recall / learn / forget），以及代理可呼叫的 `remember` / `recall` / `forget` / `learn` MCP 工具。
+
+**驗證方式：**重開 Claude Code、開任何 session。開頭出現像 `◉ MeMesh ready · no memories for "your-project" yet` 的狀態列 — 那一行就是外掛在運作的證明，不需要另外跑指令。（有記憶之後會改顯示數量。）CLI 與本地儀表板無需任何額外的全域安裝就能完整使用 — `npx @pcircle/memesh <command>` 可執行所有 CLI 指令，`npx @pcircle/memesh` 可在 `localhost:3737` 啟動儀表板。MCP server 直接從外掛內建的編譯產物啟動 — 不需要 `npx` 查找、不需要 `npm install -g`、不需要本地建置步驟。memesh 透過 Node 內建的 `node:sqlite`（22.13+）存放資料，所以升級 Node 不會留下一個為錯誤 runtime 編譯的二進位檔。
 
 ### 選項 B — npm 全域安裝（可選最佳化）
 
@@ -135,15 +143,54 @@ npm install -g @pcircle/memesh
 
 如果你透過**選項 A**（`/plugin install memesh@pcircle-memesh`）安裝，請略過此步驟 — Claude Code 會自動接好外掛 hooks。
 
-如果你透過**選項 B**（`npm install -g`）安裝，CLI 已在 PATH 上、MCP server 也已註冊，但 Claude Code session hooks 並未自動接上。沒有這些 hooks 還是可以手動使用 `memesh remember` / `recall`，但**自動擷取迴路**（session → 教訓 → 下次 session 主動回憶）就會靜默不動。
+如果你透過**選項 B**（`npm install -g`）安裝，CLI 已在 PATH 上 — 但**還沒有任何東西接進 Claude Code**：npm 套件刻意不執行安裝腳本，把 MCP server 和 hooks 接進 Claude Code 的是外掛（選項 A）。npm 路徑自己能接的是 session hooks。沒有這些 hooks 還是可以手動使用 `memesh remember` / `recall`，但**自動擷取迴路**（session → 教訓 → 下次 session 主動回憶）就會靜默不動。
+
+```bash
+memesh setup                 # 偵測 Claude Code / Codex / Gemini、逐一詢問接線、接完驗證
+```
+
+或手動逐步：
 
 ```bash
 memesh install-hooks         # 把 memesh hooks 加進 ~/.claude/settings.json
-memesh doctor                # 確認「Hooks wired into Claude Code」過了
+memesh setup --check         # 機器層級驗證：讀各主機自己的設定，什麼都不改
 ```
 
 這些 hooks 會跟你既有的 `~/.claude/hooks/` 自訂 hooks 共存 — `install-hooks` 用追加方式寫入，從不覆寫你的東西。要移除：`memesh uninstall-hooks`。
 
+### 從 Codex CLI 和 Gemini CLI 用同一份記憶
+
+`memesh-mcp` 是標準的 stdio MCP server，任何支援 MCP 的主機都能用 — 不限 Claude Code。裝好選項 B（`memesh-mcp` 在 `PATH` 上）之後，每個主機註冊一次：
+
+```bash
+# OpenAI Codex CLI — 會把 [mcp_servers.memesh] 寫進 ~/.codex/config.toml
+codex mcp add memesh -- memesh-mcp
+
+# Google Gemini CLI — user 範圍，每個資料夾都能用
+gemini mcp add -s user memesh memesh-mcp
+```
+
+每個主機讀寫的都是同一個 `~/.memesh/knowledge-graph.db`，所以在 Claude Code session 存的記憶，Codex 和 Gemini 都回憶得到，反之亦然。驗證：
+
+```bash
+codex mcp list       # memesh 應顯示為 enabled
+gemini mcp list      # memesh 應顯示 "Connected"
+```
+
+> **設定的指令要用 `memesh-mcp`，不要用 `npx -p @pcircle/memesh`。**當主機的工作目錄在這個 repo 的 checkout 裡時，`npx -p` 會解析到*本地*套件，靜默執行工作樹當下的狀態而不是安裝好的正式版。
+
+### 原生整合：Hermes Agent
+
+**Hermes Agent** (NousResearch) 有一套第一方 `MemoryProvider` 外掛系統 — MeMesh 整合的層級與 Hermes 自己內建的記憶後端（honcho、mem0、hindsight）相同，不是 HTTP 橋接。與 MCP 模式手動呼叫工具不同，Hermes 的 provider 系統在每一輪自動執行 `recall`/`remember`。
+
+整合將 Hermes 的 `prefetch()` 和 `sync_turn()` hooks 直接對應到 MeMesh 的 HTTP API。完整指南包含 provider 程式結構、設定，以及來自真實部署的四個陷阱：**[docs/platforms/hermes-agent.md](docs/platforms/hermes-agent.md)**
+
+### 原生整合：OpenClaw
+
+**OpenClaw** 有一套第一方記憶能力外掛系統 — MeMesh 整合的層級與 OpenClaw 自己內建的後端（LanceDB）相同，不是 HTTP 橋接。外掛透過 `api.registerMemoryCapability()` 註冊，並提供 `memory_recall`/`memory_store`/`memory_forget` 工具，以及在 `before_prompt_build` hook 上自動 recall。
+
+**與 Hermes 的關鍵差異**：OpenClaw 的自動擷取有門檻控制（觸發時每輪最多 3 筆記憶），而非每一輪都擷取。整合對應到 MeMesh 的 HTTP API（`/v1/recall`、`/v1/remember`、`/v1/forget`）。完整 TypeScript 外掛合約、設定形狀與陷阱：**[docs/platforms/openclaw.md](docs/platforms/openclaw.md)**
+
 ### 第二步：保存一個決策
 
 > 下方的 bash 範例假設 `memesh` 已在 `PATH` 上（選項 B）。選項 A（純外掛）使用者有兩條等價路徑：在 Claude Code 對話中發問（`/memesh` skill 與 MCP 工具涵蓋同樣的流程），或將任何 shell 中的 `memesh` 替換為 `npx @pcircle/memesh` — 旗標相同，不需要全域安裝。
@@ -191,6 +238,32 @@ memesh serve
   <img src="docs/images/dashboard-graph.png" alt="MeMesh 圖表 — 互動式知識圖，具有類型篩選和自我中心模式" width="100%" />
 </p>
 
+### 看看它幫你記了什麼
+
+任何時候一條指令，就能印出你的代理對目前專案知道什麼 — 工作做到哪、決策、教訓、近期活動（以參考資料的形式包好）：
+
+```bash
+memesh briefing
+```
+
+```text
+Where "your-project" was left off (today):
+- Goal: Ship the payment retry logic
+- Next: Open the PR once CI is green
+
+Decisions and direction for "your-project":
+- [decision] Use FTS5 as the retrieval baseline
+```
+
+Claude Code 在 session 開始時自動收到的就是同一個區塊，其他 MCP 用戶端呼叫 `briefing` 工具也拿到同一份 — 代理一開場就有方向，不用重讀整個 repo，你也不用再重講上禮拜的事。儀表板（`memesh serve`）是完整的視覺化版本。
+
+### 你的資料
+
+- **就一個本機檔案。**所有東西都在 `~/.memesh/knowledge-graph.db` — SQLite、在你的硬碟上。沒有雲端帳號；除非你自己設定雲端 embedder 或 LLM，否則什麼都不會離開你的機器。
+- **備份 = 複製那個檔案。**還原 = 複製回去。
+- **隨時暫停擷取**：`export MEMESH_AUTO_CAPTURE=false`。
+- **全部刪除**：移除 `~/.memesh/`。
+
 ---
 
 ## 誰應該用 MeMesh？
@@ -259,6 +332,22 @@ memesh export-schema \
 
 ---
 
+## 基準測試 — 95.60% R@5 on LongMemEval-S
+
+MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌入），對照公開的 [LongMemEval-S](https://huggingface.co/datasets/xiaowu0162/longmemeval) 基準測試（500 題，MIT 授權）量測：
+
+| 系統 | R@5 | 來源 |
+|---|---|---|
+| **MeMesh（Mode A，經由 `recallEnhanced()`）** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
+| MemPalace | 96.6% | 廠商自行回報 |
+| Supermemory | ~82% | 廠商估計值 |
+| Zep | 63.8% | LongMemEval 論文 |
+| Mem0 | 49.0% | LongMemEval 論文 |
+
+重現指令、資料集 SHA256、原始逐題結果與已知失敗分析全部都在 [`benchmarks/longmemeval/`](benchmarks/longmemeval/)。約 10 秒可重跑一次。
+
+---
+
 ## Claude Code 自動進行的事情
 
 你不需要手動記住所有事情。MeMesh 有 **6 個 hooks**，會在你工作時自動擷取與注入知識：
@@ -385,7 +474,7 @@ memesh config set embedder.model text-embedding-3-small
 
 ---
 
-## 全部 7 個記憶工具
+## 全部 9 個記憶工具
 
 | 工具 | 做什麼 |
 |------|--------|
@@ -395,6 +484,8 @@ memesh config set embedder.model text-embedding-3-small
 | `export` | 在專案或團隊成員之間以 JSON 共享記憶 |
 | `import` | 匯入記憶，包含合併策略（跳過 / 覆寫 / 追加） |
 | `learn` | 記錄來自錯誤的結構化教訓（錯誤、根本原因、修復、預防） |
+| `task_state` | 讀取或記下工作進度——目標、下一步、卡住的地方、剛完成的事 |
+| `briefing` | 組合好的工作拓撲——Claude Code 在 session 開始拿到的那個區塊，任何 MCP client 都拿得到 |
 | `user_patterns` | 分析你的工作模式——時間表、工具、優勢、學習領域 |
 
 ---
@@ -426,18 +517,22 @@ Claude Code 的 plugin marketplace 在安裝時把版本釘住，**不會**自
 
 **方法 A — `/plugin` 介面**：先 uninstall `memesh@pcircle-memesh`，再重新安裝。Claude Code 會抓 marketplace 最新版。
 
-**方法 B — 一行指令**（不用點 UI、可重複執行）：
+**方法 B — 一行指令**（不用點 UI、可重複執行；需要 npm CLI，`npm install -g @pcircle/memesh`）：
+
+```bash
+memesh upgrade-plugin
+```
+
+它會自己找到已安裝的 plugin 版本、確認前置工具都在，再幫你執行內建的升級腳本。前置工具：PATH 上要有 `node`、`npm`、`rsync`（macOS 內建 rsync；Debian/Ubuntu：`sudo apt install rsync`）。
+
+只裝了 plugin、沒裝 npm CLI 的人，仍然可以手動執行腳本 — 把路徑裡的版本換成你安裝的版本：
 
 ```bash
-# 如果 plugin 已經是 v4.2.5 或更新，腳本已經內建：
 bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
 
-# 如果是 v4.2.5 之前的版本（也就是 v4.2.4 或 v4.2.3），
-# 腳本還沒在你的 plugin 裡，改用 npm-global 的副本：
+# v4.2.5 之前的安裝還沒內建這個腳本，改用 npm-global 的副本
+# （參考上面「安裝路徑一覽」）：
 bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
-
-# （這假設你也跑過 `npm install -g @pcircle/memesh`。如果還沒，
-# 現在正好可以一起裝 — 參考上面「安裝路徑一覽」說明為什麼大部分人兩條路徑都裝。）
 ```
 
 腳本會 fast-forward marketplace cache、把新版本放進 `~/.claude/plugins/cache/`、安裝 runtime deps，然後把 `installed_plugins.json` 重指向新版本。執行完請重啟 Claude Code 讓 MCP server 重連。
@@ -451,8 +546,8 @@ Session 開始時，有新版本可下載時會跳一行 banner（每版本每 2
 ## 貢獻
 
 ```bash
-git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
-cd memesh-llm-memory && npm install && npm run build
+git clone https://github.com/PCIRCLE-AI/memesh
+cd memesh && npm install && npm run build
 npm test             # 630 項測試
 npm run test:e2e-dashboard
 ```