@seanhogg/builderforce-memory-mcp 2026.7.14 → 2026.9.28

package/src/compaction.ts

@@ -0,0 +1,126 @@
+/**
+ * Compaction — turning an ABSORBED memory into a terse pointer stub.
+ *
+ * Once a fact has been folded into an Evermind (or any downstream learner) the
+ * full body has done its job: keeping it verbatim in the store means every
+ * subsequent recall pays for text the model already carries in its weights.
+ * Compaction replaces the body with a one-line `[absorbed→Evermind vN] <first
+ * line>` pointer, so the fact stops filling context while it stays findable.
+ *
+ * The rules live here — not in the tool handler and not in a transport — because
+ * BOTH the in-process `memory_compact` tool and any external compactor (the
+ * BuilderForce VS Code extension rewrites the snapshot directly) must produce
+ * byte-identical stubs; otherwise re-running either one re-stubs the other's work.
+ *
+ * Dependency-free and published as its own subpath
+ * (`@seanhogg/builderforce-memory-mcp/compaction`), so an external compactor imports
+ * these rules instead of re-implementing them — the marker below is the shared
+ * idempotency contract between the two processes.
+ */
+
+/**
+ * Marker that opens every compacted stub — also the idempotency guard. An entry
+ * whose content already starts with this is skipped, so compacting twice (or
+ * from two processes) never double-stubs.
+ */
+export const STUB_PREFIX = "[absorbed→Evermind";
+
+/** Default cap on the pointer line carried inside a stub. */
+export const DEFAULT_STUB_CHARS = 140;
+
+/** True when a body is already a compaction stub. */
+export function isStub(content: string): boolean {
+    return content.trimStart().startsWith(STUB_PREFIX);
+}
+
+/** The first non-empty line of a body, trimmed to `max` chars — the stub's pointer text. */
+export function firstLine(content: string, max = DEFAULT_STUB_CHARS): string {
+    const line =
+        content
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .find((l) => l.length > 0) ?? "";
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+}
+
+/** Build the terse stub that replaces an absorbed entry's body. */
+export function memoryStub(content: string, version: number, maxChars = DEFAULT_STUB_CHARS): string {
+    return `${STUB_PREFIX} v${version}] ${firstLine(content, maxChars)}`;
+}
+
+/** One entry considered for compaction. */
+export interface CompactionCandidate {
+    key: string;
+    content: string;
+}
+
+/** A body rewrite the caller should apply. */
+export interface CompactionWrite {
+    key: string;
+    /** The stub that replaces the entry's body. */
+    content: string;
+    /** Characters recovered by this rewrite. */
+    bytesSaved: number;
+}
+
+/** Why a candidate was left alone. */
+export interface CompactionSkip {
+    key: string;
+    reason: "not_found" | "already_compacted" | "not_smaller";
+}
+
+/** The decided plan: what to write, what to leave, and the total recovered. */
+export interface CompactionPlan {
+    writes: CompactionWrite[];
+    skipped: CompactionSkip[];
+    bytesSaved: number;
+}
+
+/** Options controlling how a stub body is produced. */
+export interface CompactionOptions {
+    /** Explicit replacement body. Omit to generate a pointer from each entry's own first line. */
+    stub?: string;
+    /** Evermind version that absorbed the facts; appears in a generated stub. Default 0. */
+    version?: number;
+    /** Max characters of a generated pointer line. Default {@link DEFAULT_STUB_CHARS}. */
+    maxChars?: number;
+}
+
+/**
+ * Decide the compaction for a set of candidates. Pure — no I/O — so the same
+ * rules are unit-testable and reusable by any caller that can read and write
+ * memories. `undefined` content means the key was not found.
+ */
+export function planCompaction(
+    candidates: Array<CompactionCandidate | { key: string; content: undefined }>,
+    opts: CompactionOptions = {},
+): CompactionPlan {
+    const version = opts.version ?? 0;
+    const maxChars = Math.max(20, opts.maxChars ?? DEFAULT_STUB_CHARS);
+    const writes: CompactionWrite[] = [];
+    const skipped: CompactionSkip[] = [];
+    let bytesSaved = 0;
+
+    for (const c of candidates) {
+        const content = c.content;
+        if (typeof content !== "string" || !content.trim()) {
+            skipped.push({ key: c.key, reason: "not_found" });
+            continue;
+        }
+        if (isStub(content)) {
+            skipped.push({ key: c.key, reason: "already_compacted" });
+            continue;
+        }
+        const stub = opts.stub ?? memoryStub(content, version, maxChars);
+        // Never grow an entry — a "compaction" that costs tokens is a regression.
+        if (stub.length >= content.length) {
+            skipped.push({ key: c.key, reason: "not_smaller" });
+            continue;
+        }
+        const saved = content.length - stub.length;
+        writes.push({ key: c.key, content: stub, bytesSaved: saved });
+        bytesSaved += saved;
+    }
+
+    return { writes, skipped, bytesSaved };
+}

