linksee-memory 0.11.4 → 0.12.0

package/README.md

@@ -618,7 +618,7 @@ Use both.
 linksee-memory runs locally and is built to read — and send — as little as possible.
 
 - **Local-first.** Memory is one SQLite file at `~/.linksee-memory/memory.db`. No account, no cloud, no API key.
-- **Telemetry is opt-in and OFF by default.** Nothing is sent unless you set `LINKSEE_TELEMETRY=basic`. Even then it never sends your source code, file contents, prompts, conversation, entity/project names, or the memory DB — only anonymous counters ([details](#telemetry-opt-in-off-by-default)).
+- **Telemetry is opt-in and OFF by default.** `setup` asks once; nothing is sent unless you agree there (or set `LINKSEE_TELEMETRY=basic`). Even then it never sends your source code, file contents, prompts, conversation, entity/project names, or the memory DB — only anonymous counters ([details](#telemetry-opt-in-off-by-default)).
 - **No automatic repo crawling.** linksee reads: memory you explicitly save, your `map.yaml`, the specific files a map reality-check points at, the local SQLite DB, and — when the Stop hook fires — your Claude Code session transcript (locally, to capture what happened). It does **not** crawl your repo, read `.env`/secrets/`node_modules`, or touch your home directory on its own.
 - **Clean MCP transport.** The server writes only JSON-RPC to stdout; all logs go to stderr.
 - **Hooks are documented and removable.** `setup` adds a Stop hook (session capture) and an optional guard hook. They make no network calls by default, are time-bounded, fail-open (a hook error never breaks your session), and are listed under [Uninstall](#uninstall).
@@ -636,6 +636,8 @@ linksee-memory ships with **opt-in** anonymous telemetry that helps us understan
 ```bash
 export LINKSEE_TELEMETRY=basic     # opt in
 export LINKSEE_TELEMETRY=off       # opt out (or just unset the variable)
+# `linksee-memory setup` also asks once and records your choice in
+# ~/.linksee-memory/telemetry-consent (delete that file to be asked again).
 ```
 
 ### Exactly what gets sent (Level 1 contract)

package/dist/bin/setup.js

@@ -70,6 +70,9 @@ const GUARD_COMMAND = 'npx -y linksee-memory guard';
 const PROJECT_DIR = process.cwd();
 const PROJECT_CLAUDE_DIR = join(PROJECT_DIR, '.claude');
 const PROJECT_SETTINGS_PATH = join(PROJECT_CLAUDE_DIR, 'settings.json');
+// Opt-in telemetry consent recorded at setup time (read by telemetry.ts getTelemetryMode).
+const TELEMETRY_DIR = process.env.LINKSEE_MEMORY_DIR ?? join(HOME, '.linksee-memory');
+const TELEMETRY_CONSENT_FILE = join(TELEMETRY_DIR, 'telemetry-consent');
 const CHECK = '\x1b[32m✓\x1b[0m';
 const SKIP = '\x1b[33m○\x1b[0m';
 const FAIL = '\x1b[31m✗\x1b[0m';
@@ -225,13 +228,15 @@ const GUARD_HOOKS = {
 function guardWiredFor(s, ev) {
     return (s.hooks?.[ev] ?? []).some((entry) => entry?.hooks?.some((h) => typeof h?.command === 'string' && h.command.includes('linksee-memory-guard')));
 }
-function askYesNo(question) {
+function askYesNo(question, defaultYes = true) {
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.question(`${question} [Y/n] `, (ans) => {
+        rl.question(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `, (ans) => {
             rl.close();
             const a = ans.trim().toLowerCase();
-            resolve(a === '' || a === 'y' || a === 'yes'); // default = yes
+            if (a === '')
+                return resolve(defaultYes);
+            resolve(a === 'y' || a === 'yes');
         });
     });
 }
@@ -288,13 +293,58 @@ async function configureGuard() {
 }
 const guardConfigured = await configureGuard();
 console.log('');
+// ── Telemetry consent (opt-in, anonymous, off unless you agree) ──────────
+async function configureTelemetryConsent() {
+    console.log(`${BOLD}Anonymous usage stats${RESET} ${DIM}(optional)${RESET}`);
+    const env = (process.env.LINKSEE_TELEMETRY || '').toLowerCase().trim();
+    if (env) {
+        console.log(`  ${SKIP} Controlled by LINKSEE_TELEMETRY=${env} ${DIM}(env overrides)${RESET}`);
+        return;
+    }
+    if (existsSync(TELEMETRY_CONSENT_FILE)) {
+        let cur = 'off';
+        try {
+            cur = (readFileSync(TELEMETRY_CONSENT_FILE, 'utf8').trim().toLowerCase()) || 'off';
+        }
+        catch { /* ignore */ }
+        console.log(`  ${SKIP} Already chosen: ${cur === 'basic' ? 'on' : 'off'} ${DIM}(edit ${TELEMETRY_CONSENT_FILE} to change)${RESET}`);
+        return;
+    }
+    if (dryRun) {
+        console.log(`  ${DIM}[dry-run] Would ask whether to share anonymous usage stats${RESET}`);
+        return;
+    }
+    const dnt = process.env.DO_NOT_TRACK === '1' || process.env.DO_NOT_TRACK === 'true';
+    if (dnt || autoYes || !process.stdin.isTTY) {
+        try {
+            mkdirSync(TELEMETRY_DIR, { recursive: true });
+            writeFileSync(TELEMETRY_CONSENT_FILE, 'off');
+        }
+        catch { /* best-effort */ }
+        const why = dnt ? 'DO_NOT_TRACK' : autoYes ? '--yes → off' : 'non-interactive';
+        console.log(`  ${SKIP} Left off ${DIM}(${why})${RESET}`);
+        return;
+    }
+    console.log(`  ${DIM}Helps us see which workflows actually work. Anonymous counts only —`);
+    console.log(`  never your memory, code, prompts, file contents, entity names, or paths.`);
+    console.log(`  Off unless you say yes; change anytime with LINKSEE_TELEMETRY=off.${RESET}`);
+    const ok = await askYesNo('  Share anonymous usage stats?', false);
+    try {
+        mkdirSync(TELEMETRY_DIR, { recursive: true });
+        writeFileSync(TELEMETRY_CONSENT_FILE, ok ? 'basic' : 'off');
+    }
+    catch { /* best-effort */ }
+    console.log(`  ${ok ? CHECK : SKIP} Telemetry ${ok ? 'enabled — thank you!' : 'left off'}`);
+}
+await configureTelemetryConsent();
+console.log('');
 // ── Summary ──────────────────────────────────────────────
 console.log(`${BOLD}Setup complete!${RESET}`);
 console.log('');
 console.log('How it works:');
 console.log(`  ${DIM}• Every session is auto-captured (decisions, caveats, learnings)${RESET}`);
 console.log(`  ${DIM}• Agent auto-recalls past context when starting a task${RESET}`);
-console.log(`  ${DIM}• Memory is local-first (nothing leaves your machine)${RESET}`);
+console.log(`  ${DIM}• Memory is local-first (your memory never leaves your machine)${RESET}`);
 console.log(`  ${DIM}• Works across Claude Code, Cursor, Windsurf, Codex, Gemini (cross-agent)${RESET}`);
 if (guardConfigured) {
     console.log(`  ${DIM}• Re-injection guard re-surfaces this project's accepted decisions before edits${RESET}`);

package/dist/lib/guard.js

@@ -12,11 +12,12 @@
 // FAIL-OPEN by construction: every DB op is best-effort; only an explicit 'hard' contradiction yields
 // a block. Lexical only (no embeddings): reuses lexical-match.ts (the same logic as the detector).
 import { normPath, compileGlob, parseArray, matchViolation, SCRAPE_ANCHOR } from './lexical-match.js';
+import { supersededAnchorIds } from './truth-engine.js';
 // "accepted = the only thing the gate compares against": declared (status active), still live
 // (lifecycle active|experiment — NOT at_risk/superseded/deprecated), and not explicitly card-disabled.
 // at_risk(stale) anchors deliberately DON'T gate — we don't enforce a rule we're no longer sure of.
-const ACCEPTED_SQL = `status = 'active'
-  AND lifecycle IN ('active', 'experiment')
+const ACCEPTED_SQL = `status = 'active'
+  AND lifecycle IN ('active', 'experiment')
   AND COALESCE(json_extract(card_policy, '$.enabled'), 1) != 0`;
 const nowSec = () => Math.floor(Date.now() / 1000);
 function jsonGet(json, key, def) {
@@ -37,10 +38,16 @@ function bestEffort(fn) {
     }
 }
 export function acceptedAnchors(db) {
-    return db
-        .prepare(`SELECT id, kind, statement, rationale, affects, detect_terms, violation_signal, card_policy
+    const rows = db
+        .prepare(`SELECT id, kind, statement, rationale, affects, detect_terms, violation_signal, card_policy
          FROM drift_anchors WHERE ${ACCEPTED_SQL}`)
         .all();
+    // A superseded anchor must stop gating. The block/warn text tells the user to run
+    // resolve_drift(action:'supersede') — if the gate ignored that resolution, following the
+    // instruction would not lift the block (dead end). status/lifecycle are not touched by
+    // supersede, so the resolution record is the only place that knows.
+    const retired = supersededAnchorIds(db);
+    return retired.size === 0 ? rows : rows.filter((a) => !retired.has(a.id));
 }
 function buildActionCtx(input) {
     const files = [];
@@ -123,7 +130,7 @@ function withinCooldown(db, anchorId, sessionId) {
     return !!row;
 }
 function logInjection(db, matches, act, surface, sessionId) {
-    const ins = db.prepare(`INSERT INTO injection_log (anchor_id, session_id, trigger, surface, tool_name, action_snip, verdict)
+    const ins = db.prepare(`INSERT INTO injection_log (anchor_id, session_id, trigger, surface, tool_name, action_snip, verdict)
      VALUES (?, ?, 'gate', ?, ?, ?, ?)`);
     const snip = (act.lines[0] ?? '').slice(0, 120);
     const tx = db.transaction(() => {
@@ -175,16 +182,19 @@ export function formatReinject(matches, gate) {
 export function buildBootDigest(db, opts = {}) {
     const maxAnchors = opts.maxAnchors ?? 8;
     const maxForks = opts.maxForks ?? 5;
-    const anchors = db
-        .prepare(`SELECT id, statement, rationale FROM drift_anchors
-         WHERE ${ACCEPTED_SQL} AND kind IN ('prohibition', 'decision', 'constraint')
+    // Same rule as the gate: never re-surface a decision the user has already superseded.
+    const retiredIds = supersededAnchorIds(db);
+    const anchorRows = db
+        .prepare(`SELECT id, statement, rationale FROM drift_anchors
+         WHERE ${ACCEPTED_SQL} AND kind IN ('prohibition', 'decision', 'constraint')
          ORDER BY confidence DESC, updated_at DESC LIMIT ?`)
-        .all(maxAnchors);
+        .all(maxAnchors + retiredIds.size);
+    const anchors = anchorRows.filter((a) => !retiredIds.has(a.id)).slice(0, maxAnchors);
     const forks = db
-        .prepare(`SELECT c.id, c.rationale, a.statement
-         FROM memory_write_candidates c
-         LEFT JOIN drift_anchors a ON a.id = c.target_node_id
-         WHERE c.scope = 'orphaned_proposal' AND c.status = 'pending_review'
+        .prepare(`SELECT c.id, c.rationale, a.statement
+         FROM memory_write_candidates c
+         LEFT JOIN drift_anchors a ON a.id = c.target_node_id
+         WHERE c.scope = 'orphaned_proposal' AND c.status = 'pending_review'
          ORDER BY c.created_at DESC LIMIT ?`)
         .all(maxForks);
     // Distillation pressure — the routine's structural trigger. The drain must not depend on
@@ -192,10 +202,10 @@ export function buildBootDigest(db, opts = {}) {
     // EVERY session boot says so. Inflow (new sessions) vs drain (8/dream) stays visible.
     let distill = 0;
     try {
-        distill = db.prepare(`SELECT COUNT(*) AS n FROM memories
-          WHERE layer IN ('learning', 'caveat') AND json_valid(content)
-            AND (json_extract(content, '$.needs_distill') = 1
-                 OR json_extract(content, '$.why') = 'Decision detected by pattern match — may need agent enrichment'
+        distill = db.prepare(`SELECT COUNT(*) AS n FROM memories
+          WHERE layer IN ('learning', 'caveat') AND json_valid(content)
+            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;
     }
     catch {
@@ -228,11 +238,11 @@ export function buildBootDigest(db, opts = {}) {
 export function backfillHeeded(db) {
     bestEffort(() => {
         const live = `SELECT anchor_id FROM drift_edges WHERE verdict = 'contradicts' AND status = 'open'`;
-        db.prepare(`UPDATE injection_log SET heeded = 0
-         WHERE heeded IS NULL AND surface IN ('warn', 'inform') AND verdict = 'contradicts'
+        db.prepare(`UPDATE injection_log SET heeded = 0
+         WHERE heeded IS NULL AND surface IN ('warn', 'inform') AND verdict = 'contradicts'
            AND anchor_id IN (${live})`).run();
-        db.prepare(`UPDATE injection_log SET heeded = 1
-         WHERE heeded IS NULL AND surface IN ('warn', 'inform')
+        db.prepare(`UPDATE injection_log SET heeded = 1
+         WHERE heeded IS NULL AND surface IN ('warn', 'inform')
            AND anchor_id NOT IN (${live})`).run();
         db.prepare(`UPDATE injection_log SET heeded = 1 WHERE heeded IS NULL AND surface = 'block'`).run();
     });
@@ -244,16 +254,16 @@ export function getReinjectionFriction(db, opts = {}) {
     const minC = opts.minContradicts ?? 3;
     backfillHeeded(db);
     const rows = db
-        .prepare(`SELECT i.anchor_id,
-              SUM(CASE WHEN i.verdict = 'contradicts' THEN 1 ELSE 0 END) AS gate_contradicts,
-              SUM(CASE WHEN i.surface = 'block' THEN 1 ELSE 0 END)       AS gate_blocks,
-              SUM(CASE WHEN i.heeded = 0 THEN 1 ELSE 0 END)              AS ignored,
-              datetime(MAX(i.occurred_at), 'unixepoch')                 AS last_at,
-              a.statement, a.lifecycle, a.card_policy
-         FROM injection_log i
-         JOIN drift_anchors a ON a.id = i.anchor_id
-        WHERE a.status = 'active'
-        GROUP BY i.anchor_id
+        .prepare(`SELECT i.anchor_id,
+              SUM(CASE WHEN i.verdict = 'contradicts' THEN 1 ELSE 0 END) AS gate_contradicts,
+              SUM(CASE WHEN i.surface = 'block' THEN 1 ELSE 0 END)       AS gate_blocks,
+              SUM(CASE WHEN i.heeded = 0 THEN 1 ELSE 0 END)              AS ignored,
+              datetime(MAX(i.occurred_at), 'unixepoch')                 AS last_at,
+              a.statement, a.lifecycle, a.card_policy
+         FROM injection_log i
+         JOIN drift_anchors a ON a.id = i.anchor_id
+        WHERE a.status = 'active'
+        GROUP BY i.anchor_id
        HAVING gate_contradicts >= ?`)
         .all(minC);
     const realityStmt = db.prepare(`SELECT COUNT(*) AS n FROM drift_edges WHERE anchor_id = ? AND verdict = 'contradicts' AND status = 'open'`);

package/dist/lib/telemetry.js

@@ -29,6 +29,19 @@ export function getTelemetryMode() {
     const v = (process.env.LINKSEE_TELEMETRY || '').toLowerCase().trim();
     if (v === 'basic' || v === 'on' || v === '1' || v === 'true')
         return 'basic';
+    if (v)
+        return 'off'; // any explicit env value (off/0/false/no/…) always wins
+    // No env override → use the consent recorded at setup time. Stays off if absent,
+    // so "off by default" holds: nothing is sent unless the user agreed at setup.
+    try {
+        const consentFile = join(TELEMETRY_DIR, 'telemetry-consent');
+        if (existsSync(consentFile)) {
+            const c = readFileSync(consentFile, 'utf8').trim().toLowerCase();
+            if (c === 'basic' || c === 'on')
+                return 'basic';
+        }
+    }
+    catch { /* ignore */ }
     return 'off';
 }
 export function getOrCreateAnonId() {

package/dist/lib/truth-engine.d.ts

@@ -65,6 +65,22 @@ export interface DecisionDetail extends TruthNode {
         detected_at: number;
     }>;
 }
+/**
+ * Anchors that have been explicitly superseded ("intent evolved, this is the new direction").
+ *
+ * Resolutions live in meta.t3_resolutions keyed `A<anchor_id>`, one record per anchor
+ * (a later resolve_drift overwrites the earlier one), so the current resolution for
+ * anchor N is simply t3_resolutions["A"+N].
+ *
+ * NOTE the asymmetry: a supersede record names BOTH sides (superseded_node = the old
+ * anchor, superseded_by = the new one). Only the OLD one is retired — the new anchor must
+ * keep enforcing, so we match on `superseded_node` and never on `superseded_by`.
+ *
+ * Used by the gate (guard.ts) so that the enforcement layer honours the same
+ * make-or-break rule as the reporting layer: a divergence accounted for by a recorded
+ * resolution is NOT drift.
+ */
+export declare function supersededAnchorIds(db: Database.Database): Set<number>;
 export declare function getTruthView(db: Database.Database, opts?: {
     domain?: string;
     decision_mode?: string;

package/dist/lib/truth-engine.js

@@ -59,6 +59,22 @@ function classifySpecies(decision_mode) {
         default: return 'hypothesis';
     }
 }
+// ── Edge summary (one line the agent can act on) ─────────────────────────────
+function summarizeEdges(verdict, edges) {
+    const latest = edges[0];
+    let ev = {};
+    try {
+        ev = JSON.parse(latest.evidence || '{}');
+    }
+    catch { /* ignore */ }
+    const file = ev.file_path ? String(ev.file_path).replace(/\\/g, '/').split('/').slice(-2).join('/') : null;
+    const hit = ev.hit_term ? ` hit "${ev.hit_term}"` : '';
+    const when = new Date(latest.detected_at * 1000).toISOString().slice(0, 10);
+    const head = verdict === 'contradicts'
+        ? `${edges.length} open contradiction${edges.length > 1 ? 's' : ''}`
+        : `declared but not found in reality (${edges.length} absent signal${edges.length > 1 ? 's' : ''})`;
+    return `${head}${file ? ` — ${file}` : ''}${hit} (${when}). resolve_drift: fix if reality is wrong, dismiss if false positive.`;
+}
 function buildResolutionLookup(db) {
     const t3res = safeJsonParse(db.prepare("SELECT value FROM meta WHERE key='t3_resolutions'").get()?.value, {});
     const t2res = safeJsonParse(db.prepare("SELECT value FROM meta WHERE key='t2_resolutions'").get()?.value, {});
@@ -67,6 +83,11 @@ function buildResolutionLookup(db) {
     return function resolutionFor(id) {
         const matches = [];
         for (const r of Object.values(t3res)) {
+            // A supersede record names both sides. Only the OLD anchor is accounted for by it;
+            // the replacement must stay checkable (otherwise a new North Star could never drift,
+            // because the supersede branch wins over the contradicts branch).
+            if (r && r.action === 'supersede' && r.superseded_by === id && r.superseded_node !== id)
+                continue;
             if (r && (r.superseded_node === id || r.superseded_by === id ||
                 r.node === id || r.direction_node === id || r.constraint_node === id)) {
                 matches.push(r);
@@ -91,12 +112,39 @@ function buildResolutionLookup(db) {
     };
 }
 // ── Core: getTruthView ───────────────────────────────────────────────────────
+/**
+ * Anchors that have been explicitly superseded ("intent evolved, this is the new direction").
+ *
+ * Resolutions live in meta.t3_resolutions keyed `A<anchor_id>`, one record per anchor
+ * (a later resolve_drift overwrites the earlier one), so the current resolution for
+ * anchor N is simply t3_resolutions["A"+N].
+ *
+ * NOTE the asymmetry: a supersede record names BOTH sides (superseded_node = the old
+ * anchor, superseded_by = the new one). Only the OLD one is retired — the new anchor must
+ * keep enforcing, so we match on `superseded_node` and never on `superseded_by`.
+ *
+ * Used by the gate (guard.ts) so that the enforcement layer honours the same
+ * make-or-break rule as the reporting layer: a divergence accounted for by a recorded
+ * resolution is NOT drift.
+ */
+export function supersededAnchorIds(db) {
+    const out = new Set();
+    for (const key of ['t3_resolutions', 't2_resolutions']) {
+        const res = safeJsonParse(db.prepare('SELECT value FROM meta WHERE key = ?').get(key)?.value, {});
+        for (const r of Object.values(res)) {
+            if (r && r.action === 'supersede' && typeof r.superseded_node === 'number') {
+                out.add(r.superseded_node);
+            }
+        }
+    }
+    return out;
+}
 export function getTruthView(db, opts = {}) {
     const now = Date.now();
     const resolutionFor = buildResolutionLookup(db);
     // ── Candidates (indexed by target node) ──
     const candRows = db
-        .prepare(`SELECT id, candidate_type, target_node_id, rationale, confidence, status, proposed_node
+        .prepare(`SELECT id, candidate_type, target_node_id, rationale, confidence, status, proposed_node
        FROM memory_write_candidates ORDER BY id DESC`)
         .all();
     const pendingByNode = new Map();
@@ -112,9 +160,24 @@ export function getTruthView(db, opts = {}) {
             cardByNode.set(c.target_node_id, c);
         }
     }
+    // ── Open drift edges (what the detector actually observed) ──
+    // The detector writes drift_edges; a truth view that never reads them will report 🔵 for
+    // anchors it has hard evidence against. (2026-09-05: 11 open `contradicts` edges across 4
+    // anchors — one of them the PII constraint — all rendered "reality matches intent".)
+    const edgeRows = db
+        .prepare(`SELECT anchor_id, verdict, confidence, evidence, detected_at
+         FROM drift_edges WHERE status = 'open'
+        ORDER BY detected_at DESC`)
+        .all();
+    const openEdges = new Map();
+    for (const e of edgeRows) {
+        if (!openEdges.has(e.anchor_id))
+            openEdges.set(e.anchor_id, []);
+        openEdges.get(e.anchor_id).push(e);
+    }
     // ── Active nodes + state derivation ──
-    let sql = `SELECT id, node_type, domain, decision_mode, statement, rationale, confidence, lifecycle,
-            card_policy, review_after
+    let sql = `SELECT id, node_type, domain, decision_mode, statement, rationale, confidence, lifecycle,
+            card_policy, review_after
      FROM drift_anchors WHERE status = 'active'`;
     const params = [];
     if (opts.domain) {
@@ -137,6 +200,9 @@ export function getTruthView(db, opts = {}) {
         const pending = pendingByNode.get(r.id);
         const card = cardByNode.get(r.id);
         const overdue = r.review_after != null && r.review_after * 1000 < now;
+        const edges = openEdges.get(r.id) ?? [];
+        const contradicts = edges.filter((e) => e.verdict === 'contradicts');
+        const absent = edges.filter((e) => e.verdict === 'absent');
         // ── State derivation (the make-or-break logic) ──
         let state;
         let accounted;
@@ -159,8 +225,22 @@ export function getTruthView(db, opts = {}) {
             accounted = true;
             accountedBy = 'supersede (intentional evolution)';
         }
-        else if (pending) {
-            // 🟡 Soft signal awaiting human decision
+        else if (res?.action === 'dismiss') {
+            // 🔵 a human looked at the signal and called it a false positive — that IS an answer.
+            state = 'aligned';
+            accounted = true;
+            accountedBy = 'dismiss (false positive)';
+        }
+        else if (contradicts.length > 0) {
+            // 🔴 the detector has hard evidence against this anchor and nobody has answered it.
+            // resolve_drift(fix|dismiss) closes the edges; supersede/acknowledge are handled above.
+            state = 'drift';
+            accounted = false;
+            accountedBy = null;
+        }
+        else if (pending || absent.length > 0) {
+            // 🟡 Soft signal awaiting human decision (a pending candidate, or "declared but not
+            // found in reality" — absent is weaker than contradicts, so it asks rather than alarms)
             state = 'review';
             accounted = false;
             accountedBy = null;
@@ -177,9 +257,15 @@ export function getTruthView(db, opts = {}) {
             accounted = true;
             accountedBy = null;
         }
+        // Say what was observed. Never claim convergence when nothing was checked — an agent
+        // reading "reality matches intent" will trust it; "no signal observed" it will verify.
         const reality = card?.rationale
             ?? pending?.rationale
-            ?? (state === 'aligned' ? 'Committed reality matches intent (convergent)' : null);
+            ?? (contradicts.length > 0 ? summarizeEdges('contradicts', contradicts) : null)
+            ?? (absent.length > 0 ? summarizeEdges('absent', absent) : null)
+            ?? (state === 'aligned'
+                ? (accountedBy ? 'Accounted for by recorded resolution' : 'No signal observed (not verified against reality)')
+                : null);
         return {
             id: r.id,
             node_type: r.node_type,
@@ -264,8 +350,8 @@ export function getTruthView(db, opts = {}) {
 // ── check_decision: single-node deep view ────────────────────────────────────
 export function getDecisionDetail(db, anchorId) {
     const row = db
-        .prepare(`SELECT id, kind, node_type, domain, decision_mode, statement, rationale, confidence,
-              lifecycle, card_policy, review_after, affects, detect_terms, violation_signal, tier
+        .prepare(`SELECT id, kind, node_type, domain, decision_mode, statement, rationale, confidence,
+              lifecycle, card_policy, review_after, affects, detect_terms, violation_signal, tier
        FROM drift_anchors WHERE id = ? AND status = 'active'`)
         .get(anchorId);
     if (!row)
@@ -283,14 +369,14 @@ export function getDecisionDetail(db, anchorId) {
     // State derivation (same logic)
     let state, accounted, accountedBy;
     const pendingCand = db
-        .prepare(`SELECT id, candidate_type, target_node_id, rationale, confidence, status
-       FROM memory_write_candidates
-       WHERE target_node_id = ? AND status = 'pending_review'
+        .prepare(`SELECT id, candidate_type, target_node_id, rationale, confidence, status
+       FROM memory_write_candidates
+       WHERE target_node_id = ? AND status = 'pending_review'
        ORDER BY id DESC`)
         .all(anchorId);
     const cardCand = db
-        .prepare(`SELECT rationale FROM memory_write_candidates
-       WHERE target_node_id = ? AND proposed_node LIKE '%"src":"t%'
+        .prepare(`SELECT rationale FROM memory_write_candidates
+       WHERE target_node_id = ? AND proposed_node LIKE '%"src":"t%'
        ORDER BY id DESC LIMIT 1`)
         .get(anchorId);
     const hasPending = pendingCand.length > 0;
@@ -328,7 +414,7 @@ export function getDecisionDetail(db, anchorId) {
         ?? (state === 'aligned' ? 'Committed reality matches intent (convergent)' : null);
     // Drift edges for this anchor
     const edges = db
-        .prepare(`SELECT id AS edge_id, verdict, confidence, status, detected_at
+        .prepare(`SELECT id AS edge_id, verdict, confidence, status, detected_at
        FROM drift_edges WHERE anchor_id = ? ORDER BY detected_at DESC`)
         .all(anchorId);
     return {

package/dist/mcp/server.js

@@ -174,6 +174,7 @@ const TOOLS = [
                 path: { type: 'string', description: 'File path or substring. When set, returns file edit history with per-edit user-intent context instead of memory search.' },
                 max_intents: { type: 'number', description: 'For file mode: max user-intent snippets. Default 10.', default: 10 },
                 scope_to_roots: { type: 'boolean', default: false, description: 'For file mode: filter to client-provided roots.' },
+                explain: { type: 'boolean', default: false, description: 'Include ranking internals (composite, heat, band, momentum, match_reasons, score_breakdown). Off by default so more memories fit the token budget.' },
                 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 },
             },
@@ -200,6 +201,7 @@ const TOOLS = [
             properties: {
                 domain: { type: 'string', description: 'Filter by domain (strategy, product, engineering, growth, etc.)' },
                 decision_mode: { type: 'string', description: 'Filter by decision_mode (hypothesis, constraint, commitment, source_of_truth)' },
+                verbose: { type: 'boolean', default: false, description: 'Return full aligned nodes and all candidates. Default is compact: attention items in full, aligned as id+statement per domain, candidates as counts.' },
             },
         },
     },
@@ -767,12 +769,18 @@ function handleRecall(args) {
             content: parsedContent,
             importance: r.importance,
             pinned: r.importance >= 0.9,
-            heat: Number(r.heat_score.toFixed(1)),
-            band: r.heat_band,
-            composite: Number(r.composite_score.toFixed(3)),
-            match_reasons: r._reasons,
-            score_breakdown: r._breakdown,
+            // Ranking internals only on request — they roughly double the per-memory cost and an
+            // agent acting on the memory needs what/why/state, not the scorer's arithmetic.
+            ...(args?.explain ? {
+                heat: Number(r.heat_score.toFixed(1)),
+                band: r.heat_band,
+                composite: Number(r.composite_score.toFixed(3)),
+                match_reasons: r._reasons,
+                score_breakdown: r._breakdown,
+            } : {}),
         };
+        if (!args?.explain)
+            delete memObj.entity.momentum;
         const memTokens = estimateTokens(JSON.stringify(memObj));
         if (memoriesOut.length > 0 && accTokens + memTokens > maxTokens) {
             stoppedBy = 'tokens';
@@ -1287,14 +1295,35 @@ function handleDriftStatus(args) {
         by_state.held > 0 ? `⚪ ${by_state.held} held` : null,
         `🔵 ${by_state.aligned} aligned`,
     ].filter(Boolean).join(' · ');
+    if (args?.verbose) {
+        return JSON.stringify({
+            ok: true,
+            triage: `${nodes} anchors: ${triage}`,
+            nextReopen: view.nextReopen,
+            attention: view.attention,
+            alignedByDomain: view.alignedByDomain,
+            candidates: view.candidates,
+            counts: view.counts,
+        });
+    }
+    // Compact by default. The agent asked "what needs attention" — answer that in full and keep
+    // the rest to one line per node. (Full form was ~15k tokens for 43 anchors; the 2 drifting
+    // items were buried under 41 aligned ones with rationale.)
+    const aligned = view.alignedByDomain.map((g) => ({
+        domain: g.domain,
+        count: g.nodes.length,
+        nodes: g.nodes.map((n) => ({ id: n.id, statement: n.statement, reality: n.reality })),
+    }));
+    const cand = view.candidates;
     return JSON.stringify({
         ok: true,
         triage: `${nodes} anchors: ${triage}`,
         nextReopen: view.nextReopen,
         attention: view.attention,
-        alignedByDomain: view.alignedByDomain,
-        candidates: view.candidates,
+        aligned,
+        candidates: { auto: cand?.auto?.length ?? 0, suppressed: cand?.suppressed?.length ?? 0 },
         counts: view.counts,
+        hint: 'verbose:true for full aligned nodes and candidate details; check_decision(anchor_id) for one node.',
     });
 }
 // Fix ① (2026-06-17): infer the Map project from the client's workspace roots when the
@@ -1315,9 +1344,39 @@ async function resolveProjectFromRoots() {
     });
     return matches.length === 1 ? matches[0] : undefined; // unique repo match only; else ② handles it
 }
+// ①b (2026-09-05): when the client sends no roots (common — not every MCP host implements
+// roots), infer the map from the files edited most recently. The DB already knows what you
+// touched; the map slug is a path segment of those files.
+function resolveProjectFromRecentEdits() {
+    const projects = listMapProjects(db);
+    if (projects.length <= 1)
+        return { project: projects[0] };
+    const rows = db
+        .prepare(`SELECT file_path FROM session_file_edits
+        WHERE occurred_at > unixepoch() - 86400
+        ORDER BY occurred_at DESC LIMIT 50`)
+        .all();
+    if (rows.length === 0)
+        return {};
+    const hits = new Map();
+    for (const r of rows) {
+        const segs = r.file_path.toLowerCase().replace(/\\/g, '/').split('/');
+        for (const p of projects)
+            if (segs.includes(p.toLowerCase()))
+                hits.set(p, (hits.get(p) ?? 0) + 1);
+    }
+    if (hits.size === 0)
+        return {};
+    const [best, second] = [...hits.entries()].sort((a, b) => b[1] - a[1]);
+    if (second && second[1] === best[1])
+        return {}; // tie → still ambiguous
+    return { project: best[0], from: 'recent_edits' };
+}
 async function handleWhereAmI(args) {
-    // ① resolve project from cwd/roots when not explicitly passed; ② (inside whereAmI) is the fallback.
-    const project = args?.project ?? (await resolveProjectFromRoots());
+    // ① roots; ①b recent edits; ② (inside whereAmI) is the last fallback.
+    let project = args?.project ?? (await resolveProjectFromRoots());
+    if (!project)
+        project = resolveProjectFromRecentEdits().project;
     const res = whereAmI(db, {
         query: args?.query, node_id: args?.node_id, project, limit: args?.limit,
     });
@@ -1325,7 +1384,7 @@ async function handleWhereAmI(args) {
         return JSON.stringify({
             ok: true, located: false, reason: 'ambiguous_project',
             available_projects: res.ambiguous.available,
-            hint: `Multiple maps imported — pass project: one of [${res.ambiguous.available.join(', ')}]. (No-arg can't yet tell which repo you mean; cwd/roots match is coming.)`,
+            hint: `Multiple maps imported and none matched your workspace roots or the files you edited in the last 24h — pass project: one of [${res.ambiguous.available.join(', ')}].`,
         });
     }
     if (res.matched.length === 0) {
@@ -1535,6 +1594,9 @@ function handleDream(args) {
         FROM memories m JOIN entities e ON e.id = m.entity_id
        WHERE m.layer IN ('learning', 'caveat')
          AND json_valid(m.content)
+         -- 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, '$.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')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.11.4",
+  "version": "0.12.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",
   "type": "module",
@@ -32,7 +32,7 @@
     "dev": "tsx src/mcp/server.ts",
     "migrate": "node dist/db/migrate.js",
     "migrate:dev": "tsx src/db/migrate.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "node scripts/release-gate.mjs && npm run build"
   },
   "keywords": [
     "mcp",