linksee-memory 0.7.1 → 0.8.0

package/dist/mcp/server.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // linksee-memory MCP server (stdio transport).
-// Tools: remember / recall / read_smart
-// v0.7.0 — unified 3-tool surface (Context7-style simplification)
+// Tools: remember / recall / read_smart / drift_status / check_decision / declare_anchor / resolve_drift
+// v0.8.0 — drift MCP tools (P0: agents can now query & act on drift state)
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
@@ -19,7 +19,9 @@ import { PROMPTS, getPrompt } from './prompts.js';
 import { fetchRoots, isInsideRoots } from './roots.js';
 import { sampleConsolidation } from './sampling.js';
 import { confirmForget } from './elicitation.js';
-const SERVER_VERSION = '0.7.0';
+import { getTruthView, getDecisionDetail, resolveDrift } from '../lib/truth-engine.js';
+import { declareAnchor, setNodeFields } from '../lib/drift-anchors.js';
+const SERVER_VERSION = '0.8.0';
 const db = openDb();
 runMigrations(db);
 // Auto-maintenance: consolidate stale memories on startup (non-blocking)
@@ -142,6 +144,68 @@ const TOOLS = [
             required: ['path'],
         },
     },
+    // ── Drift tools (v0.8.0) ─────────────────────────────────────────────────
+    {
+        name: 'drift_status',
+        description: 'Check what\'s drifting right now — the "Intent Datadog" for your product decisions.\n\nReturns a structured truth map showing which decisions/constraints/hypotheses are:\n🔴 drift (unaccounted divergence from intent)\n🟡 review (soft signal, awaiting human decision)\n⚪ held (acknowledged, time-boxed, not forgotten)\n🔵 aligned (reality matches intent)\n\nNodes are classified into 4 species:\n• hypothesis → Decision Cards (decision journal format)\n• constraint → Rules (pass/fail checklist)\n• commitment → Heartbeats (cadence monitoring)\n• source_of_truth → Reference (stable anchors)\n\nWHEN TO CALL:\n• At session start — "what needs my attention?"\n• Before making a decision — check for existing anchors on the topic\n• After completing work — verify drift state changed\n• When the user asks about product health / what\'s broken / what\'s stale',
+        inputSchema: {
+            type: 'object',
+            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)' },
+            },
+        },
+    },
+    {
+        name: 'check_decision',
+        description: 'Deep-dive into a specific decision/anchor — its state, premises, drift edges, and pending candidates.\n\nReturns the full context for one truth-map node: what was decided, why, what reality says, whether it\'s drifting, and what actions are pending.\n\nWHEN TO CALL:\n• When the user asks about a specific decision ("what happened with X?")\n• Before resolving a drift signal — understand the full picture first\n• When reviewing premises of a decision ("is this still true?")',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                anchor_id: { type: 'number', description: 'The drift_anchor ID to inspect' },
+            },
+            required: ['anchor_id'],
+        },
+    },
+    {
+        name: 'declare_anchor',
+        description: 'Declare a new decision, constraint, or prohibition as a truth-map anchor.\n\nAnchors are NORMATIVE claims: "we decided X", "Y is forbidden", "Z must always hold."\nThe drift detector later checks these against committed reality.\n\ndeclare-don\'t-mine: anchors come ONLY from explicit human declaration, never from pattern extraction.\n\nWHEN TO CALL:\n• When the user makes a product decision ("let\'s go with approach A")\n• When a constraint is established ("never do X")\n• When a commitment is made ("we ship weekly")\n• When the user says "anchor this" / "record this decision"',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', enum: ['prohibition', 'decision', 'constraint'], description: 'Anchor type' },
+                statement: { type: 'string', description: 'The normative claim (>= 8 chars)' },
+                rationale: { type: 'string', description: 'Why this was decided' },
+                affects: { type: 'array', items: { type: 'string' }, description: 'Path globs that scope this anchor' },
+                detect_terms: { type: 'array', items: { type: 'string' }, description: 'Keywords for scoping' },
+                violation_signal: { type: 'array', items: { type: 'string' }, description: 'Terms whose presence = violation (required for prohibition/decision)' },
+                tier: { type: 'string', enum: ['human', 'explicit'], description: 'Declaration tier (default: human)' },
+                // v9 ProjectCoreNode fields
+                node_type: { type: 'string', description: 'Node type label' },
+                domain: { type: 'string', description: 'Domain (strategy, product, engineering, etc.)' },
+                decision_mode: { type: 'string', enum: ['hypothesis', 'constraint', 'commitment', 'source_of_truth'], description: 'Classification for 4-species display' },
+                confidence: { type: 'number', minimum: 0, maximum: 1, description: 'Confidence level (0.0-1.0)' },
+                lifecycle: { type: 'string', description: 'Lifecycle state (active, at_risk, retired)' },
+                review_after: { type: 'string', description: 'ISO date for next review (e.g. "2026-07-04")' },
+            },
+            required: ['kind', 'statement'],
+        },
+    },
+    {
+        name: 'resolve_drift',
+        description: 'Record a resolution for a drifting anchor — the human feedback loop.\n\n4 resolution actions:\n• fix — "we fixed the code/reality to match intent" → state becomes aligned\n• supersede — "intent evolved, this is the new direction" → state becomes aligned\n• acknowledge — "we know, parking it for now" → state becomes held (with optional review date)\n• dismiss — "false positive, not actually drifting" → edges dismissed\n\nWHEN TO CALL:\n• After drift_status shows 🔴 drift or 🟡 review items\n• When the user says "that\'s fixed" / "ignore that" / "we changed direction"\n• When acknowledging a known gap with a review date',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                anchor_id: { type: 'number', description: 'The drift_anchor ID to resolve' },
+                action: { type: 'string', enum: ['fix', 'supersede', 'acknowledge', 'dismiss'], description: 'Resolution action' },
+                rationale: { type: 'string', description: 'Why this resolution (recorded for audit trail)' },
+                review_after: { type: 'string', description: 'For acknowledge: ISO date to re-check (e.g. "2026-07-04")' },
+                superseded_by: { type: 'number', description: 'For supersede: the new anchor ID that replaces this one' },
+            },
+            required: ['anchor_id', 'action'],
+        },
+    },
 ];
 // ============================================================
 // Handlers
