@pcircle/memesh 4.5.1 → 4.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (202) hide show
  1. package/.claude-plugin/marketplace.json +5 -3
  2. package/.claude-plugin/plugin.json +6 -4
  3. package/AGENTS.md +116 -0
  4. package/README.de.md +141 -48
  5. package/README.md +173 -48
  6. package/README.zh-TW.md +142 -48
  7. package/dashboard/dist/index.html +15 -14
  8. package/dist/cli/view-live.js +3 -3
  9. package/dist/core/analytics.d.ts +9 -0
  10. package/dist/core/analytics.d.ts.map +1 -1
  11. package/dist/core/analytics.js +36 -18
  12. package/dist/core/analytics.js.map +1 -1
  13. package/dist/core/auto-tagger.d.ts.map +1 -1
  14. package/dist/core/auto-tagger.js +4 -9
  15. package/dist/core/auto-tagger.js.map +1 -1
  16. package/dist/core/briefing.d.ts +8 -0
  17. package/dist/core/briefing.d.ts.map +1 -0
  18. package/dist/core/briefing.js +92 -0
  19. package/dist/core/briefing.js.map +1 -0
  20. package/dist/core/capture-flag.d.ts +5 -0
  21. package/dist/core/capture-flag.d.ts.map +1 -0
  22. package/dist/core/capture-flag.js +10 -0
  23. package/dist/core/capture-flag.js.map +1 -0
  24. package/dist/core/config.d.ts +0 -1
  25. package/dist/core/config.d.ts.map +1 -1
  26. package/dist/core/config.js.map +1 -1
  27. package/dist/core/conflict-candidates.d.ts +20 -0
  28. package/dist/core/conflict-candidates.d.ts.map +1 -0
  29. package/dist/core/conflict-candidates.js +79 -0
  30. package/dist/core/conflict-candidates.js.map +1 -0
  31. package/dist/core/conflict-judge.d.ts +47 -0
  32. package/dist/core/conflict-judge.d.ts.map +1 -0
  33. package/dist/core/conflict-judge.js +189 -0
  34. package/dist/core/conflict-judge.js.map +1 -0
  35. package/dist/core/demo.d.ts.map +1 -1
  36. package/dist/core/demo.js +1 -1
  37. package/dist/core/demo.js.map +1 -1
  38. package/dist/core/digest-validator.d.ts.map +1 -1
  39. package/dist/core/digest-validator.js +3 -5
  40. package/dist/core/digest-validator.js.map +1 -1
  41. package/dist/core/doctor.d.ts +2 -0
  42. package/dist/core/doctor.d.ts.map +1 -1
  43. package/dist/core/doctor.js +59 -62
  44. package/dist/core/doctor.js.map +1 -1
  45. package/dist/core/dreamer.d.ts +5 -2
  46. package/dist/core/dreamer.d.ts.map +1 -1
  47. package/dist/core/dreamer.js +329 -25
  48. package/dist/core/dreamer.js.map +1 -1
  49. package/dist/core/embedder.d.ts +8 -4
  50. package/dist/core/embedder.d.ts.map +1 -1
  51. package/dist/core/embedder.js +82 -24
  52. package/dist/core/embedder.js.map +1 -1
  53. package/dist/core/failure-analyzer.d.ts.map +1 -1
  54. package/dist/core/failure-analyzer.js +7 -12
  55. package/dist/core/failure-analyzer.js.map +1 -1
  56. package/dist/core/graph.d.ts +12 -0
  57. package/dist/core/graph.d.ts.map +1 -1
  58. package/dist/core/graph.js +56 -1
  59. package/dist/core/graph.js.map +1 -1
  60. package/dist/core/guards.d.ts +20 -0
  61. package/dist/core/guards.d.ts.map +1 -0
  62. package/dist/core/guards.js +103 -0
  63. package/dist/core/guards.js.map +1 -0
  64. package/dist/core/install-channel.d.ts +1 -1
  65. package/dist/core/install-channel.d.ts.map +1 -1
  66. package/dist/core/install-channel.js +16 -5
  67. package/dist/core/install-channel.js.map +1 -1
  68. package/dist/core/install-hooks.d.ts +5 -0
  69. package/dist/core/install-hooks.d.ts.map +1 -1
  70. package/dist/core/install-hooks.js +0 -0
  71. package/dist/core/install-hooks.js.map +1 -1
  72. package/dist/core/json-utils.d.ts +1 -0
  73. package/dist/core/json-utils.d.ts.map +1 -1
  74. package/dist/core/json-utils.js +19 -10
  75. package/dist/core/json-utils.js.map +1 -1
  76. package/dist/core/kg-backfill.d.ts +5 -2
  77. package/dist/core/kg-backfill.d.ts.map +1 -1
  78. package/dist/core/kg-backfill.js +155 -5
  79. package/dist/core/kg-backfill.js.map +1 -1
  80. package/dist/core/lifecycle.d.ts.map +1 -1
  81. package/dist/core/lifecycle.js +14 -21
  82. package/dist/core/lifecycle.js.map +1 -1
  83. package/dist/core/memory-tool.d.ts.map +1 -1
  84. package/dist/core/memory-tool.js +4 -4
  85. package/dist/core/memory-tool.js.map +1 -1
  86. package/dist/core/operations.d.ts +13 -2
  87. package/dist/core/operations.d.ts.map +1 -1
  88. package/dist/core/operations.js +115 -28
  89. package/dist/core/operations.js.map +1 -1
  90. package/dist/core/prompt-safety.d.ts +1 -0
  91. package/dist/core/prompt-safety.d.ts.map +1 -1
  92. package/dist/core/prompt-safety.js +7 -0
  93. package/dist/core/prompt-safety.js.map +1 -1
  94. package/dist/core/schema-export.d.ts.map +1 -1
  95. package/dist/core/schema-export.js +31 -0
  96. package/dist/core/schema-export.js.map +1 -1
  97. package/dist/core/serializer.d.ts.map +1 -1
  98. package/dist/core/serializer.js +8 -0
  99. package/dist/core/serializer.js.map +1 -1
  100. package/dist/core/setup.d.ts +29 -0
  101. package/dist/core/setup.d.ts.map +1 -0
  102. package/dist/core/setup.js +127 -0
  103. package/dist/core/setup.js.map +1 -0
  104. package/dist/core/task-state-store.d.ts +17 -0
  105. package/dist/core/task-state-store.d.ts.map +1 -0
  106. package/dist/core/task-state-store.js +45 -0
  107. package/dist/core/task-state-store.js.map +1 -0
  108. package/dist/core/task-state.d.ts +19 -0
  109. package/dist/core/task-state.d.ts.map +1 -0
  110. package/dist/core/task-state.js +91 -0
  111. package/dist/core/task-state.js.map +1 -0
  112. package/dist/core/time-utils.d.ts +2 -0
  113. package/dist/core/time-utils.d.ts.map +1 -0
  114. package/dist/core/time-utils.js +14 -0
  115. package/dist/core/time-utils.js.map +1 -0
  116. package/dist/core/title.d.ts +5 -0
  117. package/dist/core/title.d.ts.map +1 -0
  118. package/dist/core/title.js +14 -0
  119. package/dist/core/title.js.map +1 -0
  120. package/dist/core/transcript-source.d.ts.map +1 -1
  121. package/dist/core/transcript-source.js +2 -3
  122. package/dist/core/transcript-source.js.map +1 -1
  123. package/dist/core/types.d.ts +5 -0
  124. package/dist/core/types.d.ts.map +1 -1
  125. package/dist/core/why.d.ts +54 -0
  126. package/dist/core/why.d.ts.map +1 -0
  127. package/dist/core/why.js +168 -0
  128. package/dist/core/why.js.map +1 -0
  129. package/dist/core/work-topology.d.ts +36 -0
  130. package/dist/core/work-topology.d.ts.map +1 -0
  131. package/dist/core/work-topology.js +192 -0
  132. package/dist/core/work-topology.js.map +1 -0
  133. package/dist/db.d.ts +33 -11
  134. package/dist/db.d.ts.map +1 -1
  135. package/dist/db.js +307 -315
  136. package/dist/db.js.map +1 -1
  137. package/dist/knowledge-graph.d.ts +1 -0
  138. package/dist/knowledge-graph.d.ts.map +1 -1
  139. package/dist/knowledge-graph.js +50 -40
  140. package/dist/knowledge-graph.js.map +1 -1
  141. package/dist/skills-manifest.json +62 -22
  142. package/dist/storage/conflicts.d.ts.map +1 -1
  143. package/dist/storage/conflicts.js +2 -7
  144. package/dist/storage/conflicts.js.map +1 -1
  145. package/dist/storage/fts-index.d.ts +4 -2
  146. package/dist/storage/fts-index.d.ts.map +1 -1
  147. package/dist/storage/fts-index.js +16 -4
  148. package/dist/storage/fts-index.js.map +1 -1
  149. package/dist/storage/schema.d.ts +20 -0
  150. package/dist/storage/schema.d.ts.map +1 -0
  151. package/dist/storage/schema.js +274 -0
  152. package/dist/storage/schema.js.map +1 -0
  153. package/dist/storage/sqlite.d.ts.map +1 -1
  154. package/dist/storage/sqlite.js +1 -1
  155. package/dist/storage/sqlite.js.map +1 -1
  156. package/dist/transports/cli/cli.d.ts +1 -4
  157. package/dist/transports/cli/cli.d.ts.map +1 -1
  158. package/dist/transports/cli/cli.js +579 -66
  159. package/dist/transports/cli/cli.js.map +1 -1
  160. package/dist/transports/http/server.d.ts.map +1 -1
  161. package/dist/transports/http/server.js +242 -303
  162. package/dist/transports/http/server.js.map +1 -1
  163. package/dist/transports/mcp/handlers.d.ts +46 -0
  164. package/dist/transports/mcp/handlers.d.ts.map +1 -1
  165. package/dist/transports/mcp/handlers.js +59 -4
  166. package/dist/transports/mcp/handlers.js.map +1 -1
  167. package/dist/transports/schemas.d.ts +29 -10
  168. package/dist/transports/schemas.d.ts.map +1 -1
  169. package/dist/transports/schemas.js +33 -8
  170. package/dist/transports/schemas.js.map +1 -1
  171. package/hooks/hooks.json +10 -0
  172. package/llms-install.md +138 -0
  173. package/package.json +14 -9
  174. package/scripts/hooks/_generated/capture-flag.js +17 -0
  175. package/scripts/hooks/_generated/fts-index.js +16 -4
  176. package/scripts/hooks/_generated/guards.js +110 -0
  177. package/scripts/hooks/_generated/schema.js +281 -0
  178. package/scripts/hooks/_generated/sqlite.js +1 -1
  179. package/scripts/hooks/_generated/task-state.js +98 -0
  180. package/scripts/hooks/_generated/time-utils.js +21 -0
  181. package/scripts/hooks/_generated/title.js +21 -0
  182. package/scripts/hooks/_generated/work-topology.js +199 -0
  183. package/scripts/hooks/_shared.js +197 -480
  184. package/scripts/hooks/guard-check.js +76 -0
  185. package/scripts/hooks/post-commit.js +31 -1
  186. package/scripts/hooks/pre-compact.js +13 -1
  187. package/scripts/hooks/pre-edit-recall.js +158 -120
  188. package/scripts/hooks/session-start.js +169 -82
  189. package/scripts/hooks/session-summary.js +78 -90
  190. package/skills/memesh/SKILL.md +108 -76
  191. package/README.es.md +0 -467
  192. package/README.fr.md +0 -459
  193. package/README.ja.md +0 -467
  194. package/README.ko.md +0 -467
  195. package/README.pt.md +0 -459
  196. package/README.th.md +0 -460
  197. package/README.vi.md +0 -459
  198. package/README.zh-CN.md +0 -466
  199. package/dist/cli/view.d.ts +0 -3
  200. package/dist/cli/view.d.ts.map +0 -1
  201. package/dist/cli/view.js +0 -523
  202. package/dist/cli/view.js.map +0 -1
