linksee-memory 0.17.2 → 0.18.1

package/dist/skill/SKILL.md

@@ -30,9 +30,11 @@ description: |
 
 Claude Code forgets everything when a session ends. The solution the user taught yesterday, the failure you hit today, the decision made three days ago — all of it is normally lost. **linksee-memory is the "memory that doesn't disappear" device.**
 
-Writes are handled automatically by the Stop hook (already running). But **reads require the agent to actively pull**. This skill instills that "go look first" habit in the agent.
+Writes happen automatically only when `linksee-memory setup` installed the Stop hook. The Claude Code plugin alone has no hooks: nothing is saved unless the agent calls `remember`. Either way, **reads require the agent to actively pull**. This skill instills that "go look first" habit in the agent.
 
-*JP: Claude Code は session が終わると全部忘れる。linksee-memory は「消えない記憶」を作る装置。書き込みは Stop hook が自動でやってくれるが、読み出しはエージェントが能動的にやる必要がある。*
+*JP: Claude Code は session が終わると全部忘れる。linksee-memory は「消えない記憶」を作る装置。書き込みの自動保存は `setup` で Stop hook を入れた場合だけ。plugin 単独では hook が無いので、`remember` を呼ばない限り何も保存されない。読み出しはどちらでもエージェントが能動的にやる必要がある。*
+
+**Tool names depend on how linksee-memory was installed.** The examples below use the short tool name (`recall`, `remember`, …). Registered with `npx -y linksee-memory setup` or `claude mcp add`, the full name is `mcp__linksee__<tool>`; installed as the Claude Code plugin, it is `mcp__plugin_linksee-memory_linksee__<tool>` ([why](https://code.claude.com/docs/en/mcp#plugin-provided-mcp-servers)). Use whichever is present in your tool list.
 
 ---
 
@@ -155,7 +157,7 @@ open → decided → in_progress → done
 |---|---|---|
 | `affects` | string[] | File paths or areas this touches. Critical for future `recall_file` accuracy |
 | `next_action` | string / null | What should happen next. Null if done/completed |
-| `supersedes_id` | number / null | Memory ID this replaces (builds pivot chains) |
+| `supersedes_id` | number / null | Memory ID this replaces. Content only — the link that recall acts on is the `remember` argument `supersedes: <id>` (0.18.0) |
 | `prior_belief` | string | What we used to think (for learnings — enables belief-update tracking) |
 | `evidence_refs` | object[] | Links to evidence: `{"type": "session"|"file"|"url", "id": "...", "label": "..."}`. Store as REFERENCES, never inline the full content |
 
@@ -185,7 +187,7 @@ Before starting any new task, inject past context.
 **At the very beginning of a conversation**, use `list_entities` first to understand what you know:
 
 ```
-mcp__linksee__list_entities({ min_memories: 5, limit: 10 })
+list_entities({ min_memories: 5, limit: 10 })
 ```
 
 The returned "high-momentum entities" are the projects likely to be discussed. Each entity's `layer_breakdown` reveals patterns ("this project has many caveats", "goal is unfinished", etc.).
@@ -193,7 +195,7 @@ The returned "high-momentum entities" are the projects likely to be discussed. E
 Then, once a specific task starts, recall:
 
 ```
-mcp__linksee__recall({
+recall({
   query: "<keywords of current task — project name + technology>",
   max_tokens: 2000
 })
@@ -244,7 +246,7 @@ The recall engine uses FTS5 full-text search + heat_score ranking. Your query de
 Before touching a specific file, check its edit history:
 
 ```
-mcp__linksee__recall_file({
+recall_file({
   path_substring: "<file path or substring match>",
   max_intents: 5
 })
@@ -259,7 +261,7 @@ Returns: the file's entire edit history + **the user message that drove each edi
 When you need to read a file, **use `read_smart` instead of the standard `Read` tool**:
 
 ```
-mcp__linksee__read_smart({
+read_smart({
   path: "<absolute path>"
 })
 ```
@@ -290,7 +292,7 @@ update_memory({
 The moment an error, failure, or "doesn't work" happens, record immediately:
 
 ```
-mcp__linksee__remember({
+remember({
   entity_name: "<project name or service name>",
   entity_kind: "project",
   layer: "caveat",
@@ -330,7 +332,7 @@ mcp__linksee__remember({
 When you understand something new, change approaches, or solve a problem:
 
 ```
-mcp__linksee__remember({
+remember({
   entity_name: "<entity>",
   entity_kind: "project | concept | ...",
   layer: "learning",
@@ -372,7 +374,7 @@ Recording `prior_belief` leaves a **belief-update history**. Later, this becomes
 2. ❌ Solve an error on the spot without recording — future you (or another agent) will hit the same failure
 3. ❌ Use `Read` everywhere instead of `read_smart` (wastes tokens)
 4. ❌ Write caveats in a flippant tone — preserve them seriously
-5. ❌ Try to call a `consolidate` tool — there is none; consolidation is a server opt-in that deletes originals (see below)
+5. ❌ Try to call a `consolidate` tool — there is none; consolidation is a CLI subcommand / server opt-in (see below)
 6. ❌ Recall the same entity twice in one session without new context (wastes tokens)
 7. ❌ Write `recall({ query: "what happened last time" })` — use specific keywords
 
@@ -380,9 +382,9 @@ Recording `prior_belief` leaves a **belief-update history**. Later, this becomes
 
 ## 🔁 Consolidation — off unless the user turns it on
 
-There is no `consolidate` tool. Consolidation clusters cold, low-importance memories older than 7 days into one `learning`-layer entry and **deletes the originals**, so since 0.17.1 it never runs on its own. The user can opt in by starting the server with `LINKSEE_AUTO_CONSOLIDATE=1` (then it runs at start-up, at most weekly).
+There is no `consolidate` tool. Consolidation clusters cold, low-importance memories older than 7 days into one `learning`-layer entry. Since 0.18.1 it **keeps the originals**: each gets `consolidated_into: <summary id>` and `recall` hides it by default (`consolidated_hidden` says how many; `include_consolidated: true` shows them). Up to 0.18.0 it deleted them — rows lost that way come back only from a backup. It never runs on its own: the user runs `npx -y linksee-memory consolidate --dry-run` (shows) / `--apply` (folds), or starts the server with `LINKSEE_AUTO_CONSOLIDATE=1` (at start-up, at most weekly).
 
-Do not suggest turning it on as routine housekeeping. If the user asks about a large DB, explain the trade-off (originals are deleted) and suggest backing up `~/.linksee-memory/` first.
+Do not suggest turning it on as routine housekeeping. If the user asks about a large DB, say what it does (summaries + hidden originals, nothing deleted) and point at `--dry-run` first.
 
 **`caveat` memories and active `goal` memories are never consolidated away.**
 
@@ -435,7 +437,7 @@ User: "Let's switch to Stripe for payments"
    → Look for: type="decision", state="decided" memories on the same topic
 2. If past decision found:
    a. Tell user: "Previously we decided <X> because <reason>. Override?"
-   b. If user confirms override → use supersedes_id to link to old decision
+   b. If user confirms override → `remember({ content, supersedes: <old memory_id> })` (recall then hides the old decision)
    c. If user says "oh right, keep it" → no new memory needed, proceed
 3. If no past decision found → proceed to record (see Case E below)
 ```
@@ -714,7 +716,7 @@ Now you have both bodies of knowledge before starting
 
 | Moment | recall precision | Why |
 |---|---|---|
-| Day 1 | low (little data) | Stop hook is still collecting |
+| Day 1 | low (little data) | the Stop hook (if `setup` installed it) or your own `remember` calls are still collecting |
 | Week 1 | medium | thousands of memories, FTS5 kicks in |
 | Month 1 | high | heat_score stabilizes, important memories surface |
 | Month 3+ | strongest | learnings crystallized (distilled) |
@@ -724,6 +726,6 @@ Now you have both bodies of knowledge before starting
 ---
 
 *This skill runs on top of linksee-memory MCP v0.4.0+.*
-*Auto-write via Stop hook, explicit read via recall.*
+*Auto-write via the Stop hook when `setup` installed it (the plugin has no hooks), explicit read via recall.*
 *Listed in MCP Official Registry, PulseMCP, mcpservers.org, Glama.*
 *MIT License — Synapse Arrows PTE. LTD.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.17.2",
+  "version": "0.18.1",
   "mcpName": "io.github.michielinksee/linksee-memory",
   "description": "Hand a project over — to your next session, to Cursor/Codex/Gemini, to your successor — with the reasons attached. Local-first memory MCP for coding agents: decisions re-injected before the agent acts, drift detection across every project you run. One SQLite file, nothing leaves your machine.",
   "type": "module",
@@ -16,7 +16,8 @@
     "linksee-memory-guard": "dist/bin/guard-hook.js",
     "linksee-memory-map": "dist/bin/map-import.js",
     "linksee-memory-export": "dist/bin/export-report.js",
-    "linksee-memory-share-draft": "dist/bin/share-draft.js"
+    "linksee-memory-share-draft": "dist/bin/share-draft.js",
+    "linksee-memory-consolidate": "dist/bin/consolidate.js"
   },
   "main": "./dist/mcp/server.js",
   "files": [
@@ -30,6 +31,7 @@
   "scripts": {
     "build": "tsc && node -e \"require('fs').copyFileSync('src/db/schema.sql','dist/db/schema.sql'); require('fs').mkdirSync('dist/skill',{recursive:true}); require('fs').copyFileSync('src/skill/SKILL.md','dist/skill/SKILL.md')\"",
     "start": "node dist/mcp/server.js",
+    "test": "node test/share-draft.mjs && node test/live-check.mjs && node test/supersede-source.mjs && node test/session-import.mjs && node test/import-cli-append-only.mjs && node test/distill-triage.mjs && node test/consolidate-no-delete.mjs && node test/auto-consolidate.mjs",
     "dev": "tsx src/mcp/server.ts",
     "migrate": "node dist/db/migrate.js",
     "migrate:dev": "tsx src/db/migrate.ts",