linksee-memory 0.15.1 → 0.16.0

package/README.md

@@ -1,12 +1,12 @@
 # linksee-memory
 
-> **Your agent forgets everything when a session ends. Worse — it silently drifts from what you decided last week.**
+> **Claude Code forgets everything when you start a new session. Your successor knows even less.**
 >
-> **Linksee Memory catches when your project drifts from its own decisions** — the option abandoned at a fork, the pipeline that quietly stalled, the code that contradicts what you agreed — and a re-injection guard re-surfaces the locked decision **before** the agent acts. Rules you've explicitly hardened get blocked.
+> **Linksee Memory lets you hand a project over — to your next session, to Cursor or Codex, to the person after you — with the reasons attached.** Record a decision once (`remember({ content, anchor: {} })`) and it comes back *before* the agent acts on it: re-injected on session start and ahead of every Edit / Write / Bash that touches it. Change your mind on the record and it stops nagging; leave it and it keeps the next agent from repeating last week's mistake.
 >
-> Underneath sits a 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**: 6-layer structured memory with precision recall and an AST-aware diff cache (50–99% token savings on re-reads).
+> Underneath: **drift detection** across every project you run in parallel — which ones quietly left their goal (🔴), which were checked and hold (🔵), which nobody has looked at yet (⚫). One local SQLite file that **Claude Code, Cursor, Windsurf, OpenAI Codex and Gemini CLI** all read. Nothing leaves your machine.
 >
