linksee-memory 0.12.1 → 0.13.0

package/README.md

@@ -207,7 +207,14 @@ It is **fail-open by construction**: any parse / DB / logic error surfaces nothi
 
 ### Enable it
 
-`npx -y linksee-memory setup` offers to wire this into your **project's** `.claude/settings.json` (Step 4). To do it by hand, drop this block into `.claude/settings.json` at your project root — it points at the globally-installed `linksee-memory-guard` bin, so no build step is needed:
+`npx -y linksee-memory setup` wires this into `~/.claude/settings.json` (Step 4), so it is on in **every** repo — the same scope your memory already lives at. One SQLite file holds the anchors for all your projects; enforcing them per-repo meant declaring a decision once and having it enforced nowhere.
+
+- `--project-guard` — this repo only, the old behaviour
+- `--no-guard` — skip it
+
+Anchors with `affects` globs fire only on matching paths; an unscoped anchor fires on its own `detect_terms` / `violation_signal`. Nothing is ever **blocked** unless you explicitly hardened it (`resolve_drift(action:'harden')`) — everything else re-injects the decision as context.
+
+To wire it by hand instead, drop this block into `.claude/settings.json` (project root, or `~/.claude/settings.json` for every repo) — it points at the globally-installed `linksee-memory-guard` bin, so no build step is needed:
 
 ```json
 {

package/dist/bin/setup.js

@@ -2,15 +2,17 @@
 // setup: One-command setup for Linksee Memory — the "Use Linksee" installer.
 //
 // Usage:
-//   npx linksee-memory setup          (interactive setup)
-//   npx linksee-memory setup --yes    (accept all defaults, no prompts)
+//   npx linksee-memory setup             (interactive setup)
+//   npx linksee-memory setup --yes       (accept all defaults, no prompts)
 //   npx linksee-memory setup --dry-run
+//   npx linksee-memory setup --no-guard  (skip the re-injection guard)
+//   npx linksee-memory setup --project-guard  (wire the guard to THIS repo only)
 //
 // Does four things:
 //   1. Registers the MCP server with Claude Code
 //   2. Installs the SKILL.md (agent trigger phrases)
 //   3. Configures the Stop hook (auto-capture sessions) — user-global
-//   4. Offers to wire the re-injection guard into THIS project's .claude/settings.json
+//   4. Wires the re-injection guard into ~/.claude/settings.json (every project)
 //
 // After setup, every Claude Code session:
 //   - Auto-captures decisions, learnings, caveats to local memory
@@ -21,15 +23,30 @@
 // Why: Competing memory tools (claude-mem, etc.) are one-install-and-done.
 // Our MCP approach gives more precision, but the setup was 3 manual steps.
 // This command eliminates that friction entirely.
+//
+// Why the guard is user-global (2026-09-07): memory is global — one SQLite file holding the
+// anchors for every repo — but the guard used to be wired per project, opt-in. So the anchors
+// existed everywhere and were enforced nowhere. The author's own machine had 42 active anchors
+// and no PreToolUse hook in any project; the one layer no competing tool has was switched off
+// where it was written. A founder running twenty repos should not run setup twenty times.
+//
+// Safe by construction: the hook is fail-open, and it can only DENY when an anchor was
+// explicitly hardened via resolve_drift(action:'harden'). Anything else re-injects text.
+// Anchors with `affects` globs only fire on matching paths; unscoped ones fire on their own
+// detect_terms / violation_signal, so cross-repo noise is bounded by what you declared.
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { createInterface } from 'node:readline';
+import { guardFullyWired, wireGuard, syncWiredFor } from '../lib/guard-wiring.js';
 const args = process.argv.slice(2);
 const dryRun = args.includes('--dry-run');
 const autoYes = args.includes('--yes') || args.includes('-y');
+const noGuard = args.includes('--no-guard');
+// Opt back into the old behaviour: wire the guard to this repo instead of every repo.
+const projectGuard = args.includes('--project-guard');
 const showHelp = args.includes('--help') || args.includes('-h');
 if (showHelp) {
     console.log(`linksee-memory-setup — One-command setup for Linksee Memory
