@seanhogg/builderforce-memory-mcp 2026.6.30 → 2026.6.34

package/dist/transports/http.d.ts

@@ -1,8 +1,22 @@
 /**
  * HTTP transport — the multi-tenant / networked path (builderforce.ai hosting,
- * remote claws). Stateless Streamable HTTP: one short-lived McpServer +
+ * remote hosts). Stateless Streamable HTTP: one short-lived McpServer +
  * transport per request, so it scales horizontally with no sticky sessions.
- * Bearer-token auth gates every request.
+ *
+ * Auth model (pick one, in precedence order):
+ *   • `tenants` — a `{ token: backend }` map. The bearer token selects the
+ *     tenant's OWN backend (namespace isolation); an unknown token is 401. This
+ *     is the production multi-tenant mode — one token can never read another
+ *     tenant's facts.
+ *   • `resolveBackend` — a function `(token) => backend` for dynamic tenant
+ *     resolution (e.g. a gateway lookup).
+ *   • `authToken` — a single shared secret guarding the one positional backend
+ *     (single-tenant / reference hosting).
+ *   • none — open, only valid behind a trusted gateway that already authed.
+ *
+ * Token comparison is constant-time (hash + timingSafeEqual / hash-keyed lookup),
+ * and an optional fixed-window rate limit (per tenant, or per client IP when
+ * unauthenticated) caps abuse.
  *
  * Consumed from the Claude Agent SDK as:
  *   mcpServers: {
@@ -15,16 +29,36 @@ import type { MemoryBackend } from "../backend.js";
 import { type McpServerOptions } from "./mcp-server.js";
 export interface HttpHandlerOptions extends McpServerOptions {
     /**
-     * Shared secret required in `Authorization: Bearer <token>`. When set, every
-     * request without a matching token is rejected 401. Omit only behind a trusted
-     * gateway that has already authenticated the caller.
+     * Shared secret required in `Authorization: Bearer <token>` for the single
+     * positional backend. Every request without a matching token is rejected 401.
+     * Omit only behind a trusted gateway that has already authenticated the caller.
      */
     authToken?: string;
+    /**
+     * Multi-tenant map: bearer token → that tenant's backend. When set, the token
+     * selects the backend (namespace isolation) and the positional `backend` is
+     * only used as a fallback when no token-auth modes match. Lookups are keyed by
+     * token hash, never the raw token.
+     */
+    tenants?: Record<string, MemoryBackend>;
+    /**
+     * Dynamic tenant resolver: `(token) => backend | undefined`. Used when tenants
+     * live in an external store. Returning undefined → 401.
+     */
+    resolveBackend?: (token: string) => MemoryBackend | undefined | Promise<MemoryBackend | undefined>;
+    /** Fixed-window rate limit applied per tenant (or per client IP if open). */
+    rateLimit?: {
+        windowMs: number;
+        max: number;
+    };
+    /** Injectable clock (ms) for deterministic rate-limit tests. */
+    now?: () => number;
 }
 /**
  * Returns a `(req, res) => Promise<void>` handler you mount on any Node HTTP
- * server (or Express). Per request it spins up a stateless MCP server bound to
- * `backend`, handles the MCP exchange, and tears down on response close.
+ * server (or Express). Per request it authenticates, resolves the tenant
+ * backend, rate-limits, spins up a stateless MCP server bound to that backend,
+ * handles the MCP exchange, and tears down on response close.
  */
 export declare function createMemoryHttpHandler(backend: MemoryBackend, opts?: HttpHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
 //# sourceMappingURL=http.d.ts.map

package/dist/transports/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IACxD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,kBAAuB,GAC9B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAuB9D"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAGxE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IACxD;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;IACnG,6EAA6E;IAC7E,SAAS,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAcD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,kBAAuB,GAC9B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAyD9D"}

package/dist/transports/http.js