package/README.md CHANGED
@@ -1,9 +1,9 @@
1
- 🌐 [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)
1
+ 🌐 [English](README.md) | [繁體中文](README.zh-TW.md) | [Deutsch](README.de.md)
2
2
 
3
3
  <p align="center">
4
- <h1 align="center">MeMesh LLM Memory</h1>
4
+ <h1 align="center">MeMesh</h1>
5
5
  <p align="center">
6
- <strong>Local memory for Claude Code and MCP coding agents.</strong><br />
6
+ <strong>Agentic memory for coding agents.</strong><br />
7
7
  One SQLite file. No Docker. No cloud required.
8
8
  </p>
9
9
  <p align="center">
@@ -16,32 +16,40 @@
16
16
 
17
17
  ---
18
18
 
19
- **MeMesh** — the open-source **memory layer** for Claude Code & MCP agents. One SQLite file. No cloud. Plugs into any LLM.
19
+ **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.
20
20
 
21
- ## 95.60% R@5 on LongMemEval-S — beats Mem0 by 46 points
21
+ ## Install
22
22
 
23
- 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):
23
+ **In Claude Code** — type these in the chat (hooks, memory tools and the `/memesh` skill are wired automatically):
24
24
 
25
- | System | R@5 | Source |
26
- |---|---|---|
27
- | **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
28
- | MemPalace | 96.6% | Vendor self-report |
29
- | Supermemory | ~82% | Vendor estimate |
30
- | Zep | 63.8% | LongMemEval paper |
31
- | Mem0 | 49.0% | LongMemEval paper |
25
+ ```
26
+ /plugin marketplace add PCIRCLE-AI/memesh
27
+ /plugin install memesh@pcircle-memesh
28
+ ```
32
29
 