@@ -62,11 +79,9 @@ const MCP_COMMAND = `claude mcp add -s user ${SERVER_NAME} -- npx -y linksee-mem
 // Subcommand form (npx -y linksee-memory <sub>) so the hooks resolve for a cold user —
 // npx can resolve the package name, but not sibling bin names like linksee-memory-sync.
 const HOOK_COMMAND = 'npx -y linksee-memory sync';
-// Re-injection guard — wired into the PROJECT (not user-global) settings, because it enforces THIS
-// project's accepted decisions. Mirrors the dogfood wiring's ${CLAUDE_PROJECT_DIR}/dist/bin path, but
-// points at the globally-installed `linksee-memory-guard` bin so it ships without a build step. Shell
-// form (resolved at run time) survives npx-cache eviction; a baked dist path would not.
-const GUARD_COMMAND = 'npx -y linksee-memory guard';
+// Re-injection guard: command + merge rules live in lib/guard-wiring.ts (shared with the tests).
+// It points at the globally-installed bin rather than a dist path, so it ships without a build
+// step, and the shell form is resolved at run time so it survives npx-cache eviction.
 const PROJECT_DIR = process.cwd();
 const PROJECT_CLAUDE_DIR = join(PROJECT_DIR, '.claude');
 const PROJECT_SETTINGS_PATH = join(PROJECT_CLAUDE_DIR, 'settings.json');
@@ -195,7 +210,9 @@ if (existsSync(SETTINGS_PATH)) {
 }
 // Check if hook already exists
 const stopHooks = settings?.hooks?.Stop ?? [];
-const alreadyHooked = stopHooks.some((entry) => entry.hooks?.some((h) => h.command?.includes('linksee-memory-sync')));
+// Recognise every shape the sync hook has been wired in (npx subcommand, global bin, dist
+// path, exec form) — a narrower probe appended a second copy, see lib/guard-wiring.ts.
+const alreadyHooked = syncWiredFor(settings, 'Stop');
 if (alreadyHooked) {
     console.log(`  ${SKIP} Stop hook already configured`);
 }
@@ -217,17 +234,7 @@ else {
     console.log(`  ${CHECK} Stop hook added → ${SETTINGS_PATH}`);
 }
 console.log('');
-const GUARD_EVENTS = ['SessionStart', 'PreToolUse'];
-const GUARD_HOOKS = {
-    // matchers + timeouts mirror the dogfood .claude/settings.json
-    SessionStart: { matcher: 'startup|resume|compact', hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 15 }] },
-    PreToolUse: { matcher: 'Edit|Write|Bash', hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 8 }] },
-};
-// Idempotency probe: is OUR guard already wired for this event? (Match by bin name so a manually-added
-// or previously-installed entry isn't duplicated, and other people's hooks are never touched.)
-function guardWiredFor(s, ev) {
-    return (s.hooks?.[ev] ?? []).some((entry) => entry?.hooks?.some((h) => typeof h?.command === 'string' && h.command.includes('linksee-memory-guard')));
-}
+// ── Step 4: Wire the re-injection guard (user-global by default) ─────────
 function askYesNo(question, defaultYes = true) {
     return new Promise((resolve) => {
         const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -241,54 +248,60 @@ function askYesNo(question, defaultYes = true) {
     });
 }
 async function configureGuard() {
-    console.log(`${BOLD}[4/4]${RESET} Configuring re-injection guard (this project)...`);
-    let project = {};
-    if (existsSync(PROJECT_SETTINGS_PATH)) {
+    // Default target is the user-global settings — the same scope the MCP server is registered
+    // at, and the same scope the memory itself lives at. --project-guard keeps the old per-repo
+    // behaviour for people who want the guard in one repo only.
+    const targetPath = projectGuard ? PROJECT_SETTINGS_PATH : SETTINGS_PATH;
+    const targetDir = projectGuard ? PROJECT_CLAUDE_DIR : CLAUDE_DIR;
+    const scopeLabel = projectGuard ? 'this project' : 'all projects';
+    console.log(`${BOLD}[4/4]${RESET} Configuring re-injection guard (${scopeLabel})...`);
+    if (noGuard) {
+        console.log(`  ${SKIP} Skipped (--no-guard). Enable later: npx -y linksee-memory setup`);
+        return false;
+    }
+    let settings = {};
+    if (existsSync(targetPath)) {
         try {
             // Strip a leading BOM (U+FEFF) — Windows editors (Notepad) emit UTF-8+BOM, which JSON.parse rejects.
-            const raw = readFileSync(PROJECT_SETTINGS_PATH, 'utf8');
-            project = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
+            const raw = readFileSync(targetPath, 'utf8');
+            settings = JSON.parse(raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw);
         }
         catch {
             // Never clobber a file we can't parse — the user may have hand-authored it.
-            console.log(`  ${FAIL} Could not parse ${PROJECT_SETTINGS_PATH} — left untouched`);
+            console.log(`  ${FAIL} Could not parse ${targetPath} — left untouched`);
             console.log(`  ${DIM}Add the guard block by hand (see README → Re-injection Guard).${RESET}`);
             return false;
         }
     }
-    if (GUARD_EVENTS.every((ev) => guardWiredFor(project, ev))) {
-        console.log(`  ${SKIP} Guard already wired in ${PROJECT_SETTINGS_PATH}`);
+    if (guardFullyWired(settings)) {
+        console.log(`  ${SKIP} Guard already wired in ${targetPath}`);
         return true;
     }
     if (dryRun) {
-        console.log(`  ${DIM}[dry-run] Would merge SessionStart + PreToolUse guard hooks into ${PROJECT_SETTINGS_PATH}${RESET}`);
+        console.log(`  ${DIM}[dry-run] Would merge SessionStart + PreToolUse guard hooks into ${targetPath}${RESET}`);
         return false;
     }
-    // "Offer" — opt-in, because the guard can deny tool calls on a 'hard' contradiction.
-    if (!autoYes) {
-        if (!process.stdin.isTTY) {
-            console.log(`  ${SKIP} Skipped (non-interactive shell). Re-run with --yes, or paste the README block.`);
-            return false;
-        }
+    // Ask when there is someone to ask. A non-interactive run used to skip silently, which is
+    // how the guard ended up installed nowhere — setup's job is to configure, so it configures
+    // and says so loudly instead.
+    if (!autoYes && process.stdin.isTTY) {
         console.log(`  ${DIM}Re-injects your accepted decisions before Edit/Write/Bash and on session start.`);
-        console.log(`  Fail-open — only an action that contradicts a 'hard' anchor is ever blocked.${RESET}`);
-        const ok = await askYesNo(`  Wire it into ${PROJECT_SETTINGS_PATH}?`);
+        console.log(`  Fail-open — only an action contradicting a 'hard' anchor is ever blocked.${RESET}`);
+        const ok = await askYesNo(`  Wire it into ${targetPath}?`);
         if (!ok) {
             console.log(`  ${SKIP} Skipped. Enable later via the README → Re-injection Guard.`);
             return false;
         }
     }
-    // Merge, don't replace: append only the events we don't already own; leave foreign hooks intact.
-    const hooks = project.hooks ?? (project.hooks = {});
-    for (const ev of GUARD_EVENTS) {
-        if (!Array.isArray(hooks[ev]))
-            hooks[ev] = [];
-        if (!guardWiredFor(project, ev))
-            hooks[ev].push(GUARD_HOOKS[ev]);
+    // Merge, don't replace (see lib/guard-wiring.ts for the rules it holds to).
+    wireGuard(settings);
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(targetPath, JSON.stringify(settings, null, 2), 'utf8');
+    console.log(`  ${CHECK} Guard wired → ${targetPath} ${DIM}(${scopeLabel})${RESET}`);
+    if (!projectGuard) {
+        console.log(`  ${DIM}Active in every repo. Scope an anchor with \`affects\` globs to limit where it fires;`);
+        console.log(`  --no-guard to skip, --project-guard for this repo only.${RESET}`);
     }