package/src/embedding/evermind-embedder.ts

@@ -0,0 +1,276 @@
+/**
+ * evermind-embedder — SSM-embedding recall for a HEADLESS host, with no GPU.
+ *
+ * The stdio/HTTP servers used to rank recall by word overlap because standing up
+ * the embedding model was assumed to mean standing up WebGPU. It does not:
+ * `EvermindLM` is a pure-CPU model and `EvermindLM.embed()` mean-pools + L2-
+ * normalises the same hidden state the GPU `HybridMambaModel.embed()` does, to the
+ * same contract. So a headless Node process can embed — it just needs the
+ * checkpoint and the tokenizer that produced its token ids.
+ *
+ * This module is the loader for that pair, plus the ONE thing a per-session
+ * subprocess needs to make embedding affordable: a vector cache that OUTLIVES the
+ * process. Recall embeds the query plus every stored memory; recomputing 200
+ * memory embeddings on the first recall of every session would cost more than the
+ * lexical ranking it replaces. The cache is stamped with the model's fingerprint,
+ * so an adapted checkpoint invalidates it wholesale rather than silently mixing
+ * vectors from two different models.
+ *
+ * It mirrors how this package already persists memories: a JSON file alongside the
+ * memory snapshot, written by the process that owns it, tolerant of a corrupt or
+ * absent file (drop it and recompute — a cache is never the source of truth).
+ */
+
+/** The seam `MemoryStore.recallRanked(query, k, runtime)` consumes. */
+export interface TextEmbedderLike {
+    embed(text: string): Promise<Float32Array>;
+    /** Vector width. */
+    readonly dimensions: number;
+    /** Model identity — vectors are only comparable within one fingerprint. */
+    readonly fingerprint: string;
+}
+
+/** A text embedder that also owns a persistent cache. */
+export interface PersistentTextEmbedder extends TextEmbedderLike {
+    /** Write any pending vectors to disk now. Safe to call repeatedly. */
+    flush(): void;
+}
+
+export interface EvermindEmbedderOptions {
+    /**
+     * Absolute path to a `.evermind` package holding an `evermind-lm` checkpoint.
+     * This is the model whose hidden state becomes the embedding.
+     */
+    modelFile: string;
+    /**
+     * Absolute path to the tokenizer JSON that produced the checkpoint's token ids
+     * (`BPETokenizer.toObject()`, or a Hugging Face `tokenizer.json`).
+     *
+     * Only needed for a package that does NOT embed its own tokenizer. Token ids are
+     * meaningless without the exact vocabulary behind them, so an `.evermind` built
+     * with `PackageMeta.tokenizer` carries one and is self-contained — that is
+     * preferred over any file, because a file can be the WRONG vocabulary while the
+     * embedded one is checksummed and vocab-size-checked against the checkpoint.
+     * Resolution order: the package's own tokenizer, then this path, then a sibling
+     * `<modelFile>.tokenizer.json`.
+     */
+    tokenizerFile?: string;
+    /**
+     * Absolute path for the persistent vector cache. Omit to disable persistence
+     * (vectors are still cached in memory for the life of the process).
+     */
+    cacheFile?: string;
+    /** Max vectors retained in the cache (LRU past this). Default 4000. */
+    maxEntries?: number;
+    /** Debounce before a dirty cache is written back, ms. Default 500. */
+    flushDelayMs?: number;
+}
+
+/** Minimal structural view of the optional engine package. */
+interface EmbedEngine {
+    EvermindModelPackage: {
+        fromBlob(blob: ArrayBuffer): {
+            manifest: { modelType?: string; tokenizerFormat?: string };
+            loadLM(): unknown;
+            /** Present on engines that support the embedded-tokenizer section. */
+            loadTokenizer?(): { encode(t: string): number[] } | null;
+        };
+    };
+    BPETokenizer: {
+        new (): { loadFromSpec(spec: unknown): void; loadHuggingFace(spec: unknown): void; encode(t: string): number[] };
+    };
+    EvermindTextEmbedder: new (model: unknown, codec: unknown) => TextEmbedderLike;
+}
+
+type FsLike = {
+    readFileSync(path: string, enc: "utf8"): string;
+    readFileSync(path: string): Uint8Array;
+    writeFileSync(path: string, data: string): void;
+    existsSync(path: string): boolean;
+};
+
+const DEFAULT_MAX_ENTRIES = 4000;
+const DEFAULT_FLUSH_DELAY_MS = 500;
+
+/** The on-disk cache shape: a fingerprint stamp plus text→vector rows. */
+interface VectorCacheFile {
+    fingerprint: string;
+    dimensions: number;
+    /** [text, vector] pairs, least-recently-used first (insertion order is the LRU). */
+    vectors: Array<[string, number[]]>;
+}
+
+/** Indirect import so the optional engine peer is never statically resolved. */
+function dynamicImport(m: string): Promise<unknown> {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+    return new Function("m", "return import(m)")(m) as Promise<unknown>;
+}
+
+/**
+ * Load the tokenizer spec from `file`, accepting either `BPETokenizer.toObject()`
+ * output or a Hugging Face `tokenizer.json`.
+ */
+function loadCodec(engine: EmbedEngine, fs: FsLike, file: string): { encode(t: string): number[] } {
+    const spec = JSON.parse(fs.readFileSync(file, "utf8")) as { vocab?: unknown; merges?: unknown; model?: unknown };
+    const tok = new engine.BPETokenizer();
+    if (spec.vocab && spec.merges) tok.loadFromSpec(spec);
+    else tok.loadHuggingFace(spec);
+    return tok;
+}
+
+/**
+ * Build a CPU text embedder from a `.evermind` package + its tokenizer, wrapped in
+ * a persistent vector cache.
+ *
+ * Returns `null` — never throws — when the engine peer is absent, a file is
+ * missing, or the package is not an `evermind-lm`. Recall then stays on the
+ * lexical ranking and says so, which is the correct degrade: a memory server that
+ * refuses to start because an OPTIONAL model is unavailable is worse than one that
+ * ranks by word overlap.
+ */
+export async function createEvermindEmbedder(
+    opts: EvermindEmbedderOptions,
+): Promise<PersistentTextEmbedder | null> {
+    try {
+        const engine = (await dynamicImport("@seanhogg/builderforce-memory-engine")) as Partial<EmbedEngine>;
+        if (!engine?.EvermindModelPackage || !engine.BPETokenizer || !engine.EvermindTextEmbedder) return null;
+
+        const fs = (await dynamicImport("node:fs")) as FsLike;
+        if (!fs.existsSync(opts.modelFile)) return null;
+
+        const bytes = fs.readFileSync(opts.modelFile);
+        const blob = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+        const pkg = (engine as EmbedEngine).EvermindModelPackage.fromBlob(blob);
+        if (pkg.manifest.modelType !== "evermind-lm") return null;
+
+        // Prefer the package's OWN tokenizer. It is checksummed and cross-checked
+        // against the checkpoint's vocab size at package time, so it cannot be the
+        // wrong vocabulary — which a separate file silently can be. Falling back to a
+        // file keeps every package written before the section existed working.
+        const embedded = pkg.loadTokenizer?.() ?? null;
+        let codec: { encode(t: string): number[] };
+        if (embedded) {
+            codec = embedded;
+        } else {
+            const tokenizerFile = opts.tokenizerFile ?? `${opts.modelFile}.tokenizer.json`;
+            if (!fs.existsSync(tokenizerFile)) return null;
+            codec = loadCodec(engine as EmbedEngine, fs, tokenizerFile);
+        }
+        const inner = new (engine as EmbedEngine).EvermindTextEmbedder(pkg.loadLM(), codec);
+        return new CachedTextEmbedder(inner, fs, opts);
+    } catch {
+        // Any failure to stand the model up is a degrade, not a fault.
+        return null;
+    }
+}
+
+/**
+ * Wraps a text embedder with an LRU vector cache mirrored to a JSON file.
+ *
+ * Exported for hosts that already hold an embedder (a GPU runtime, say) and want
+ * the same cross-process cache — there is one implementation of "cache these
+ * vectors on disk", not one per embedder.
+ */
+export class CachedTextEmbedder implements PersistentTextEmbedder {
+    readonly dimensions: number;
+    readonly fingerprint: string;
+
+    /** text → vector. Map insertion order is the LRU order. */
+    private readonly cache = new Map<string, Float32Array>();
+    private readonly file: string | undefined;
+    private readonly maxEntries: number;
+    private readonly flushDelayMs: number;
+    private dirty = false;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+
+    constructor(
+        private readonly inner: TextEmbedderLike,
+        private readonly fs: FsLike,
+        opts: Pick<EvermindEmbedderOptions, "cacheFile" | "maxEntries" | "flushDelayMs">,
+    ) {
+        this.dimensions = inner.dimensions;
+        this.fingerprint = inner.fingerprint;
+        this.file = opts.cacheFile;
+        this.maxEntries = Math.max(1, opts.maxEntries ?? DEFAULT_MAX_ENTRIES);
+        this.flushDelayMs = Math.max(0, opts.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS);
+        this.hydrate();
+    }
+
+    async embed(text: string): Promise<Float32Array> {
+        const hit = this.cache.get(text);
+        if (hit) {
+            // LRU touch — re-insert so this entry becomes most-recently-used.
+            this.cache.delete(text);
+            this.cache.set(text, hit);
+            return hit;
+        }
+        const vec = await this.inner.embed(text);
+        this.put(text, vec);
+        return vec;
+    }
+
+    /** Write pending vectors now, cancelling any scheduled write. */
+    flush(): void {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (!this.dirty || !this.file) return;
+        const payload: VectorCacheFile = {
+            fingerprint: this.fingerprint,
+            dimensions: this.dimensions,
+            vectors: [...this.cache.entries()].map(([text, v]) => [text, Array.from(v)]),
+        };
+        try {
+            this.fs.writeFileSync(this.file, JSON.stringify(payload));
+            this.dirty = false;
+        } catch {
+            // A cache that cannot be written is still a working in-memory cache.
+        }
+    }
+
+    private put(text: string, vec: Float32Array): void {
+        if (this.cache.size >= this.maxEntries) {
+            const lru = this.cache.keys().next().value;
+            if (lru !== undefined) this.cache.delete(lru);
+        }
+        this.cache.set(text, vec);
+        this.dirty = true;
+        this.schedule();
+    }
+
+    /**
+     * Debounce the write-back: one recall embeds the query plus every new memory,
+     * and that burst should cost ONE file write, not one per vector.
+     */
+    private schedule(): void {
+        if (!this.file || this.timer) return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.flush();
+        }, this.flushDelayMs);
+        // Never hold the process open for a cache write.
+        (this.timer as unknown as { unref?: () => void }).unref?.();
+    }
+
+    /**
+     * Read the cache back. A cache stamped with a DIFFERENT fingerprint is from a
+     * different (or adapted) model, so its vectors are not comparable with this
+     * model's — it is dropped whole rather than mixed in.
+     */
+    private hydrate(): void {
+        if (!this.file || !this.fs.existsSync(this.file)) return;
+        let parsed: VectorCacheFile;
+        try {
+            parsed = JSON.parse(this.fs.readFileSync(this.file, "utf8")) as VectorCacheFile;
+        } catch {
+            return;
+        }
+        if (!parsed || parsed.fingerprint !== this.fingerprint || !Array.isArray(parsed.vectors)) return;
+        for (const row of parsed.vectors) {
+            if (!Array.isArray(row) || typeof row[0] !== "string" || !Array.isArray(row[1])) continue;
+            if (row[1].length !== this.dimensions) continue;
+            this.cache.set(row[0], Float32Array.from(row[1]));
+        }
+    }
+}