33
- 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).
30
+ Restart Claude Code. A `◉ MeMesh` status line at the top of your next session means it is capturing.
34
31
 
35
- ---
32
+ **In a terminal** — the `memesh` CLI, the dashboard, and the `memesh-mcp` server for Codex / Gemini / Cursor (needs [Node 22.13+](https://nodejs.org)):
33
+
34
+ ```bash
35
+ npm install -g @pcircle/memesh
36
+ memesh doctor # verifies this install end to end
37
+ ```
38
+
39
+ 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).
40
+
41
+ > **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.
36
42
 
37
43
  ## The Problem
38
44
 
39
- 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.
45
+ 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.
40
46
 
41
- **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.
47
+ 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.
48
+
49
+ **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.
42
50
 
43
51
  > [!IMPORTANT]
44
- > Actively developed — features may change between releases. [Open an issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues) for bugs or feature requests.
52
+ > Actively developed — features may change between releases. [Open an issue](https://github.com/PCIRCLE-AI/memesh/issues) for bugs or feature requests.
45
53
 
46
54
  ---
47
55
 
@@ -65,7 +73,7 @@ flowchart TB
65
73
  subgraph paths["Two install paths"]
66
74
  direction LR
67
75
  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
68
- 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
76
+ 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
69
77
  end
70
78
 
71
79
  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
111
119
  If you use Claude Code, install MeMesh as a plugin from inside the CLI:
112
120
 
113
121
  ```
114
- /plugin marketplace add PCIRCLE-AI/memesh-llm-memory
122
+ /plugin marketplace add PCIRCLE-AI/memesh
115
123
  /plugin install memesh@pcircle-memesh
116
124
  ```
117
125
 
118
126
  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.
119
127
 
128
+ **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.)
129
+
120
130
  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.
121
131
 
122
132
  > **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
137
147
 
138
148
  If you installed via **Option A** (`/plugin install memesh@pcircle-memesh`), skip this step — Claude Code wires plugin hooks automatically.
139
149
 
140
- 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.
150
+ 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.
151
+
152
+ ```bash
153
+ memesh setup # detects Claude Code / Codex / Gemini, offers to wire each, verifies
154
+ ```
155
+
156
+ Or the individual steps by hand:
141
157
 
142
158
  ```bash
143
159
  memesh install-hooks # adds memesh's hooks to ~/.claude/settings.json
144
- memesh doctor # verifies "Hooks wired into Claude Code" passes
160
+ memesh setup --check # machine-level verification: reads the hosts' own config, changes nothing
145
161
  ```
146
162
 
147
163
  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"
167
183
 
168
184
  > **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.
169
185
 
186
+ ### Native integration: Hermes Agent
187
+
188
+ **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.
189
+
190
+ 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)**
191
+
192
+ ### Native integration: OpenClaw
193
+
194
+ **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.
195
+
196
+ **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)**
197
+
170
198
  ### Step 2: Store a decision
