linksee-memory 0.7.2 → 0.10.0

package/dist/bin/declare-anchor.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/declare-anchor.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+// linksee-memory-declare — declare / list / retire drift anchors (v8).
+//
+// The explicit write path for drift observability. Anchors declared here are clean
+// by construction (declare-don't-mine): a human typed them. The bulk seeding script
+// (curate the existing candidate pool) reuses curateAnchorFromMemory() from the lib.
+//
+// Usage:
+//   linksee-memory-declare list [--status active|retired] [--kind prohibition|decision|constraint]
+//   linksee-memory-declare add --kind <k> --statement "<text>" [--rationale "<text>"]
+//        [--affects "glob1,glob2"] [--terms "t1,t2"] [--violation "v1,v2"] [--tier human|explicit]
+//   linksee-memory-declare retire --id <n>
+import { openDb, runMigrations } from '../db/migrate.js';
+import { declareAnchor, listAnchors, retireAnchor, setNodeFields, getCurrentTruth, getAlertPolicy, setAlertPolicy, } from '../lib/drift-anchors.js';
+function parseFlags(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                out[key] = 'true';
+            }
+            else {
+                out[key] = next;
+                i++;
+            }
+        }
+    }
+    return out;
+}
+function splitList(v) {
+    if (!v)
+        return [];
+    return v
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function print(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+function main() {
+    const [, , sub, ...rest] = process.argv;
+    const flags = parseFlags(rest);
+    const db = openDb();
+    runMigrations(db); // ensure drift tables exist when run standalone
+    try {
+        switch (sub) {
+            case 'add': {
+                const anchor = declareAnchor(db, {
+                    kind: flags.kind,
+                    statement: flags.statement ?? '',
+                    rationale: flags.rationale,
+                    affects: splitList(flags.affects),
+                    detect_terms: splitList(flags.terms),
+                    violation_signal: splitList(flags.violation),
+                    tier: flags.tier || undefined,
+                });
+                // v9 ProjectCoreNode fields (minimal input — only what's given):
+                //   --node-type --domain --mode --confidence --cadence --stale-days --applies --not-applies
+                const nf = {};
+                if (flags['node-type'])
+                    nf.node_type = flags['node-type'];
+                if (flags.domain)
+                    nf.domain = flags.domain;
+                if (flags.mode)
+                    nf.decision_mode = flags.mode;
+                if (flags.confidence)
+                    nf.confidence = Number(flags.confidence);
+                if (flags.cadence || flags['stale-days']) {
+                    const cp = { enabled: true };
+                    if (flags.cadence)
+                        cp.cadence_days = Number(flags.cadence);
+                    if (flags['stale-days'])
+                        cp.stale_threshold_days = Number(flags['stale-days']);
+                    nf.card_policy = cp;
+                }
+                if (flags.applies || flags['not-applies']) {
+                    const vs = {};
+                    if (flags.applies)
+                        vs.applies_to = splitList(flags.applies);
+                    if (flags['not-applies'])
+                        vs.does_not_apply_to = splitList(flags['not-applies']);
+                    nf.validity_scope = vs;
+                }
+                if (Object.keys(nf).length)
+                    setNodeFields(db, anchor.id, nf);
+                print({ ok: true, declared: anchor, node_fields: Object.keys(nf).length ? nf : null });
+                break;
+            }
+            case 'retire': {
+                const id = Number(flags.id);
+                if (!Number.isFinite(id))
+                    throw new Error('--id <n> required');
+                const ok = retireAnchor(db, id);
+                print({ ok, retired: ok ? id : null });
+                break;
+            }
+            case 'list':
+            case undefined: {
+                const anchors = listAnchors(db, {
+                    status: flags.status,
+                    kind: flags.kind,
+                });
+                print({ ok: true, count: anchors.length, anchors });
+                break;
+            }
+            case 'truth': {
+                // ⑧ read_smart-style scoped read: active Current-Truth slice only.
+                const nodes = getCurrentTruth(db, { domain: flags.domain, decision_mode: flags.mode });
+                print({ ok: true, scope: { domain: flags.domain ?? 'all', decision_mode: flags.mode ?? 'all' }, count: nodes.length, current_truth: nodes });
+                break;
+            }
+            case 'policy': {
+                const p = {};
+                if (flags['max-cards-per-day'])
+                    p.max_cards_per_day = Number(flags['max-cards-per-day']);
+                if (flags['max-soft-per-week'])
+                    p.max_soft_cards_per_week = Number(flags['max-soft-per-week']);
+                if (flags['min-soft-confidence'])
+                    p.min_confidence_for_soft_card = Number(flags['min-soft-confidence']);
+                if (flags['two-sided'])
+                    p.require_two_sided_evidence = flags['two-sided'] !== 'false';
+                const policy = Object.keys(p).length ? setAlertPolicy(db, p) : getAlertPolicy(db);
+                print({ ok: true, alert_policy: policy });
+                break;
+            }
+            default:
+                throw new Error(`unknown subcommand "${sub}" — use: add | list | retire | truth | policy`);
+        }
+    }
+    catch (err) {
+        print({ ok: false, error: err?.message ?? String(err) });
+        db.close();
+        process.exit(1);
+    }
+    db.close();
+}
+if (import.meta.url === `file://${process.argv[1]}` ||
+    process.argv[1]?.endsWith('declare-anchor.ts') ||
+    process.argv[1]?.endsWith('declare-anchor.js')) {
+    main();
+}
+//# sourceMappingURL=declare-anchor.js.map

package/dist/bin/detect-drift.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/detect-drift.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// linksee-memory-detect — run the drift detector (照合: declared intent vs. actual reality).
+//
+// The manual-trigger entry point for drift detection (the cadence question). Mirrors
+// declare-anchor.ts; purely additive — touches only drift_edges (the feature's own table) and
+// ONLY when --persist is passed. SAFE BY DEFAULT: a bare run is a dry-run (reads only, no
+// writes), so you can preview drift before committing it to the view. Pass --persist to write
+// the edges that /drift renders. No embedding layer: matching is lexical/glob/trigram-FTS only.
+//
+// Usage:
+//   linksee-memory-detect                  # dry-run — preview drift, writes NOTHING (default)
+//   linksee-memory-detect --persist         # write contradicts/absent edges into drift_edges
+//   linksee-memory-detect --stale-days 30   # override absence staleness gate (default 14)
+//   linksee-memory-detect --threshold 0.5   # override emit threshold (default 0.5)
+import { openDb, runMigrations } from '../db/migrate.js';
+import { detectDrift, detectFileViolations } from '../lib/drift-detection.js';
+function parseFlags(argv) {
+    const out = {};
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a.startsWith('--')) {
+            const key = a.slice(2);
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                out[key] = 'true';
+            }
+            else {
+                out[key] = next;
+                i++;
+            }
+        }
+    }
+    return out;
+}
+function print(obj) {
+    process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
+}
+function main() {
+    const [, , ...rest] = process.argv;
+    const flags = parseFlags(rest);
+    const persist = flags.persist === 'true';
+    const staleDays = flags['stale-days'] !== undefined ? Number(flags['stale-days']) : undefined;
+    const emitThreshold = flags.threshold !== undefined ? Number(flags.threshold) : undefined;
+    if (staleDays !== undefined && !Number.isFinite(staleDays))
+        throw new Error('--stale-days <n> must be a number');
+    if (emitThreshold !== undefined && !Number.isFinite(emitThreshold))
+        throw new Error('--threshold <n> must be a number');
+    const db = openDb();
+    runMigrations(db); // ensure drift tables exist when run standalone
+    try {
+        const res = detectDrift(db, { dryRun: !persist, staleDays, emitThreshold });
+        const fres = detectFileViolations(db, { dryRun: !persist, emitThreshold });
+        print({
+            ok: true,
+            mode: persist ? 'PERSISTED' : 'DRY RUN (no writes — pass --persist to write)',
+            persisted: res.persisted,
+            anchorsScanned: res.anchorsScanned,
+            editsScanned: res.editsScanned,
+            // v1 — edit-snippet scan (what a captured edit's snippet contained)
+            editSnippetScan: {
+                contradicts: res.contradicts,
+                absent: res.absent,
+                edgesEmitted: res.edgesEmitted,
+                byAnchorHits: res.byAnchor.filter((b) => b.contradicts > 0 || b.absent > 0),
+                samples: res.samples.slice(0, 6),
+            },
+            // v2 — current-file scan (live file:line against violation_signal)
+            currentFileScan: {
+                filesScanned: fres.filesScanned,
+                anchorsCapped: fres.anchorsCapped,
+                contradicts: fres.contradicts,
+                edgesEmitted: fres.edgesEmitted,
+                byAnchorHits: fres.byAnchor,
+                samples: fres.samples.slice(0, 14),
+            },
+            totalEdgesEmitted: res.edgesEmitted + fres.edgesEmitted,
+        });
+    }
+    catch (err) {
+        print({ ok: false, error: err?.message ?? String(err) });
+        db.close();
+        process.exit(1);
+    }
+    db.close();
+}
+if (import.meta.url === `file://${process.argv[1]}` ||
+    process.argv[1]?.endsWith('detect-drift.ts') ||
+    process.argv[1]?.endsWith('detect-drift.js')) {
+    main();
+}
+//# sourceMappingURL=detect-drift.js.map