package/src/embedding/index.ts

@@ -0,0 +1,54 @@
+/**
+ * embedding — stand up the recall embedder for a headless server.
+ *
+ * Both out-of-process bins (stdio and HTTP) need the SAME decision: is an
+ * embedding model configured, and if so where do its vectors get cached? That
+ * decision lives here once, so the two servers cannot drift into ranking recall
+ * differently from one another.
+ */
+
+import { createEvermindEmbedder, type PersistentTextEmbedder } from "./evermind-embedder.js";
+
+export { createEvermindEmbedder, CachedTextEmbedder } from "./evermind-embedder.js";
+export type { EvermindEmbedderOptions, PersistentTextEmbedder, TextEmbedderLike } from "./evermind-embedder.js";
+
+/** Absolute path to a `.evermind` package (an `evermind-lm`) to embed recall with. */
+export const MODEL_FILE_ENV = "BUILDERFORCE_MEMORY_MODEL";
+/** Absolute path to the tokenizer JSON matching that checkpoint. */
+export const TOKENIZER_FILE_ENV = "BUILDERFORCE_MEMORY_TOKENIZER";
+/** Absolute path for the persistent vector cache; defaults beside the snapshot. */
+export const VECTOR_CACHE_ENV = "BUILDERFORCE_MEMORY_VECTORS";
+
+/**
+ * Where vectors are cached by default: beside the memory snapshot, under the same
+ * name. They belong together — the cache is only meaningful for the memories in
+ * that snapshot, and pointing a second store at the same vectors would be a cache
+ * for the wrong corpus.
+ */
+export function defaultVectorCacheFile(memoryFile: string): string {
+    return memoryFile.replace(/\.json$/i, "") + ".vectors.json";
+}
+
+export interface RecallEmbedderEnv {
+    env?: Record<string, string | undefined>;
+    /** The snapshot path in effect — used to site the default vector cache. */
+    memoryFile: string;
+}
+
+/**
+ * The embedder this server should rank recall with, or `null` when none is
+ * configured (recall then ranks lexically and says so).
+ *
+ * Opt-in by design: no model path, no model. A memory server must start and serve
+ * recall on a host that has never downloaded a checkpoint.
+ */
+export async function createRecallEmbedder(opts: RecallEmbedderEnv): Promise<PersistentTextEmbedder | null> {
+    const env = opts.env ?? process.env;
+    const modelFile = env[MODEL_FILE_ENV];
+    if (!modelFile) return null;
+    return createEvermindEmbedder({
+        modelFile,
+        tokenizerFile: env[TOKENIZER_FILE_ENV],
+        cacheFile: env[VECTOR_CACHE_ENV] || defaultVectorCacheFile(opts.memoryFile),
+    });
+}

