@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.
- package/.claude-plugin/marketplace.json +5 -3
- package/.claude-plugin/plugin.json +6 -4
- package/AGENTS.md +116 -0
- package/README.de.md +141 -48
- package/README.md +173 -48
- package/README.zh-TW.md +142 -48
- package/dashboard/dist/index.html +15 -14
- package/dist/cli/view-live.js +3 -3
- package/dist/core/analytics.d.ts +9 -0
- package/dist/core/analytics.d.ts.map +1 -1
- package/dist/core/analytics.js +36 -18
- package/dist/core/analytics.js.map +1 -1
- package/dist/core/auto-tagger.d.ts.map +1 -1
- package/dist/core/auto-tagger.js +4 -9
- package/dist/core/auto-tagger.js.map +1 -1
- package/dist/core/briefing.d.ts +8 -0
- package/dist/core/briefing.d.ts.map +1 -0
- package/dist/core/briefing.js +92 -0
- package/dist/core/briefing.js.map +1 -0
- package/dist/core/capture-flag.d.ts +5 -0
- package/dist/core/capture-flag.d.ts.map +1 -0
- package/dist/core/capture-flag.js +10 -0
- package/dist/core/capture-flag.js.map +1 -0
- package/dist/core/config.d.ts +0 -1
- package/dist/core/config.d.ts.map +1 -1
- package/dist/core/config.js.map +1 -1
- package/dist/core/conflict-candidates.d.ts +20 -0
- package/dist/core/conflict-candidates.d.ts.map +1 -0
- package/dist/core/conflict-candidates.js +79 -0
- package/dist/core/conflict-candidates.js.map +1 -0
- package/dist/core/conflict-judge.d.ts +47 -0
- package/dist/core/conflict-judge.d.ts.map +1 -0
- package/dist/core/conflict-judge.js +189 -0
- package/dist/core/conflict-judge.js.map +1 -0
- package/dist/core/demo.d.ts.map +1 -1
- package/dist/core/demo.js +1 -1
- package/dist/core/demo.js.map +1 -1
- package/dist/core/digest-validator.d.ts.map +1 -1
- package/dist/core/digest-validator.js +3 -5
- package/dist/core/digest-validator.js.map +1 -1
- package/dist/core/doctor.d.ts +2 -0
- package/dist/core/doctor.d.ts.map +1 -1
- package/dist/core/doctor.js +59 -62
- package/dist/core/doctor.js.map +1 -1
- package/dist/core/dreamer.d.ts +5 -2
- package/dist/core/dreamer.d.ts.map +1 -1
- package/dist/core/dreamer.js +329 -25
- package/dist/core/dreamer.js.map +1 -1
- package/dist/core/embedder.d.ts +8 -4
- package/dist/core/embedder.d.ts.map +1 -1
- package/dist/core/embedder.js +82 -24
- package/dist/core/embedder.js.map +1 -1
- package/dist/core/failure-analyzer.d.ts.map +1 -1
- package/dist/core/failure-analyzer.js +7 -12
- package/dist/core/failure-analyzer.js.map +1 -1
- package/dist/core/graph.d.ts +12 -0
- package/dist/core/graph.d.ts.map +1 -1
- package/dist/core/graph.js +56 -1
- package/dist/core/graph.js.map +1 -1
- package/dist/core/guards.d.ts +20 -0
- package/dist/core/guards.d.ts.map +1 -0
- package/dist/core/guards.js +103 -0
- package/dist/core/guards.js.map +1 -0
- package/dist/core/install-channel.d.ts +1 -1
- package/dist/core/install-channel.d.ts.map +1 -1
- package/dist/core/install-channel.js +16 -5
- package/dist/core/install-channel.js.map +1 -1
- package/dist/core/install-hooks.d.ts +5 -0
- package/dist/core/install-hooks.d.ts.map +1 -1
- package/dist/core/install-hooks.js +0 -0
- package/dist/core/install-hooks.js.map +1 -1
- package/dist/core/json-utils.d.ts +1 -0
- package/dist/core/json-utils.d.ts.map +1 -1
- package/dist/core/json-utils.js +19 -10
- package/dist/core/json-utils.js.map +1 -1
- package/dist/core/kg-backfill.d.ts +5 -2
- package/dist/core/kg-backfill.d.ts.map +1 -1
- package/dist/core/kg-backfill.js +155 -5
- package/dist/core/kg-backfill.js.map +1 -1
- package/dist/core/lifecycle.d.ts.map +1 -1
- package/dist/core/lifecycle.js +14 -21
- package/dist/core/lifecycle.js.map +1 -1
- package/dist/core/memory-tool.d.ts.map +1 -1
- package/dist/core/memory-tool.js +4 -4
- package/dist/core/memory-tool.js.map +1 -1
- package/dist/core/operations.d.ts +13 -2
- package/dist/core/operations.d.ts.map +1 -1
- package/dist/core/operations.js +115 -28
- package/dist/core/operations.js.map +1 -1
- package/dist/core/prompt-safety.d.ts +1 -0
- package/dist/core/prompt-safety.d.ts.map +1 -1
- package/dist/core/prompt-safety.js +7 -0
- package/dist/core/prompt-safety.js.map +1 -1
- package/dist/core/schema-export.d.ts.map +1 -1
- package/dist/core/schema-export.js +31 -0
- package/dist/core/schema-export.js.map +1 -1
- package/dist/core/serializer.d.ts.map +1 -1
- package/dist/core/serializer.js +8 -0
- package/dist/core/serializer.js.map +1 -1
- package/dist/core/setup.d.ts +29 -0
- package/dist/core/setup.d.ts.map +1 -0
- package/dist/core/setup.js +127 -0
- package/dist/core/setup.js.map +1 -0
- package/dist/core/task-state-store.d.ts +17 -0
- package/dist/core/task-state-store.d.ts.map +1 -0
- package/dist/core/task-state-store.js +45 -0
- package/dist/core/task-state-store.js.map +1 -0
- package/dist/core/task-state.d.ts +19 -0
- package/dist/core/task-state.d.ts.map +1 -0
- package/dist/core/task-state.js +91 -0
- package/dist/core/task-state.js.map +1 -0
- package/dist/core/time-utils.d.ts +2 -0
- package/dist/core/time-utils.d.ts.map +1 -0
- package/dist/core/time-utils.js +14 -0
- package/dist/core/time-utils.js.map +1 -0
- package/dist/core/title.d.ts +5 -0
- package/dist/core/title.d.ts.map +1 -0
- package/dist/core/title.js +14 -0
- package/dist/core/title.js.map +1 -0
- package/dist/core/transcript-source.d.ts.map +1 -1
- package/dist/core/transcript-source.js +2 -3
- package/dist/core/transcript-source.js.map +1 -1
- package/dist/core/types.d.ts +5 -0
- package/dist/core/types.d.ts.map +1 -1
- package/dist/core/why.d.ts +54 -0
- package/dist/core/why.d.ts.map +1 -0
- package/dist/core/why.js +168 -0
- package/dist/core/why.js.map +1 -0
- package/dist/core/work-topology.d.ts +36 -0
- package/dist/core/work-topology.d.ts.map +1 -0
- package/dist/core/work-topology.js +192 -0
- package/dist/core/work-topology.js.map +1 -0
- package/dist/db.d.ts +33 -11
- package/dist/db.d.ts.map +1 -1
- package/dist/db.js +307 -315
- package/dist/db.js.map +1 -1
- package/dist/knowledge-graph.d.ts +1 -0
- package/dist/knowledge-graph.d.ts.map +1 -1
- package/dist/knowledge-graph.js +50 -40
- package/dist/knowledge-graph.js.map +1 -1
- package/dist/skills-manifest.json +62 -22
- package/dist/storage/conflicts.d.ts.map +1 -1
- package/dist/storage/conflicts.js +2 -7
- package/dist/storage/conflicts.js.map +1 -1
- package/dist/storage/fts-index.d.ts +4 -2
- package/dist/storage/fts-index.d.ts.map +1 -1
- package/dist/storage/fts-index.js +16 -4
- package/dist/storage/fts-index.js.map +1 -1
- package/dist/storage/schema.d.ts +20 -0
- package/dist/storage/schema.d.ts.map +1 -0
- package/dist/storage/schema.js +274 -0
- package/dist/storage/schema.js.map +1 -0
- package/dist/storage/sqlite.d.ts.map +1 -1
- package/dist/storage/sqlite.js +1 -1
- package/dist/storage/sqlite.js.map +1 -1
- package/dist/transports/cli/cli.d.ts +1 -4
- package/dist/transports/cli/cli.d.ts.map +1 -1
- package/dist/transports/cli/cli.js +579 -66
- package/dist/transports/cli/cli.js.map +1 -1
- package/dist/transports/http/server.d.ts.map +1 -1
- package/dist/transports/http/server.js +242 -303
- package/dist/transports/http/server.js.map +1 -1
- package/dist/transports/mcp/handlers.d.ts +46 -0
- package/dist/transports/mcp/handlers.d.ts.map +1 -1
- package/dist/transports/mcp/handlers.js +59 -4
- package/dist/transports/mcp/handlers.js.map +1 -1
- package/dist/transports/schemas.d.ts +29 -10
- package/dist/transports/schemas.d.ts.map +1 -1
- package/dist/transports/schemas.js +33 -8
- package/dist/transports/schemas.js.map +1 -1
- package/hooks/hooks.json +10 -0
- package/llms-install.md +138 -0
- package/package.json +14 -9
- package/scripts/hooks/_generated/capture-flag.js +17 -0
- package/scripts/hooks/_generated/fts-index.js +16 -4
- package/scripts/hooks/_generated/guards.js +110 -0
- package/scripts/hooks/_generated/schema.js +281 -0
- package/scripts/hooks/_generated/sqlite.js +1 -1
- package/scripts/hooks/_generated/task-state.js +98 -0
- package/scripts/hooks/_generated/time-utils.js +21 -0
- package/scripts/hooks/_generated/title.js +21 -0
- package/scripts/hooks/_generated/work-topology.js +199 -0
- package/scripts/hooks/_shared.js +197 -480
- package/scripts/hooks/guard-check.js +76 -0
- package/scripts/hooks/post-commit.js +31 -1
- package/scripts/hooks/pre-compact.js +13 -1
- package/scripts/hooks/pre-edit-recall.js +158 -120
- package/scripts/hooks/session-start.js +169 -82
- package/scripts/hooks/session-summary.js +78 -90
- package/skills/memesh/SKILL.md +108 -76
- package/README.es.md +0 -467
- package/README.fr.md +0 -459
- package/README.ja.md +0 -467
- package/README.ko.md +0 -467
- package/README.pt.md +0 -459
- package/README.th.md +0 -460
- package/README.vi.md +0 -459
- package/README.zh-CN.md +0 -466
- package/dist/cli/view.d.ts +0 -3
- package/dist/cli/view.d.ts.map +0 -1
- package/dist/cli/view.js +0 -523
- package/dist/cli/view.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
🌐 [English](README.md) | [繁體中文](README.zh-TW.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
|
|
4
|
+
<h1 align="center">MeMesh</h1>
|
|
5
5
|
<p align="center">
|
|
6
|
-
<strong>
|
|
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** —
|
|
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
|
-
##
|
|
21
|
+
## Install
|
|
22
22
|
|
|
23
|
-
|
|
23
|
+
**In Claude Code** — type these in the chat (hooks, memory tools and the `/memesh` skill are wired automatically):
|
|
24
24
|
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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 **
|
|
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
|
-
|
|
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
|
-
| **
|
|
330
|
-
| **
|
|
331
|
-
| **
|
|
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** —
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
#
|
|
462
|
-
#
|
|
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
|
|
482
|
-
cd memesh
|
|
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
|
```
|