@pcircle/memesh 4.6.2 → 4.7.2

package/.claude-plugin/marketplace.json

@@ -7,8 +7,8 @@
     {
       "name": "memesh",
       "source": "./",
-      "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
-      "version": "4.6.2",
+      "description": "MeMesh \u2014 agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
+      "version": "4.7.2",
       "author": {
         "name": "PCIRCLE AI"
       },

package/.claude-plugin/plugin.json

@@ -1,10 +1,10 @@
 {
   "name": "memesh",
-  "description": "MeMesh — agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
+  "description": "MeMesh \u2014 agentic memory for coding agents. Captured from the agent's real work via hooks, recalled when it acts. One SQLite file, zero cloud required.",
   "author": {
     "name": "PCIRCLE AI"
   },
-  "version": "4.6.2",
+  "version": "4.7.2",
   "homepage": "https://github.com/PCIRCLE-AI/memesh",
   "repository": "https://github.com/PCIRCLE-AI/memesh",
   "license": "MIT",

package/AGENTS.md

@@ -91,8 +91,15 @@ injected), and do not `remember` commits or session summaries by hand. Manual
 calls are for what hooks cannot see — decisions and their rationale, lessons
 worth keeping, and user-stated task state.
 
-Other hosts (Codex CLI, Gemini CLI, Cursor, …) have no hooks: there the loop
-is fully manual, and it is worth running.
+On a host with no hooks (Gemini CLI, Cursor, an MCP-only setup, …) the loop is
+fully manual, and it is worth running.
+
+Codex CLI can be either. Wired as an MCP server it has no hooks, like the
+above. Installed as a plugin (`codex plugin add memesh@pcircle-memesh`) it
+reads the same `hooks/hooks.json` manifest Claude Code does and runs the same
+hook scripts, so the topology is injected for you there too. If you are unsure
+which one you are in, `memesh doctor` names it: the "Hooks wired into Claude
+Code" row says which plugin runtime it found.
 
 ## Working on this repository (contributing agents)
 

package/README.de.md

@@ -16,11 +16,13 @@
 
 ---
 
-**MeMesh** — Open-Source-**agentischer Speicher** für Claude Code & MCP-Coding-Agenten: erfasst aus der echten Arbeit des Agenten, injiziert in dem Moment, in dem er handelt, ehrlich gehalten, wenn er sich selbst widerspricht. Eine SQLite-Datei. Keine Cloud.
+**MeMesh** ist eine **Open-Source-Speicherschicht** für KI-Coding-Agenten — für Claude Code, Codex, Gemini, Cursor und andere MCP-Clients.
+
+Sie erfasst Memories aus dem, was der Agent wirklich tut, und gibt das Passende genau dann zurück, wenn er handelt. Widersprechen sich zwei Memories, sagt sie es. Alles liegt in einer SQLite-Datei, ohne Cloud.
 
 ## Installation
 
-**In Claude Code** — diese zwei Zeilen im Chat eingeben (Hooks, Memory-Tools und der `/memesh`-Skill werden automatisch verdrahtet):
+**In Claude Code** — diese zwei Zeilen im Chat eingeben (Hooks, Memory-Tools und der `/memesh`-Skill werden automatisch eingerichtet):
 
 ```
 /plugin marketplace add PCIRCLE-AI/memesh
@@ -36,15 +38,26 @@ npm install -g @pcircle/memesh
 memesh doctor        # prüft diese Installation Ende-zu-Ende
 ```
 
-Die meisten Claude-Code-Nutzer wollen am Ende **beides** — gemeinsame Datenbank, kein Konflikt. Details, weitere Agenten, Upgrades: siehe „In 60 Sekunden starten" unten.
+Die meisten Claude-Code-Nutzer installieren am Ende **beides**. Beide nutzen dieselbe Datenbank und kommen sich nicht in die Quere. Details, weitere Agenten und Upgrades stehen unten unter „In 60 Sekunden starten".
 
 ## Das Problem
 
-Ihr Coding-Agent vergisst nicht nur Fakten zwischen Sessions — er **wiederholt Arbeit**. Er schlägt erneut den Ansatz vor, den Sie letzten Monat abgelehnt haben, stolpert über denselben fehlschlagenden Test, entdeckt die Constraint wieder, die im März die Produktion kaputt gemacht hat, und bittet Sie, die Architektur erneut zu erklären, die er selbst mitentworfen hat.
+Ihr Coding-Agent vergisst zwischen zwei Sessions nicht nur Fakten. Schlimmer: er **macht dieselbe Arbeit noch einmal**.
+
+- Er schlägt wieder den Ansatz vor, den Sie letzten Monat abgelehnt haben
+- Er stolpert erneut über denselben fehlschlagenden Test
+- Er „entdeckt" die Einschränkung wieder, die im März die Produktion lahmgelegt hat
+- Er bittet Sie, ihm die Architektur zu erklären, die er selbst mitentworfen hat
+
+Das ist kein Problem des Chatverlaufs. Was zwischen Sessions überleben muss, ist nicht das Gespräch, sondern die *Arbeit*: welche Entscheidungen gefallen sind, warum, was fehlgeschlagen ist, wie es behoben wurde — und wie das alles zusammenhängt.
 
-Das ist kein Chatverlauf-Problem, sondern ein Agenten-Speicher-Problem. Was zwischen Sessions überleben muss, ist die *Arbeit*: Entscheidungen mit ihren Gründen, Fehlschläge mit ihren Behebungen und die Verbindungen dazwischen.
+**Genau diese Lücke füllt MeMesh.** Es tut drei Dinge:
 
-**MeMesh ist dieser Speicher.** Hooks erfassen ihn aus dem, was der Agent tatsächlich tut (Sessions, Commits, Fehlschläge — keine manuellen Notizen), Recall injiziert ihn in dem Moment, in dem der Agent handelt (Session-Start, vor Dateibearbeitungen), und die Wissensgraph-Schicht hält ihn über die Zeit ehrlich (Supersession, LLM-beurteilte Konflikterkennung). Installation via npm, der Speicher liegt in `~/.memesh/knowledge-graph.db`, Anbindung an Claude Code oder jeden MCP-kompatiblen Client.
+- **Automatisch festhalten**: Hooks erfassen, was der Agent wirklich tut — Sessions, Commits, Fehlschläge. Keine handgeschriebenen Notizen
+- **Zurückgeben, wenn es zählt**: beim Session-Start und vor jeder Dateibearbeitung landen die passenden Memories vor dem Agenten
+- **Nicht verrotten lassen**: neue Entscheidungen lösen alte ab, und widersprechen sich zwei Memories, beurteilt ein LLM den Konflikt und markiert ihn
+
+Installation über npm, gespeichert wird in `~/.memesh/knowledge-graph.db`, angebunden an Claude Code oder jeden MCP-fähigen Client.
 
 > [!IMPORTANT]
 > **Aktiv entwickeltes Projekt** — Funktionen entwickeln sich kontinuierlich weiter und können sich zwischen Releases ändern. Bei Bugs oder Feature-Wünschen bitte [ein Issue eröffnen](https://github.com/PCIRCLE-AI/memesh/issues).
@@ -65,7 +78,7 @@ flowchart TB
     subgraph clients["Where you use memesh from"]
       direction LR
       CC["Claude Code<br/>(chat + agent)"]:::client
-      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Codex, Gemini, Cursor...)"]:::client
     end
 
     subgraph paths["Two install paths"]
@@ -152,7 +165,7 @@ memesh setup --check         # Prüfung auf Maschinenebene: liest die Host-Confi
 
 Die Hooks existieren neben Ihren bestehenden Custom-Hooks unter `~/.claude/hooks/` — `install-hooks` schreibt additiv und überschreibt nie Ihre Einträge. Zum Entfernen: `memesh uninstall-hooks`.
 
-### Dieselben Memories aus Codex CLI und Gemini CLI
+### Dieselben Memories aus Codex CLI, Gemini CLI, Cursor und anderen MCP-Clients
 
 `memesh-mcp` ist ein gewöhnlicher stdio-MCP-Server — jeder MCP-fähige Host kann ihn nutzen, nicht nur Claude Code. Mit installierter Option B (`memesh-mcp` im `PATH`) einmal pro Host registrieren:
 
@@ -164,7 +177,18 @@ codex mcp add memesh -- memesh-mcp
 gemini mcp add -s user memesh memesh-mcp
 ```
 
-Jeder Host liest und schreibt dieselbe `~/.memesh/knowledge-graph.db` — eine in Claude Code gespeicherte Memory ist aus Codex oder Gemini abrufbar, und umgekehrt. Prüfen:
+Für Cursor fügen Sie denselben stdio-Server in `~/.cursor/mcp.json` (global)
+oder in `.cursor/mcp.json` (projektspezifisch) ein:
+
+```json
+{
+  "mcpServers": {
+    "memesh": { "command": "memesh-mcp" }
+  }
+}
+```
+
+Jeder Host liest und schreibt dieselbe `~/.memesh/knowledge-graph.db` — eine in einem Agenten gespeicherte Memory ist aus Codex, Gemini, Cursor oder einem anderen MCP-Client abrufbar. Prüfen:
 
 ```bash
 codex mcp list       # memesh sollte als enabled gelistet sein
@@ -264,8 +288,8 @@ Denselben Block erhält Claude Code automatisch beim Session-Start, und jeder an
 |---------------|---------------------|
 | **Claude Code verwenden** | Projektentscheidungen, dateispezifische Erkenntnisse und vergangene Fehler während der Arbeit automatisch abrufen |
 | **Power-User von Coding-Agenten** | Eine lokale Speicherschicht über MCP-kompatible Tools verteilen |
-| **ein Team mit KI-Coding-Workflows experimentiert** | Projektwissen ohne gehostete Infrastruktur aus- und importieren |
-| **Agent-Entwickler** | Lokalen Speicher via MCP, HTTP oder CLI hinzufügen |
+| **Codex, Gemini, Cursor, Claude Code oder einen anderen MCP-Client einzeln nutzt** | Eine lokale Speicherschicht über Agenten und Sessions hinweg verwenden |
+| **einen Agenten integrieren** | Lokalen Speicher via MCP, HTTP oder CLI hinzufügen |
 
 ---
 
@@ -402,12 +426,12 @@ Wenn npm eine installierte Version als veraltet kennzeichnet (typischerweise ein
 
 **🔄 Wissensentwicklung** — Entscheidungen ändern sich. `forget` archiviert alte Memories (löscht nie). `supersedes`-Relationen verbinden alt → neu. Ihr KI sieht immer die aktuelle Version.
 
-**⚠️ Konflikterkennung** — Wenn Sie zwei Memories haben, die sich widersprechen, warnt Sie MeMesh.
+**⚠️ Konflikterkennung** — `memesh dream conflicts` lässt das LLM Ihre semantisch nächstliegenden Memory-Paare auf Widerspruch, Supersession oder Duplikat prüfen und legt die Treffer als Vorschläge ab. Nichts wird von selbst übernommen: Sie prüfen mit `dream list` / `dream show`, und erst ein akzeptierter Vorschlag erstellt die Relation — danach trägt jedes `recall`, das eine der beiden Memories betrifft, die Warnung. Kausalität wird nie aus Zeitstempeln abgeleitet; die Urteile beruhen darauf, was die Memories tatsächlich aussagen.
 
 **🕸️ Wissensgraph-Konnektivität** — `memesh kg backfill-relations --all-rules` verknüpft verwaiste Entitäten über Tag-Kookurrenz, Projekt-Clustering, Sitzungskontext und Namensähnlichkeit — ohne LLM.
 
-**📦 Team-Freigabe** — `memesh export > team-knowledge.json` → mit Team teilen → `memesh import team-knowledge.json`
-Importierte Bundles bleiben durchsuchbar, aber MeMesh injiziert importierte Memories nicht automatisch in Claude Hooks, bis Sie sie überprüfen oder lokal neu speichern.
+**📦 Persönliches Backup und Migration** — `memesh export > memesh-backup.json` → auf einen anderen Rechner kopieren → `memesh import memesh-backup.json`
+Importierte Bundles bleiben durchsuchbar, aber MeMesh injiziert importierte Memories nicht automatisch in den Host-Kontext, bis Sie sie überprüfen oder lokal neu speichern.
 
 ---
 
@@ -416,14 +440,53 @@ Importierte Bundles bleiben durchsuchbar, aber MeMesh injiziert importierte Memo
 > "MeMesh hat sich daran erinnert, dass wir vor drei Wochen PKCE gegenüber Implicit Flow gewählt haben. Als ich Claude erneut nach Auth fragte, wusste es bereits Bescheid — keine Wiederholungen nötig."
 > — **Einzelentwickler, baut eine SaaS**
 
-> "Wir exportieren unseren Team-Memory jeden Freitag und importieren ihn Montag. Jedes Claude des Teams startet die Woche mit dem Wissen aus der Vorwoche."
-> — **3er-Startup mit gemeinsamer Wissensbasis**
+> "Eine in Claude Code gespeicherte Entscheidung war am nächsten Tag aus Codex abrufbar. Dieselbe lokale Memory folgt meiner Arbeit statt einem einzelnen Agenten."
+> — **Einzelentwickler mit mehreren Coding-Agenten**
 
 > "Das Dashboard zeigte mir, dass 90 % meiner Memories automatisch generierte Session-Logs waren. Ich begann, `remember` bewusst für Architekturentscheidungen zu nutzen. Ein Spielwechsel."
 > — **Entwickler, der das Analytics-Panel entdeckte**
 
 ---
 
+## Rezepte
+
+### Einen Widerspruch erkennen, bevor er zum Problem wird
+
+Zwei Entscheidungen, Wochen auseinander getroffen, die nicht beide wahr sein können — genau das Fehlerbild, das eine Memory-Schicht abfangen soll:
+
+```bash
+memesh remember --name retry-policy --type decision \
+  --obs "Alle HTTP-Clients wiederholen fehlgeschlagene Requests bis zu 5-mal mit exponentiellem Backoff."
+# ...Wochen später entscheidet jemand das Gegenteil...
+memesh remember --name retry-policy-v2 --type decision \
+  --obs "HTTP-Clients dürfen niemals automatisch wiederholen — sofort fehlschlagen und den Fehler melden."
+
+memesh dream conflicts        # markiert das Paar, mit Begründung
+memesh dream show 1           # Urteil, Auszüge und Folgen der Annahme lesen
+memesh dream accept 1         # SIE entscheiden — nichts wird je automatisch verknüpft
+memesh recall "retry policy"  # → Warnung: Konflikte erkannt
+```
+
+Ab dann wird jedem Assistenten, der eine der beiden Entscheidungen abruft, gesagt, dass sie im Widerspruch stehen — statt selbstbewusst die zuerst gefundene zu zitieren.
+
+### Eine Erinnerung, drei Assistenten
+
+MeMesh ist ein MCP-Server, daher bedient dieselbe SQLite-Datei jeden MCP-Client auf der Maschine. Einmal pro Tool registrieren (die genauen Befehle stehen oben unter „In 60 Sekunden starten") — und eine in Claude Code gespeicherte Entscheidung wird mitten in der Session von Codex oder Gemini CLI abgerufen: kein erneutes Erklären, kein Kontext zwischen Anbietern hin- und herkopieren.
+
+### Entscheidungen so festhalten, dass sie auffindbar bleiben
+
+Auto-Capture hält die Session-Historie fest, aber die Erinnerungen, die sich wirklich auszahlen, sind die bewusst gespeicherten:
+
+```bash
+memesh remember --name auth-approach --type decision \
+  --obs "JWT mit RS256; PKCE statt Implicit Flow, weil der Client öffentlich ist." \
+  --tags "project:myapp" "topic:auth"
+```
+
+Verknüpfen Sie dann Folgen mit ihren Ursachen, sobald sie eintreten — von jedem MCP-Client aus, in normalen Worten: „diesen Vorfall als Lektion speichern, beeinflusst von auth-approach". Das `remember`-Tool nimmt frei formulierte Relationen entgegen, und `caused` / `influenced` sind das dokumentierte Kausal-Vokabular (Ursache → Wirkung, explizit angegeben — MeMesh leitet Kausalität nie aus Zeitstempeln ab). Wochen später liefert `memesh recall "warum haben wir uns für PKCE entschieden"` die Entscheidung samt der aufgezeichneten Folgen — nachvollziehbare Begründung, nicht nur zufällig passender Text.
+
+---
+
 ## Smart Mode freischalten (optional)
 
 MeMesh funktioniert standardmäßig offline — Recall bleibt strikt LLM-frei (95,60 % R@5 auf LongMemEval-S, ohne LLM). Fügen Sie einen LLM API-Schlüssel nur hinzu, wenn Sie LLM-augmentierte Analyseflüsse zusätzlich nutzen möchten: intelligentere Session-Extraktion, Auto-Tagging neuer Memories, Lektionen aus Fehlern und `dream` Kompression:
@@ -471,7 +534,7 @@ Wechselst du zu einer anderen Dimension (z. B. 768 → 1536), wird **nichts gel
 | `remember` | Wissen mit Beobachtungen, Relationen und Tags speichern |
 | `recall` | FTS5 + sqlite-vec Suche mit Multi-Faktor-Bewertung (Relevanz, Aktualität, Häufigkeit, Konfidenz, Abruf-Auswirkung) — kein LLM auf dem Hot Path |
 | `forget` | Soft-Archivierung (löscht nie) oder entfernt spezifische Beobachtungen |
-| `export` | Memories als JSON zwischen Projekten oder Teamkollegen teilen |
+| `export` | Memories als JSON sichern, migrieren oder zwischen kompatiblen Agenten übertragen |
 | `import` | Memories mit Merge-Strategien importieren (Skip / Overwrite / Append) |
 | `learn` | Strukturierte Lektionen aus Fehlern erfassen (Fehler, Grundursache, Behebung, Prävention) |
 | `task_state` | Arbeitsstand lesen oder festhalten — Ziel, nächster Schritt, Blocker, gerade Erledigtes |

package/README.md

@@ -16,7 +16,7 @@
 
 ---
 
-**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.
+**MeMesh** — open-source **agentic memory** for individual AI coding agents: compatible with Claude Code, Codex, Gemini, Cursor, and other MCP clients. Captured from the agent's real work, injected at the moment it acts, kept honest when it contradicts itself. One SQLite file. No cloud.
 
 ## Install
 
@@ -67,7 +67,7 @@ flowchart TB
     subgraph clients["Where you use memesh from"]
       direction LR
       CC["Claude Code<br/>(chat + agent)"]:::client
-      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Codex, Gemini, Cursor...)"]:::client
     end
 
     subgraph paths["Two install paths"]
@@ -162,7 +162,7 @@ memesh setup --check         # machine-level verification: reads the hosts' own
 
 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`.
 
-### Same memory from Codex CLI and Gemini CLI
+### Same memory from Codex CLI, Gemini CLI, Cursor, and other MCP clients
 
 `memesh-mcp` is a plain stdio MCP server, so any MCP-capable host can talk to it — not just Claude Code. With Option B installed (`memesh-mcp` on your `PATH`), register it once per host:
 
@@ -174,7 +174,18 @@ codex mcp add memesh -- memesh-mcp
 gemini mcp add -s user memesh memesh-mcp
 ```
 
-Every host reads and writes the same `~/.memesh/knowledge-graph.db`, so a memory stored from a Claude Code session is recallable from Codex or Gemini, and the other way around. Verify from either host by asking it to call the `recall` tool, or from a terminal:
+For Cursor, add the same stdio server to `~/.cursor/mcp.json` (global) or
+`.cursor/mcp.json` (project-local):
+
+```json
+{
+  "mcpServers": {
+    "memesh": { "command": "memesh-mcp" }
+  }
+}
+```
+
+Every host reads and writes the same `~/.memesh/knowledge-graph.db`, so a memory stored from one agent is recallable from Codex, Gemini, Cursor, or another MCP client. Verify from the host by asking it to call the `recall` tool, or from a terminal:
 
 ```bash
 codex mcp list       # memesh should be listed as enabled
@@ -276,8 +287,8 @@ This same block is what Claude Code receives automatically at session start, and
 |---------------|---------------------|
 | **A developer using Claude Code** | Auto-recall project decisions, file-specific lessons, and past failures as you work |
 | **A coding-agent power user** | Share one local memory layer across MCP-compatible tools |
-| **A team experimenting with AI coding workflows** | Export/import project knowledge without introducing hosted infrastructure |
-| **An agent developer** | Add local memory through MCP, HTTP, or the CLI |
+| **An individual using Codex, Gemini, Cursor, Claude Code, or another MCP client** | Use one local memory layer across agents and sessions |
+| **A developer integrating an agent** | Add local memory through MCP, HTTP, or the CLI |
 
 ---
 
@@ -419,8 +430,8 @@ When npm flags an installed version as deprecated (typically a security advisory
 
 **🕸️ 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.
 
-**📦 Team Sharing** — `memesh export > team-knowledge.json` → share with your team → `memesh import team-knowledge.json`
-Imported bundles stay searchable, but MeMesh does not auto-inject imported memories into Claude hooks until you review or re-store them locally.
+**📦 Personal backup and migration** — `memesh export > memesh-backup.json` → copy it to another machine → `memesh import memesh-backup.json`
+Imported bundles stay searchable, but MeMesh does not auto-inject imported memories into host context until you review or re-store them locally.
 
 ---
 
@@ -429,8 +440,8 @@ Imported bundles stay searchable, but MeMesh does not auto-inject imported memor
 > "MeMesh remembered that we chose PKCE over implicit flow three weeks ago. When I asked Claude about auth again, it already knew — no re-explaining needed."
 > — **Solo developer, building a SaaS**
 
-> "We export our team's memory every Friday and import it Monday. Everyone's Claude starts the week knowing what the team learned last week."
-> — **3-person startup, shared knowledge base**
+> "I stored a decision from Claude Code and recalled it from Codex the next day. The same local memory followed my work instead of one agent."
+> — **Solo developer using multiple coding agents**
 
 > "The dashboard showed me that 90% of my memories were auto-generated session logs. I started using `remember` deliberately for architecture decisions. Game changer."
 > — **Developer who discovered the analytics panel**
@@ -538,7 +549,7 @@ If you switch to an embedder with a different dimension (e.g. 768 → 1536), **n
 | `remember` | Store knowledge with observations, relations, and tags |
 | `recall` | FTS5 + sqlite-vec search with multi-factor scoring (relevance, recency, frequency, confidence, recall impact) — no LLM in the hot path |
 | `forget` | Soft-archive (never deletes) or remove specific observations |
-| `export` | Share memories as JSON between projects or team members |
+| `export` | Back up, migrate, or move memories as JSON between compatible agents |
 | `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 |

package/README.zh-TW.md

@@ -16,7 +16,9 @@
 
 ---
 
-**MeMesh** — 給 Claude Code 和 MCP 程式開發代理的開源**代理式記憶**：從代理的實際工作中擷取，在它行動的當下注入，記憶自相矛盾時保持誠實。一個 SQLite 檔案。不需要雲端。
+**MeMesh** 是給 AI 程式開發代理用的**開源記憶層**，支援 Claude Code、Codex、Gemini、Cursor 和其他 MCP 用戶端。
+
+它從代理實際做的事情裡擷取記憶，在代理要動手的那一刻把相關的部分送回去。記憶彼此矛盾時，它會說出來。全部存在一個 SQLite 檔案裡，不需要雲端。
 
 ## 安裝
 
@@ -36,15 +38,26 @@ npm install -g @pcircle/memesh
 memesh doctor        # 端到端驗證這份安裝
 ```
 
-大多數 Claude Code 使用者最後兩種都會裝 — 它們共用同一個資料庫、永不衝突。細節、其他代理、升級方式：見下方「60 秒快速開始」。
+多數 Claude Code 使用者兩種都會裝。它們共用同一個資料庫，不會互相干擾。想知道細節、其他代理怎麼接、怎麼升級，看下面的「60 秒快速開始」。
 
 ## 問題所在
 
-你的程式開發代理在對話之間不只是忘記事實 — 它會**重複做過的工作**。它會重新提出你上個月否決過的做法，被同一個失敗的測試絆倒，重新發現三月那次弄壞 production 的限制條件，還要你重新解釋那個它自己參與設計的架構。
+你的代理換一次對話就忘光，這還不是最糟的。最糟的是它會**把做過的事再做一次**：
+
+- 重新提議你上個月否決掉的做法
+- 再一次被同一個測試絆倒
+- 重新「發現」三月那條弄壞 production 的限制
+- 要你重講一遍當初它也有份設計的架構
+
+這不是「聊天記錄沒存好」的問題。要留下來的不是對話，是*工作本身*——做過什麼決定、為什麼那樣決定、哪裡失敗過、後來怎麼修的，以及這些事情之間的關係。
 
-這不是聊天記錄的問題，而是代理記憶的問題。需要在對話之間留存下來的是*工作本身*：決策連同它的理由、失敗連同它的修法，以及它們之間的關聯。
+**MeMesh 補的就是這一塊。** 它做三件事：
 
-**MeMesh 就是那份記憶。** Hooks 從代理實際做的事情擷取記憶（session、commit、失敗 — 不是手動筆記），回憶在代理行動的當下注入記憶（session 開始時、編輯檔案前），知識圖譜層則讓記憶長期保持誠實（supersession 汰換、由 LLM 判定的衝突偵測）。用 npm 安裝，把記憶保存在 `~/.memesh/knowledge-graph.db`，然後連接到 Claude Code 或任何支援 MCP 的用戶端。
+- **自動記下來**：hooks 從代理真正做過的事情擷取——session、commit、失敗，不用你手動寫筆記
+- **在需要的時候送回去**：session 開始時、要改檔案之前，把相關記憶放進代理眼前
+- **不讓記憶爛掉**：新的決定會取代舊的，兩筆記憶互相矛盾時由 LLM 判斷並標記出來
+
+用 npm 裝，記憶放在 `~/.memesh/knowledge-graph.db`，接上 Claude Code 或任何支援 MCP 的用戶端就能用。
 
 > [!IMPORTANT]
 > **持續開發中的專案** — 功能會持續更新，版本之間可能會有變動。遇到問題或想要新功能，請[開 issue](https://github.com/PCIRCLE-AI/memesh/issues)。
@@ -65,7 +78,7 @@ flowchart TB
     subgraph clients["Where you use memesh from"]
       direction LR
       CC["Claude Code<br/>(chat + agent)"]:::client
-      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Codex, Gemini, Cursor...)"]:::client
     end
 
     subgraph paths["Two install paths"]
@@ -158,7 +171,7 @@ memesh setup --check         # 機器層級驗證：讀各主機自己的設定
 
 這些 hooks 會跟你既有的 `~/.claude/hooks/` 自訂 hooks 共存 — `install-hooks` 用追加方式寫入，從不覆寫你的東西。要移除：`memesh uninstall-hooks`。
 
-### 從 Codex CLI 和 Gemini CLI 用同一份記憶
+### 從 Codex CLI、Gemini CLI、Cursor 與其他 MCP 用戶端使用同一份記憶
 
 `memesh-mcp` 是標準的 stdio MCP server，任何支援 MCP 的主機都能用 — 不限 Claude Code。裝好選項 B（`memesh-mcp` 在 `PATH` 上）之後，每個主機註冊一次：
 
@@ -170,7 +183,17 @@ codex mcp add memesh -- memesh-mcp
 gemini mcp add -s user memesh memesh-mcp
 ```
 
-每個主機讀寫的都是同一個 `~/.memesh/knowledge-graph.db`，所以在 Claude Code session 存的記憶，Codex 和 Gemini 都回憶得到，反之亦然。驗證：
+Cursor 請將同一個 stdio server 加入 `~/.cursor/mcp.json`（全域），或專案內的 `.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "memesh": { "command": "memesh-mcp" }
+  }
+}
+```
+
+每個主機讀寫的都是同一個 `~/.memesh/knowledge-graph.db`，所以在任何代理儲存的記憶，Codex、Gemini、Cursor 和其他 MCP 用戶端都能回憶得到。請從主機要求它呼叫 `recall` 工具驗證：
 
 ```bash
 codex mcp list       # memesh 應顯示為 enabled
@@ -272,8 +295,8 @@ Claude Code 在 session 開始時自動收到的就是同一個區塊，其他 M
 |---------------|---------------------|
 | **使用 Claude Code 的開發者** | 在工作時自動回憶專案決策、檔案特定的經驗教訓和過去的失敗 |
 | **程式開發代理進階使用者** | 在多個 MCP 相容工具間共享一層在地記憶 |
-| **嘗試 AI 程式開發工作流的團隊** | 匯出／匯入專案知識，無需引入託管基礎設施 |
-| **代理開發者** | 透過 MCP、HTTP 或 CLI 添加在地記憶 |
+| **使用 Codex、Gemini、Cursor、Claude Code 或其他 MCP 用戶端的個人** | 在不同代理與 session 之間使用同一層在地記憶 |
+| **整合 AI 代理的開發者** | 透過 MCP、HTTP 或 CLI 添加在地記憶 |
 
 ---
 
@@ -411,12 +434,12 @@ MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌
 
 **🔄 知識演進** — 決策會改變。`forget` 歸檔舊記憶（永不刪除）。`supersedes` 關係連結舊 → 新。你的 AI 總是看到最新版本。
 
-**⚠️ 衝突偵測** — 如果你有兩個互相矛盾的記憶，MeMesh 會警告你。
+**⚠️ 衝突偵測** — `memesh dream conflicts` 會讓 LLM 判定語意上最接近的記憶配對，找出矛盾、汰換或重複，並把結果暫存成提案。沒有東西會自動套用：你用 `dream list` / `dream show` 檢視，只有被接受的提案才會建立關係 —— 之後每次 `recall` 碰到其中任一筆記憶都會帶上警告。因果關係從不從時間戳推論；判決依據的是記憶內容本身怎麼說。
 
 **🕸️ 知識圖連通性** — `memesh kg backfill-relations --all-rules` 使用標籤共現、專案叢集、會話上下文和名稱相似度連結孤立實體 — 無需 LLM。
 
-**📦 團隊共享** — `memesh export > team-knowledge.json` → 與團隊共享 → `memesh import team-knowledge.json`
-匯入的組合保持可搜尋，但 MeMesh 不會自動將匯入的記憶注入 Claude hooks，直到你檢查或在本地重新儲存。
+**📦 個人備份與搬遷** — `memesh export > memesh-backup.json` → 複製到另一台機器 → `memesh import memesh-backup.json`
+匯入的組合保持可搜尋，但 MeMesh 不會自動將匯入的記憶注入 host context，直到你檢查或在本地重新儲存。
 
 ---
 
@@ -425,14 +448,53 @@ MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌
 > 「MeMesh 記得我們三週前選擇了 PKCE 而不是隱式流程。當我再次問 Claude 關於身份驗證的問題時，它已經知道了——不需要重新解釋。」
 > — **獨立開發者，正在打造 SaaS**
 
-> 「我們每個星期五匯出團隊的記憶，星期一匯入。每個人的 Claude 在新一週開始時都知道團隊上週學到的東西。」
-> — **3 人新創公司，共享知識庫**
+> 「我在 Claude Code 儲存的決策，隔天可以從 Codex 找回來。同一份在地記憶跟著工作走，不會被綁在單一代理上。」
+> — **使用多個程式開發代理的個人開發者**
 
 > 「儀表板顯示我 90% 的記憶是自動生成的對話日誌。我開始有意使用 `remember` 來記錄架構決策。改變了遊戲規則。」
 > — **發現分析面板的開發者**
 
 ---
 
+## 食譜
+
+### 在矛盾咬你之前先抓到它
+
+兩個決策，隔了好幾週做的，卻不可能同時為真 — 這正是記憶層存在的目的，就是要抓到這種失敗模式：
+
+```bash
+memesh remember --name retry-policy --type decision \
+  --obs "所有 HTTP client 在請求失敗時都用指數退避重試，最多 5 次。"
+# ...幾週後，有人做了完全相反的決定...
+memesh remember --name retry-policy-v2 --type decision \
+  --obs "HTTP client 絕對不能自動重試 — 立刻失敗並把錯誤丟出來。"
+
+memesh dream conflicts        # 判定器標出這一對，附上判斷理由
+memesh dream show 1           # 看完整的判決、引用的段落，接受後會建立什麼
+memesh dream accept 1         # 由你決定 — 沒有東西會自動連起來
+memesh recall "retry policy"  # → 警告：偵測到衝突
+```
+
+從此之後，任何回憶到這兩個決策之一的代理都會被告知它們互相矛盾 — 而不是自信地引用剛好先找到的那一個。
+
+### 一份記憶，三個代理
+
+MeMesh 是一個 MCP server，所以同一個 SQLite 檔案能服務機器上的每一個 MCP 用戶端。每個工具只要註冊一次（確切指令見上方「60 秒快速開始」），在 Claude Code 記錄的決策，session 進行到一半時就能被 Codex 或 Gemini CLI 回憶起來 — 不用重新解釋，不用在不同廠商之間複製貼上 context。
+
+### 記錄決策讓它們保持可被找到
+
+自動擷取會保留 session 歷史，但真正划算的是那些刻意記下的記憶：
+
+```bash
+memesh remember --name auth-approach --type decision \
+  --obs "JWT 搭配 RS256；選 PKCE 而不是 implicit flow，因為 client 是公開的。" \
+  --tags "project:myapp" "topic:auth"
+```
+
+事情發生時，用平常講話的方式把結果連回原因 — 從任何 MCP 用戶端都行，像是：「把這次事故記成一個教訓，受 auth-approach 影響」。`remember` 工具接受自由格式的關係，`caused`／`influenced` 是文件裡定義的因果詞彙（因 → 果，要明確說出來 — MeMesh 從不從時間戳推論因果關係）。幾週後，`memesh recall "為什麼選 PKCE"` 會回傳那個決策，連同它記錄下來的後續影響一起 — 是可以追溯的推理，不只是剛好比對到的文字。
+
+---
+
 ## 解鎖智慧模式（可選）
 
 MeMesh 預設離線運作 — 回憶嚴格保持 LLM-free（開箱即用就有 LongMemEval-S 上 95.60% R@5）。只有當你想要在上層加入 LLM 增強的分析流程時，才需要加入 LLM API 金鑰：更聰明的 session 擷取、新記憶的自動標籤、從失敗產生教訓，以及 `dream` 壓縮：
@@ -480,7 +542,7 @@ memesh config set embedder.provider openai          # or: ollama
 | `remember` | 用觀察、關係和標籤儲存知識 |
 | `recall` | FTS5 + sqlite-vec 搜尋，包含多因素評分（相關性、近期性、頻率、信心、回憶影響）— 熱路徑上不使用 LLM |
 | `forget` | 軟歸檔（永不刪除）或移除特定觀察 |
-| `export` | 在專案或團隊成員之間以 JSON 共享記憶 |
+| `export` | 以 JSON 備份、搬遷記憶，或在相容代理之間轉移 |
 | `import` | 匯入記憶，包含合併策略（跳過 / 覆寫 / 追加） |
 | `learn` | 記錄來自錯誤的結構化教訓（錯誤、根本原因、修復、預防） |
 | `task_state` | 讀取或記下工作進度——目標、下一步、卡住的地方、剛完成的事 |
@@ -547,7 +609,7 @@ Session 開始時，有新版本可下載時會跳一行 banner（每版本每 2
 ```bash
 git clone https://github.com/PCIRCLE-AI/memesh
 cd memesh && npm install && npm run build
-npm test             # 630 項測試
+npm test
 npm run test:e2e-dashboard
 ```