171
199
 
172
200
  > 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.
@@ -203,17 +231,43 @@ memesh serve
203
231
  ```
204
232
 
205
233
  <p align="center">
206
- <img src="docs/images/dashboard-search.png" alt="MeMesh Search — find any memory instantly" width="100%" />
234
+ <img src="docs/images/dashboard-search.png" alt="MeMesh — find any memory instantly" width="100%" />
207
235
  </p>
208
236
 
209
237
  <p align="center">
210
- <img src="docs/images/dashboard-analytics.png" alt="MeMesh Analytics — health score, timeline, patterns, knowledge coverage" width="100%" />
238
+ <img src="docs/images/dashboard-analytics.png" alt="MeMesh analytics — health score, timeline, patterns, knowledge coverage" width="100%" />
211
239
  </p>
212
240
 
213
241
  <p align="center">
214
242
  <img src="docs/images/dashboard-graph.png" alt="MeMesh Graph — interactive knowledge graph with type filters and ego mode" width="100%" />
215
243
  </p>
216
244
 
245
+ ### See what it remembered
246
+
247
+ 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):
248
+
249
+ ```bash
250
+ memesh briefing
251
+ ```
252
+
253
+ ```text
254
+ Where "your-project" was left off (today):
255
+ - Goal: Ship the payment retry logic
256
+ - Next: Open the PR once CI is green
257
+
258
+ Decisions and direction for "your-project":
259
+ - [decision] Use FTS5 as the retrieval baseline
260
+ ```
261
+
262
+ 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.
263
+
264
+ ### Your data
265
+
266
+ - **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.
267
+ - **Back up = copy that one file.** Restore = copy it back.
268
+ - **Pause capture anytime**: `export MEMESH_AUTO_CAPTURE=false`.
269
+ - **Delete everything**: remove `~/.memesh/`.
270
+
217
271
  ---
218
272
 
219
273
  ## Who Is This For?
@@ -282,9 +336,25 @@ Paste tools into any API call
282
336
 
283
337
  ---
284
338
 
339
+ ## Benchmarks — 95.60% R@5 on LongMemEval-S
340
+
341
+ 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):
342
+
343
+ | System | R@5 | Source |
344
+ |---|---|---|
345
+ | **MeMesh (Mode A, via `recallEnhanced()`)** | **95.60%** | [benchmarks/longmemeval/RESULTS.md](benchmarks/longmemeval/RESULTS.md) |
346
+ | MemPalace | 96.6% | Vendor self-report |
347
+ | Supermemory | ~82% | Vendor estimate |
348
+ | Zep | 63.8% | LongMemEval paper |
349
+ | Mem0 | 49.0% | LongMemEval paper |
350
+
351
+ 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).
352
+
353
+ ---
354
+
285
355
  ## What Happens Automatically In Claude Code
286
356
 
287
- You don't need to manually remember everything. MeMesh has **6 hooks** that capture and inject knowledge while you work:
357
+ You don't need to manually remember everything. MeMesh has **7 hooks** that capture and inject knowledge while you work:
288
358
 
289
359
  | When | What MeMesh does |
290
360
  |------|------------------|
@@ -294,6 +364,7 @@ You don't need to manually remember everything. MeMesh has **6 hooks** that capt
294
364
  | **After every `git commit`** | Records what you changed, with diff stats |
295
365
  | **When Claude stops** | Captures files edited, errors fixed, and auto-generates structured lessons from failures |
296
366
  | **Before context compaction** | Saves knowledge before it's lost to context limits |
367
+ | **Before risky commands and edits** | Fires the lesson-guards you accepted — a warning at the exact moment a recorded mistake is about to repeat |
297
368
 
298
369
  > **Opt out anytime:** `export MEMESH_AUTO_CAPTURE=false`
299
370
 
@@ -322,17 +393,14 @@ When npm flags an installed version as deprecated (typically a security advisory
322
393
 
323
394
  ## Dashboard
324
395
 
325
- 8 tabs, 11 languages, zero external dependencies. Access at `http://localhost:3737/dashboard` when the server is running.
396
+ 5 tabs, 11 languages, zero external dependencies. Access at `http://localhost:3737/dashboard` when the server is running.
326
397
 
