@seanhogg/builderforce-memory-mcp 2026.7.12 → 2026.9.27

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:
@@ -36,8 +48,10 @@ export function bfmemHookSource(memoryFile: string): string {
  *                 durable correction is persisted via memory_remember.
  */
 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() {
@@ -51,6 +65,27 @@ function tokens(s) {
     return String(s || "").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3);
 }
 
+// ── Per-session injection ledger ─────────────────────────────────────────────
+// The SessionStart digest and the per-prompt recall both push memory CONTENT
+// into the context window, where it stays for the rest of the session. Without
+// dedup, a long session re-injects the same memories on every turn — unbounded
+// growth that is exactly what pushes a session past 150k tokens. The ledger
+// records which keys have already been surfaced THIS session so we inject each
+// memory at most once. Keyed by the host-provided session_id; degrades to the
+// old always-inject behaviour when no id is available.
+function ledgerFile(sid) {
+    const safe = String(sid || "").replace(/[^a-zA-Z0-9_.-]/g, "").slice(0, 80) || "nosession";
+    return path.join(os.tmpdir(), "bfmem-injected-" + safe + ".json");
+}
+function loadLedger(sid) {
+    try { const a = JSON.parse(fs.readFileSync(ledgerFile(sid), "utf8")); return new Set(Array.isArray(a) ? a : []); }
+    catch { return new Set(); }
+}
+function saveLedger(sid, set) {
+    if (!sid) return; // no id → no dedup state to persist (safe fallback)
+    try { fs.writeFileSync(ledgerFile(sid), JSON.stringify([...set].slice(-500))); } catch { /* best effort */ }
+}
+
 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.",
@@ -59,13 +94,18 @@ if (mode === "--precompact") {
 }
 
 if (mode === "--recall") {
-    let prompt = "";
-    try { const j = JSON.parse(readStdin() || "{}"); prompt = typeof j.prompt === "string" ? j.prompt : ""; } catch { /* no input */ }
+    let prompt = "", sid = "";
+    try {
+        const j = JSON.parse(readStdin() || "{}");
+        prompt = typeof j.prompt === "string" ? j.prompt : "";
+        sid = typeof j.session_id === "string" ? j.session_id : "";
+    } 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 led = loadLedger(sid);
     const scored = entries
         .map((e) => {
             const hay = new Set(tokens([e.key, e.content, (e.tags || []).join(" ")].join(" ")));
@@ -74,10 +114,13 @@ if (mode === "--recall") {
             return { e, score };
         })
         .filter((x) => x.score >= 2)
+        .filter((x) => !led.has(x.e.key)) // already surfaced this session → don't re-inject
         .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");
+    for (const x of scored) led.add(x.e.key);
+    saveLedger(sid, led);
+    const lines = scored.map((x) => "• " + x.e.key + ": " + String(x.e.content || "").slice(0, 200)).join("\\n");
     process.stdout.write(
         "[builderforce-memory] Relevant stored memories for this request — use these instead of re-deriving or re-reading:\\n" + lines,
     );
@@ -148,19 +191,37 @@ if (mode === "--capture") {
     process.exit(0);
 }
 
+// SessionStart (default mode). Read the source + session_id so we can (a) seed
+// the per-session ledger with the digest keys and (b) skip re-injecting on
+// 'resume', where the earlier context — including this digest — is retained and
+// a second copy would be pure waste.
+let src = "startup", sessionId = "";
+try {
+    const j = JSON.parse(readStdin() || "{}");
+    if (typeof j.source === "string") src = j.source;
+    if (typeof j.session_id === "string") sessionId = j.session_id;
+} catch { /* no input */ }
+
 const entries = loadEntries();
 if (entries.length === 0) {
-    process.stdout.write(
+    if (src !== "resume") 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
+const ranked = 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");
+    .slice(0, 6);
+
+// Record the digest keys so per-prompt recall won't re-surface what's already
+// on screen. Fresh window (startup/clear) → new ledger; otherwise merge.
+const led = (src === "startup" || src === "clear") ? new Set() : loadLedger(sessionId);
+for (const e of ranked) led.add(e.key);
+saveLedger(sessionId, led);
+
+if (src === "resume") process.exit(0); // context retained across resume — nothing to re-inject
+const top = ranked.map((e) => "• " + e.key + ": " + e.content.slice(0, 180)).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,
 );
@@ -213,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
@@ -251,12 +336,28 @@ export function installClaudeCombo(opts: {
         fs.copyFileSync(paths.settingsFile, `${paths.settingsFile}.bak`);
     }
     const hooks = (settings.hooks && typeof settings.hooks === "object" ? settings.hooks : {}) as Record<string, unknown>;
+    // Compare commands by a normalized form (path separators unified, whitespace
+    // collapsed, case-folded) so a re-install can't register a second copy of the
+    // same hook just because an earlier run wrote "C:/…" and this one writes
+    // "C:\…". Without this, Windows accumulates duplicate SessionStart/PreCompact
+    // hooks that each fire — doubling the memory the combo injects every session.
+    const normCmd = (c: string) => String(c ?? "").replace(/\\/g, "/").replace(/\s+/g, " ").trim().toLowerCase();
+    const hookRef = normCmd(paths.hookScript);
     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); }
+        const arr = (Array.isArray(hooks[event]) ? hooks[event] : []) as Array<{ hooks?: Array<{ type?: string; command?: string }> }>;
+        // Drop any existing group that points at OUR hook script for THIS mode
+        // (any path-separator variant), then re-add exactly one canonical entry.
+        // This both dedupes accidental duplicates and refreshes the command.
+        const kept = arr.filter((g) => !(g.hooks || []).some((h) => {
+            const n = normCmd(h.command ?? "");
+            return n.includes(hookRef) && n.endsWith(mode);
+        }));
+        const wasPresent = kept.length !== arr.length;
+        kept.push({ hooks: [{ type: "command", command }] });
+        hooks[event] = kept;
+        if (!wasPresent) added.push(event);
     }
     settings.hooks = hooks;
     const settingsDir = nodePath.dirname(paths.settingsFile);

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;