-> `npx -y linksee-memory setup` — one command, done.
+> `npx -y linksee-memory setup` — one command, on in every repo.
 
 [![npm](https://img.shields.io/npm/v/linksee-memory.svg)](https://www.npmjs.com/package/linksee-memory)
 [![license](https://img.shields.io/npm/l/linksee-memory.svg)](./LICENSE)
@@ -19,6 +19,46 @@
 <!-- releases: tag-driven, published from CI via npm trusted publishing (OIDC).
      See .github/workflows/publish.yml — no token, no OTP, provenance attached automatically. -->
 
+## Questions this answers
+
+These are the questions people actually type — measured, verbatim (2026-09-04). If yours is here, this is the answer.
+
+**Claude Code forgets everything when I start a new session. How do I make it remember decisions across sessions?**  
+Run `npx -y linksee-memory setup`. Every new session opens with `recall()` — a brief of what needs attention, where you are, what's unresolved — and your locked decisions are re-injected before the agent acts. Nothing to re-explain.
+
+**Claude Codeがセッションをまたぐと過去の経緯を忘れてしまいます。記憶を持たせる方法を教えてください。**  
+`npx -y linksee-memory setup` の一回で入ります。新しいセッションは `recall()` の brief（注意すべきこと・いまどこか・未解決）から始まり、固定した決定は行動の直前に再注入されます。説明し直す必要はありません。
+
+**What is the best MCP server for persistent memory across AI coding agents?**  
+Honest answer: if "remember across sessions" is all you need, a `CLAUDE.md` is enough — we measured it. Linksee is for the three moments it isn't: right before a mistake, when you change your mind, and when you run many projects and need to see which one drifted.
+
+**AIコーディングエージェント用の記憶MCPサーバーでおすすめはありますか？**  
+正直に言うと、「セッションを跨いで覚える」だけなら `CLAUDE.md` で足ります（実測しました）。Linksee が要るのは、間違いかけたとき・方針を変えたとき・並行案件のどれが外れたかを知りたいとき、の3場面です。
+
+**I want one shared memory between Claude Code, Cursor, and OpenAI Codex. What tools exist for that?**  
+One SQLite file. Claude Code, Cursor, Windsurf, OpenAI Codex and Gemini CLI all read and write the same memory — a decision made in one shows up in the others.
+
+**Claude CodeとCursorとCodexで同じ記憶を共有したいのですが、どうすればいいですか？**  
+SQLite ファイル1つを全員で読みます。Claude Code / Cursor / Windsurf / Codex / Gemini CLI のどこで決めた決定も、他のエージェントの行動の直前に出てきます。
+
+**My AI agent keeps re-implementing things we already decided against. How can I detect that a codebase has drifted from past decisions?**  
+Declare the decision (`remember({ content, anchor: { violation_signal: [...] } })`). The guard then warns — or blocks, if you hardened it — the moment an edit contradicts it, and `drift_status` shows every decision that reality has quietly left.
+
+**過去に決めた設計方針とコードがずれていないかを検出できるツールはありますか？**  
+決定を宣言しておくと（`remember({ content, anchor: {...} })`）、それに反する編集の直前に警告（hardened なら拒否）が出ます。`drift_status` は「宣言と現実がずれた決定」を証拠つきで一覧します。
+
+**Is there a local-first, self-hosted alternative to Mem0 for agent memory?**  
+Yes. No account, no API key, no cloud — one local file, MIT licensed. `npx -y linksee-memory setup` and it's on.
+
+**Mem0 vs Zep vs Letta for a coding agent's long-term memory — which should I pick?**  
+We installed them and ran one scenario across all of them. Storing and recalling a decision: everyone passes. The difference appears *before a mistake* and *when you change your mind* — Linksee is built for those two moments; the others leave them to you.
+
+**How do I stop Claude Code from repeating the same mistake it made last week?**  
+Record it as a caveat (`remember({ content, layer: 'caveat' })`). Caveats are protected from forgetting and come back when the same ground is touched again — and if you anchor it, the guard stops the repeat before it lands.
+
+**開発の意思決定履歴をMCPサーバーで残しておく定番のやり方はありますか？**  
+`remember({ content, anchor: {} })` の1回で、記録と強制が同時に入ります。`drift_status` がその台帳で、各決定が いま守られているか（🔵）・ずれているか（🔴）・誰も確かめていないか（⚫）を示します。
+
 ## 🪄 Three spells to remember
 
 | Say this | What happens |

package/dist/lib/distill-triage.d.ts

@@ -0,0 +1,29 @@
+import type Database from 'better-sqlite3';
+export declare const SETTLE_SECONDS: number;
+export declare const STALE_DAYS = 90;
+export declare const SHORT_CHARS = 40;
+export type TriageVerdict = 'auto-noise' | 'auto-stale' | 'keep';
+export declare function classifyRaw(what: string, ageDays: number, accessCount: number): {
+    verdict: TriageVerdict;
+    reason: string;
+};
+export interface TriageReport {
+    scanned: number;
+    noise: number;
+    stale: number;
+    remaining: number;
+    dryRun: boolean;
+    samples: {
+        noise: string[];
+        stale: string[];
+    };
+}
+/**
+ * Walk every needs_distill memory outside the settle window and archive the ones a rule can
+ * settle. Idempotent — archived rows no longer match the WHERE clause.
+ */
+export declare function triageDistillQueue(db: Database.Database, opts?: {
+    dryRun?: boolean;
+}): TriageReport;
+/** Count of rows still awaiting a human/agent rewrite (outside the settle window). */
+export declare function distillPending(db: Database.Database): number;

package/dist/lib/distill-triage.js

@@ -0,0 +1,104 @@
+// distill-triage — keep the distill queue honest without an LLM.
+//
+// The Stop hook stores raw user utterances with needs_distill:true (no LLM runs in the hook
+// path — anchor #70), and the agent is meant to rewrite them via recall({ dream: true }). On
+// the author's machine that queue reached 389 and nobody drained it, because most of it was
+// never a decision: "OK. Aからいこう", a pasted file path, "はい。そうしましょう". Asking an
+// agent to distill those is asking it to find meaning that is not there.
+//
+// So: classify before asking. Two verdicts need no intelligence, only a rule —
+//   auto-noise  the utterance carries no decision object (too short, a bare acknowledgement or
+//               imperative, a path/URL/attachment reference)
+//   auto-stale  never recalled and older than STALE_DAYS — whatever it was, nobody came back
+//
+// Both are archived, never deleted: type → note, state → superseded, distill_verdict records
+// why. needs_distill stays TRUE — anchor #70 says the flag must not be dropped, and it stays
+// truthful: no agent ever rewrote this row. The queue, the pending count and the boot digest
+// exclude rows that carry a verdict. Layer and protection are untouched (a caveat stays a
+// caveat — it just stops being asked about). Reversible: delete distill_verdict from the JSON.
+//
+// Measured before shipping (2026-09-07, 389 raw): noise 88, stale 51, queue 250 — and the
+// noise sample was read by a human before the rule was trusted.
+export const SETTLE_SECONDS = 30 * 60; // a session still in motion is not triaged (matches dream)
+export const STALE_DAYS = 90;
+export const SHORT_CHARS = 40;
+const ACK_ONLY = /^(ok|okay|はい|そうだね|そうですね|うん|了解|いいね|ありがとう|お願い|進めて|次いこう|やろう|それで|続けて|よし|では|じゃあ|なるほど)[\s。、.,!！]*$/i;
+const ACK_LEAD = /^(ok|okay|はい|そうだね|そうですね|うん|了解|いいね|ありがとう|よし|では|じゃあ|なるほど)[\s。、.,!！]+/i;
+const BARE_REF = /^(@"|@[A-Za-z]:|"?[A-Za-z]:\\|https?:\/\/)/;
+const DECISION_OBJECT = /決めた|採用|確定|却下|やめ|禁止|方針|に(する|しよう)|でいこう|で行こう|decid|chose|going with|switch(ing)? to|settled on|approved|instead/i;
+export function classifyRaw(what, ageDays, accessCount) {
+    const w = (what ?? '').trim();
+    if (w.length < SHORT_CHARS)
+        return { verdict: 'auto-noise', reason: `shorter than ${SHORT_CHARS} chars` };
+    if (ACK_ONLY.test(w))
+        return { verdict: 'auto-noise', reason: 'acknowledgement only' };
+    if (BARE_REF.test(w) && w.length < 120)
+        return { verdict: 'auto-noise', reason: 'bare path/URL reference' };
+    if (ACK_LEAD.test(w) && !DECISION_OBJECT.test(w) && w.length < 80)
+        return { verdict: 'auto-noise', reason: 'acknowledgement with no decision object' };
+    if (ageDays > STALE_DAYS && accessCount === 0)
+        return { verdict: 'auto-stale', reason: `never recalled in ${STALE_DAYS}+ days` };
+    return { verdict: 'keep', reason: '' };
+}
+/**
+ * Walk every needs_distill memory outside the settle window and archive the ones a rule can
+ * settle. Idempotent — archived rows no longer match the WHERE clause.
+ */
+export function triageDistillQueue(db, opts = {}) {
+    const now = Math.floor(Date.now() / 1000);
+    const rows = db
+        .prepare(`SELECT id, content, access_count, created_at FROM memories
+        WHERE json_valid(content)
+          AND json_extract(content, '$.needs_distill') = 1
+          AND json_extract(content, '$.distill_verdict') IS NULL
+          AND created_at < ?`)
+        .all(now - SETTLE_SECONDS);
+    const report = { scanned: rows.length, noise: 0, stale: 0, remaining: 0, dryRun: !!opts.dryRun, samples: { noise: [], stale: [] } };
+    const update = db.prepare('UPDATE memories SET content = ? WHERE id = ?');
+    const apply = db.transaction(() => {
+        for (const r of rows) {
+            let c;
+            try {
+                c = JSON.parse(r.content);
+            }
+            catch {
+                report.remaining++;
+                continue;
+            }
+            const what = String(c.what ?? '');
+            const ageDays = (now - r.created_at) / 86400;
+            const { verdict, reason } = classifyRaw(what, ageDays, r.access_count ?? 0);
+            if (verdict === 'keep') {
+                report.remaining++;
+                continue;
+            }
+            if (verdict === 'auto-noise')
+                report.noise++;
+            else
+                report.stale++;
+            const bucket = report.samples[verdict === 'auto-noise' ? 'noise' : 'stale'];
+            if (bucket.length < 5)
+                bucket.push(what.replace(/\s+/g, ' ').slice(0, 80));
+            if (opts.dryRun)
+                continue;
+            c.distill_verdict = verdict;
+            c.distill_reason = reason;
+            c.type = 'note';
+            c.state = 'superseded';
+            update.run(JSON.stringify(c), r.id);
+        }
+    });
+    apply();
+    return report;
+}
+/** Count of rows still awaiting a human/agent rewrite (outside the settle window). */
+export function distillPending(db) {
+    const now = Math.floor(Date.now() / 1000);
+    const r = db
+        .prepare(`SELECT COUNT(*) AS c FROM memories
+        WHERE json_valid(content) AND json_extract(content, '$.needs_distill') = 1
+          AND json_extract(content, '$.distill_verdict') IS NULL AND created_at < ?`)
+        .get(now - SETTLE_SECONDS);
+    return r?.c ?? 0;
+}
+//# sourceMappingURL=distill-triage.js.map

package/dist/lib/guard.js

@@ -264,6 +264,7 @@ export function buildBootDigest(db, opts = {}) {
     try {
         distill = db.prepare(`SELECT COUNT(*) AS n FROM memories
           WHERE layer IN ('learning', 'caveat') AND json_valid(content)
+            AND json_extract(content, '$.distill_verdict') IS NULL
             AND (json_extract(content, '$.needs_distill') = 1
                  OR json_extract(content, '$.why') = 'Decision detected by pattern match — may need agent enrichment'
                  OR json_extract(content, '$.why') = 'User-stated warning/prohibition — auto-extracted by caveat pattern match')`).get().n;
@@ -285,7 +286,7 @@ export function buildBootDigest(db, opts = {}) {
             parts.push(`• ${f.statement ?? f.rationale}`);
     }
     if (distill > 0) {
-        parts.push('', `🧪 ${distill} auto-captured memories are still raw utterances — call dream() and rewrite the distill_queue via remember(memory_id, content) with "distilled": true.`);
+        parts.push('', `🧪 ${distill} auto-captured memories still need a rewrite (rules already settled the acknowledgements and stale ones). Do 3: recall({ dream: true }) → remember({ memory_id, content }) with "distilled": true.`);
     }
     if (anchors.length > 0)
         parts.push('', 'Honor these unless you explicitly supersede them (resolve_drift action=supersede).');

package/dist/mcp/server.js

@@ -24,6 +24,7 @@ import { getTruthView, getDecisionDetail, resolveDrift } from '../lib/truth-engi
 import { declareAnchor, setNodeFields } from '../lib/drift-anchors.js';
 import { getReinjectionFriction, setGateMode } from '../lib/guard.js';
 import { logAnchorTouch } from '../lib/anchor-touch.js';
+import { triageDistillQueue, distillPending } from '../lib/distill-triage.js';
 import { whereAmI, listMapProjects } from '../lib/map-view.js';
 import { readFileSync, existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
@@ -90,6 +91,13 @@ setTimeout(() => {
         if (shouldRun) {
             runConsolidate(db, { scope: 'all', min_age_days: 7 });
             process.stderr.write('[linksee-memory] auto-consolidate complete\n');
+            // Triage the distill queue by rule before any agent is asked to think about it.
+            try {
+                const t = triageDistillQueue(db);
+                if (t.noise + t.stale > 0)
+                    process.stderr.write(`[linksee-memory] distill triage: archived ${t.noise} noise + ${t.stale} stale, ${t.remaining} remain\n`);
+            }
+            catch { /* never block startup */ }
         }
     }
     catch { /* non-fatal */ }
@@ -195,6 +203,7 @@ const TOOLS = [
                 where: { description: 'Locate on the Current Truth Map. A topic string, or true to auto-locate from the files you edited recently. Returns your node, journey stage, blast radius, and the decision behind it.', anyOf: [{ type: 'string' }, { type: 'boolean' }] },
                 project: { type: 'string', description: 'With where: the Map project slug, when several maps are imported.' },
                 dream: { type: 'boolean', default: false, description: 'Return the full triage set: North Star, orphaned proposals (each with candidate_id), distill_queue, friction. Resolve proposals with resolve_drift({ candidate_id, action }); rewrite distill items with remember({ memory_id, content }).' },
+                distill: { type: 'number', description: 'With dream: how many raw memories to return for rewriting (default 8, max 25). The queue is value-ordered; rule-verdicted items never appear.' },
                 overview: { type: 'boolean', default: false, description: 'Return the entity list instead of the session brief when no query is given.' },
                 kind: { type: 'string', enum: ['person', 'company', 'project', 'concept', 'file', 'other'], description: 'For overview mode: filter by entity kind.' },
                 min_memories: { type: 'number', description: 'For overview mode: minimum memory count. Default 1.', default: 1 },
@@ -1431,7 +1440,7 @@ async function handleSessionBrief() {
             north_star: d.north_star ? { id: d.north_star.id, statement: String(d.north_star.statement).slice(0, 160) } : null,
             proposals: d.total ?? 0,
             proposals_top: (d.candidates ?? []).slice(0, 3).map((c) => ({ candidate_id: c.candidate_id ?? c.id, statement: String(c.statement ?? c.target_statement ?? '').slice(0, 120) })),
-            distill_queue: d.distill_total ?? 0,
+            distill_queue: d.distill_total ?? 0, // rows still needing a rewrite; rule-verdicted rows are not counted
             friction: d.friction_total ?? 0,
         };
     }
@@ -1855,6 +1864,7 @@ function handleDream(args) {
     // utterances (no LLM there); the agent rewrites them here into clean what/why via
     // remember(memory_id, content). Matches needs_distill (new) AND the legacy hardcoded
     // why-strings so the existing backlog is drainable without a backfill write.
+    const distillLimit = Math.max(1, Math.min(25, Number(args?.distill ?? 8) || 8));
     let distillQueue = [];
     try {
         const rows = db.prepare(`
@@ -1865,10 +1875,15 @@ function handleDream(args) {
          -- settle window: the Stop hook extracts every turn, so the newest rows belong to a
          -- session still in motion. Don't ask the agent to distill the conversation it is in.
          AND m.created_at < unixepoch() - 1800
+         AND json_extract(m.content, '$.distill_verdict') IS NULL
          AND (json_extract(m.content, '$.needs_distill') = 1
               OR json_extract(m.content, '$.why') = 'Decision detected by pattern match — may need agent enrichment'
               OR json_extract(m.content, '$.why') = 'User-stated warning/prohibition — auto-extracted by caveat pattern match')
-       ORDER BY m.created_at DESC LIMIT 8
+       ORDER BY (m.layer = 'caveat') DESC,
+                (e.name <> 'Local') DESC,
+                length(json_extract(m.content, '$.what')) DESC,
+                m.created_at DESC
+       LIMIT ${distillLimit}
     `).all();
         distillQueue = rows.map((r) => {
             let c = {};
@@ -1898,7 +1913,9 @@ function handleDream(args) {
             friction,
             friction_total: friction.length,
             distill_queue: distillQueue,
-            distill_total: distillQueue.length,
+            distill_total: distillPending(db),
+            distill_shown: distillQueue.length,
+            distill_hint: 'Ordered by value (caveats first, named entities, longer text). Pass distill: N (max 25) for a longer drain. Rules already set a distill_verdict on acknowledgements, bare paths and 90-day-old never-recalled items — you only see what needs judgement.',
             message: friction.length > 0
                 ? 'No North Star declared yet — but the re-injection layer surfaced friction below: anchors being violated despite being re-surfaced. Declare a North Star (declare_anchor node_type:"north_star"), and act on the friction items.'
                 : 'No North Star declared yet. Declare one with declare_anchor(node_type: "north_star") before dreaming.',

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "linksee-memory",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "mcpName": "io.github.michielinksee/linksee-memory",
-  "description": "Local-first agent memory MCP — cross-agent brain with drift detection, 6-layer structured memory + token-saving file diff cache",
+  "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",
   "bin": {
     "linksee-memory": "dist/mcp/server.js",
@@ -39,14 +39,24 @@
     "mcp",
     "model-context-protocol",
     "memory",
-    "agent",
     "agent-memory",
+    "persistent-memory",
+    "long-term-memory",
+    "session-memory",
+    "handover",
+    "hand-off",
+    "decision-log",
+    "drift-detection",
+    "guardrails",
     "claude",
     "claude-code",
     "cursor",
+    "windsurf",
+    "codex",
+    "gemini-cli",
     "chatgpt",
-    "sqlite",
     "local-first",
+    "sqlite",
     "token-savings",
     "cross-agent"
   ],