-    mkdirSync(PROJECT_CLAUDE_DIR, { recursive: true });
-    writeFileSync(PROJECT_SETTINGS_PATH, JSON.stringify(project, null, 2), 'utf8');
-    console.log(`  ${CHECK} Guard wired → ${PROJECT_SETTINGS_PATH}`);
     return true;
 }
 const guardConfigured = await configureGuard();

package/dist/lib/guard-wiring.d.ts

@@ -0,0 +1,54 @@
+export type HookCommand = {
+    type: string;
+    command?: string;
+    timeout?: number;
+    args?: string[];
+};
+export type HookEntry = {
+    matcher?: string;
+    hooks?: HookCommand[];
+};
+export type ClaudeSettings = {
+    hooks?: Record<string, HookEntry[]>;
+    [k: string]: unknown;
+};
+export declare const GUARD_EVENTS: readonly ["SessionStart", "PreToolUse"];
+export type GuardEvent = (typeof GUARD_EVENTS)[number];
+/** The bin every wiring form resolves to; used as the idempotency key. */
+export declare const GUARD_BIN = "linksee-memory-guard";
+export declare const GUARD_COMMAND = "npx -y linksee-memory guard";
+export declare const GUARD_HOOKS: Record<GuardEvent, HookEntry>;
+/**
+ * Is one of OUR hooks of `kind` already wired for this event?
+ *
+ * Shared by the guard and the session-sync hook because they hit the same trap: each has been
+ * wired as an npx subcommand, as a global bin, as a dist path, and in exec form with the path
+ * in `args`. A probe that knows only one shape appends a duplicate — which is exactly what
+ * happened to the Stop hook on 2026-09-07 (`sync-session.js` did not match `linksee-memory-sync`,
+ * so setup added a second one and sessions were captured twice).
+ */
+export declare function linkseeHookWired(settings: ClaudeSettings, event: string, kind: 'guard' | 'sync'): boolean;
+/** Is the session-sync (Stop) hook already wired? */
+export declare function syncWiredFor(settings: ClaudeSettings, event?: string): boolean;
+/**
+ * Is OUR guard already wired for this event?
+ *
+ * Has to recognise every shape the guard has ever been wired in, or setup duplicates it:
+ *   npx -y linksee-memory guard                              (what setup writes)
+ *   linksee-memory-guard                                     (the global bin)
+ *   node /path/to/linksee-memory/dist/bin/guard-hook.js      (the old README block)
+ *   { command: 'node', args: ['.../dist/bin/guard-hook.js'] } (exec form — the path is in args)
+ *
+ * The last two put the identifying part in different places, so match against command and args
+ * joined together. `guard-hook` alone is accepted because the exec form carries no package name.
+ */
+export declare function guardWiredFor(settings: ClaudeSettings, event: string): boolean;
+export declare function guardFullyWired(settings: ClaudeSettings): boolean;
+/**
+ * Add the guard to any event it does not already own. Mutates and returns `settings`, plus the
+ * events that were actually added (empty when it was already wired).
+ */
+export declare function wireGuard(settings: ClaudeSettings): {
+    settings: ClaudeSettings;
+    added: GuardEvent[];
+};