package/src/index.ts

@@ -8,7 +8,14 @@
  */
 
 // ── Seam ────────────────────────────────────────────────────────────────────
-export type { MemoryBackend, RecallHit, RememberInput } from "./backend.js";
+export type { MemoryBackend, RankedRecall, RecallHit, RecallMethod, RememberInput } from "./backend.js";
+
+// -- CPU SSM-embedding recall (no GPU) --------------------------------------
+// The headless servers rank recall by EvermindLM embedding cosine fused with the
+// lexical ranking whenever a checkpoint is configured; exported so an embedding
+// host can build the same embedder (and share its persistent vector cache).
+export { createRecallEmbedder, createEvermindEmbedder, CachedTextEmbedder, defaultVectorCacheFile, MODEL_FILE_ENV, TOKENIZER_FILE_ENV, VECTOR_CACHE_ENV } from "./embedding/index.js";
+export type { EvermindEmbedderOptions, PersistentTextEmbedder, TextEmbedderLike, RecallEmbedderEnv } from "./embedding/index.js";
 
 // ── Local backend (IndexedDB via @seanhogg/builderforce-memory) ────────────────────────
 export { MemoryStoreBackend, createLocalMemoryStoreBackend } from "./backends/memory-store.js";
@@ -18,6 +25,13 @@ export type { LocalBackendOptions } from "./backends/memory-store.js";
 export { buildMemoryTools } from "./tools.js";
 export type { MemoryTool, MemoryToolsOptions, ToolResult } from "./tools.js";
 