327
398
  | Tab | What you see |
328
399
  |-----|-------------|
329
- | **Insights** | Memory insights — weekly recaps and pattern proposals from the dreamer engine; one-click accept/reject |
330
- | **Search** | Full-text + vector similarity search across all memories |
331
- | **Browse** | Paginated list of all entities with archive/restore |
332
- | **Analytics** | Memory Health Score, 30-day timeline, PM velocity + KG connectivity metrics, work patterns, cleanup suggestions |
400
+ | **Home** | What memesh did for you dreamer insights lead: weekly recaps and pattern proposals with one-click accept/reject; the full analytics stack (Memory Health Score, 30-day timeline, PM velocity + KG connectivity, work patterns) folds into an on-demand expander |
401
+ | **Memories** | The whole library behind one surface — instant filter plus Enter for server-ranked search (full-text + vector), scope chips for the work layer (goals/decisions/lessons/plans) vs evidence vs all vs archived, a cluster composition bar, per-row expandable detail (lessons keep their structured error/root-cause/fix/prevention view), archive/restore inline |
402
+ | **Project** | One project's history the roadmap view (phases, milestones, key lessons) behind a project selector |
333
403
  | **Graph** | Interactive force-directed knowledge graph with type filters, search, ego mode, recency heatmap |
334
- | **Lessons** | Structured lessons from past failures (error, root cause, fix, prevention) |
335
- | **Manage** | Archive and restore entities |
336
404
  | **Settings** | LLM provider config, instant language selector |
