linksee-memory 0.7.2 → 0.10.0
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/LICENSE +21 -21
- package/README.md +839 -678
- package/dist/bin/declare-anchor.d.ts +2 -0
- package/dist/bin/declare-anchor.js +146 -0
- package/dist/bin/detect-drift.d.ts +2 -0
- package/dist/bin/detect-drift.js +91 -0
- package/dist/bin/guard-hook.d.ts +2 -0
- package/dist/bin/guard-hook.js +96 -0
- package/dist/bin/import-sessions.js +44 -11
- package/dist/bin/install-skill.js +14 -14
- package/dist/bin/setup.js +107 -18
- package/dist/bin/stats.js +20 -20
- package/dist/db/migrate.js +52 -28
- package/dist/db/schema.sql +371 -232
- package/dist/lib/consolidate.js +19 -19
- package/dist/lib/drift-anchors.d.ts +78 -0
- package/dist/lib/drift-anchors.js +224 -0
- package/dist/lib/drift-detection.d.ts +62 -0
- package/dist/lib/drift-detection.js +416 -0
- package/dist/lib/drift-view.d.ts +62 -0
- package/dist/lib/drift-view.js +120 -0
- package/dist/lib/edge-detection.js +8 -8
- package/dist/lib/guard.d.ts +81 -0
- package/dist/lib/guard.js +321 -0
- package/dist/lib/lexical-match.d.ts +6 -0
- package/dist/lib/lexical-match.js +87 -0
- package/dist/lib/momentum.js +7 -7
- package/dist/lib/session-extractor.d.ts +1 -0
- package/dist/lib/session-extractor.js +62 -11
- package/dist/lib/truth-engine.d.ts +84 -0
- package/dist/lib/truth-engine.js +417 -0
- package/dist/mcp/read-smart.js +8 -8
- package/dist/mcp/server.js +573 -3
- package/dist/skill/SKILL.md +734 -631
- package/package.json +10 -5
package/README.md
CHANGED
|
@@ -1,678 +1,839 @@
|
|
|
1
|
-
# linksee-memory
|
|
2
|
-
|
|
3
|
-
> **Your agent forgets everything when a session ends.
|
|
4
|
-
>
|
|
5
|
-
> Local-first cross-LLM memory MCP — one SQLite file that **Claude Code, Cursor, Windsurf, OpenAI Codex, and Gemini CLI** all read from. Not just "what happened" but **WHY** it happened: 6-layer structured memory with precision recall that
|
|
6
|
-
>
|
|
7
|
-
>
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
[](https://www.npmjs.com/package/linksee-memory)
|
|
12
|
+
[](./LICENSE)
|
|
13
|
+
[](https://registry.modelcontextprotocol.io/)
|
|
14
|
+
[](https://glama.ai/mcp/servers/michielinksee/linksee-memory)
|
|
15
|
+
|
|
16
|
+
🌐 **Landing page**: [linksee-site.vercel.app](https://linksee-site.vercel.app) (includes non-developer onboarding for Claude Desktop / Cursor / Claude Code / OpenAI Codex / Gemini CLI)
|
|
17
|
+
|
|
18
|
+
## 📣 As featured on
|
|
19
|
+
|
|
20
|
+
- **Zenn**: [あなたの Claude Code、 実は前回のセッションを完全に忘れている](https://zenn.dev/kanseilink/articles/linksee-memory-claude-code-recall-20260508) — 73 ♡ on Zenn, **165+ users on Hatena Bookmark**, picked up by tech blogs + YouTube shorts (May 2026)
|
|
21
|
+
- **Zenn**: [あなたの MCP server、 実は Tools しか使ってない (5 blocks 全実装 / v0.3.0)](https://zenn.dev/kanseilink/articles/linksee-memory-mcp-five-blocks-20260507) — the 1% of MCP servers that implement all 5 blocks
|
|
22
|
+
- **Zenn**: [あなたの Claude memory、 実は Claude にしか残らない (5 LLM 横断する方法)](https://zenn.dev/kanseilink/articles/linksee-memory-claude-cross-llm-20260511) — cross-LLM memory pattern (May 12, 2026)
|
|
23
|
+
- **Zenn**: [Glama listing で 3 週間止まった話 (5 つの罠と解決策)](https://zenn.dev/michielinksee/articles/linksee-memory-mcp-publish-glama-traps-20260506) — npm + Glama deployment retrospective
|
|
24
|
+
|
|
25
|
+
> 「Cordex/Cursor/Code/Gemini 全部につなげられるから、 横断的にできてる MCP ってところがこれのすごいところ」
|
|
26
|
+
> — [Hatena Bookmark, May 2026](https://b.hatena.ne.jp/entry/s/zenn.dev/kanseilink/articles/linksee-memory-claude-code-recall-20260508) (165+ users)
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## 🎬 See it in action
|
|
31
|
+
|
|
32
|
+
**Without linksee-memory** — Monday morning, new Claude session:
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
You: We deployed last week but it crashed. How did we fix it?
|
|
36
|
+
Claude: I don't have access to previous sessions. Can you describe
|
|
37
|
+
what happened and walk me through the problem?
|
|
38
|
+
|
|
39
|
+
[30 minutes of log-spelunking and re-explanation]
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
**With linksee-memory** — Same question, different outcome:
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
You: We deployed last week but it crashed. How did we fix it?
|
|
46
|
+
Claude: Let me check my caveats...
|
|
47
|
+
|
|
48
|
+
🧠 [caveat] NextAuth sessions invalidate when JWT_SECRET
|
|
49
|
+
rotates — redeploy all affected projects in parallel.
|
|
50
|
+
(from session 2026-04-13, importance: 0.9)
|
|
51
|
+
|
|
52
|
+
Is this the deploy you're asking about? We hit it when
|
|
53
|
+
we rotated secrets mid-flow.
|
|
54
|
+
|
|
55
|
+
You: Yes, exactly. Let's not repeat that.
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
That single `caveat` memory is what separates "flat fact storage" from "the agent actually remembers the WHY". linksee-memory stores it across **six explicit layers** so retrieval stays explainable.
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 🧠 The 6-layer structure
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
┌─────────────────────────────────────────────────────────────┐
|
|
66
|
+
│ 🎯 goal ← what the user is working toward │
|
|
67
|
+
├─────────────────────────────────────────────────────────────┤
|
|
68
|
+
│ 🧭 context ← why this, why now — constraints, people │
|
|
69
|
+
├─────────────────────────────────────────────────────────────┤
|
|
70
|
+
│ 💗 emotion ← user tone signals (frustration, etc.) │
|
|
71
|
+
├─────────────────────────────────────────────────────────────┤
|
|
72
|
+
│ 🛠 implementation ← how it was done (+ what failed) │
|
|
73
|
+
├─────────────────────────────────────────────────────────────┤
|
|
74
|
+
│ ⚠️ caveat ← "never do this again" · auto-protected │
|
|
75
|
+
├─────────────────────────────────────────────────────────────┤
|
|
76
|
+
│ 🌱 learning ← patterns distilled from cold memories │
|
|
77
|
+
└─────────────────────────────────────────────────────────────┘
|
|
78
|
+
│
|
|
79
|
+
▼
|
|
80
|
+
Ranked recall via relevance × heat × momentum × importance
|
|
81
|
+
Returns match_reasons explaining each hit
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Every memory is tagged with **exactly one layer**. `caveat`-layer entries are protected from auto-forgetting. Cold low-importance memories are auto-consolidated into `learning` entries on server startup.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## What it does
|
|
89
|
+
|
|
90
|
+
Most "agent memory" services (Mem0, Letta, Zep) save a flat list of facts. Then the agent looks at "edited file X 30 times" and has no idea why. **linksee-memory keeps the WHY.**
|
|
91
|
+
|
|
92
|
+
It is a Model Context Protocol (MCP) server with **7 tools** that gives any AI agent structured memory + drift detection:
|
|
93
|
+
|
|
94
|
+
| | Mem0 / Letta / Zep | Claude Code auto-memory | linksee-memory |
|
|
95
|
+
|---|---|---|---|
|
|
96
|
+
| Cross-agent | △ (cloud) | ❌ Claude only | ✅ single SQLite file |
|
|
97
|
+
| 6-layer WHY structure | ❌ flat | ❌ flat markdown | ✅ goal / context / emotion / impl / caveat / learning |
|
|
98
|
+
| **Drift detection** | ❌ | ❌ | ✅ intent ↔ reality divergence tracking |
|
|
99
|
+
| File diff cache | ❌ | ❌ | ✅ AST-aware, 50-99% token savings on re-reads |
|
|
100
|
+
| Active forgetting | △ | ❌ | ✅ Ebbinghaus curve, caveat layer protected |
|
|
101
|
+
| Local-first / private | ❌ | ✅ | ✅ |
|
|
102
|
+
|
|
103
|
+
## Four pillars
|
|
104
|
+
|
|
105
|
+
1. **Token savings** via `read_smart` — sha256 + AST/heading/indent chunking. Re-reads return only diffs. **Measured 86% saved on a typical TS file edit, 99% saved on unchanged re-reads.**
|
|
106
|
+
2. **Cross-agent portability** — single SQLite file at `~/.linksee-memory/memory.db`. Same brain for Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI.
|
|
107
|
+
3. **WHY-first structured memory** — six explicit layers (`goal` / `context` / `emotion` / `implementation` / `caveat` / `learning`). Solves "flat fact memory is useless without goals".
|
|
108
|
+
4. **Drift detection** — declare decisions as anchors, then the engine automatically detects when committed reality diverges from stated intent. Think "Datadog for product decisions" — unaccounted divergences surface as drift, intentional evolution (recorded as supersede/fix) stays quiet.
|
|
109
|
+
|
|
110
|
+
## 🔍 Drift Detection — "Intent Datadog"
|
|
111
|
+
|
|
112
|
+
Most teams make decisions, then forget them. The agent from last week decided "we'll use FTS5 instead of vector search" — but this week a new session installs `pgvector` without knowing why that was rejected. **That's drift.** Not a bug. Not malice. Just forgotten context.
|
|
113
|
+
|
|
114
|
+
Linksee Memory's drift detection catches this:
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
You: What's drifting right now?
|
|
118
|
+
Agent: [calls drift_status]
|
|
119
|
+
|
|
120
|
+
28 anchors: ⚪ 1 held · 🔵 27 aligned
|
|
121
|
+
|
|
122
|
+
Needs attention:
|
|
123
|
+
⚪ HELD — "Focus on 4 areas: Recipe layer, agent-native API,
|
|
124
|
+
Japanese market, Agent Insights"
|
|
125
|
+
↻ Reopens 2026-07-04
|
|
126
|
+
|
|
127
|
+
Everything else is aligned — no unaccounted divergence.
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
### How it works
|
|
131
|
+
|
|
132
|
+
1. **Declare** decisions as anchors: `declare_anchor({ kind: "decision", statement: "We use FTS5, not vector search", violation_signal: ["pgvector", "embedding"] })`
|
|
133
|
+
2. **The engine detects** when committed code reality diverges from these anchors
|
|
134
|
+
3. **State derivation** classifies each anchor:
|
|
135
|
+
- 🔴 **Drift** — reality diverges with no recorded resolution
|
|
136
|
+
- 🟡 **Review** — a soft signal awaits your decision
|
|
137
|
+
- ⚪ **Held** — you acknowledged the gap, parked it with a review date
|
|
138
|
+
- 🔵 **Aligned** — reality matches intent, or a recorded resolution explains the change
|
|
139
|
+
4. **Resolve** with `fix`, `supersede`, `acknowledge`, or `dismiss`
|
|
140
|
+
|
|
141
|
+
The **make-or-break rule**: a divergence accounted for by a recorded resolution (supersede/fix/acknowledge) is NOT drift. Only unaccounted gaps are flagged. This means intentional evolution stays quiet while silent abandonment gets caught.
|
|
142
|
+
|
|
143
|
+
### 4-species taxonomy
|
|
144
|
+
|
|
145
|
+
Anchors are classified into four species with different display formats:
|
|
146
|
+
|
|
147
|
+
| Species | Icon | Display Format | Example |
|
|
148
|
+
|---|---|---|---|
|
|
149
|
+
| Hypothesis | 🧪 | Decision Card (journal format) | "We'll launch English-first on HN" |
|
|
150
|
+
| Constraint | 🔒 | Rule (pass/fail checklist) | "All writes go through remember()" |
|
|
151
|
+
| Commitment | 🔁 | Heartbeat (alive/dead) | "Ship a new version every week" |
|
|
152
|
+
| Source of Truth | 📍 | Reference (stable anchor) | "MCP server runs on stdio, single SQLite" |
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
<a id="reinjection-guard"></a>
|
|
157
|
+
|
|
158
|
+
## 🛡 Re-injection Guard — enforce decisions *before* the action
|
|
159
|
+
|
|
160
|
+
Drift detection (above) is **post-hoc** — it tells you reality diverged *after* the change lands. The re-injection guard is the **pre-action** half: it re-surfaces the decision you locked **before** the agent runs the tool that would break it.
|
|
161
|
+
|
|
162
|
+
It exists for one specific, infuriating failure mode ([anthropics/claude-code#15443](https://github.com/anthropics/claude-code/issues/15443)): *"Claude read the rule, understood it, and still used `cp`."* Having the rule in context isn't enough — so the guard runs **outside the agent's volition**, as a Claude Code hook:
|
|
163
|
+
|
|
164
|
+
| Hook event | Fires on | What it does |
|
|
165
|
+
|---|---|---|
|
|
166
|
+
| **`PreToolUse`** | `Edit` / `Write` / `Bash` | Checks the pending action against your accepted anchors. A `gate_mode:'hard'` contradiction is **denied**; a softer match re-injects the decision as a reminder; no match → nothing happens. |
|
|
167
|
+
| **`SessionStart`** | `startup` / `resume` / `compact` | Replays your locked decisions + open forks into the fresh session — killing the "groundhog day" amnesia where a new agent repeats last week's call. |
|
|
168
|
+
|
|
169
|
+
It is **fail-open by construction**: any parse / DB / logic error surfaces nothing and lets the action through. The *only* thing that ever blocks is an explicit `hard` contradiction on a decision **you** declared.
|
|
170
|
+
|
|
171
|
+
### Enable it
|
|
172
|
+
|
|
173
|
+
`npx linksee-memory-setup` offers to wire this into your **project's** `.claude/settings.json` (Step 4). To do it by hand, drop this block into `.claude/settings.json` at your project root — it points at the globally-installed `linksee-memory-guard` bin, so no build step is needed:
|
|
174
|
+
|
|
175
|
+
```json
|
|
176
|
+
{
|
|
177
|
+
"hooks": {
|
|
178
|
+
"SessionStart": [
|
|
179
|
+
{
|
|
180
|
+
"matcher": "startup|resume|compact",
|
|
181
|
+
"hooks": [
|
|
182
|
+
{ "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 15 }
|
|
183
|
+
]
|
|
184
|
+
}
|
|
185
|
+
],
|
|
186
|
+
"PreToolUse": [
|
|
187
|
+
{
|
|
188
|
+
"matcher": "Edit|Write|Bash",
|
|
189
|
+
"hooks": [
|
|
190
|
+
{ "type": "command", "command": "npx -y linksee-memory-guard", "timeout": 8 }
|
|
191
|
+
]
|
|
192
|
+
}
|
|
193
|
+
]
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
It's **project-scoped on purpose** — the guard enforces *this* repo's decisions, and you opt in per project rather than letting it deny tool calls everywhere (the Stop hook from setup, by contrast, is user-global). Declare what it should watch with `declare_anchor(...)`; set `card_policy.gate_mode:'hard'` on an anchor to make a contradiction **block** instead of just warn (the soft default only re-injects). Anchors that are stale (`at_risk`), superseded, or card-disabled never gate.
|
|
199
|
+
|
|
200
|
+
> Developing linksee-memory itself? The repo dogfoods the guard via a (gitignored) `.claude/settings.json` that points at the local build (`node ${CLAUDE_PROJECT_DIR}/dist/bin/guard-hook.js`) so it runs against your uncommitted changes. End-user projects should use the published `npx -y linksee-memory-guard` form above.
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## Quick Start — One Command
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
npx linksee-memory-setup
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
This does everything:
|
|
211
|
+
1. Registers the MCP server with Claude Code
|
|
212
|
+
2. Installs the agent skill (teaches the agent when to recall/remember)
|
|
213
|
+
3. Configures auto-capture (every session saved to your local brain)
|
|
214
|
+
4. Offers to wire the [re-injection guard](#reinjection-guard) into this project (pre-action decision enforcement)
|
|
215
|
+
|
|
216
|
+
Restart Claude Code, then just chat normally. Add **"Use Linksee"** to any prompt to trigger memory recall.
|
|
217
|
+
|
|
218
|
+
### Manual setup (if you prefer step-by-step)
|
|
219
|
+
|
|
220
|
+
<details>
|
|
221
|
+
<summary>Click to expand manual installation</summary>
|
|
222
|
+
|
|
223
|
+
**Install & register:**
|
|
224
|
+
|
|
225
|
+
```bash
|
|
226
|
+
claude mcp add -s user linksee -- npx -y linksee-memory
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Tools appear as `mcp__linksee__remember`, `mcp__linksee__recall`, `mcp__linksee__read_smart`.
|
|
230
|
+
|
|
231
|
+
**Install the skill (auto-invocation):**
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
npx -y linksee-memory-install-skill
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Copies `SKILL.md` to `~/.claude/skills/linksee-memory/`. Agent auto-fires on phrases like "前に…", "また同じエラー", "覚えておいて", new task starts, file edits, etc.
|
|
238
|
+
|
|
239
|
+
**Configure auto-capture (Stop hook):**
|
|
240
|
+
|
|
241
|
+
Add to `~/.claude/settings.json`:
|
|
242
|
+
|
|
243
|
+
```json
|
|
244
|
+
{
|
|
245
|
+
"hooks": {
|
|
246
|
+
"Stop": [
|
|
247
|
+
{
|
|
248
|
+
"matcher": "",
|
|
249
|
+
"hooks": [
|
|
250
|
+
{ "type": "command", "command": "npx -y linksee-memory-sync" }
|
|
251
|
+
]
|
|
252
|
+
}
|
|
253
|
+
]
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Each turn end takes ~100 ms. Failures are silent. Logs at `~/.linksee-memory/hook.log`.
|
|
259
|
+
|
|
260
|
+
</details>
|
|
261
|
+
|
|
262
|
+
### Other editors / CLIs
|
|
263
|
+
|
|
264
|
+
Linksee Memory is a standard MCP server (stdio). Any tool that speaks MCP can connect:
|
|
265
|
+
|
|
266
|
+
<details>
|
|
267
|
+
<summary><strong>Cursor</strong></summary>
|
|
268
|
+
|
|
269
|
+
Add to `~/.cursor/mcp.json`:
|
|
270
|
+
|
|
271
|
+
```json
|
|
272
|
+
{
|
|
273
|
+
"mcpServers": {
|
|
274
|
+
"linksee": {
|
|
275
|
+
"command": "npx",
|
|
276
|
+
"args": ["-y", "linksee-memory"]
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Restart Cursor. Memory tools appear in the agent panel.
|
|
283
|
+
|
|
284
|
+
</details>
|
|
285
|
+
|
|
286
|
+
<details>
|
|
287
|
+
<summary><strong>Windsurf</strong></summary>
|
|
288
|
+
|
|
289
|
+
Add to `~/.codeium/windsurf/mcp_config.json`:
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
{
|
|
293
|
+
"mcpServers": {
|
|
294
|
+
"linksee": {
|
|
295
|
+
"command": "npx",
|
|
296
|
+
"args": ["-y", "linksee-memory"]
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
}
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
</details>
|
|
303
|
+
|
|
304
|
+
<details>
|
|
305
|
+
<summary><strong>OpenAI Codex CLI</strong></summary>
|
|
306
|
+
|
|
307
|
+
```bash
|
|
308
|
+
codex --mcp-server "npx -y linksee-memory"
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
Or add to `~/.codex/config.json`:
|
|
312
|
+
|
|
313
|
+
```json
|
|
314
|
+
{
|
|
315
|
+
"mcpServers": {
|
|
316
|
+
"linksee": {
|
|
317
|
+
"command": "npx",
|
|
318
|
+
"args": ["-y", "linksee-memory"]
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
</details>
|
|
325
|
+
|
|
326
|
+
<details>
|
|
327
|
+
<summary><strong>Gemini CLI</strong></summary>
|
|
328
|
+
|
|
329
|
+
Add to `~/.gemini/settings.json`:
|
|
330
|
+
|
|
331
|
+
```json
|
|
332
|
+
{
|
|
333
|
+
"mcpServers": {
|
|
334
|
+
"linksee": {
|
|
335
|
+
"command": "npx",
|
|
336
|
+
"args": ["-y", "linksee-memory"]
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
}
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
</details>
|
|
343
|
+
|
|
344
|
+
All editors share the same `~/.linksee-memory/memory.db`. A decision made in Claude Code is recalled in Cursor. A caveat recorded in Windsurf prevents the same mistake in Codex.
|
|
345
|
+
|
|
346
|
+
### Database location
|
|
347
|
+
|
|
348
|
+
Default: `~/.linksee-memory/memory.db`. Override with `LINKSEE_MEMORY_DIR` env var.
|
|
349
|
+
|
|
350
|
+
## What's new in v0.9
|
|
351
|
+
|
|
352
|
+
| Feature | Detail |
|
|
353
|
+
|---|---|
|
|
354
|
+
| **Re-injection guard** | The pre-action half of drift detection. A Claude Code `PreToolUse` hook re-surfaces (or, on a `hard` contradiction, blocks) an accepted decision *before* the agent runs `Edit`/`Write`/`Bash`; a `SessionStart` boot digest replays your locked decisions into each fresh session. Fail-open by design. See [Re-injection Guard](#reinjection-guard). |
|
|
355
|
+
| **Shippable hook wiring** | `linksee-memory-setup` now offers to merge the guard hooks into your project's `.claude/settings.json` (pointing at the published `linksee-memory-guard` bin), and the block is documented for copy-paste. Previously the wiring lived only in a gitignored dogfood config. |
|
|
356
|
+
|
|
357
|
+
## What's new in v0.8
|
|
358
|
+
|
|
359
|
+
| Feature | Detail |
|
|
360
|
+
|---|---|
|
|
361
|
+
| **4 drift detection tools** | `drift_status`, `check_decision`, `declare_anchor`, `resolve_drift` — agents can now query and act on intent ↔ reality divergence. The biggest gap in agent memory (decisions are forgotten across sessions) is now closed. |
|
|
362
|
+
| **Truth engine** | State derivation logic (drift/review/held/aligned) now lives in the MCP engine, not just the dashboard. Any MCP client can query drift status. |
|
|
363
|
+
| **4-species taxonomy** | Anchors classified as hypothesis/constraint/commitment/source_of_truth with species-appropriate display formats. |
|
|
364
|
+
| **Resolution priority** | When multiple resolutions exist for an anchor, the most recent one wins (prevents stale acknowledge from shadowing a newer fix). |
|
|
365
|
+
|
|
366
|
+
<details>
|
|
367
|
+
<summary>What's new in v0.7</summary>
|
|
368
|
+
|
|
369
|
+
| Feature | Detail |
|
|
370
|
+
|---|---|
|
|
371
|
+
| **3-tool unified surface** | 8 tools → 3: `remember` (create + update + delete), `recall` (search + file history + overview), `read_smart` (token-saving reads). Fewer tools = better cross-LLM consistency. Follows Context7's proven pattern. |
|
|
372
|
+
| **Auto-consolidate** | Consolidation runs automatically on server startup (non-blocking, 7-day threshold). No manual `consolidate()` calls needed. |
|
|
373
|
+
| **Deprecation guidance** | Old tool names (`forget`, `recall_file`, etc.) return specific migration examples instead of silent failures. |
|
|
374
|
+
| **"Use Linksee Memory" trigger** | Add "Use Linksee Memory" to any prompt to force memory recall — same adoption pattern as Context7. |
|
|
375
|
+
| **Claude Code Plugin** | `claude plugin add -- linksee-memory` — ships MCP server + auto-invocation skill in one install. |
|
|
376
|
+
|
|
377
|
+
</details>
|
|
378
|
+
|
|
379
|
+
<details>
|
|
380
|
+
<summary>What's new in v0.4</summary>
|
|
381
|
+
|
|
382
|
+
| Feature | Detail |
|
|
383
|
+
|---|---|
|
|
384
|
+
| **One-command setup** | `npx linksee-memory-setup` — registers MCP server, installs skill, configures auto-capture hook. One command instead of three. |
|
|
385
|
+
| **Structured memory v2** | 3-axis classification (altitude × type × state) for every memory. Auto-extraction from sessions produces machine-scannable JSON, not raw chat dumps. |
|
|
386
|
+
| **Precision recall guide** | SKILL.md now teaches agents HOW to write effective queries, WHEN to recall vs skip, and WHEN to proactively surface caveats before risky actions. |
|
|
387
|
+
| **Five MCP Blocks** | Tools + Resources + Prompts + Sampling + Roots + Elicitation. Most MCP servers expose only Tools; linksee-memory implements all five primitives. |
|
|
388
|
+
|
|
389
|
+
</details>
|
|
390
|
+
|
|
391
|
+
## 7 Tools (v0.8)
|
|
392
|
+
|
|
393
|
+
### Memory tools
|
|
394
|
+
|
|
395
|
+
| Tool | What it does |
|
|
396
|
+
|---|---|
|
|
397
|
+
| `remember` | **Save / update / delete** memories. Auto-classifies into 6 layers. Modes: create (default), update (`memory_id` + fields), delete (`forget: true` + `memory_id`). |
|
|
398
|
+
| `recall` | **Search / file history / overview.** Modes: search (`query`), file history (`path`), entity overview (no params). FTS5 + heat × momentum ranking with `match_reasons`. |
|
|
399
|
+
| `read_smart` | **Token-saving file reader** with AST diff caching. First read = full content. Re-read unchanged = ~50 tokens. Re-read modified = changed chunks only. |
|
|
400
|
+
|
|
401
|
+
### Drift tools (v0.8.0)
|
|
402
|
+
|
|
403
|
+
| Tool | What it does |
|
|
404
|
+
|---|---|
|
|
405
|
+
| `drift_status` | **"What's drifting right now?"** Returns the truth map with 4-species classification (hypothesis/constraint/commitment/source_of_truth) and per-node state (🔴 drift / 🟡 review / ⚪ held / 🔵 aligned). |
|
|
406
|
+
| `check_decision` | **Deep-dive into a specific decision.** Returns the full context: what was decided, why, what reality says, pending candidates, and drift edges. |
|
|
407
|
+
| `declare_anchor` | **Record a decision as a truth-map anchor.** The drift detector checks these against committed reality. Supports v9 fields (domain, confidence, lifecycle, review_after). |
|
|
408
|
+
| `resolve_drift` | **Close the loop.** Record a resolution: `fix` (reality now matches), `supersede` (intent evolved), `acknowledge` (parking with review date), or `dismiss` (false positive). |
|
|
409
|
+
|
|
410
|
+
Previous versions exposed 3 tools — v0.8.0 added 4 drift tools that let agents query and act on product-level intent ↔ reality divergence. The memory tools are unchanged.
|
|
411
|
+
|
|
412
|
+
### CLI utilities
|
|
413
|
+
|
|
414
|
+
| Command | Purpose |
|
|
415
|
+
|---|---|
|
|
416
|
+
| `npx linksee-memory-setup` | One-command setup: MCP server + skill + Stop hook, then offers to wire the re-injection guard into this project. Idempotent — skips what's already done. |
|
|
417
|
+
| `npx linksee-memory` | MCP server (stdio) |
|
|
418
|
+
| `npx linksee-memory-sync` | Claude Code Stop-hook entry point |
|
|
419
|
+
| `npx linksee-memory-guard` | Re-injection guard hook: `PreToolUse` gate (`Edit`/`Write`/`Bash`) + `SessionStart` boot digest. Wired per-project (see [Re-injection Guard](#reinjection-guard)); fail-open. |
|
|
420
|
+
| `npx linksee-memory-import` | Batch-import Claude Code session JSONL history |
|
|
421
|
+
| `npx linksee-memory-install-skill` | Install the Claude Code Skill that teaches the agent when to call recall/remember/read_smart |
|
|
422
|
+
| `npx linksee-memory-stats` | Summary of the local DB (entity count / layer breakdown / top entities / top edited files). Add `--json` for machine-readable output. |
|
|
423
|
+
|
|
424
|
+
## The 6 memory layers
|
|
425
|
+
|
|
426
|
+
Each entity (person / company / project / file / concept) can have memories across six layers. Since v0.4, each memory uses the **3-axis structured format** (altitude × type × state):
|
|
427
|
+
|
|
428
|
+
```json
|
|
429
|
+
{
|
|
430
|
+
"title": "freee OAuth token expires in 24h",
|
|
431
|
+
"altitude": "implementation",
|
|
432
|
+
"type": "outcome",
|
|
433
|
+
"state": "done",
|
|
434
|
+
"what": "freee OAuth token expires in 24 hours. Must refresh proactively.",
|
|
435
|
+
"why": "freee uses short-lived tokens unlike most SaaS (usually 30-90 day expiry)",
|
|
436
|
+
"affects": ["src/integrations/freee/auth.ts"],
|
|
437
|
+
"next_action": null
|
|
438
|
+
}
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
- `caveat` memories are auto-protected from forgetting (pain lessons, never lost).
|
|
442
|
+
- `goal` memories bypass decay while the goal is active.
|
|
443
|
+
- `state` tracks lifecycle: `open` → `decided` → `in_progress` → `done` / `stalled` / `superseded`.
|
|
444
|
+
|
|
445
|
+
## Architecture
|
|
446
|
+
|
|
447
|
+
A single SQLite file (`better-sqlite3` + FTS5 trigram tokenizer for JP/EN) contains five layers:
|
|
448
|
+
|
|
449
|
+
- **Layer 1** — `entities` (facts: people / companies / projects / concepts / files)
|
|
450
|
+
- **Layer 2** — `edges` (associations, graph adjacency)
|
|
451
|
+
- **Layer 3** — `memories` (6-layer structured meanings per entity)
|
|
452
|
+
- **Layer 4** — `events` (time-series log for heat / momentum computation)
|
|
453
|
+
- **Layer 5** — `file_snapshots` + `session_file_edits` (diff cache + conversation↔file linkage)
|
|
454
|
+
|
|
455
|
+
The conversation↔file linkage is the key. Every file edit captured by the Stop hook is stored alongside the **user message that drove the edit**. So `recall({ path: "server.ts" })` returns "this file was edited 30 times across 3 days, and here are the actual user instructions that motivated each change".
|
|
456
|
+
|
|
457
|
+
## Why the design choices
|
|
458
|
+
|
|
459
|
+
- **Local-first** — your conversation history is private. Nothing leaves your machine.
|
|
460
|
+
- **Single file** — `memory.db` is one portable artifact. Backup = file copy.
|
|
461
|
+
- **MCP stdio** — works with every agent that speaks MCP, no plugins per host.
|
|
462
|
+
- **Reuses proven schemas** — `heat_score` / `momentum_score` ported from a production sales-intelligence codebase. Rule-based, no LLM dependency in the hot path.
|
|
463
|
+
|
|
464
|
+
## Roadmap
|
|
465
|
+
|
|
466
|
+
- ✅ 3-tool unified surface (remember / recall / read_smart) — v0.7.0
|
|
467
|
+
- ✅ Auto-consolidate on server startup — v0.7.0
|
|
468
|
+
- ✅ Claude Code Plugin (`claude plugin add -- linksee-memory`)
|
|
469
|
+
- ✅ Five MCP Blocks (Tools + Resources + Prompts + Sampling + Roots + Elicitation)
|
|
470
|
+
- ✅ Stop-hook auto-capture for Claude Code
|
|
471
|
+
- ✅ JP/EN trigram FTS5
|
|
472
|
+
- ✅ One-command setup (`npx linksee-memory-setup`)
|
|
473
|
+
- ✅ Structured memory v2 (3-axis classification: altitude × type × state)
|
|
474
|
+
- ✅ Cross-LLM: Claude Code, Cursor, Windsurf, OpenAI Codex, Gemini CLI
|
|
475
|
+
- ✅ Landing page ([linksee-site.vercel.app](https://linksee-site.vercel.app))
|
|
476
|
+
- ✅ Drift detection engine + 4 MCP drift tools — v0.8.0
|
|
477
|
+
- ✅ 4-species truth map (hypothesis/constraint/commitment/source_of_truth) — v0.8.0
|
|
478
|
+
- ✅ Dashboard with Decision Register visualization
|
|
479
|
+
- 🔮 Obsidian plugin (read truth map in your vault)
|
|
480
|
+
- 🔮 Vector search via `sqlite-vec` (already in deps, embedding backend pending)
|
|
481
|
+
- 🔮 Cross-device cloud sync (Pro tier)
|
|
482
|
+
|
|
483
|
+
## Comparison with Claude Code auto-memory
|
|
484
|
+
|
|
485
|
+
Claude Code ships a built-in memory feature at `~/.claude/projects/<path>/memory/*.md` — flat markdown notes for user preferences. linksee-memory **complements** it:
|
|
486
|
+
|
|
487
|
+
- auto-memory = your scrapbook of "remember I prefer X"
|
|
488
|
+
- linksee-memory = structured cross-agent brain with file diff cache and per-edit WHY
|
|
489
|
+
|
|
490
|
+
Use both.
|
|
491
|
+
|
|
492
|
+
## Telemetry (opt-in, off by default)
|
|
493
|
+
|
|
494
|
+
linksee-memory ships with **opt-in** anonymous telemetry that helps us understand which MCP servers and workflows actually work in the wild. **Nothing is sent unless you explicitly enable it.** No conversation content, no file content, no entity names, no project paths — ever.
|
|
495
|
+
|
|
496
|
+
### Enable
|
|
497
|
+
|
|
498
|
+
```bash
|
|
499
|
+
export LINKSEE_TELEMETRY=basic # opt in
|
|
500
|
+
export LINKSEE_TELEMETRY=off # opt out (or just unset the variable)
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
### Exactly what gets sent (Level 1 contract)
|
|
504
|
+
|
|
505
|
+
After each Claude Code session ends, the Stop hook sends one POST to `https://kansei-link-mcp-production.up.railway.app/api/telemetry/linksee` containing only these fields:
|
|
506
|
+
|
|
507
|
+
| Field | Example | What it is |
|
|
508
|
+
|---|---|---|
|
|
509
|
+
| `anon_id` | `d7924ced-3879-…` | Random UUID generated locally on first opt-in. Stored at `~/.linksee-memory/telemetry-id` — delete the file to reset. |
|
|
510
|
+
| `linksee_version` | `0.0.3` | Package version |
|
|
511
|
+
| `session_turn_count` | `120` | How many turns the session had |
|
|
512
|
+
| `session_duration_sec` | `3600` | How long the session lasted |
|
|
513
|
+
| `file_ops_edit/write/read` | `12, 2, 40` | Counts only |
|
|
514
|
+
| `mcp_servers` | `["kansei-link","freee","slack"]` | Names of MCP servers configured (from `~/.claude.json`). Names only — never command paths. |
|
|
515
|
+
| `file_extensions` | `{".ts":60,".md":30}` | Percent distribution of file extensions touched |
|
|
516
|
+
| `read_smart_*`, `recall_*` | counts | Tool usage counters |
|
|
517
|
+
|
|
518
|
+
**What is NEVER sent**:
|
|
519
|
+
- ❌ Conversation messages (user or assistant)
|
|
520
|
+
- ❌ File contents
|
|
521
|
+
- ❌ Entity names, project names, file paths, URLs
|
|
522
|
+
- ❌ Memory-layer text (goal / context / emotion / impl / caveat / learning)
|
|
523
|
+
- ❌ Authentication tokens, API keys, secrets
|
|
524
|
+
- ❌ Your IP address (only a one-way hash for abuse detection)
|
|
525
|
+
|
|
526
|
+
### Why we ask
|
|
527
|
+
|
|
528
|
+
Aggregated MCP-usage data helps the [KanseiLink](https://kansei-link.com) project rank which agent integrations actually work for real developers. If you're happy to contribute, `LINKSEE_TELEMETRY=basic` takes 1 second to set and helps the entire MCP ecosystem improve.
|
|
529
|
+
|
|
530
|
+
The full payload schema and validation logic is open-source — read `src/lib/telemetry.ts` if you want to verify exactly what leaves your machine.
|
|
531
|
+
|
|
532
|
+
## Pricing
|
|
533
|
+
|
|
534
|
+
**Free forever.**
|
|
535
|
+
|
|
536
|
+
linksee-memory is local-first and runs entirely on your machine. There is no hosted component you need to pay for. The SQLite DB lives in your home directory; backup = file copy.
|
|
537
|
+
|
|
538
|
+
No account, no credit card, no API key. Just install and use.
|
|
539
|
+
|
|
540
|
+
## Troubleshooting
|
|
541
|
+
|
|
542
|
+
<details>
|
|
543
|
+
<summary><b>The skill isn't firing — Claude Code doesn't call <code>recall</code> when I ask about past work.</b></summary>
|
|
544
|
+
|
|
545
|
+
1. Verify the skill was installed:
|
|
546
|
+
```bash
|
|
547
|
+
ls ~/.claude/skills/linksee-memory/SKILL.md
|
|
548
|
+
```
|
|
549
|
+
If absent, run `npx -y linksee-memory-install-skill`.
|
|
550
|
+
2. Restart Claude Code. Skills are indexed on session start.
|
|
551
|
+
3. Check that the MCP is registered under the name `linksee` (the skill expects `mcp__linksee__*` tool names):
|
|
552
|
+
```bash
|
|
553
|
+
claude mcp list | grep linksee
|
|
554
|
+
```
|
|
555
|
+
If it's registered as something else, either re-register or edit `~/.claude/skills/linksee-memory/SKILL.md` to match.
|
|
556
|
+
</details>
|
|
557
|
+
|
|
558
|
+
<details>
|
|
559
|
+
<summary><b>Stop hook isn't recording my sessions.</b></summary>
|
|
560
|
+
|
|
561
|
+
1. Check the hook log: `cat ~/.linksee-memory/hook.log`
|
|
562
|
+
2. Run a manual test:
|
|
563
|
+
```bash
|
|
564
|
+
echo '{"session_id":"test","transcript_path":"/path/to/some.jsonl"}' | npx linksee-memory-sync
|
|
565
|
+
```
|
|
566
|
+
3. Make sure the `Stop` hook in `~/.claude/settings.json` points to `npx -y linksee-memory-sync` (not the old `-import`).
|
|
567
|
+
</details>
|
|
568
|
+
|
|
569
|
+
<details>
|
|
570
|
+
<summary><b>Upgrading from v0.0.5 or earlier — my recalls are mostly tagged "Card_Navi" or my project-dir name.</b></summary>
|
|
571
|
+
|
|
572
|
+
v0.0.6+ fixed the entity detection bug that collapsed all memories into the session's starting cwd. To re-index existing history with correct project attribution, run:
|
|
573
|
+
|
|
574
|
+
```bash
|
|
575
|
+
npx linksee-memory-import --all
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
The importer is idempotent (wipes existing session data before re-inserting). Typical runtime: a few minutes for hundreds of sessions. Expect a dramatic improvement in `recall` precision afterward.
|
|
579
|
+
</details>
|
|
580
|
+
|
|
581
|
+
<details>
|
|
582
|
+
<summary><b><code>recall</code> returns too much — the context window fills up fast.</b></summary>
|
|
583
|
+
|
|
584
|
+
Reduce `max_tokens`:
|
|
585
|
+
```
|
|
586
|
+
recall({ query: "...", max_tokens: 800 }) // default is 2000
|
|
587
|
+
```
|
|
588
|
+
Or narrow with `entity_name` and `layer`:
|
|
589
|
+
```
|
|
590
|
+
recall({ query: "...", entity_name: "my-project", layer: "caveat" })
|
|
591
|
+
```
|
|
592
|
+
</details>
|
|
593
|
+
|
|
594
|
+
<details>
|
|
595
|
+
<summary><b>How do I reset / delete all memory?</b></summary>
|
|
596
|
+
|
|
597
|
+
```bash
|
|
598
|
+
rm -rf ~/.linksee-memory # nuke everything; next run creates a fresh DB
|
|
599
|
+
```
|
|
600
|
+
|
|
601
|
+
Or delete individual memories via `remember({ forget: true, memory_id: <id> })`.
|
|
602
|
+
</details>
|
|
603
|
+
|
|
604
|
+
<details>
|
|
605
|
+
<summary><b>DB is getting large (>100 MB). How do I trim it?</b></summary>
|
|
606
|
+
|
|
607
|
+
Consolidation runs automatically on server startup (7-day threshold). It clusters old cold memories into compressed learning-layer summaries. Caveat and active-goal layers are always preserved.
|
|
608
|
+
|
|
609
|
+
If you want to force a manual consolidation, restart the MCP server — auto-consolidate triggers on every startup.
|
|
610
|
+
</details>
|
|
611
|
+
|
|
612
|
+
## FAQ
|
|
613
|
+
|
|
614
|
+
<details>
|
|
615
|
+
<summary><strong>What is drift detection and why do I need it?</strong></summary>
|
|
616
|
+
|
|
617
|
+
Drift = when your code reality silently diverges from what you decided. Example: Last week you decided "FTS5, not vector search" but this week a new agent session installs pgvector without knowing the history.
|
|
618
|
+
|
|
619
|
+
Linksee Memory tracks this by letting you declare decisions as "anchors" and then automatically checking committed code against them. The make-or-break rule: **intentional evolution (recorded as fix/supersede) stays quiet, while unaccounted gaps get flagged.** It's like Datadog but for product decisions instead of server metrics.
|
|
620
|
+
|
|
621
|
+
You don't need to use drift detection to benefit from linksee-memory — the 3 memory tools (remember/recall/read_smart) work independently. Drift tools are an additional layer for teams and solo devs managing multiple projects.
|
|
622
|
+
</details>
|
|
623
|
+
|
|
624
|
+
<details>
|
|
625
|
+
<summary><strong>How is this different from Mem0 / Letta / Zep?</strong></summary>
|
|
626
|
+
|
|
627
|
+
Three axes:
|
|
628
|
+
1. **Local-first**: those tools require cloud accounts and send your data to their servers. linksee-memory runs entirely on your machine — one SQLite file, no network calls by default.
|
|
629
|
+
2. **WHY-layered**: they store flat facts or knowledge-graph nodes. linksee-memory has 6 explicit layers (`goal`/`context`/`emotion`/`implementation`/`caveat`/`learning`) so retrieval returns structured reasoning, not just data.
|
|
630
|
+
3. **File diff cache**: `read_smart` tool saves 86–99% of tokens on file re-reads via AST-aware chunking. None of the memory services do this — it's a feature usually shipped in IDEs.
|
|
631
|
+
</details>
|
|
632
|
+
|
|
633
|
+
<details>
|
|
634
|
+
<summary><strong>Why not just use Claude's built-in auto-memory?</strong></summary>
|
|
635
|
+
|
|
636
|
+
Claude Code's auto-memory is Claude-only (doesn't help if you switch to Cursor, OpenAI Codex, or Gemini CLI) and stores flat markdown with no structure. linksee-memory is the same local-first principle but:
|
|
637
|
+
- Works across Claude Code, Cursor, OpenAI Codex, Gemini CLI (shared SQLite)
|
|
638
|
+
- Structured 6-layer format makes recall explainable
|
|
639
|
+
- Auto-consolidation compresses cold memories on startup; caveats are permanently protected
|
|
640
|
+
</details>
|
|
641
|
+
|
|
642
|
+
<details>
|
|
643
|
+
<summary><strong>Is 86% token savings real? Where does it come from?</strong></summary>
|
|
644
|
+
|
|
645
|
+
Yes — see `tools/bench-read-smart.ts` in the repo. The `read_smart` tool:
|
|
646
|
+
1. Hashes file content on first read, returns full content + chunk metadata (AST/heading/indent boundaries).
|
|
647
|
+
2. On re-read with unchanged mtime+sha256, returns `~50 tokens` of "unchanged" confirmation instead of re-sending the file.
|
|
648
|
+
3. On real edits, returns only the changed chunks as full content + unchanged chunks as metadata-only references.
|
|
649
|
+
|
|
650
|
+
For a typical TypeScript file edit in an agentic loop, this cuts round-trip token costs by ~86%. On pure re-reads (user navigating back to a previously-read file), savings exceed 99%.
|
|
651
|
+
</details>
|
|
652
|
+
|
|
653
|
+
<details>
|
|
654
|
+
<summary><strong>Does "local-first" mean no way to sync across my machines?</strong></summary>
|
|
655
|
+
|
|
656
|
+
The default is no sync — the SQLite file lives at `~/.linksee-memory/memory.db` and stays there. If you want multi-machine sync, put that directory under Syncthing / iCloud Drive / Dropbox / Google Drive — it's a single file, so any file-sync tool works. (Avoid simultaneous edits from two machines while the MCP server is running on both; SQLite's WAL mode handles single-writer well but multi-writer conflicts can corrupt.)
|
|
657
|
+
</details>
|
|
658
|
+
|
|
659
|
+
<details>
|
|
660
|
+
<summary><strong>What happens when the DB gets huge?</strong></summary>
|
|
661
|
+
|
|
662
|
+
Two mechanisms:
|
|
663
|
+
1. **Ebbinghaus forgetting**: cold low-importance memories decay naturally, eligible for auto-forget sweeps. `caveat` layer and memories with `importance ≥ 0.9` are always protected.
|
|
664
|
+
2. **Auto-consolidation**: runs on every server startup (7-day threshold). Compresses clusters of cold low-importance memories by entity into a single `learning`-layer summary, then deletes the originals. No manual scheduling needed.
|
|
665
|
+
|
|
666
|
+
In practice a solo developer hits ~100MB after 6 months of heavy use. A year-old DB I tested with 80K memories still recalls in <10ms.
|
|
667
|
+
</details>
|
|
668
|
+
|
|
669
|
+
<details>
|
|
670
|
+
<summary><strong>Can I use this without Claude Code?</strong></summary>
|
|
671
|
+
|
|
672
|
+
Yes — any MCP-compatible client works:
|
|
673
|
+
- **Claude Code**: `claude mcp add -s user linksee -- npx -y linksee-memory`
|
|
674
|
+
- **Claude Desktop**: add to `claude_desktop_config.json` (see [onboarding on the LP](https://linksee-site.vercel.app))
|
|
675
|
+
- **Cursor**: add to MCP settings in Cursor → Settings → Features → Model Context Protocol
|
|
676
|
+
- **OpenAI Codex**: `codex mcp add linksee -- npx -y linksee-memory` (or `~/.codex/config.toml` with `[mcp_servers.linksee]` block)
|
|
677
|
+
- **Gemini CLI**: add to `~/.gemini/settings.json` mcpServers section
|
|
678
|
+
- **ChatGPT (web/mobile app)**: stdio MCP not supported by the consumer app — requires Remote MCP server over HTTPS (not yet available).
|
|
679
|
+
- **Custom agent**: the MCP stdio protocol is documented at modelcontextprotocol.io
|
|
680
|
+
</details>
|
|
681
|
+
|
|
682
|
+
<details>
|
|
683
|
+
<summary><strong>What telemetry does it send?</strong></summary>
|
|
684
|
+
|
|
685
|
+
**By default: zero network calls, zero telemetry.** There's an optional Level-1 telemetry mode you can enable that sends anonymized aggregate metrics (tool call counts, error rates, latency percentiles — never memory content, never file paths, never queries). The exact payload schema is documented in the [Telemetry section](#telemetry-opt-in-off-by-default) and you see every byte before opting in.
|
|
686
|
+
</details>
|
|
687
|
+
|
|
688
|
+
<details>
|
|
689
|
+
<summary><strong>How do I verify it's actually working?</strong></summary>
|
|
690
|
+
|
|
691
|
+
After install, in a new Claude session ask: *"Can you remember that I prefer TypeScript over JavaScript? Use Linksee Memory."* Claude should confirm it called `mcp__linksee__remember` and stored this. Then in a **different session** ask: *"What languages do I prefer? Use Linksee Memory."* It should recall via `mcp__linksee__recall` and return the preference with `match_reasons` showing why.
|
|
692
|
+
</details>
|
|
693
|
+
|
|
694
|
+
## Support
|
|
695
|
+
|
|
696
|
+
- **Issues & bug reports**: [github.com/michielinksee/linksee-memory/issues](https://github.com/michielinksee/linksee-memory/issues)
|
|
697
|
+
- **Feature requests**: open an issue with the `enhancement` label
|
|
698
|
+
- **Security concerns**: see [SECURITY.md](./SECURITY.md) if present, or file a private advisory on GitHub
|
|
699
|
+
- **Company**: Synapse Arrows PTE. LTD. (Singapore)
|
|
700
|
+
|
|
701
|
+
## Changelog
|
|
702
|
+
|
|
703
|
+
### v0.8.0 — Drift Detection MCP Tools (2026-06-08)
|
|
704
|
+
|
|
705
|
+
**3 tools → 7 tools.** The biggest update since launch — agents can now detect, query, and resolve intent ↔ reality drift.
|
|
706
|
+
|
|
707
|
+
**New tools:**
|
|
708
|
+
- **`drift_status`** — returns the truth map with 4-species classification and per-node drift state
|
|
709
|
+
- **`check_decision`** — deep-dive into a single anchor: state, edges, pending candidates
|
|
710
|
+
- **`declare_anchor`** — record a decision/constraint/prohibition as a truth-map node (with v9 ProjectCoreNode fields)
|
|
711
|
+
- **`resolve_drift`** — close the feedback loop: fix / supersede / acknowledge / dismiss
|
|
712
|
+
|
|
713
|
+
**New engine module:**
|
|
714
|
+
- **`truth-engine.ts`** — state derivation logic migrated from the dashboard into the MCP engine. Any MCP client can now query drift status without a dashboard.
|
|
715
|
+
- **Resolution priority fix**: when multiple resolutions reference the same anchor, the most recent one wins (by `resolved_at` timestamp). Prevents a stale acknowledge from shadowing a newer fix.
|
|
716
|
+
- **4-species classification**: nodes classified by `decision_mode` into hypothesis / constraint / commitment / source_of_truth with display format guidance.
|
|
717
|
+
|
|
718
|
+
No breaking changes to existing memory tools. All 3 memory tools (remember, recall, read_smart) are unchanged.
|
|
719
|
+
|
|
720
|
+
### v0.7.2 — Recall ergonomics + auto-edge detection + classifier precision (2026-05-30)
|
|
721
|
+
|
|
722
|
+
Quality pass on v0.7.0 / v0.7.1 — sharper day-to-day agent UX and cleaner data for the dashboard:
|
|
723
|
+
|
|
724
|
+
- **`recall` token discipline**: drops the redundant `content_raw` from the response (parsed `content` was already there — it was a 2× duplicate), and actually enforces `max_tokens` by greedy assembly that measures real serialized size (was a flat ~100 tok/memory estimate). Adds `approx_tokens` to the response so the agent can see its budget usage. The same query that previously returned ~15,800 tokens for a 1200 budget now stays inside it.
|
|
725
|
+
- **`recall` precision**: near-duplicate memories — same entity + near-identical core text, e.g. the same message captured under both `goal` and `learning` — collapse to one in the result set. Composite weights adapt to query specificity: multi-term queries weight relevance higher so off-topic-but-pinned memories don't crowd narrow recalls.
|
|
726
|
+
- **Capture dedup (write side)**: `session-extractor` now produces AT MOST one memory per user turn, with priority `goal[first_intent] > caveat > decision > context`. A first-intent message containing decision words (e.g. "決めた" / "これで進めよう") is no longer double-saved as both `goal` and `learning`.
|
|
727
|
+
- **`memory_edges` auto-detection**: the previously-empty `memory_edges` table is now populated during the sleep-mode consolidation sweep. `detectMemoryEdges()` links a later DECISION memory to the most-recent earlier same-topic decision within an entity (chain, not clique) so the dashboard can render Pivot Chains. The default relation is `extends` — a same-topic later decision builds on, but does NOT deactivate, the earlier one. Explicit reversal markers (やめる / revert / instead of) produce `contradicts`; explicit replacement markers (の代わり / replaces / deprecate) produce `supersedes`. Prevents silent deactivation of still-valid decisions.
|
|
728
|
+
- **`inferType` / `inferState` precision**: chitchat acknowledgements ("そうだね" / "ありがとう"), pasted terminal/git/email content, and meta-noise no longer classify as `decision` — they return `note` / `open` before pattern matching. The learning-layer default → `decision` is gated by this guard. Real decisions (採用 / 決めた, even after an acknowledgement opener) survive.
|
|
729
|
+
|
|
730
|
+
No schema migration, no breaking API changes. Existing rows keep their stored content; the classifier improvements apply to new captures going forward.
|
|
731
|
+
|
|
732
|
+
### v0.7.1 — Review fixes (2026-05-29)
|
|
733
|
+
|
|
734
|
+
Based on Opus 4.7 design review of v0.7.0:
|
|
735
|
+
|
|
736
|
+
- **P0 — Required params guidance**: `remember` tool description now includes "REQUIRED PARAMS BY MODE" section so LLMs know exactly which fields are needed for create vs update vs delete.
|
|
737
|
+
- **P0 — Migration guidance**: Deprecated tool names (`forget`, `recall_file`, etc.) now return specific migration examples instead of generic errors.
|
|
738
|
+
- **P1 — recall path+query merge**: When both `path` and `query` are provided to `recall`, results from file history and memory search are merged into a single response.
|
|
739
|
+
- **P2 — Auto-consolidate safety**: Table existence check via `sqlite_master` before querying `consolidations` table, preventing errors on fresh databases.
|
|
740
|
+
|
|
741
|
+
### v0.7.0 — 3-Tool Unified Surface (2026-05-29)
|
|
742
|
+
|
|
743
|
+
**8 tools → 3 tools.** Following Context7's proven pattern of fewer tools = better cross-LLM consistency.
|
|
744
|
+
|
|
745
|
+
**Breaking change**: The following tools are removed from the MCP surface. Calling them returns a migration guide:
|
|
746
|
+
|
|
747
|
+
| Old tool | New equivalent |
|
|
748
|
+
|---|---|
|
|
749
|
+
| `forget` | `remember({ forget: true, memory_id: <id> })` |
|
|
750
|
+
| `update_memory` | `remember({ memory_id: <id>, content: "..." })` |
|
|
751
|
+
| `recall_file` | `recall({ path: "server.ts" })` |
|
|
752
|
+
| `list_entities` | `recall({})` (no params = entity overview) |
|
|
753
|
+
| `consolidate` | Auto-runs on server startup (7-day threshold) |
|
|
754
|
+
|
|
755
|
+
**New unified tools:**
|
|
756
|
+
- **`remember`** — create + update + delete in one tool. Mode is inferred from params.
|
|
757
|
+
- **`recall`** — search + file history + overview in one tool. Mode is inferred from params.
|
|
758
|
+
- **`read_smart`** — unchanged.
|
|
759
|
+
|
|
760
|
+
**Other changes:**
|
|
761
|
+
- Auto-consolidate on server startup (non-blocking `setTimeout`, 7-day threshold, `sqlite_master` safety check)
|
|
762
|
+
- Claude Code Plugin bundle (`claude plugin add -- linksee-memory`)
|
|
763
|
+
- Deprecation errors include specific migration examples
|
|
764
|
+
|
|
765
|
+
All internal handler functions are preserved — this is a surface change, not a logic rewrite.
|
|
766
|
+
|
|
767
|
+
### v0.2.0 — English-first launch readiness (2026-04-20)
|
|
768
|
+
|
|
769
|
+
Prepares the package for a broader (primarily English-speaking) audience on Reddit, Hacker News, and Anthropic Discord. No breaking API changes.
|
|
770
|
+
|
|
771
|
+
- **Bilingualized `SKILL.md`** (auto-invocation skill). The bundled skill that `linksee-memory-install-skill` copies into `~/.claude/skills/linksee-memory/SKILL.md` was Japanese-first; it is now English-primary with Japanese trigger phrases preserved inline. English speakers now get the skill firing on natural English phrases ("how did we solve this before?", "same error again", "remember this") in addition to the existing JP triggers.
|
|
772
|
+
- **Install-skill CLI output is bilingual**: example test phrases shown after installation include both English and Japanese.
|
|
773
|
+
- **Session-extractor EN coverage** (`linksee-memory-import`): expanded regex patterns for decisions, failures, and caveats so English Claude Code session logs get auto-tagged correctly. Additions include `let's go`, `pivot`, `switch to`, `settled on`, `approved`, `doesn't work`, `stuck`, `same error again`, `hit an error`, `debug`, `broke`, `revert`.
|
|
774
|
+
- **Clearer caveat-forget error hint**: the previous message said "lower importance below 0.9 first, then forget" which was misleading — caveat-layer memories are permanently protected regardless of importance. The hint now correctly distinguishes layer-protection from pin-protection.
|
|
775
|
+
- **README rework** for launch readiness: added a "See it in action" before/after scenario, ASCII 6-layer diagram, MCP Official Registry + Glama score badges, landing-page link, and an 8-item FAQ covering questions that surface during public launches.
|
|
776
|
+
- Internal: SKILL.md now documents pairing with KanseiLink skill as an English workflow example.
|
|
777
|
+
|
|
778
|
+
No code changes to the MCP protocol surface; all existing MCP clients continue to work unchanged.
|
|
779
|
+
|
|
780
|
+
### v0.1.1 — Pin threshold tweak (2026-04-19)
|
|
781
|
+
|
|
782
|
+
Based on real-world feedback that `importance=0.95` memories were not
|
|
783
|
+
being treated as pinned despite intent.
|
|
784
|
+
|
|
785
|
+
- **Pin threshold lowered from `>= 1.0` to `>= 0.9`.** Memories with
|
|
786
|
+
`importance >= 0.9` are now exempt from the auto-forget sweep and
|
|
787
|
+
surface `pinned: true` in `recall` and `remember` responses. This
|
|
788
|
+
matches the natural mental model ("0.9 = high importance = should
|
|
789
|
+
survive cleanup") without requiring exact `1.0`.
|
|
790
|
+
- All existing memories with `importance >= 0.9` (including older ones
|
|
791
|
+
set to `0.9` or `0.95`) become pinned automatically — no migration
|
|
792
|
+
needed.
|
|
793
|
+
- Updated tool descriptions and error messages to reflect the new
|
|
794
|
+
threshold.
|
|
795
|
+
|
|
796
|
+
### v0.1.0 — Major UX update (2026-04-18)
|
|
797
|
+
|
|
798
|
+
Based on one week of dogfooding, here's what changed:
|
|
799
|
+
|
|
800
|
+
**New tools**
|
|
801
|
+
- `update_memory` — atomic edit with preserved `memory_id`. Solves the "forget+remember breaks session_file_edits links" bug.
|
|
802
|
+
- `list_entities` — fast "what do I know about?" primitive for session init. Supports `kind`/`min_memories` filters and returns layer breakdown.
|
|
803
|
+
- `npx linksee-memory-stats` — local DB summary CLI.
|
|
804
|
+
|
|
805
|
+
**`recall` enhancements**
|
|
806
|
+
- `match_reasons` array on each memory: e.g. `["content_match_fts", "heat:hot", "pinned"]`.
|
|
807
|
+
- `score_breakdown` with per-dimension scores (relevance / heat / momentum / importance).
|
|
808
|
+
- Pagination via `offset` / `has_more` / `stopped_by`.
|
|
809
|
+
- `limit` parameter (hard cap, complements `max_tokens` budget).
|
|
810
|
+
- `band` filter to request only hot/warm/cold/frozen memories.
|
|
811
|
+
- `mark_accessed=false` for preview queries that shouldn't bump heat.
|
|
812
|
+
- **Layer aliases**: `decisions` → `learning`, `warnings` → `caveat`, `how` → `implementation`, etc.
|
|
813
|
+
- **Fix**: opportunistic refresh of stale entity momentum scores. Entities recalled >1 h after last remember() no longer return stale momentum.
|
|
814
|
+
|
|
815
|
+
**`remember` enhancements**
|
|
816
|
+
- Quality check: rejects pasted assistant output / CI logs / stack traces unless `force=true`.
|
|
817
|
+
- `importance=1.0` now implicitly pins the memory (survives auto-forget).
|
|
818
|
+
- Layer aliases accepted.
|
|
819
|
+
|
|
820
|
+
**`forget` changes**
|
|
821
|
+
- Pinned memories (importance=1.0) now preserved alongside caveat-layer memories.
|
|
822
|
+
- Clear error response when attempting to delete a protected or missing memory.
|
|
823
|
+
- dry-run now includes `sample_ids_to_drop`.
|
|
824
|
+
|
|
825
|
+
**`consolidate` changes**
|
|
826
|
+
- `dry_run: true` preview mode — reports cluster count + candidates without writing.
|
|
827
|
+
|
|
828
|
+
**Infra**
|
|
829
|
+
- Fixed fresh-DB migration bug (was querying `meta` table before it existed).
|
|
830
|
+
- Bumped to Node 20+ for structured language feature usage.
|
|
831
|
+
|
|
832
|
+
All changes are **backward compatible** — existing integrations continue to work. Server.ts version banner now reports `v0.1.0`.
|
|
833
|
+
|
|
834
|
+
### Older versions
|
|
835
|
+
See [GitHub Releases](https://github.com/michielinksee/linksee-memory/releases).
|
|
836
|
+
|
|
837
|
+
## License
|
|
838
|
+
|
|
839
|
+
MIT — Synapse Arrows PTE. LTD.
|