+// ── Compaction (absorbed fact → one-line pointer stub) ───────────────────────
+// Exported so an EXTERNAL compactor (the BuilderForce VS Code extension rewrites
+// the snapshot file directly) can produce byte-identical stubs, keeping the two
+// paths idempotent with respect to each other.
+export { STUB_PREFIX, DEFAULT_STUB_CHARS, isStub, firstLine, memoryStub, planCompaction } from "./compaction.js";
+export type { CompactionCandidate, CompactionWrite, CompactionSkip, CompactionPlan, CompactionOptions } from "./compaction.js";
+
 // ── Transports ──────────────────────────────────────────────────────────────
 export { createMemoryMcpServer } from "./transports/sdk.js";
 export type { SdkServerOptions, SdkMcpServerConfig } from "./transports/sdk.js";
@@ -32,7 +46,7 @@ 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";
+export { buildServerSpec, defaultMemoryFile, resolveMemoryFile, MCP_PACKAGE, MCP_BIN, MEMORY_FILE_ENV, RUNTIME_PEERS } from "./install/server-spec.js";
 export type { StdioServerSpec, ServerSpecOptions } from "./install/server-spec.js";
 export { installMemoryServer } from "./install/install.js";
 export type { InstallOptions, InstallResult, InstallStatus, HostSelector, FsLike } from "./install/install.js";
