@seanhogg/builderforce-memory-mcp 2026.6.30 → 2026.6.31

package/README.md

@@ -95,6 +95,24 @@ write tools; `--local=<dist/bin/stdio.js>` runs a checkout for development.
 The same launch spec is exported for programmatic use:
 `buildServerSpec()` / `installMemoryServer()` (see `src/install/`).
 
+### Claude Code: the self-driving "memory combo"
+
+Registering the server gives Claude Code the memory *tools*. For Claude Code the
+installer ALSO wires hooks so memory is **self-driving instead of advisory** (skip
+with `--no-hooks`):
+
+| Hook | Behaviour |
+|------|-----------|
+| `SessionStart` | Inject a digest of the top durable memories. |
+| `PreCompact` | Flush durable learnings before the window is summarised. |
+| `UserPromptSubmit` | **Contextual recall** — score memories against the prompt and inject the relevant ones, so a stored fact is retrieved at the *decision point*, not only at session start. |
+| `Stop` | **Autonomous capture** — if the user's last message was a durable instruction/correction and it wasn't consolidated this turn, BLOCK the stop with a directive to `memory_remember`. Capture flows through the MCP write path (never racing the snapshot); a `stop_hook_active` guard means at most one nudge per turn. |
+
+All four point at one generated, dependency-free hook script
+(`~/.claude/builderforce-memory/bfmem-hook.mjs`, four modes) plus a companion
+skill. Idempotent + `.bak`-safe. Source of truth: `src/install/claude-hooks.ts`
+(`installClaudeCombo` / `bfmemHookSource`).
+
 ## Quick start — stdio (any process / language)
 
 ```bash

package/dist/bin/install.js

@@ -17,8 +17,10 @@
  */
 import os from "node:os";
 import path from "node:path";
+import nodeFs from "node:fs";
 import { HOSTS } from "../install/hosts.js";
 import { installMemoryServer } from "../install/install.js";
+import { installClaudeCombo } from "../install/claude-hooks.js";
 function argValue(name) {
     const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
     return hit ? hit.slice(name.length + 3) : undefined;
@@ -73,6 +75,26 @@ for (const r of results) {
     if (r.status === "installed" || r.status === "updated")
         wrote += 1;
 }
+// ── Claude Code memory combo (hooks + companion skill) ───────────────────────
+// Registering the server above gives Claude Code the TOOLS; this adds the
+// self-driving behaviour (SessionStart digest, contextual recall, autonomous Stop
+// capture). Only for Claude Code, only when present, and skippable via --no-hooks.
+const claudeResult = results.find((r) => r.host === "claude-code");
+const claudePresent = claudeResult && claudeResult.status !== "unsupported" && claudeResult.status !== "error";
+if (claudePresent && !hasFlag("no-hooks")) {
+    try {
+        const combo = installClaudeCombo({
+            fs: nodeFs,
+            claudeDir: path.join(os.homedir(), ".claude"),
+            memoryFile,
+        });
+        const what = combo.addedHooks.length ? `added ${combo.addedHooks.join(", ")}` : "already current";
+        process.stdout.write(`✓ Claude Code memory combo: hooks ${what}; recall + autonomous capture wired\n`);
+    }
+    catch (err) {
+        process.stderr.write(`✗ Claude Code hooks: ${String(err.message ?? err)}\n`);
+    }
+}
 if (results.length === 0) {
     process.stdout.write("No MCP hosts detected. Pass --host=all to write configs anyway, or --host=cursor (etc.).\n");
 }

package/dist/bin/install.js.map

@@ -1 +1 @@
-{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/bin/install.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/bin/install.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -24,4 +24,6 @@ export { installMemoryServer } from "./install/install.js";
 export type { InstallOptions, InstallResult, InstallStatus, HostSelector, FsLike } from "./install/install.js";
 export { HOSTS, SERVER_KEY, findHost } from "./install/hosts.js";
 export type { HostAdapter, HostEnv, ConfigFormat } from "./install/hosts.js";
+export { installClaudeCombo, bfmemHookSource, companionSkillMd, claudeComboPaths } from "./install/claude-hooks.js";
+export type { ClaudeComboPaths } from "./install/claude-hooks.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAC/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAC/F,YAAY,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAGtE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEhF,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAChG,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAC/G,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG7E,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js

@@ -19,4 +19,7 @@ export { createMemoryHttpHandler } from "./transports/http.js";
 export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";
 export { installMemoryServer } from "./install/install.js";
 export { HOSTS, SERVER_KEY, findHost } from "./install/hosts.js";
+// Claude Code "memory combo" — hooks (SessionStart/PreCompact/UserPromptSubmit/Stop)
+// + companion skill that make memory self-driving (contextual recall + autonomous capture).
+export { installClaudeCombo, bfmemHookSource, companionSkillMd, claudeComboPaths } from "./install/claude-hooks.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,0FAA0F;AAC1F,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAG/F,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,0FAA0F;AAC1F,OAAO,EAAE,kBAAkB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAG/F,iFAAiF;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAG9C,+EAA+E;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAG/D,iFAAiF;AACjF,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEjE,qFAAqF;AACrF,4FAA4F;AAC5F,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/install/claude-hooks.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Claude Code "memory combo" — the hooks + companion skill half of the install.
+ *
+ * Registering the MCP server (install.ts) gives Claude Code the memory TOOLS.
+ * This module adds the behaviour that makes memory SELF-DRIVING rather than
+ * advisory, so the agent doesn't have to be reminded to use it:
+ *
+ *   SessionStart      → inject a digest of the top durable memories.
+ *   PreCompact        → flush durable learnings before the window is summarised.
+ *   UserPromptSubmit  → CONTEXTUAL recall: score memories against the prompt and
+ *                       inject the relevant ones (so a stored fact is retrieved at
+ *                       the decision point, not just at session start).
+ *   Stop              → AUTONOMOUS capture: detect a durable instruction/correction
+ *                       in the user's last message and, if it wasn't consolidated
+ *                       this turn, BLOCK the stop with a directive to memory_remember
+ *                       (capture flows through the MCP write path — never racing the
+ *                       server's snapshot).
+ *
+ * All four point at one generated, dependency-free hook script (DRY). The combo
+ * is idempotent and backup-safe, matching install.ts.
+ */
+import type { FsLike } from "./install.js";
+/** The single hook script, four modes. `memoryFile` is the JSON snapshot path. */
+export declare function bfmemHookSource(memoryFile: string): string;
+/** The companion skill doc that teaches the recall/remember discipline. */
+export declare function companionSkillMd(): string;
+/** Files/paths the combo manages, derived from the Claude config dir (~/.claude). */
+export interface ClaudeComboPaths {
+    claudeDir: string;
+    settingsFile: string;
+    hookScript: string;
+    companionSkill: string;
+}
+export declare function claudeComboPaths(claudeDir: string): ClaudeComboPaths;
+/**
+ * Write the hook script + companion skill and register all four hooks in
+ * settings.json. Idempotent (skips a hook command already present) and
+ * backup-safe (.bak before overwriting settings). Returns the events it added.
+ */
+export declare function installClaudeCombo(opts: {
+    fs: FsLike;
+    claudeDir: string;
+    memoryFile: string;
+}): {
+    hookScript: string;
+    addedHooks: string[];
+    settingsFile: string;
+};
+//# sourceMappingURL=claude-hooks.d.ts.map

package/dist/install/claude-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-hooks.d.ts","sourceRoot":"","sources":["../../src/install/claude-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CA6I1D;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,IAAI,MAAM,CA0BzC;AAED,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAOpE;AASD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACtB,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAmCrE"}

package/dist/install/claude-hooks.js

@@ -0,0 +1,255 @@
+/**
+ * Claude Code "memory combo" — the hooks + companion skill half of the install.
+ *
+ * Registering the MCP server (install.ts) gives Claude Code the memory TOOLS.
+ * This module adds the behaviour that makes memory SELF-DRIVING rather than
+ * advisory, so the agent doesn't have to be reminded to use it:
+ *
+ *   SessionStart      → inject a digest of the top durable memories.
+ *   PreCompact        → flush durable learnings before the window is summarised.
+ *   UserPromptSubmit  → CONTEXTUAL recall: score memories against the prompt and
+ *                       inject the relevant ones (so a stored fact is retrieved at
+ *                       the decision point, not just at session start).
+ *   Stop              → AUTONOMOUS capture: detect a durable instruction/correction
+ *                       in the user's last message and, if it wasn't consolidated
+ *                       this turn, BLOCK the stop with a directive to memory_remember
+ *                       (capture flows through the MCP write path — never racing the
+ *                       server's snapshot).
+ *
+ * All four point at one generated, dependency-free hook script (DRY). The combo
+ * is idempotent and backup-safe, matching install.ts.
+ */
+import nodePath from "node:path";
+/** The single hook script, four modes. `memoryFile` is the JSON snapshot path. */
+export function bfmemHookSource(memoryFile) {
+    return `#!/usr/bin/env node
+/**
+ * builderforce-memory hook — generated by builderforce-memory-install. Dependency-free:
+ * reads only the JSON snapshot, never stands up the MCP server.
+ *   --session     SessionStart: inject a small digest of durable memories.
+ *   --precompact  PreCompact: remind to flush learnings before summarisation.
+ *   --recall      UserPromptSubmit: contextual recall — inject memories relevant to the prompt.
+ *   --capture     Stop: autonomous consolidation — block the stop until a detected
+ *                 durable correction is persisted via memory_remember.
+ */
+import fs from "node:fs";
+
+const FILE = ${JSON.stringify(memoryFile)};
+const mode = process.argv[2] || "--session";
+
+function readStdin() {
+    try { return fs.readFileSync(0, "utf8"); } catch { return ""; }
+}
+function loadEntries() {
+    try { const p = JSON.parse(fs.readFileSync(FILE, "utf8")); return Array.isArray(p) ? p : []; }
+    catch { return []; }
+}
+function tokens(s) {
+    return String(s || "").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3);
+}
+
+if (mode === "--precompact") {
+    process.stdout.write(
+        "[builderforce-memory] Context is about to be compacted. Persist any durable learnings from this session — decisions, fixes, project facts, user preferences — by calling memory_remember with concise one-line facts. Recall them later with memory_recall instead of re-reading files.",
+    );
+    process.exit(0);
+}
+
+if (mode === "--recall") {
+    let prompt = "";
+    try { const j = JSON.parse(readStdin() || "{}"); prompt = typeof j.prompt === "string" ? j.prompt : ""; } catch { /* no input */ }
+    if (!prompt) process.exit(0);
+    const entries = loadEntries();
+    if (entries.length === 0) process.exit(0);
+    const q = new Set(tokens(prompt));
+    if (q.size === 0) process.exit(0);
+    const scored = entries
+        .map((e) => {
+            const hay = new Set(tokens([e.key, e.content, (e.tags || []).join(" ")].join(" ")));
+            let score = 0;
+            for (const t of q) if (hay.has(t)) score++;
+            return { e, score };
+        })
+        .filter((x) => x.score >= 2)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 3);
+    if (scored.length === 0) process.exit(0);
+    const lines = scored.map((x) => "• " + x.e.key + ": " + String(x.e.content || "").slice(0, 240)).join("\\n");
+    process.stdout.write(
+        "[builderforce-memory] Relevant stored memories for this request — use these instead of re-deriving or re-reading:\\n" + lines,
+    );
+    process.exit(0);
+}
+
+if (mode === "--capture") {
+    let input = {};
+    try { input = JSON.parse(readStdin() || "{}"); } catch { /* no input */ }
+    if (input.stop_hook_active) process.exit(0);
+    const tpath = input.transcript_path;
+    if (!tpath || typeof tpath !== "string") process.exit(0);
+
+    let raw = "";
+    try {
+        const stat = fs.statSync(tpath);
+        const want = Math.min(stat.size, 400000);
+        const fd = fs.openSync(tpath, "r");
+        const buf = Buffer.alloc(want);
+        fs.readSync(fd, buf, 0, want, stat.size - want);
+        fs.closeSync(fd);
+        raw = buf.toString("utf8");
+    } catch { process.exit(0); }
+
+    const msgs = [];
+    for (const ln of raw.split("\\n")) { if (ln.trim()) { try { msgs.push(JSON.parse(ln)); } catch { /* partial */ } } }
+
+    let lastUserText = "";
+    let rememberedThisTurn = false;
+    for (let i = msgs.length - 1; i >= 0; i--) {
+        const m = msgs[i] || {};
+        const inner = m.message || m;
+        const role = inner.role;
+        const content = inner.content;
+        if (role === "assistant" && !lastUserText) {
+            if (Array.isArray(content)) for (const c of content) {
+                if (c && c.type === "tool_use" && typeof c.name === "string" && c.name.includes("memory_remember")) rememberedThisTurn = true;
+            }
+        }
+        if (role === "user" && !lastUserText) {
+            let txt = "";
+            if (typeof content === "string") txt = content;
+            else if (Array.isArray(content)) for (const c of content) {
+                if (typeof c === "string") txt += c + " ";
+                else if (c && c.type === "text" && typeof c.text === "string") txt += c.text + " ";
+            }
+            if (txt.trim()) lastUserText = txt;
+        }
+    }
+    if (!lastUserText || rememberedThisTurn) process.exit(0);
+
+    const lower = lastUserText.toLowerCase();
+    const SIGNALS = [
+        "you have to", "you should", "you need to", "you must", "from now on", "going forward",
+        "always ", "never ", "make sure", "remember to", "don't forget", "do not forget",
+        "i keep telling", "i already told", "shouldn't have to", "keep having to remind",
+        "you forgot", "you keep", "that's wrong", "you're wrong", "this is wrong", "stop ",
+    ];
+    const hit = SIGNALS.find((s) => lower.includes(s));
+    if (!hit) process.exit(0);
+
+    const snippet = lastUserText.trim().slice(0, 240);
+    const reason =
+        "[builderforce-memory] A durable instruction/correction was detected in the user's last message and you did NOT consolidate it this turn. " +
+        "Before stopping, call memory_remember with a concise, stable-keyed fact capturing it (reuse the same key to replace a superseded one, or memory_forget it). " +
+        "User said: '" + snippet + "'. If it is genuinely not durable (a one-off, or already stored), briefly say why and then stop.";
+    process.stdout.write(JSON.stringify({ decision: "block", reason }));
+    process.exit(0);
+}
+
+const entries = loadEntries();
+if (entries.length === 0) {
+    process.stdout.write(
+        "[builderforce-memory] Active (memory empty). Store durable facts with memory_remember and retrieve them with memory_recall instead of re-reading files or chat history — that is how token usage stays low.",
+    );
+    process.exit(0);
+}
+const top = entries
+    .map((e) => ({ key: e.key, content: String(e.content ?? ""), importance: typeof e.importance === "number" ? e.importance : 0.5 }))
+    .sort((a, b) => b.importance - a.importance)
+    .slice(0, 8)
+    .map((e) => "• " + e.key + ": " + e.content.slice(0, 200))
+    .join("\\n");
+process.stdout.write(
+    "[builderforce-memory] Active — token-saving memory loaded. Before re-reading files or history, call memory_recall. Store durable facts with memory_remember.\\nTop memories:\\n" + top,
+);
+`;
+}
+/** The companion skill doc that teaches the recall/remember discipline. */
+export function companionSkillMd() {
+    return `---
+name: builderforce-memory
+description: Token-saving persistent memory. Recall durable facts (decisions, fixes, project context, user preferences) instead of re-reading files or chat history, and remember new durable facts as you learn them.
+---
+
+# builderforce-memory — the conductor
+
+Persistent memory backed by the \`builderforce-memory\` MCP server. The point is
+**token reduction**: pull a small relevant slice from memory instead of re-reading
+the full file/history. The install also wires hooks so this is largely automatic:
+the SessionStart digest, contextual recall on each prompt, and an autonomous Stop
+capture that won't let a durable correction go unrecorded.
+
+## Tools
+- \`memory_recall(query, [k])\` — top-K relevant memories. First move on a task.
+- \`memory_get(key)\` — exact lookup by key.
+- \`memory_recall_by_tag(tag)\` — everything under a tag.
+- \`memory_remember(key, content, [tags], [importance])\` — store ONE durable fact.
+- \`memory_forget(key)\` — drop a superseded fact.
+
+## Discipline
+Reuse a stable key to REPLACE a fact (write-through), don't append duplicates.
+Store decisions, non-obvious fixes, project constraints, user preferences — one
+tight line each. Not things git already records or one-off turn details.
+`;
+}
+export function claudeComboPaths(claudeDir) {
+    return {
+        claudeDir,
+        settingsFile: nodePath.join(claudeDir, "settings.json"),
+        hookScript: nodePath.join(claudeDir, "builderforce-memory", "bfmem-hook.mjs"),
+        companionSkill: nodePath.join(claudeDir, "skills", "builderforce-memory", "SKILL.md"),
+    };
+}
+const HOOK_EVENTS = [
+    { event: "SessionStart", mode: "--session" },
+    { event: "PreCompact", mode: "--precompact" },
+    { event: "UserPromptSubmit", mode: "--recall" },
+    { event: "Stop", mode: "--capture" },
+];
+/**
+ * Write the hook script + companion skill and register all four hooks in
+ * settings.json. Idempotent (skips a hook command already present) and
+ * backup-safe (.bak before overwriting settings). Returns the events it added.
+ */
+export function installClaudeCombo(opts) {
+    const { fs, memoryFile } = opts;
+    const paths = claudeComboPaths(opts.claudeDir);
+    // 1) Hook script.
+    const hookDir = nodePath.dirname(paths.hookScript);
+    if (!fs.existsSync(hookDir))
+        fs.mkdirSync(hookDir, { recursive: true });
+    fs.writeFileSync(paths.hookScript, bfmemHookSource(memoryFile));
+    // 2) Companion skill.
+    const skillDir = nodePath.dirname(paths.companionSkill);
+    if (!fs.existsSync(skillDir))
+        fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(paths.companionSkill, companionSkillMd());
+    // 3) Merge hooks into settings.json.
+    let settings = {};
+    if (fs.existsSync(paths.settingsFile)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(paths.settingsFile, "utf8"));
+        }
+        catch {
+            throw new Error("existing settings.json is not valid JSON");
+        }
+        fs.copyFileSync(paths.settingsFile, `${paths.settingsFile}.bak`);
+    }
+    const hooks = (settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {});
+    const added = [];
+    for (const { event, mode } of HOOK_EVENTS) {
+        const command = `node "${paths.hookScript}" ${mode}`;
+        const arr = (Array.isArray(hooks[event]) ? hooks[event] : (hooks[event] = []));
+        const exists = arr.some((g) => (g.hooks || []).some((h) => h.command === command));
+        if (!exists) {
+            arr.push({ hooks: [{ type: "command", command }] });
+            added.push(event);
+        }
+    }
+    settings.hooks = hooks;
+    const settingsDir = nodePath.dirname(paths.settingsFile);
+    if (!fs.existsSync(settingsDir))
+        fs.mkdirSync(settingsDir, { recursive: true });
+    fs.writeFileSync(paths.settingsFile, `${JSON.stringify(settings, null, 2)}\n`);
+    return { hookScript: paths.hookScript, addedHooks: added, settingsFile: paths.settingsFile };
+}
+//# sourceMappingURL=claude-hooks.js.map