@@ -1,8 +1,22 @@
 /**
  * HTTP transport — the multi-tenant / networked path (builderforce.ai hosting,
- * remote claws). Stateless Streamable HTTP: one short-lived McpServer +
+ * remote hosts). Stateless Streamable HTTP: one short-lived McpServer +
  * transport per request, so it scales horizontally with no sticky sessions.
- * Bearer-token auth gates every request.
+ *
+ * Auth model (pick one, in precedence order):
+ *   • `tenants` — a `{ token: backend }` map. The bearer token selects the
+ *     tenant's OWN backend (namespace isolation); an unknown token is 401. This
+ *     is the production multi-tenant mode — one token can never read another
+ *     tenant's facts.
+ *   • `resolveBackend` — a function `(token) => backend` for dynamic tenant
+ *     resolution (e.g. a gateway lookup).
+ *   • `authToken` — a single shared secret guarding the one positional backend
+ *     (single-tenant / reference hosting).
+ *   • none — open, only valid behind a trusted gateway that already authed.
+ *
+ * Token comparison is constant-time (hash + timingSafeEqual / hash-keyed lookup),
+ * and an optional fixed-window rate limit (per tenant, or per client IP when
+ * unauthenticated) caps abuse.
  *
  * Consumed from the Claude Agent SDK as:
  *   mcpServers: {
@@ -12,25 +26,78 @@
  */
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { buildMcpServer } from "./mcp-server.js";
-function unauthorized(res) {
-    res.writeHead(401, { "content-type": "application/json" });
-    res.end(JSON.stringify({ error: "unauthorized" }));
+import { RateLimiter, bearerToken, buildTenantIndex, hashToken, timingSafeEqualStr } from "./auth.js";
+function send(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+/** First-hop client IP, for rate-limiting unauthenticated callers. */
+function clientIp(req) {
+    const fwd = req.headers["x-forwarded-for"];
+    const first = Array.isArray(fwd) ? fwd[0] : fwd?.split(",")[0];
+    return (first?.trim() || req.socket?.remoteAddress || "unknown");
 }
 /**
  * Returns a `(req, res) => Promise<void>` handler you mount on any Node HTTP
- * server (or Express). Per request it spins up a stateless MCP server bound to
- * `backend`, handles the MCP exchange, and tears down on response close.
+ * server (or Express). Per request it authenticates, resolves the tenant
+ * backend, rate-limits, spins up a stateless MCP server bound to that backend,
+ * handles the MCP exchange, and tears down on response close.
  */
 export function createMemoryHttpHandler(backend, opts = {}) {
+    const tenantIndex = opts.tenants ? buildTenantIndex(opts.tenants) : undefined;
+    const limiter = opts.rateLimit
+        ? new RateLimiter(opts.rateLimit.windowMs, opts.rateLimit.max, opts.now ?? (() => Date.now()))
+        : undefined;
     return async (req, res) => {
-        if (opts.authToken) {
-            const header = req.headers["authorization"];
-            if (header !== `Bearer ${opts.authToken}`) {
-                unauthorized(res);
+        const token = bearerToken(req.headers["authorization"]);
+        // ── Resolve the per-request backend + a rate-limit key ────────────────
+        let resolved;
+        let rateKey;
+        if (tenantIndex) {
+            // Multi-tenant: token → that tenant's backend (hash-keyed lookup).
+            if (!token) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            resolved = tenantIndex.get(hashToken(token));
+            if (!resolved) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            rateKey = `t:${hashToken(token)}`;
+        }
+        else if (opts.resolveBackend) {
+            if (!token) {
+                send(res, 401, { error: "unauthorized" });
                 return;
             }
+            resolved = await opts.resolveBackend(token);
+            if (!resolved) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            rateKey = `t:${hashToken(token)}`;
+        }
+        else if (opts.authToken) {
+            // Single shared secret, constant-time compare.
+            if (!token || !timingSafeEqualStr(token, opts.authToken)) {
+                send(res, 401, { error: "unauthorized" });
+                return;
+            }
+            resolved = backend;
+            rateKey = `t:${hashToken(token)}`;
+        }
+        else {
+            // Open (trusted gateway): rate-limit by client IP.
+            resolved = backend;
+            rateKey = `ip:${clientIp(req)}`;
+        }
+        // ── Rate limit ────────────────────────────────────────────────────────
+        if (limiter && !limiter.check(rateKey)) {
+            send(res, 429, { error: "rate_limited" });
+            return;
         }
-        const server = buildMcpServer(backend, opts);
+        const server = buildMcpServer(resolved, opts);
         // Stateless: no session id generator → a fresh transport per request.
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         res.on("close", () => {

package/dist/transports/http.js.map

@@ -1 +1 @@
-{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,6BAA6B,EAAE,MAAM,oDAAoD,CAAC;AAEnG,OAAO,EAAE,cAAc,EAAyB,MAAM,iBAAiB,CAAC;AAWxE,SAAS,YAAY,CAAC,GAAmB;IACrC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;IAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACnC,OAAsB,EACtB,OAA2B,EAAE;IAE7B,OAAO,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QACtB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;YAC5C,IAAI,MAAM,KAAK,UAAU,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;gBACxC,YAAY,CAAC,GAAG,CAAC,CAAC;gBAClB,OAAO;YACX,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC7C,sEAAsE;QACtE,MAAM,SAAS,GAAG,IAAI,6BAA6B,CAAC,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAC,CAAC;QAEvF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACjB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;QACxB,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,8EAA8E;QAC9E,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/transports/http.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.34",
   "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.34"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -83,7 +83,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "tsc && node --test tests/install.test.mjs tests/tools.test.mjs",
+    "test": "tsc && node --test tests/install.test.mjs tests/tools.test.mjs tests/http.test.mjs",
     "lint": "eslint src/",
     "typecheck:native": "tsgo --noEmit"
   }

package/src/backends/memory-store.ts

@@ -81,7 +81,7 @@ export interface LocalBackendOptions {
     /**
      * Optional SSMRuntime for embedding-based recall. Omit for lexical (Jaccard)
      * recall. In the agent-runtime, pass `ssmMemoryService.runtime` here to reuse
-     * the already-loaded hippocampus instead of standing up a second model.
+     * the already-loaded Evermind runtime instead of standing up a second model.
      */
     runtime?: unknown;
     /**

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

@@ -29,6 +29,7 @@ export { runStdio } from "./transports/stdio.js";
 
 export { createMemoryHttpHandler } from "./transports/http.js";
 export type { HttpHandlerOptions } from "./transports/http.js";
+export { hashToken, timingSafeEqualStr, buildTenantIndex, bearerToken, RateLimiter } from "./transports/auth.js";
 
 // ── Multi-host installer (wire the stdio server into any MCP-capable agent) ───
 export { buildServerSpec, MCP_PACKAGE, MCP_BIN, RUNTIME_PEERS } from "./install/server-spec.js";
@@ -37,3 +38,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 };
+}

package/src/transports/auth.ts

@@ -0,0 +1,78 @@
+/**
+ * transports/auth.ts — auth + rate-limiting primitives for the HTTP transport.
+ *
+ * The networked MCP surface is multi-tenant: one bearer token must map to ONE
+ * tenant's memory namespace, the comparison must not leak the secret through a
+ * timing side channel, and a noisy or hostile caller must not be able to hammer
+ * the server. These helpers provide exactly those three pieces, dependency-free
+ * (node:crypto only).
+ */
+
+import { createHash, timingSafeEqual } from "node:crypto";
+
+/** SHA-256 hex digest of a token — the stable, non-reversible lookup key. */
+export function hashToken(token: string): string {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+}
+
+/**
+ * Constant-time string equality. Hashes both sides to fixed-length digests
+ * first, so neither the comparison nor the input length leaks the secret.
+ */
+export function timingSafeEqualStr(a: string, b: string): boolean {
+    const ha = createHash("sha256").update(a, "utf8").digest();
+    const hb = createHash("sha256").update(b, "utf8").digest();
+    return timingSafeEqual(ha, hb);
+}
+
+/**
+ * Build a tenant lookup keyed by token HASH (never the raw token). Resolving a
+ * presented token is a hash + map lookup — no per-character secret comparison,
+ * so there is no early-return timing channel on the token value.
+ */
+export function buildTenantIndex<B>(tenants: Record<string, B>): Map<string, B> {
+    const index = new Map<string, B>();
+    for (const [token, backend] of Object.entries(tenants)) {
+        if (token) index.set(hashToken(token), backend);
+    }
+    return index;
+}
+
+/** Fixed-window rate limiter. Memory-bounded by pruning expired windows. */
+export class RateLimiter {
+    private readonly _hits = new Map<string, { count: number; resetAt: number }>();
+
+    constructor(
+        private readonly windowMs: number,
+        private readonly max: number,
+        private readonly now: () => number = () => Date.now(),
+    ) {}
+
+    /** Returns true when the call is allowed; false when the window is exhausted. */
+    check(key: string): boolean {
+        const t = this.now();
+        const entry = this._hits.get(key);
+        if (!entry || t >= entry.resetAt) {
+            if (this._hits.size > 10_000) this._prune(t);
+            this._hits.set(key, { count: 1, resetAt: t + this.windowMs });
+            return true;
+        }
+        if (entry.count >= this.max) return false;
+        entry.count++;
+        return true;
+    }
+
+    private _prune(t: number): void {
+        for (const [k, v] of this._hits) {
+            if (t >= v.resetAt) this._hits.delete(k);
+        }
+    }
+}
+
+/** Extract the bearer token from an Authorization header value, or undefined. */
+export function bearerToken(header: string | string[] | undefined): string | undefined {
+    const value = Array.isArray(header) ? header[0] : header;
+    if (!value) return undefined;
+    const m = /^Bearer\s+(.+)$/i.exec(value.trim());
+    return m ? m[1]!.trim() : undefined;
+}