package/dist/bin/guard-hook.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/guard-hook.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// linksee-memory-guard — Claude Code hook adapter for the re-injection layer.
+//
+// Reads a hook event JSON from stdin and emits hook-control JSON to stdout:
+//   • PreToolUse  (matcher Edit|Write|Bash) → gateAction → block (hard) / soft-inject (warn|inform)
+//   • SessionStart (startup|resume|compact)  → buildBootDigest → additionalContext
+//
+// FAIL-OPEN by construction: any parse/DB/logic error → NO output, exit 0 → the tool/session proceeds
+// unblocked. The ONLY thing that ever blocks is an explicit `gate_mode:'hard'` contradiction. This is
+// intentional — a guard that breaks the user's workflow on its own bug is a footgun.
+//
+// Wire it (project or ~/.claude/settings.json), exec form so Windows .cmd shims are bypassed:
+//   { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write|Bash",
+//       "hooks": [ { "type": "command", "command": "node",
+//                    "args": ["${CLAUDE_PROJECT_DIR}/dist/bin/guard-hook.js"], "timeout": 8 } ] } ] } }
+import { pathToFileURL } from 'node:url';
+import { openDb, runMigrations } from '../db/migrate.js';
+import { gateAction, buildBootDigest } from '../lib/guard.js';
+function readStdin() {
+    return new Promise((resolve) => {
+        const chunks = [];
+        process.stdin.on('data', (c) => chunks.push(c));
+        process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        process.stdin.on('error', () => resolve(''));
+    });
+}
+function emit(obj) {
+    process.stdout.write(JSON.stringify(obj));
+}
+async function main() {
+    let ev;
+    try {
+        ev = JSON.parse(await readStdin());
+    }
+    catch {
+        process.exit(0); // unparseable stdin → fail-open
+    }
+    if (!ev || typeof ev !== 'object')
+        process.exit(0);
+    let db;
+    try {
+        db = openDb();
+        db.pragma('busy_timeout = 2000'); // MCP server may hold a write lock; wait briefly, else fail-open
+        runMigrations(db); // ensures injection_log exists even when run standalone
+    }
+    catch {
+        process.exit(0); // can't open DB → never block
+    }
+    try {
+        if (ev.hook_event_name === 'PreToolUse') {
+            const ti = (ev.tool_input ?? {});
+            const r = gateAction(db, {
+                tool: ev.tool_name,
+                file_path: ti.file_path,
+                command: ti.command,
+                content: ti.content,
+                diff: ti.new_string ?? ti.diff, // Edit passes new_string; some tools pass diff
+            }, { sessionId: ev.session_id });
+            if (r.gate === 'block') {
+                emit({
+                    hookSpecificOutput: {
+                        hookEventName: 'PreToolUse',
+                        permissionDecision: 'deny',
+                        permissionDecisionReason: r.reinject,
+                    },
+                });
+            }
+            else if (r.gate === 'warn' || r.gate === 'inform') {
+                emit({
+                    hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: r.reinject },
+                });
+            }
+            // 'allow' → emit nothing
+        }
+        else if (ev.hook_event_name === 'SessionStart') {
+            const d = buildBootDigest(db);
+            if (d.text) {
+                emit({ hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: d.text } });
+            }
+        }
+    }
+    catch {
+        /* fail-open: surface nothing rather than risk blocking on a guard bug */
+    }
+    try {
+        db.close();
+    }
+    catch {
+        /* ignore */
+    }
+    process.exit(0);
+}
+const invoked = !!process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invoked)
+    main();
+//# sourceMappingURL=guard-hook.js.map