package/dist/install/claude-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-hooks.js","sourceRoot":"","sources":["../../src/install/claude-hooks.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-mcp",
-  "version": "2026.6.30",
+  "version": "2026.6.31",
   "description": "BuilderForce Agent Memory — MCP transport. Exposes @seanhogg/builderforce-memory to any MCP client (Claude Agent SDK in-process, stdio, or HTTP) over a pluggable MemoryBackend, with token-saving fetch-on-demand recall.",
   "type": "module",
   "main": "dist/index.js",
@@ -73,7 +73,7 @@
     "fake-indexeddb": "^6.0.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory": "2026.6.30"
+    "@seanhogg/builderforce-memory": "2026.6.31"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/bin/install.ts

@@ -18,8 +18,10 @@
 
 import os from "node:os";
 import path from "node:path";
+import nodeFs from "node:fs";
 import { HOSTS } from "../install/hosts.js";
 import { installMemoryServer, type HostSelector } from "../install/install.js";
+import { installClaudeCombo } from "../install/claude-hooks.js";
 
 function argValue(name: string): string | undefined {
     const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
@@ -83,6 +85,26 @@ for (const r of results) {
     if (r.status === "installed" || r.status === "updated") wrote += 1;
 }
 
+// ── Claude Code memory combo (hooks + companion skill) ───────────────────────
+// Registering the server above gives Claude Code the TOOLS; this adds the
+// self-driving behaviour (SessionStart digest, contextual recall, autonomous Stop
+// capture). Only for Claude Code, only when present, and skippable via --no-hooks.
+const claudeResult = results.find((r) => r.host === "claude-code");
+const claudePresent = claudeResult && claudeResult.status !== "unsupported" && claudeResult.status !== "error";
+if (claudePresent && !hasFlag("no-hooks")) {
+    try {
+        const combo = installClaudeCombo({
+            fs: nodeFs,
+            claudeDir: path.join(os.homedir(), ".claude"),
+            memoryFile,
+        });
+        const what = combo.addedHooks.length ? `added ${combo.addedHooks.join(", ")}` : "already current";
+        process.stdout.write(`✓ Claude Code memory combo: hooks ${what}; recall + autonomous capture wired\n`);
+    } catch (err) {
+        process.stderr.write(`✗ Claude Code hooks: ${String((err as Error).message ?? err)}\n`);
+    }
+}
+
 if (results.length === 0) {
     process.stdout.write(
         "No MCP hosts detected. Pass --host=all to write configs anyway, or --host=cursor (etc.).\n",

package/src/index.ts

@@ -37,3 +37,7 @@ export { installMemoryServer } from "./install/install.js";
 export type { InstallOptions, InstallResult, InstallStatus, HostSelector, FsLike } from "./install/install.js";
 export { HOSTS, SERVER_KEY, findHost } from "./install/hosts.js";
 export type { HostAdapter, HostEnv, ConfigFormat } from "./install/hosts.js";
+// Claude Code "memory combo" — hooks (SessionStart/PreCompact/UserPromptSubmit/Stop)
+// + companion skill that make memory self-driving (contextual recall + autonomous capture).
+export { installClaudeCombo, bfmemHookSource, companionSkillMd, claudeComboPaths } from "./install/claude-hooks.js";
+export type { ClaudeComboPaths } from "./install/claude-hooks.js";

package/src/install/claude-hooks.ts

@@ -0,0 +1,267 @@
+/**
+ * Claude Code "memory combo" — the hooks + companion skill half of the install.
+ *
+ * Registering the MCP server (install.ts) gives Claude Code the memory TOOLS.
+ * This module adds the behaviour that makes memory SELF-DRIVING rather than
+ * advisory, so the agent doesn't have to be reminded to use it:
+ *
+ *   SessionStart      → inject a digest of the top durable memories.
+ *   PreCompact        → flush durable learnings before the window is summarised.
+ *   UserPromptSubmit  → CONTEXTUAL recall: score memories against the prompt and
+ *                       inject the relevant ones (so a stored fact is retrieved at
+ *                       the decision point, not just at session start).
+ *   Stop              → AUTONOMOUS capture: detect a durable instruction/correction
+ *                       in the user's last message and, if it wasn't consolidated
+ *                       this turn, BLOCK the stop with a directive to memory_remember
+ *                       (capture flows through the MCP write path — never racing the
+ *                       server's snapshot).
+ *
+ * All four point at one generated, dependency-free hook script (DRY). The combo
+ * is idempotent and backup-safe, matching install.ts.
+ */
+
+import nodePath from "node:path";
+import type { FsLike } from "./install.js";
+
+/** The single hook script, four modes. `memoryFile` is the JSON snapshot path. */
+export function bfmemHookSource(memoryFile: string): string {
+    return `#!/usr/bin/env node
+/**
+ * builderforce-memory hook — generated by builderforce-memory-install. Dependency-free:
+ * reads only the JSON snapshot, never stands up the MCP server.
+ *   --session     SessionStart: inject a small digest of durable memories.
+ *   --precompact  PreCompact: remind to flush learnings before summarisation.
+ *   --recall      UserPromptSubmit: contextual recall — inject memories relevant to the prompt.
+ *   --capture     Stop: autonomous consolidation — block the stop until a detected
+ *                 durable correction is persisted via memory_remember.
+ */
+import fs from "node:fs";
+
+const FILE = ${JSON.stringify(memoryFile)};
+const mode = process.argv[2] || "--session";
+
+function readStdin() {
+    try { return fs.readFileSync(0, "utf8"); } catch { return ""; }
+}
+function loadEntries() {
+    try { const p = JSON.parse(fs.readFileSync(FILE, "utf8")); return Array.isArray(p) ? p : []; }
+    catch { return []; }
+}
+function tokens(s) {
+    return String(s || "").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3);
+}
+
+if (mode === "--precompact") {
+    process.stdout.write(
+        "[builderforce-memory] Context is about to be compacted. Persist any durable learnings from this session — decisions, fixes, project facts, user preferences — by calling memory_remember with concise one-line facts. Recall them later with memory_recall instead of re-reading files.",
+    );
+    process.exit(0);
+}
+
+if (mode === "--recall") {
+    let prompt = "";
+    try { const j = JSON.parse(readStdin() || "{}"); prompt = typeof j.prompt === "string" ? j.prompt : ""; } catch { /* no input */ }
+    if (!prompt) process.exit(0);
+    const entries = loadEntries();
+    if (entries.length === 0) process.exit(0);
+    const q = new Set(tokens(prompt));
+    if (q.size === 0) process.exit(0);
+    const scored = entries
+        .map((e) => {
+            const hay = new Set(tokens([e.key, e.content, (e.tags || []).join(" ")].join(" ")));
+            let score = 0;
+            for (const t of q) if (hay.has(t)) score++;
+            return { e, score };
+        })
+        .filter((x) => x.score >= 2)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 3);
+    if (scored.length === 0) process.exit(0);
+    const lines = scored.map((x) => "• " + x.e.key + ": " + String(x.e.content || "").slice(0, 240)).join("\\n");
+    process.stdout.write(
+        "[builderforce-memory] Relevant stored memories for this request — use these instead of re-deriving or re-reading:\\n" + lines,
+    );
+    process.exit(0);
+}
+
+if (mode === "--capture") {
+    let input = {};
+    try { input = JSON.parse(readStdin() || "{}"); } catch { /* no input */ }
+    if (input.stop_hook_active) process.exit(0);
+    const tpath = input.transcript_path;
+    if (!tpath || typeof tpath !== "string") process.exit(0);
+
+    let raw = "";
+    try {
+        const stat = fs.statSync(tpath);
+        const want = Math.min(stat.size, 400000);
+        const fd = fs.openSync(tpath, "r");
+        const buf = Buffer.alloc(want);
+        fs.readSync(fd, buf, 0, want, stat.size - want);
+        fs.closeSync(fd);
+        raw = buf.toString("utf8");
+    } catch { process.exit(0); }
+
+    const msgs = [];
+    for (const ln of raw.split("\\n")) { if (ln.trim()) { try { msgs.push(JSON.parse(ln)); } catch { /* partial */ } } }
+
+    let lastUserText = "";
+    let rememberedThisTurn = false;
+    for (let i = msgs.length - 1; i >= 0; i--) {
+        const m = msgs[i] || {};
+        const inner = m.message || m;
+        const role = inner.role;
+        const content = inner.content;
+        if (role === "assistant" && !lastUserText) {
+            if (Array.isArray(content)) for (const c of content) {
+                if (c && c.type === "tool_use" && typeof c.name === "string" && c.name.includes("memory_remember")) rememberedThisTurn = true;
+            }
+        }
+        if (role === "user" && !lastUserText) {
+            let txt = "";
+            if (typeof content === "string") txt = content;
+            else if (Array.isArray(content)) for (const c of content) {
+                if (typeof c === "string") txt += c + " ";
+                else if (c && c.type === "text" && typeof c.text === "string") txt += c.text + " ";
+            }
+            if (txt.trim()) lastUserText = txt;
+        }
+    }
+    if (!lastUserText || rememberedThisTurn) process.exit(0);
+
+    const lower = lastUserText.toLowerCase();
+    const SIGNALS = [
+        "you have to", "you should", "you need to", "you must", "from now on", "going forward",
+        "always ", "never ", "make sure", "remember to", "don't forget", "do not forget",
+        "i keep telling", "i already told", "shouldn't have to", "keep having to remind",
+        "you forgot", "you keep", "that's wrong", "you're wrong", "this is wrong", "stop ",
+    ];
+    const hit = SIGNALS.find((s) => lower.includes(s));
+    if (!hit) process.exit(0);
+
+    const snippet = lastUserText.trim().slice(0, 240);
+    const reason =
+        "[builderforce-memory] A durable instruction/correction was detected in the user's last message and you did NOT consolidate it this turn. " +
+        "Before stopping, call memory_remember with a concise, stable-keyed fact capturing it (reuse the same key to replace a superseded one, or memory_forget it). " +
+        "User said: '" + snippet + "'. If it is genuinely not durable (a one-off, or already stored), briefly say why and then stop.";
+    process.stdout.write(JSON.stringify({ decision: "block", reason }));
+    process.exit(0);
+}
+
+const entries = loadEntries();
+if (entries.length === 0) {
+    process.stdout.write(
+        "[builderforce-memory] Active (memory empty). Store durable facts with memory_remember and retrieve them with memory_recall instead of re-reading files or chat history — that is how token usage stays low.",
+    );
+    process.exit(0);
+}
+const top = entries
+    .map((e) => ({ key: e.key, content: String(e.content ?? ""), importance: typeof e.importance === "number" ? e.importance : 0.5 }))
+    .sort((a, b) => b.importance - a.importance)
+    .slice(0, 8)
+    .map((e) => "• " + e.key + ": " + e.content.slice(0, 200))
+    .join("\\n");
+process.stdout.write(
+    "[builderforce-memory] Active — token-saving memory loaded. Before re-reading files or history, call memory_recall. Store durable facts with memory_remember.\\nTop memories:\\n" + top,
+);
+`;
+}
+
+/** The companion skill doc that teaches the recall/remember discipline. */
+export function companionSkillMd(): string {
+    return `---
+name: builderforce-memory
+description: Token-saving persistent memory. Recall durable facts (decisions, fixes, project context, user preferences) instead of re-reading files or chat history, and remember new durable facts as you learn them.
+---
+
+# builderforce-memory — the conductor
+
+Persistent memory backed by the \`builderforce-memory\` MCP server. The point is
+**token reduction**: pull a small relevant slice from memory instead of re-reading
+the full file/history. The install also wires hooks so this is largely automatic:
+the SessionStart digest, contextual recall on each prompt, and an autonomous Stop
+capture that won't let a durable correction go unrecorded.
+
+## Tools
+- \`memory_recall(query, [k])\` — top-K relevant memories. First move on a task.
+- \`memory_get(key)\` — exact lookup by key.
+- \`memory_recall_by_tag(tag)\` — everything under a tag.
+- \`memory_remember(key, content, [tags], [importance])\` — store ONE durable fact.
+- \`memory_forget(key)\` — drop a superseded fact.
+
+## Discipline
+Reuse a stable key to REPLACE a fact (write-through), don't append duplicates.
+Store decisions, non-obvious fixes, project constraints, user preferences — one
+tight line each. Not things git already records or one-off turn details.
+`;
+}
+
+/** Files/paths the combo manages, derived from the Claude config dir (~/.claude). */
+export interface ClaudeComboPaths {
+    claudeDir: string;
+    settingsFile: string;
+    hookScript: string;
+    companionSkill: string;
+}
+
+export function claudeComboPaths(claudeDir: string): ClaudeComboPaths {
+    return {
+        claudeDir,
+        settingsFile: nodePath.join(claudeDir, "settings.json"),
+        hookScript: nodePath.join(claudeDir, "builderforce-memory", "bfmem-hook.mjs"),
+        companionSkill: nodePath.join(claudeDir, "skills", "builderforce-memory", "SKILL.md"),
+    };
+}
+
+const HOOK_EVENTS = [
+    { event: "SessionStart", mode: "--session" },
+    { event: "PreCompact", mode: "--precompact" },
+    { event: "UserPromptSubmit", mode: "--recall" },
+    { event: "Stop", mode: "--capture" },
+] as const;
+
+/**
+ * Write the hook script + companion skill and register all four hooks in
+ * settings.json. Idempotent (skips a hook command already present) and
+ * backup-safe (.bak before overwriting settings). Returns the events it added.
+ */
+export function installClaudeCombo(opts: {
+    fs: FsLike;
+    claudeDir: string;
+    memoryFile: string;
+}): { hookScript: string; addedHooks: string[]; settingsFile: string } {
+    const { fs, memoryFile } = opts;
+    const paths = claudeComboPaths(opts.claudeDir);
+
+    // 1) Hook script.
+    const hookDir = nodePath.dirname(paths.hookScript);
+    if (!fs.existsSync(hookDir)) fs.mkdirSync(hookDir, { recursive: true });
+    fs.writeFileSync(paths.hookScript, bfmemHookSource(memoryFile));
+
+    // 2) Companion skill.
+    const skillDir = nodePath.dirname(paths.companionSkill);
+    if (!fs.existsSync(skillDir)) fs.mkdirSync(skillDir, { recursive: true });
+    fs.writeFileSync(paths.companionSkill, companionSkillMd());
+
+    // 3) Merge hooks into settings.json.
+    let settings: Record<string, unknown> = {};
+    if (fs.existsSync(paths.settingsFile)) {
+        try { settings = JSON.parse(fs.readFileSync(paths.settingsFile, "utf8")) as Record<string, unknown>; }
+        catch { throw new Error("existing settings.json is not valid JSON"); }
+        fs.copyFileSync(paths.settingsFile, `${paths.settingsFile}.bak`);
+    }
+    const hooks = (settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {}) as Record<string, unknown>;
+    const added: string[] = [];
+    for (const { event, mode } of HOOK_EVENTS) {
+        const command = `node "${paths.hookScript}" ${mode}`;
+        const arr = (Array.isArray(hooks[event]) ? hooks[event] : (hooks[event] = [])) as Array<{ hooks?: Array<{ type?: string; command?: string }> }>;
+        const exists = arr.some((g) => (g.hooks || []).some((h) => h.command === command));
+        if (!exists) { arr.push({ hooks: [{ type: "command", command }] }); added.push(event); }
+    }
+    settings.hooks = hooks;
+    const settingsDir = nodePath.dirname(paths.settingsFile);
+    if (!fs.existsSync(settingsDir)) fs.mkdirSync(settingsDir, { recursive: true });
+    fs.writeFileSync(paths.settingsFile, `${JSON.stringify(settings, null, 2)}\n`);
+
+    return { hookScript: paths.hookScript, addedHooks: added, settingsFile: paths.settingsFile };
+}