337
405
 
338
406
  ---
@@ -347,7 +415,7 @@ When npm flags an installed version as deprecated (typically a security advisory
347
415
 
348
416
  **🔄 Knowledge Evolution** — Decisions change. `forget` archives old memories (never deletes). `supersedes` relations link old → new. Your AI always sees the latest version.
349
417
 
350
- **⚠️ Conflict Detection** — If you have two memories that contradict each other, MeMesh warns you.
418
+ **⚠️ 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.
351
419
 
352
420
  **🕸️ 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.
353
421
 
@@ -365,7 +433,59 @@ Imported bundles stay searchable, but MeMesh does not auto-inject imported memor
365
433
  > — **3-person startup, shared knowledge base**
366
434
 
367
435
  > "The dashboard showed me that 90% of my memories were auto-generated session logs. I started using `remember` deliberately for architecture decisions. Game changer."
368
- > — **Developer who discovered the Analytics tab**
436
+ > — **Developer who discovered the analytics panel**
437
+
438
+ ---
439
+
440
+ ## Recipes
441
+
442
+ ### Catch a contradiction before it bites
443
+
444
+ Two decisions, made weeks apart, that cannot both be true — the failure mode
445
+ a memory layer exists to catch:
446
+
447
+ ```bash
448
+ memesh remember --name retry-policy --type decision \
449
+ --obs "All HTTP clients retry failed requests up to 5 times with exponential backoff."
450
+ # ...weeks later, someone decides the opposite...
451
+ memesh remember --name retry-policy-v2 --type decision \
452
+ --obs "HTTP clients must never retry automatically — fail fast and surface the error."
453
+
454
+ memesh dream conflicts # the judge flags the pair, with its reasoning
455
+ memesh dream show 1 # read the verdict, the excerpts, what accepting creates
456
+ memesh dream accept 1 # YOU decide — nothing is ever linked automatically
457
+ memesh recall "retry policy" # → Warning: Conflicts detected
458
+ ```
459
+
460
+ From then on, any assistant that recalls either decision is told they
461
+ conflict — instead of confidently quoting whichever one it found first.
462
+
463
+ ### One memory, three assistants
464
+
465
+ MeMesh is an MCP server, so the same SQLite file serves every MCP client on
466
+ the machine. Register it once per tool (exact commands in
467
+ [Get Started](#get-started-in-60-seconds)) and a decision recorded in Claude
468
+ Code is recalled by Codex or Gemini CLI mid-session — no re-explaining, no
469
+ copy-pasting context between vendors.
470
+
471
+ ### Record decisions so they stay findable
472
+
473
+ Auto-capture keeps session history, but the memories that pay rent are the
474
+ deliberate ones:
475
+
476
+ ```bash
477
+ memesh remember --name auth-approach --type decision \
478
+ --obs "JWT with RS256; PKCE over implicit flow because the client is public." \
479
+ --tags "project:myapp" "topic:auth"
480
+ ```
481
+
482
+ Then link consequences to their causes as they happen — from any MCP client,
483
+ in plain words: *"remember this incident as a lesson, influenced by
484
+ auth-approach"*. The `remember` tool takes free-form relations, and `caused` /
485
+ `influenced` are the documented causal vocabulary (cause → effect, stated
486
+ explicitly — MeMesh never infers causality from timestamps). Weeks later,
487
+ `memesh recall "why did we pick PKCE"` returns the decision with its recorded
488
+ consequences attached — reasoning you can follow, not just text that matched.
369
489
 
370
490
  ---
371
491
 
@@ -392,13 +512,13 @@ By default MeMesh does **keyword-only** recall (FTS5) — no API key, no model d
392
512
 
393
513
  ```bash
394
514
  memesh config set embedder.provider ollama # local, needs `ollama serve`
395
- memesh config set embedder.model nomic-embed-text
396
515
  # or, for a hosted embedder:
397
516
  memesh config set embedder.provider openai
398
- memesh config set embedder.model text-embedding-3-small
399
517
  ```
400
518
 
401
- The embedder is configured **independently of the chat LLM** — changing `llm.provider` never silently changes your embeddings. If you switch to an embedder with a different dimension (e.g. 768 → 1536), MeMesh rebuilds the vector index automatically on the next write. Supported `embedder.provider` values: `ollama` (local), `openai` (hosted). With none set, recall stays on keyword search.
519
+ The embedder is configured **independently of the chat LLM** — changing `llm.provider` never silently changes your embeddings. Each provider pins its own model and width (`ollama` nomic-embed-text at 768, `openai` text-embedding-3-small at 1536); the model is not separately selectable, because a vector index is fixed at one width and a second model would put vectors from a different embedding space into it.
520
+
521
+ If you switch to an embedder with a different dimension (e.g. 768 → 1536), **nothing is deleted**. MeMesh keeps the existing index and tells you on open to run `memesh reindex`, which builds the new index beside the old one and switches over only once every memory has a vector — so an interrupted rebuild costs you nothing and resumes where it stopped. During that window semantic search is off and recall runs on keyword search alone; `recall` reports this as `degraded` rather than implying it searched. Supported `embedder.provider` values: `ollama` (local), `openai` (hosted). With none set, recall stays on keyword search.
402
522
 
403
523
  | | Level 0 (default) | Level 1 (Smart Mode) |
404
524
  |---|---|---|
@@ -411,7 +531,7 @@ The embedder is configured **independently of the chat LLM** — changing `llm.p
411
531
 
412
532
  ---
413
533
 
414
- ## All 7 Memory Tools
534
+ ## All 9 Memory Tools
415
535
 
416
536
  | Tool | What it does |
417
537
  |------|-------------|
@@ -421,6 +541,8 @@ The embedder is configured **independently of the chat LLM** — changing `llm.p
421
541
  | `export` | Share memories as JSON between projects or team members |
422
542
  | `import` | Import memories with merge strategies (skip / overwrite / append) |
423
543
  | `learn` | Record structured lessons from mistakes (error, root cause, fix, prevention) |
544
+ | `task_state` | Read or record where the work stands — goal, next step, blocker, what was just finished |
545
+ | `briefing` | The assembled work topology — the same block Claude Code gets at session start, for any MCP client |
424
546
  | `user_patterns` | Analyze your work patterns — schedule, tools, strengths, learning areas |
425
547
 
426
548
  ---
@@ -452,19 +574,22 @@ Claude Code's plugin marketplace pins versions at install time and does **not**
452
574
 
453
575
  **Option A — `/plugin` UI**: uninstall `memesh@pcircle-memesh`, then reinstall. Claude Code fetches the latest marketplace version.
454
576
 
455
- **Option B — one-line script** (no UI clicking, idempotent):
577
+ **Option B — one command** (no UI clicking, idempotent; requires the npm CLI, `npm install -g @pcircle/memesh`):
578
+
579
+ ```bash
580
+ memesh upgrade-plugin
581
+ ```
582
+
583
+ 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`).
584
+
585
+ Plugin-only users without the npm CLI can still run the script by hand — substitute your installed version into the path:
456
586
 
457
587
  ```bash
458
- # If your plugin install is v4.2.5 or newer, the script ships inside it:
459
588
  bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
460
589
 
461
- # If you installed before v4.2.5 (i.e. you're on v4.2.4 or v4.2.3),
462
- # the script isn't in your plugin yet. Use the npm-global copy instead:
590
+ # Installs from before v4.2.5 don't contain the script yet; use the
591
+ # npm-global copy instead (see "Install paths at a glance" above):
463
592
  bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
464
-
465
- # (That assumes you've also run `npm install -g @pcircle/memesh`. If you
466
- # haven't, this is also a good moment to — see the "Install paths at a
467
- # glance" section above for why most users want both paths.)
468
593
  ```
469
594
 
470
595
  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 +603,8 @@ Session start surfaces a one-line banner (throttled to once per 24h per version)
478
603
  ## Contributing
479
604
 
480
605
  ```bash
481
- git clone https://github.com/PCIRCLE-AI/memesh-llm-memory
482
- cd memesh-llm-memory && npm install && npm run build
606
+ git clone https://github.com/PCIRCLE-AI/memesh
607
+ cd memesh && npm install && npm run build
483
608
  npm test
484
609
  npm run test:e2e-dashboard
485
610
  ```