package/dist/lib/guard-wiring.js

@@ -0,0 +1,85 @@
+// guard-wiring — merge the re-injection guard's hooks into a Claude Code settings object.
+//
+// Extracted from bin/setup.ts so the merge is testable without running the installer (which
+// also registers an MCP server and copies a skill). The rules that matter here:
+//
+//   • merge, never replace — other people's hooks in the same event must survive
+//   • idempotent — running setup twice must not produce two guard entries
+//   • recognise a hand-pasted guard from the README as already-wired (match on the bin name,
+//     not on the exact command string, which differs between `npx` and a dist path)
+export const GUARD_EVENTS = ['SessionStart', 'PreToolUse'];
+/** The bin every wiring form resolves to; used as the idempotency key. */
+export const GUARD_BIN = 'linksee-memory-guard';
+export const GUARD_COMMAND = 'npx -y linksee-memory guard';
+export const GUARD_HOOKS = {
+    SessionStart: {
+        matcher: 'startup|resume|compact',
+        hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 15 }],
+    },
+    PreToolUse: {
+        matcher: 'Edit|Write|Bash',
+        hooks: [{ type: 'command', command: GUARD_COMMAND, timeout: 8 }],
+    },
+};
+/** Everything a hook entry could carry an identifier in: `command`, or `args` for the exec form. */
+function hookHaystack(h) {
+    return [h?.command, ...(h?.args ?? [])].filter((x) => typeof x === 'string').join(' ');
+}
+/**
+ * Is one of OUR hooks of `kind` already wired for this event?
+ *
+ * Shared by the guard and the session-sync hook because they hit the same trap: each has been
+ * wired as an npx subcommand, as a global bin, as a dist path, and in exec form with the path
+ * in `args`. A probe that knows only one shape appends a duplicate — which is exactly what
+ * happened to the Stop hook on 2026-09-07 (`sync-session.js` did not match `linksee-memory-sync`,
+ * so setup added a second one and sessions were captured twice).
+ */
+export function linkseeHookWired(settings, event, kind) {
+    const bare = kind === 'guard' ? 'guard-hook' : 'sync-session';
+    return (settings.hooks?.[event] ?? []).some((entry) => entry?.hooks?.some((h) => {
+        const hay = hookHaystack(h);
+        if (!hay)
+            return false;
+        return hay.includes(bare) || (hay.includes('linksee-memory') && hay.includes(kind));
+    }));
+}
+/** Is the session-sync (Stop) hook already wired? */
+export function syncWiredFor(settings, event = 'Stop') {
+    return linkseeHookWired(settings, event, 'sync');
+}
+/**
+ * Is OUR guard already wired for this event?
+ *
+ * Has to recognise every shape the guard has ever been wired in, or setup duplicates it:
+ *   npx -y linksee-memory guard                              (what setup writes)
+ *   linksee-memory-guard                                     (the global bin)
+ *   node /path/to/linksee-memory/dist/bin/guard-hook.js      (the old README block)
+ *   { command: 'node', args: ['.../dist/bin/guard-hook.js'] } (exec form — the path is in args)
+ *
+ * The last two put the identifying part in different places, so match against command and args
+ * joined together. `guard-hook` alone is accepted because the exec form carries no package name.
+ */
+export function guardWiredFor(settings, event) {
+    return linkseeHookWired(settings, event, 'guard');
+}
+export function guardFullyWired(settings) {
+    return GUARD_EVENTS.every((ev) => guardWiredFor(settings, ev));
+}
+/**
+ * Add the guard to any event it does not already own. Mutates and returns `settings`, plus the
+ * events that were actually added (empty when it was already wired).
+ */
+export function wireGuard(settings) {
+    const hooks = (settings.hooks ??= {});
+    const added = [];
+    for (const ev of GUARD_EVENTS) {
+        if (!Array.isArray(hooks[ev]))
+            hooks[ev] = [];
+        if (!guardWiredFor(settings, ev)) {
+            hooks[ev].push(GUARD_HOOKS[ev]);
+            added.push(ev);
+        }
+    }
+    return { settings, added };
+}
+//# sourceMappingURL=guard-wiring.js.map