@@ -40,5 +54,5 @@ 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";
+export { installClaudeCombo, bfmemHookSource, companionSkillMd, claudeComboPaths, pluginHooksConfig, HOOK_EVENTS } from "./install/claude-hooks.js";
+export type { ClaudeComboPaths, HookConfig } from "./install/claude-hooks.js";

package/src/install/claude-hooks.ts

@@ -22,9 +22,21 @@
 
 import nodePath from "node:path";
 import type { FsLike } from "./install.js";
+import { MEMORY_FILE_ENV } from "./server-spec.js";
 
-/** The single hook script, four modes. `memoryFile` is the JSON snapshot path. */
-export function bfmemHookSource(memoryFile: string): string {
+/**
+ * The single hook script, four modes.
+ *
+ * `memoryFile` is the JSON snapshot path to bake in. Pass `null` to emit a
+ * script that resolves the path at RUN time instead — required for the Claude
+ * Code plugin, whose files are static and machine-independent. The runtime
+ * branch must stay in lockstep with `resolveMemoryFile`; `install.test.mjs`
+ * asserts it does.
+ */
+export function bfmemHookSource(memoryFile: string | null): string {
+    const fileExpr = memoryFile === null
+        ? `process.env[${JSON.stringify(MEMORY_FILE_ENV)}] || path.join(os.homedir(), ".builderforce-memory", "memory.json")`
+        : JSON.stringify(memoryFile);
     return `#!/usr/bin/env node
 /**
  * builderforce-memory hook — generated by builderforce-memory-install. Dependency-free:
@@ -39,7 +51,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-const FILE = ${JSON.stringify(memoryFile)};
+const FILE = ${fileExpr};
 const mode = process.argv[2] || "--session";
 
 function readStdin() {
@@ -262,13 +274,37 @@ export function claudeComboPaths(claudeDir: string): ClaudeComboPaths {
     };
 }
 
-const HOOK_EVENTS = [
+/**
+ * The four events that make memory self-driving, and the hook-script mode each
+ * one runs. Single source of truth for BOTH delivery shapes: the settings.json
+ * merge performed by {@link installClaudeCombo}, and the static `hooks.json` a
+ * Claude Code plugin ships ({@link pluginHooksConfig}).
+ */
+export const HOOK_EVENTS = [
     { event: "SessionStart", mode: "--session" },
     { event: "PreCompact", mode: "--precompact" },
     { event: "UserPromptSubmit", mode: "--recall" },
     { event: "Stop", mode: "--capture" },
 ] as const;
 
+/** Hook-config shape shared by `settings.json` and a plugin's `hooks/hooks.json`. */
+export type HookConfig = Record<string, Array<{ hooks: Array<{ type: "command"; command: string }> }>>;
+
+/**
+ * The plugin form of the combo: every event pointed at the plugin-local hook
+ * script. `${CLAUDE_PLUGIN_ROOT}` is expanded by Claude Code to the installed
+ * plugin directory, so the script needs no install step and no baked-in paths.
+ */
+export function pluginHooksConfig(scriptRelPath = "hooks/bfmem-hook.mjs"): HookConfig {
+    const config: HookConfig = {};
+    for (const { event, mode } of HOOK_EVENTS) {
+        config[event] = [{
+            hooks: [{ type: "command", command: `node "\${CLAUDE_PLUGIN_ROOT}/${scriptRelPath}" ${mode}` }],
+        }];
+    }
+    return config;
+}
+
 /**
  * Write the hook script + companion skill and register all four hooks in
  * settings.json. Idempotent (skips a hook command already present) and

package/src/install/server-spec.ts

@@ -7,12 +7,37 @@
  * server is launched, so the per-host adapters never re-derive the command.
  */
 
+import nodeOs from "node:os";
+import nodePath from "node:path";
+
 export interface StdioServerSpec {
     command: string;
     args: string[];
     env?: Record<string, string>;
 }
 
+/**
+ * The default JSON snapshot path: ONE store per machine, so every MCP host
+ * (Claude Code, Cursor, Claude Desktop, …) shares the same memory.
+ *
+ * Single source of truth for the installer, the stdio bin's fallback, and the
+ * Claude Code plugin's hook script — a memory file the writer and the reader
+ * disagree about is memory that silently disappears.
+ */
+export const MEMORY_FILE_ENV = "BUILDERFORCE_MEMORY_FILE";
+
+export function defaultMemoryFile(homedir: string = nodeOs.homedir()): string {
+    return nodePath.join(homedir, ".builderforce-memory", "memory.json");
+}
+
+/** The snapshot path in effect: explicit env wins, else the shared default. */
+export function resolveMemoryFile(
+    env: Record<string, string | undefined> = process.env,
+    homedir?: string,
+): string {
+    return env[MEMORY_FILE_ENV] || defaultMemoryFile(homedir);
+}
+
 export interface ServerSpecOptions {
     /** Absolute path to the JSON snapshot that makes memory survive restarts. */
     memoryFile?: string;