package/dist/bin/import-sessions.js

@@ -16,10 +16,10 @@ import { extractSession } from '../lib/session-extractor.js';
 import { normalizeEntityName } from '../lib/normalize.js';
 const CLAUDE_PROJECTS = join(homedir(), '.claude', 'projects');
 function usage() {
-    console.log(`Usage:
-  node dist/bin/import-sessions.js [--dry-run] [--all | <projectDir> [<projectDir> ...]]
-    --all         : scan every project under ~/.claude/projects/*
-    --dry-run     : parse + extract but do not write to DB
+    console.log(`Usage:
+  node dist/bin/import-sessions.js [--dry-run] [--all | <projectDir> [<projectDir> ...]]
+    --all         : scan every project under ~/.claude/projects/*
+    --dry-run     : parse + extract but do not write to DB
     projectDir    : absolute path to a project dir (must contain *.jsonl files)`);
 }
 function collectJsonlFiles(projectDir) {
@@ -42,13 +42,33 @@ function collectJsonlFiles(projectDir) {
 }
 // Idempotent wipe: remove all rows tied to a given session_id BEFORE re-inserting.
 // Uses LIKE matching on the JSON-encoded source field for memories/events.
+// DISTILLED memories survive the wipe: a session stays ACTIVE while its raw extractions
+// get distilled (dream → remember(memory_id) rewrite), and the next Stop-hook re-import
+// must not destroy that human/agent-curated rewrite and resurrect the raw utterance.
 function wipeSession(db, sessionId) {
     const sidNeedle = `%"session_id":"${sessionId}"%`;
     const editDel = db.prepare('DELETE FROM session_file_edits WHERE session_id = ?').run(sessionId);
-    const memDel = db.prepare('DELETE FROM memories WHERE source LIKE ?').run(sidNeedle);
+    const memDel = db.prepare(`DELETE FROM memories WHERE source LIKE ?
+       AND (NOT json_valid(content) OR COALESCE(json_extract(content, '$.distilled'), 0) != 1)`).run(sidNeedle);
     const evtDel = db.prepare('DELETE FROM events WHERE payload LIKE ?').run(sidNeedle);
     return { memories: memDel.changes, edits: editDel.changes, events: evtDel.changes };
 }
+// A re-extracted memory must NOT be re-inserted if its source turn already has a surviving
+// distilled rewrite (matched by turn_uuid — the stable key shared by raw and rewrite).
+function makeDistilledTurnSet(db, sessionId) {
+    const rows = db.prepare(`SELECT source FROM memories
+      WHERE source LIKE ? AND json_valid(content) AND json_extract(content, '$.distilled') = 1`).all(`%"session_id":"${sessionId}"%`);
+    const set = new Set();
+    for (const r of rows) {
+        try {
+            const uuid = JSON.parse(r.source)?.turn_uuid;
+            if (uuid)
+                set.add(String(uuid));
+        }
+        catch { /* ignore malformed source */ }
+    }
+    return set;
+}
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('-h') || args.includes('--help')) {
@@ -86,7 +106,10 @@ async function main() {
         if (!db)
             return;
         // Idempotent: wipe any prior data for THIS session before re-inserting
+        // (distilled rewrites survive — see wipeSession), then skip re-extracting
+        // any turn that already has a distilled rewrite.
         const wiped = wipeSession(db, result.session_id);
+        const distilledTurns = makeDistilledTurnSet(db, result.session_id);
         // Resolve project entity (canonical_key = project:<name>, so same project across
         // different sessions/cwds collapses to one entity)
         let projectEntityId;
@@ -102,14 +125,19 @@ async function main() {
             const ins = db.prepare('INSERT INTO entities (kind, name, normalized_name, canonical_key) VALUES (?, ?, ?, ?)').run('project', projectName, normalized, canonicalKey);
             projectEntityId = Number(ins.lastInsertRowid);
         }
-        const insMem = db.prepare('INSERT INTO memories (entity_id, layer, content, importance, source, thread_id) VALUES (?, ?, ?, ?, ?, ?)');
+        // created_at = the source turn's true timestamp. The Stop hook re-imports the growing
+        // transcript every turn (wipe+reinsert), and DEFAULT unixepoch() restamped days-old
+        // content as "now" — inflating every time-windowed view ("today" showed last week).
+        const insMem = db.prepare('INSERT INTO memories (entity_id, layer, content, importance, source, thread_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)');
         const insEdit = db.prepare(`INSERT INTO session_file_edits (session_id, memory_id, file_path, operation, turn_uuid, context_snippet, occurred_at) VALUES (?, ?, ?, ?, ?, ?, ?)`);
         const insEvt = db.prepare('INSERT INTO events (entity_id, kind, payload, occurred_at) VALUES (?, ?, ?, ?)');
         let inserted = { memories: 0, edits: 0 };
         db.transaction(() => {
             const memContentToId = new Map();
             for (const m of result.memories) {
-                const res = insMem.run(projectEntityId, m.layer, m.content, m.importance, JSON.stringify(m.source), m.thread_id ?? null);
+                if (m.source.turn_uuid && distilledTurns.has(m.source.turn_uuid))
+                    continue; // distilled rewrite wins
+                const res = insMem.run(projectEntityId, m.layer, m.content, m.importance, JSON.stringify(m.source), m.thread_id ?? null, m.occurred_at ?? Math.floor(Date.now() / 1000));
                 memContentToId.set(m.content, Number(res.lastInsertRowid));
                 inserted.memories++;
             }
@@ -221,17 +249,22 @@ async function main() {
                 const ins = db.prepare('INSERT INTO entities (kind, name, normalized_name, canonical_key) VALUES (?, ?, ?, ?)').run('project', projectName, normalized, canonicalKey);
                 projectEntityId = Number(ins.lastInsertRowid);
             }
-            // Idempotent: wipe any prior data for THIS session before re-inserting (Phase B)
+            // Idempotent: wipe any prior data for THIS session before re-inserting (Phase B).
+            // Distilled rewrites survive the wipe and suppress re-insertion of their raw turn.
             wipeSession(db, result.session_id);
-            // Insert memories + file_edits in a single transaction per session
-            const insMem = db.prepare('INSERT INTO memories (entity_id, layer, content, importance, source, thread_id) VALUES (?, ?, ?, ?, ?, ?)');
+            const distilledTurns = makeDistilledTurnSet(db, result.session_id);
+            // Insert memories + file_edits in a single transaction per session.
+            // created_at = source-turn timestamp (see single-file mode above for why).
+            const insMem = db.prepare('INSERT INTO memories (entity_id, layer, content, importance, source, thread_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)');
             const insEdit = db.prepare(`INSERT INTO session_file_edits (session_id, memory_id, file_path, operation, turn_uuid, context_snippet, occurred_at) VALUES (?, ?, ?, ?, ?, ?, ?)`);
             const insEvt = db.prepare('INSERT INTO events (entity_id, kind, payload, occurred_at) VALUES (?, ?, ?, ?)');
             const tx = db.transaction(() => {
                 const memContentToId = new Map();
                 for (const m of result.memories) {
+                    if (m.source.turn_uuid && distilledTurns.has(m.source.turn_uuid))
+                        continue; // distilled rewrite wins
                     const srcJson = JSON.stringify(m.source);
-                    const res = insMem.run(projectEntityId, m.layer, m.content, m.importance, srcJson, m.thread_id ?? null);
+                    const res = insMem.run(projectEntityId, m.layer, m.content, m.importance, srcJson, m.thread_id ?? null, m.occurred_at ?? Math.floor(Date.now() / 1000));
                     memContentToId.set(m.content, Number(res.lastInsertRowid));
                     agg.memories_inserted++;
                 }

package/dist/bin/install-skill.js

@@ -21,20 +21,20 @@ const force = args.includes('--force') || args.includes('-f');
 const dryRun = args.includes('--dry-run');
 const showHelp = args.includes('--help') || args.includes('-h');
 if (showHelp) {
-    console.log(`linksee-memory-install-skill
-
-Install the linksee-memory Claude Code skill into ~/.claude/skills/linksee-memory/.
-
-Options:
-  --force, -f    Overwrite an existing skill file
-  --dry-run      Show what would happen without writing
-  --help, -h     This message
-
-After installation, ensure the MCP server is registered in Claude Code:
-  claude mcp add -s user linksee -- npx -y linksee-memory
-
-The skill expects tool names of the form mcp__linksee__*. If you register the
-server under a different name (e.g. "linksee-memory"), edit the skill file
+    console.log(`linksee-memory-install-skill
+
+Install the linksee-memory Claude Code skill into ~/.claude/skills/linksee-memory/.
+
+Options:
+  --force, -f    Overwrite an existing skill file
+  --dry-run      Show what would happen without writing
+  --help, -h     This message
+
+After installation, ensure the MCP server is registered in Claude Code:
+  claude mcp add -s user linksee -- npx -y linksee-memory
+
+The skill expects tool names of the form mcp__linksee__*. If you register the
+server under a different name (e.g. "linksee-memory"), edit the skill file
 afterwards.`);
     process.exit(0);
 }