@@ -345,12 +409,35 @@ function refreshStaleMomentum(entityIds) {
         catch { /* non-fatal */ }
     }
 }
+// --- recall helpers ---------------------------------------------------------
+// Rough token estimate for budgeting. ~3 chars/token is deliberately conservative
+// for mixed JP/EN (Japanese is token-dense), so we under-fill rather than blow
+// the caller's max_tokens budget.
+function estimateTokens(s) {
+    return Math.ceil(s.length / 3);
+}
+// Signature for near-duplicate collapsing in recall results. Extracts the
+// meaningful core text (what/title/decision/intent/learned) from the memory's
+// content (JSON or plain), normalizes whitespace/case, and keys it by entity so
+// the same message stored under two layers collapses to a single result.
+function contentSignature(raw, entityId) {
+    let text = raw;
+    try {
+        const o = JSON.parse(raw);
+        text = o?.what ?? o?.title ?? o?.decision ?? o?.intent ?? o?.learned ?? (typeof o === 'string' ? o : raw);
+    }
+    catch { /* plain-text content */ }
+    const norm = String(text).toLowerCase().replace(/\s+/g, ' ').trim().slice(0, 120);
+    if (norm.length < 16)
+        return ''; // too short to dedup safely
+    return `${entityId}::${norm}`;
+}
 function handleRecall(args) {
+    // max_tokens is enforced for real at assembly time (greedy fill by measured
+    // serialized size), not via a crude fixed per-memory estimate. hardLimit caps COUNT.
     const maxTokens = Math.max(100, Number(args.max_tokens ?? 2000));
-    const approxTokensPerMemory = 100;
-    const tokenBudgetLimit = Math.max(1, Math.floor(maxTokens / approxTokensPerMemory));
-    const hardLimit = Number.isFinite(args.limit) ? Math.max(1, Math.min(200, args.limit)) : tokenBudgetLimit;
-    const returnLimit = Math.min(tokenBudgetLimit, hardLimit);
+    const DEFAULT_COUNT_CAP = 50;
+    const hardLimit = Number.isFinite(args.limit) ? Math.max(1, Math.min(200, args.limit)) : DEFAULT_COUNT_CAP;
     const offset = Math.max(0, Number(args.offset ?? 0));
     const markAccessed = args.mark_accessed !== false;
     const layer = resolveLayer(args.layer);
@@ -361,8 +448,9 @@ function handleRecall(args) {
         mem_state: args.mem_state,
         thread_id: args.thread_id,
     };
-    // Fetch extra rows for composite re-rank, pagination, and band filtering
-    const fetchLimit = Math.max(returnLimit * 3, 30) + offset;
+    // Fetch a generous candidate pool for composite re-rank, dedup, pagination, band filter.
+    // Token-budget trimming happens at assembly, so fetch enough that many small memories can fill it.
+    const fetchLimit = Math.max(hardLimit * 3, 90) + offset;
     let rows = [];
     let searchMethod = 'like';
     const ftsQuery = toFtsQuery(args.query ?? '');
@@ -410,6 +498,26 @@ function handleRecall(args) {
     const minBm = Math.min(...bm25Values, 0);
     const maxBm = Math.max(...bm25Values, 1);
     const bmSpan = Math.max(0.001, maxBm - minBm);
+    // Composite weights adapt to query specificity:
+    //  - broad / no query → importance & heat carry more (relevance is a flat 0.5 anyway)
+    //  - focused (1-2 terms) → relevance leads
+    //  - narrow (3+ terms) → relevance dominates, so off-topic-but-pinned memories don't crowd in
+    const queryTermCount = String(args.query ?? '').trim().split(/\s+/).filter(Boolean).length;
+    let w_rel = 0.45, w_heat = 0.25, w_mom = 0.15, w_imp = 0.15;
+    if (useFts) {
+        if (queryTermCount >= 3) {
+            w_rel = 0.72;
+            w_heat = 0.12;
+            w_mom = 0.08;
+            w_imp = 0.08;
+        }
+        else {
+            w_rel = 0.60;
+            w_heat = 0.18;
+            w_mom = 0.12;
+            w_imp = 0.10;
+        }
+    }
     const scored = rows.map((r) => {
         const daysSince = (now - r.last_accessed_at) / 86400;
         const heat = computeHeat({
@@ -424,8 +532,7 @@ function handleRecall(args) {
         const heatNorm = heat.score / 100;
         const momNorm = Math.min(1, (r.momentum_score ?? 0) / 10);
         const importanceBoost = r.importance; // 0-1
-        // Composite: give a bit to importance so pinned (>=0.9) memories always rank high
-        const w_rel = 0.45, w_heat = 0.25, w_mom = 0.15, w_imp = 0.15;
+        // Composite (weights adapt to query specificity — computed above)
         const composite = w_rel * relevance + w_heat * heatNorm + w_mom * momNorm + w_imp * importanceBoost;
         // match_reasons: human-readable WHY this row is here
         const reasons = [];
@@ -468,31 +575,89 @@ function handleRecall(args) {
     });
     // Apply band filter AFTER scoring (needs heat.band)
     const filtered = band ? scored.filter((s) => s.heat_band === band) : scored;
-    // Sort by composite
+    // Sort by composite (best first)
     filtered.sort((a, b) => b.composite_score - a.composite_score);
-    // Pagination: skip offset, take returnLimit
-    const total = filtered.length;
-    const windowed = filtered.slice(offset, offset + returnLimit);
-    const hasMore = total > offset + windowed.length;
-    // Mark accessed (only for the returned window, and only if asked)
-    if (markAccessed && windowed.length > 0) {
+    // Dedup near-identical memories (same entity + near-identical core text).
+    // filtered is sorted desc, so the first occurrence kept is the highest-ranked.
+    // This collapses the common "same message saved under two layers" duplication.
+    const seenSig = new Set();
+    const deduped = filtered.filter((r) => {
+        const sig = contentSignature(r.content, r.entity_id);
+        if (!sig)
+            return true; // too short / no usable text → never dedup
+        if (seenSig.has(sig))
+            return false; // duplicate → drop
+        seenSig.add(sig);
+        return true;
+    });
+    const total = deduped.length;
+    // Greedy assembly under a REAL token budget: add memories (deduped + ranked) until
+    // including the next would blow max_tokens, capped at hardLimit by COUNT. Always
+    // returns at least one memory if anything matched.
+    const memoriesOut = [];
+    const returnedIds = [];
+    let accTokens = 0;
+    let stoppedBy = 'end';
+    for (let i = offset; i < total; i++) {
+        if (memoriesOut.length >= hardLimit) {
+            stoppedBy = 'limit';
+            break;
+        }
+        const r = deduped[i];
+        let parsedContent = r.content;
+        try {
+            parsedContent = JSON.parse(r.content);
+        }
+        catch { /* leave as string */ }
+        const memObj = {
+            id: r.id,
+            entity: {
+                id: r.entity_id,
+                name: r.entity_name,
+                kind: r.entity_kind,
+                momentum: Number((r.momentum_score ?? 0).toFixed(2)),
+            },
+            layer: r.layer,
+            axis: {
+                altitude: r._altitude ?? null,
+                type: r._mem_type ?? null,
+                state: r._mem_state ?? null,
+                thread_id: r._thread_id ?? null,
+            },
+            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,
+        };
+        const memTokens = estimateTokens(JSON.stringify(memObj));
+        if (memoriesOut.length > 0 && accTokens + memTokens > maxTokens) {
+            stoppedBy = 'tokens';
+            break;
+        }
+        accTokens += memTokens;
+        memoriesOut.push(memObj);
+        returnedIds.push(r.id);
+    }
+    const hasMore = offset + memoriesOut.length < total;
+    // Mark accessed (only the returned set, and only if asked)
+    if (markAccessed && returnedIds.length > 0) {
         const mark = db.prepare('UPDATE memories SET last_accessed_at = ?, access_count = access_count + 1 WHERE id = ?');
         const tx = db.transaction((ids) => { for (const id of ids)
             mark.run(now, id); });
-        tx(windowed.map((r) => r.id));
-    }
-    // Determine what stopped iteration — max_tokens vs limit vs offset+n=total
-    let stoppedBy = 'end';
-    if (windowed.length === returnLimit && total > offset + returnLimit) {
-        stoppedBy = hardLimit <= tokenBudgetLimit ? 'limit' : 'tokens';
+        tx(returnedIds);
     }
     return JSON.stringify({
         ok: true,
-        count: windowed.length,
+        count: memoriesOut.length,
         total_candidates: total,
         offset,
         has_more: hasMore,
         stopped_by: stoppedBy,
+        approx_tokens: accTokens,
         search: searchMethod,
         resolved_layer: layer ?? null,
         resolved_axis: {
@@ -500,38 +665,7 @@ function handleRecall(args) {
             type: axis.mem_type ?? null,
             state: axis.mem_state ?? null,
         },
-        memories: windowed.map((r) => {
-            let parsedContent = r.content;
-            try {
-                parsedContent = JSON.parse(r.content);
-            }
-            catch { /* leave as string */ }
-            return {
-                id: r.id,
-                entity: {
-                    id: r.entity_id,
-                    name: r.entity_name,
-                    kind: r.entity_kind,
-                    momentum: Number((r.momentum_score ?? 0).toFixed(2)),
-                },
-                layer: r.layer,
-                axis: {
-                    altitude: r._altitude ?? null,
-                    type: r._mem_type ?? null,
-                    state: r._mem_state ?? null,
-                    thread_id: r._thread_id ?? null,
-                },
-                content: parsedContent,
-                content_raw: r.content,
-                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,
-            };
-        }),
+        memories: memoriesOut,
     });
 }
 function handleForget(args) {
@@ -997,6 +1131,94 @@ async function handleRecallUnified(args) {
     return handleRecall(args);
 }
 // ============================================================
+// Drift tool handlers (v0.8.0)
+// ============================================================
+function handleDriftStatus(args) {
+    const view = getTruthView(db, {
+        domain: args?.domain,
+        decision_mode: args?.decision_mode,
+    });
+    // Build a concise triage line
+    const { by_state, nodes } = view.counts;
+    const triage = [
+        by_state.drift > 0 ? `🔴 ${by_state.drift} drifting` : null,
+        by_state.review > 0 ? `🟡 ${by_state.review} needs review` : null,
+        by_state.held > 0 ? `⚪ ${by_state.held} held` : null,
+        `🔵 ${by_state.aligned} aligned`,
+    ].filter(Boolean).join(' · ');
+    return JSON.stringify({
+        ok: true,
+        triage: `${nodes} anchors: ${triage}`,
+        nextReopen: view.nextReopen,
+        attention: view.attention,
+        alignedByDomain: view.alignedByDomain,
+        candidates: view.candidates,
+        counts: view.counts,
+    });
+}
+function handleCheckDecision(args) {
+    if (!args?.anchor_id)
+        throw new Error('anchor_id is required');
+    const detail = getDecisionDetail(db, args.anchor_id);
+    if (!detail) {
+        return JSON.stringify({ ok: false, error: `Anchor ${args.anchor_id} not found or not active` });
+    }
+    return JSON.stringify({ ok: true, decision: detail });
+}
+function handleDeclareAnchor(args) {
+    if (!args?.kind || !args?.statement) {
+        throw new Error('kind and statement are required');
+    }
+    // Create the base anchor
+    const anchor = declareAnchor(db, {
+        kind: args.kind,
+        statement: args.statement,
+        rationale: args.rationale,
+        affects: args.affects,
+        detect_terms: args.detect_terms,
+        violation_signal: args.violation_signal,
+        tier: args.tier ?? 'human',
+    });
+    // Apply v9 ProjectCoreNode fields if provided
+    const nodeFields = {};
+    if (args.node_type !== undefined)
+        nodeFields.node_type = args.node_type;
+    if (args.domain !== undefined)
+        nodeFields.domain = args.domain;
+    if (args.decision_mode !== undefined)
+        nodeFields.decision_mode = args.decision_mode;
+    if (args.confidence !== undefined)
+        nodeFields.confidence = args.confidence;
+    if (args.lifecycle !== undefined)
+        nodeFields.lifecycle = args.lifecycle;
+    if (args.review_after !== undefined) {
+        nodeFields.review_after = Math.floor(new Date(args.review_after).getTime() / 1000);
+    }
+    if (Object.keys(nodeFields).length > 0) {
+        setNodeFields(db, anchor.id, nodeFields);
+    }
+    return JSON.stringify({
+        ok: true,
+        anchor_id: anchor.id,
+        statement: anchor.statement,
+        kind: anchor.kind,
+        message: `Anchor #${anchor.id} declared: "${anchor.statement.substring(0, 80)}"`,
+    });
+}
+function handleResolveDrift(args) {
+    if (!args?.anchor_id || !args?.action) {
+        throw new Error('anchor_id and action are required');
+    }
+    const result = resolveDrift(db, {
+        anchor_id: args.anchor_id,
+        action: args.action,
+        rationale: args.rationale,
+        review_after: args.review_after,
+        superseded_by: args.superseded_by,
+    });
+    return JSON.stringify(result);
+}
+// ============================================================
 // MCP wiring
 // ============================================================
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
@@ -1014,6 +1236,19 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             case 'read_smart':
                 text = handleReadSmart(args);
                 break;
+            // Drift tools (v0.8.0)
+            case 'drift_status':
+                text = handleDriftStatus(args);
+                break;
+            case 'check_decision':
+                text = handleCheckDecision(args);
+                break;
+            case 'declare_anchor':
+                text = handleDeclareAnchor(args);
+                break;
+            case 'resolve_drift':
+                text = handleResolveDrift(args);
+                break;
             default: {
                 const migrations = {
                     update_memory: 'remember({ memory_id: <id>, content: "...", importance: 0.8 })',

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "linksee-memory",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "mcpName": "io.github.michielinksee/linksee-memory",
-  "description": "Local-first agent memory MCP — cross-agent brain with 6-layer structured memory + token-saving file diff cache",
+  "description": "Local-first agent memory MCP — cross-agent brain with drift detection, 6-layer structured memory + token-saving file diff cache",
   "type": "module",
   "bin": {
     "linksee-memory": "dist/mcp/server.js",
@@ -10,7 +10,9 @@
     "linksee-memory-sync": "dist/bin/sync-session.js",
     "linksee-memory-install-skill": "dist/bin/install-skill.js",
     "linksee-memory-stats": "dist/bin/stats.js",
-    "linksee-memory-setup": "dist/bin/setup.js"
+    "linksee-memory-setup": "dist/bin/setup.js",
+    "linksee-memory-declare": "dist/bin/declare-anchor.js",
+    "linksee-memory-detect": "dist/bin/detect-drift.js"
   },
   "main": "./dist/mcp/server.js",
   "files": [