package/dist/lib/guard.js

@@ -97,9 +97,16 @@ export function matchAction(db, act) {
                 }
             }
         }
-        // Scope (mirrors the detector): a path-scoped anchor requires the action to touch an in-scope
-        // file; a global anchor (no affects) fires on topical-term OR forbidden-signal relevance.
-        const inScope = hasScope ? pathHit : termHit || sigHit != null;
+        // Scope. `affects` says WHERE a decision applies; `violation_signal` says WHAT is forbidden.
+        // An explicit signal hit is the stronger evidence, so it brings the anchor into scope on its
+        // own — otherwise a path-scoped anchor is blind to `Bash`, which carries no file path at all.
+        // That blindness was measured on a real machine: 21 of 42 active anchors declared forbidden
+        // strings and could never fire on a Bash command — including "ALTER TABLE memories DROP" on
+        // the anchor that exists to prevent exactly that. Bash is where the destructive things run.
+        //
+        // (matchViolation already guards the obvious false positives: word boundaries, a negation
+        // window, and citation-without-call — a naive substring test produced ~90% noise.)
+        const inScope = sigHit != null || (hasScope ? pathHit : termHit);
         if (!inScope)
             continue;
         out.push({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linksee-memory",
-  "version": "0.12.1",
+  "version": "0.13.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",