@seanhogg/builderforce-memory-mcp 2026.10.2 → 2026.10.22

package/src/index.ts

@@ -18,8 +18,12 @@ export { createRecallEmbedder, createEvermindEmbedder, CachedTextEmbedder, defau
 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";
-export type { LocalBackendOptions } from "./backends/memory-store.js";
+export { MemoryStoreBackend, createLocalMemoryStoreBackend, DEFAULT_RECALL_RANKING } from "./backends/memory-store.js";
+export type { LocalBackendOptions, MemoryStoreBackendOptions, RecallRanking } from "./backends/memory-store.js";
+export { FileFactArchive, MemoryFactArchive } from "./persistence/fact-archive.js";
+export type { FactArchive } from "./persistence/fact-archive.js";
+export { SharedJsonFile, DEFAULT_BACKUPS, backupFile } from "./persistence/shared-json-file.js";
+export type { SharedJsonFileOptions } from "./persistence/shared-json-file.js";
 
 // ── Tool core ─────────────────────────────────────────────────────────────────
 export { buildMemoryTools } from "./tools.js";
@@ -32,12 +36,42 @@ export { createExperienceHost, EXPERIENCE_ENV } from "./experience/host.js";
 export type { ExperienceHost, ExperienceHostOptions, ExperienceEngine } from "./experience/host.js";
 export { nextExperienceVersion } from "./experience/train.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";
+// ── Compaction (absorbed fact → one-line pointer stub, LOSSLESS) ─────────────
+// Exported so an EXTERNAL compactor (the BuilderForce VS Code extension) produces
+// byte-identical stubs AND follows the same archive + recall-probe rules, keeping
+// the two paths idempotent with respect to each other.
+export {
+    STUB_PREFIX,
+    DEFAULT_STUB_CHARS,
+    CONTENT_LOST_LABEL,
+    isStub,
+    isContentLost,
+    firstLine,
+    memoryStub,
+    stubPointer,
+    planCompaction,
+    planLosslessCompaction,
+    probeQuestionFor,
+    probePasses,
+    defaultArchiveFile,
+    parseArchive,
+    mergeArchive,
+} from "./compaction.js";
+export type {
+    ArchivedFact,
+    ArchiveSnapshot,
+    CompactionCandidate,
+    CompactionWrite,
+    CompactionSkip,
+    CompactionPlan,
+    CompactionOptions,
+    LosslessCompactionOptions,
+    ProbeQuestion,
+    RecallProbe,
+} from "./compaction.js";
+export { createRecallProbe, lazyRecallProbe, generatorProbe, PROBE_MAX_NEW_TOKENS } from "./model/recall-probe.js";
+export { parseRestoreSource, planRestore, restoredArchive, stubVersion, MIN_POINTER_CHARS } from "./restore.js";
+export type { RestoreRecord, RestoreTarget, RestoreMatch, RestorePlan } from "./restore.js";
 
 // ── Transports ──────────────────────────────────────────────────────────────
 export { createMemoryMcpServer } from "./transports/sdk.js";
@@ -53,8 +87,19 @@ 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, 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 {
+    buildServerSpec,
+    defaultMemoryFile,
+    memoryFileCandidates,
+    resolveMemoryFile,
+    CANONICAL_MEMORY_SEGMENTS,
+    LEGACY_MEMORY_SEGMENTS,
+    MCP_PACKAGE,
+    MCP_BIN,
+    MEMORY_FILE_ENV,
+    RUNTIME_PEERS,
+} from "./install/server-spec.js";
+export type { StdioServerSpec, ServerSpecOptions, MemoryFileProbe, ResolveMemoryFileOptions } from "./install/server-spec.js";
 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";

package/src/install/claude-hooks.ts

@@ -21,8 +21,33 @@
  */
 
 import nodePath from "node:path";
+import { CONTENT_LOST_LABEL, STUB_PREFIX } from "../compaction.js";
 import type { FsLike } from "./install.js";
-import { MEMORY_FILE_ENV } from "./server-spec.js";
+import { CANONICAL_MEMORY_SEGMENTS, LEGACY_MEMORY_SEGMENTS, MEMORY_FILE_ENV } from "./server-spec.js";
+
+/** `path.join(os.homedir(), "<seg>", …)` as hook-script source. */
+const homeJoin = (segments: readonly string[]) =>
+    `path.join(os.homedir(), ${segments.map((s) => JSON.stringify(s)).join(", ")})`;
+
+/**
+ * The run-time twin of `resolveMemoryFile`, as hook-script source: the env
+ * override, else whichever candidate holds a memory.json (the most recently
+ * written when both do), else the canonical default. Built from the SAME segment
+ * constants, so the two cannot name different files.
+ */
+function runtimeMemoryFileExpr(): string {
+    return `(() => {
+    const explicit = process.env[${JSON.stringify(MEMORY_FILE_ENV)}];
+    if (explicit) return explicit;
+    const candidates = [${homeJoin(CANONICAL_MEMORY_SEGMENTS)}, ${homeJoin(LEGACY_MEMORY_SEGMENTS)}];
+    let best = null, bestMtime = -Infinity;
+    for (const c of candidates) {
+        try { const st = fs.statSync(c); if (st.isFile() && st.mtimeMs > bestMtime) { best = c; bestMtime = st.mtimeMs; } }
+        catch { /* absent */ }
+    }
+    return best || candidates[0];
+})()`;
+}
 
 /**
  * The single hook script, four modes.
@@ -32,11 +57,14 @@ import { MEMORY_FILE_ENV } from "./server-spec.js";
  * Code plugin, whose files are static and machine-independent. The runtime
  * branch must stay in lockstep with `resolveMemoryFile`; `install.test.mjs`
  * asserts it does.
+ *
+ * Compaction stubs whose original was never archived (`contentLost`) are still
+ * injected — the pointer is a real lead — but labelled
+ * {@link CONTENT_LOST_LABEL} and importance-demoted, so they rank below intact
+ * memories and are never presented as verified fact.
  */
 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);
+    const fileExpr = memoryFile === null ? runtimeMemoryFileExpr() : JSON.stringify(memoryFile);
     return `#!/usr/bin/env node
 /**
  * builderforce-memory hook — generated by builderforce-memory-install. Dependency-free:
@@ -61,6 +89,29 @@ function loadEntries() {
     try { const p = JSON.parse(fs.readFileSync(FILE, "utf8")); return Array.isArray(p) ? p : []; }
     catch { return []; }
 }
+
+// ── Compaction stubs ─────────────────────────────────────────────────────────
+// A compacted memory's full original lives in the archive beside the snapshot
+// (memory.json → memory.archive.json). A stub with NO archived original is lost
+// content: still injected (the pointer is a real lead) but labelled and demoted.
+const ARCHIVE = FILE.replace(/\\.json$/i, "") + ".archive.json";
+const STUB_PREFIX = ${JSON.stringify(STUB_PREFIX)};
+const LOST_LABEL = ${JSON.stringify(CONTENT_LOST_LABEL)};
+const LOST_DEMOTION = 0.5;
+let archivedKeys = null;
+function archived() {
+    if (archivedKeys) return archivedKeys;
+    try { const a = JSON.parse(fs.readFileSync(ARCHIVE, "utf8")); archivedKeys = new Set(Object.keys((a && a.facts) || {})); }
+    catch { archivedKeys = new Set(); }
+    return archivedKeys;
+}
+function isLost(e) {
+    // The archive decides (a snapshot's contentLost flag can trail a restore).
+    return String(e.content || "").trimStart().startsWith(STUB_PREFIX) && !archived().has(e.key);
+}
+function render(e, max) {
+    return "• " + e.key + ": " + String(e.content || "").slice(0, max) + (isLost(e) ? " " + LOST_LABEL : "");
+}
 function tokens(s) {
     return String(s || "").toLowerCase().split(/[^a-z0-9]+/).filter((t) => t.length >= 3);
 }
@@ -111,16 +162,17 @@ if (mode === "--recall") {
             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 };
+            // Lost content still qualifies on overlap, but ranks below intact memories.
+            return { e, score, rank: isLost(e) ? score * LOST_DEMOTION : 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)
+        .sort((a, b) => b.rank - a.rank)
         .slice(0, 3);
     if (scored.length === 0) process.exit(0);
     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");
+    const lines = scored.map((x) => render(x.e, 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,
     );
@@ -210,7 +262,11 @@ if (entries.length === 0) {
     process.exit(0);
 }
 const ranked = entries
-    .map((e) => ({ key: e.key, content: String(e.content ?? ""), importance: typeof e.importance === "number" ? e.importance : 0.5 }))
+    .map((e) => {
+        const importance = typeof e.importance === "number" ? e.importance : 0.5;
+        // Lost content is importance-demoted so intact memories lead the digest.
+        return { key: e.key, content: String(e.content ?? ""), importance: isLost(e) ? importance * LOST_DEMOTION : importance };
+    })
     .sort((a, b) => b.importance - a.importance)
     .slice(0, 6);
 
@@ -221,7 +277,7 @@ 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");
+const top = ranked.map((e) => render(e, 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,
 );
@@ -249,6 +305,13 @@ capture that won't let a durable correction go unrecorded.
 - \`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.
+- \`memory_compact(keys)\` — stub facts the local Evermind has absorbed (proven by a
+  recall probe; the original is archived, so recall still returns it).
+- \`memory_restore(file|json)\` — bring back the text of memories marked
+  "${CONTENT_LOST_LABEL}" from an export.
+
+A memory labelled "${CONTENT_LOST_LABEL}" is a one-line pointer whose full
+text is gone: treat it as a lead, verify it before acting on it.
 
 ## Discipline
 Reuse a stable key to REPLACE a fact (write-through), don't append duplicates.

package/src/install/server-spec.ts

@@ -7,6 +7,7 @@
  * server is launched, so the per-host adapters never re-derive the command.
  */
 
+import nodeFs from "node:fs";
 import nodeOs from "node:os";
 import nodePath from "node:path";
 
@@ -17,25 +18,90 @@ export interface StdioServerSpec {
 }
 
 /**
- * The default JSON snapshot path: ONE store per machine, so every MCP host
- * (Claude Code, Cursor, Claude Desktop, …) shares the same memory.
+ * The snapshot path override every reader and writer honours first.
  *
- * 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.
+ * ONE resolver ({@link resolveMemoryFile}) serves the installer, both server bins
+ * and the Claude Code hook script (which inlines the same rules — see
+ * `bfmemHookSource`) — a memory file the writer and the reader disagree about is
+ * memory that silently disappears.
  */
 export const MEMORY_FILE_ENV = "BUILDERFORCE_MEMORY_FILE";
 
+/** The canonical per-machine store, relative to the home directory. */
+export const CANONICAL_MEMORY_SEGMENTS = [".builderforce-memory", "memory.json"] as const;
+
+/**
+ * Where earlier installers put the store (`~/.claude/builderforce-memory/memory.json`).
+ * Still honoured: a machine whose live memory sits here keeps using it.
+ */
+export const LEGACY_MEMORY_SEGMENTS = [".claude", "builderforce-memory", "memory.json"] as const;
+
+/** The default JSON snapshot path: ONE store per machine, shared by every MCP host. */
 export function defaultMemoryFile(homedir: string = nodeOs.homedir()): string {
-    return nodePath.join(homedir, ".builderforce-memory", "memory.json");
+    return nodePath.join(homedir, ...CANONICAL_MEMORY_SEGMENTS);
+}
+
+/** Every location a store may live in, canonical first. */
+export function memoryFileCandidates(homedir: string = nodeOs.homedir()): string[] {
+    return [defaultMemoryFile(homedir), nodePath.join(homedir, ...LEGACY_MEMORY_SEGMENTS)];
+}
+
+/** File probe the resolver uses — injectable for tests. */
+export interface MemoryFileProbe {
+    /** Unix-ms modification time of `path` when it is a file, else null. */
+    fileMtime(path: string): number | null;
+}
+
+const nodeProbe: MemoryFileProbe = {
+    fileMtime(path) {
+        try {
+            const st = nodeFs.statSync(path);
+            return st.isFile() ? st.mtimeMs : null;
+        } catch {
+            return null;
+        }
+    },
+};
+
+export interface ResolveMemoryFileOptions {
+    probe?: MemoryFileProbe;
+    /** Told which store won when more than one location is in play. Default: silent. */
+    log?: (line: string) => void;
 }
 
-/** The snapshot path in effect: explicit env wins, else the shared default. */
+/**
+ * The snapshot path in effect:
+ *   1. `BUILDERFORCE_MEMORY_FILE`, when set;
+ *   2. else whichever candidate location actually holds a `memory.json` — the
+ *      most recently written one if both do (logged; neither is ever deleted);
+ *   3. else the canonical default.
+ */
 export function resolveMemoryFile(
     env: Record<string, string | undefined> = process.env,
     homedir?: string,
+    opts: ResolveMemoryFileOptions = {},
 ): string {
-    return env[MEMORY_FILE_ENV] || defaultMemoryFile(homedir);
+    const explicit = env[MEMORY_FILE_ENV];
+    if (explicit) return explicit;
+    const probe = opts.probe ?? nodeProbe;
+    const candidates = memoryFileCandidates(homedir);
+    const present = candidates
+        .map((path) => ({ path, mtime: probe.fileMtime(path) }))
+        .filter((c): c is { path: string; mtime: number } => c.mtime !== null);
+    if (present.length === 0) return candidates[0]!;
+    if (present.length === 1) {
+        if (present[0]!.path !== candidates[0]) {
+            opts.log?.(`[builderforce-memory] using the store at ${present[0]!.path} (no memory.json at ${candidates[0]}).`);
+        }
+        return present[0]!.path;
+    }
+    const winner = present.reduce((a, b) => (b.mtime > a.mtime ? b : a));
+    const others = present.filter((c) => c !== winner).map((c) => c.path);
+    opts.log?.(
+        `[builderforce-memory] memory.json exists in ${present.length} locations; using ${winner.path} ` +
+            `(most recently written). Left untouched: ${others.join(", ")}.`,
+    );
+    return winner.path;
 }
 
 export interface ServerSpecOptions {

package/src/model/recall-probe.ts

@@ -0,0 +1,81 @@
+/**
+ * The recall probe compaction runs before it stubs a fact: the person's local
+ * Evermind model — the same `.evermind` package recall embeds with and experience
+ * training adapts (`BUILDERFORCE_MEMORY_MODEL`) — is asked the question generated
+ * from the fact (`probeQuestionFor`), and the fact is stubbed only when the answer
+ * carries it. No model configured, or one that cannot generate, means no probe —
+ * and no probe means nothing is compacted.
+ */
+
+import type { RecallProbe } from "../compaction.js";
+import { MODEL_FILE_ENV, TOKENIZER_FILE_ENV } from "../embedding/index.js";
+import { loadEvermindPackage } from "./evermind-package.js";
+
+/** Structural view of an `EvermindLM` that can generate text. */
+interface GeneratingLM {
+    generateText(prompt: string, codec: unknown, opts: { maxNewTokens: number; temperature?: number }): string;
+}
+
+/** Tokens the model may spend answering one probe — a cloze answer is a word or two. */
+export const PROBE_MAX_NEW_TOKENS = 16;
+
+/** Wrap any text generator as a probe. Greedy, short, never throws. */
+export function generatorProbe(generate: (prompt: string) => string | Promise<string>): RecallProbe {
+    return {
+        async answer(question: string): Promise<string | null> {
+            try {
+                const out = await generate(question);
+                return typeof out === "string" ? out : null;
+            } catch {
+                return null;
+            }
+        },
+    };
+}
+
+export interface RecallProbeEnv {
+    env?: Record<string, string | undefined>;
+}
+
+/**
+ * The probe for this server, or null when no model is configured, the package is
+ * not a text LM, or its tokenizer cannot decode (no answer text to check).
+ */
+export async function createRecallProbe(opts: RecallProbeEnv = {}): Promise<RecallProbe | null> {
+    const env = opts.env ?? process.env;
+    const modelFile = env[MODEL_FILE_ENV];
+    if (!modelFile) return null;
+    const loaded = await loadEvermindPackage(modelFile, env[TOKENIZER_FILE_ENV] || undefined);
+    if (!loaded) return null;
+    const codec = loaded.codec as unknown as { decode?: unknown };
+    if (typeof codec.decode !== "function") return null;
+    let lm: GeneratingLM;
+    try {
+        lm = loaded.pkg.loadLM() as GeneratingLM;
+    } catch {
+        return null;
+    }
+    if (typeof lm?.generateText !== "function") return null;
+    return generatorProbe((prompt) =>
+        lm.generateText(prompt, loaded.codec, { maxNewTokens: PROBE_MAX_NEW_TOKENS, temperature: 0 }),
+    );
+}
+
+/**
+ * {@link createRecallProbe}, deferred to the first compaction — a server should not
+ * load a checkpoint at boot for a tool most sessions never call. Null when no model
+ * is configured; a model that then fails to load answers nothing (every probe fails,
+ * so nothing is stubbed).
+ */
+export function lazyRecallProbe(opts: RecallProbeEnv = {}): RecallProbe | null {
+    const env = opts.env ?? process.env;
+    if (!env[MODEL_FILE_ENV]) return null;
+    let probe: Promise<RecallProbe | null> | null = null;
+    return {
+        async answer(question: string): Promise<string | null> {
+            probe ??= createRecallProbe({ env });
+            const p = await probe;
+            return p ? p.answer(question) : null;
+        },
+    };
+}

package/src/persistence/fact-archive.ts

@@ -0,0 +1,101 @@
+/**
+ * FactArchive — where a compacted fact's full original lives once its body is a stub.
+ *
+ * The archive is deliberately NOT a field on the stored entry: the store snapshot is
+ * rebuilt from the store on every write, rewritten in place by other processes, and
+ * capped/evicted at {@link DEFAULT_MAX_ENTRIES}; an archived original riding inside
+ * it would be lost to any one of those. A separate sidecar (`memory.archive.json`,
+ * see `defaultArchiveFile`) is only ever merged into, never pruned, so an evicted or
+ * forgotten stub still has its original.
+ *
+ * Two implementations, one contract: in-memory (a backend with no disk mirror) and
+ * file-backed (shared across processes through {@link SharedJsonFile}, with its
+ * rotating backups and freshness check).
+ */
+
+import { mergeArchive, parseArchive, type ArchivedFact } from "../compaction.js";
+import { SharedJsonFile, type SharedFileFs } from "./shared-json-file.js";
+
+function isJson(text: string): boolean {
+    try {
+        JSON.parse(text);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export interface FactArchive {
+    /** The archived original for `key`, if one exists. */
+    get(key: string): ArchivedFact | undefined;
+    /** Every row, read once — for callers resolving many keys in one pass. */
+    all(): Readonly<Record<string, ArchivedFact>>;
+    /** Add or replace archive rows. Durable before it returns. */
+    putMany(facts: ArchivedFact[]): void;
+}
+
+/** Process-local archive — the default for a backend with no disk mirror. */
+export class MemoryFactArchive implements FactArchive {
+    private readonly rows: Record<string, ArchivedFact> = Object.create(null) as Record<string, ArchivedFact>;
+
+    get(key: string): ArchivedFact | undefined {
+        return this.rows[key];
+    }
+
+    all(): Readonly<Record<string, ArchivedFact>> {
+        return this.rows;
+    }
+
+    putMany(facts: ArchivedFact[]): void {
+        for (const f of facts) this.rows[f.key] = f;
+    }
+}
+
+/**
+ * Archive mirrored to a JSON file several processes share. Re-reads the file when it
+ * changed underneath this process; every write merges into the latest on-disk text,
+ * so two writers add to one archive rather than overwriting each other's rows.
+ */
+export class FileFactArchive implements FactArchive {
+    private rows: Record<string, ArchivedFact> = {};
+    private text: string | null = null;
+    private readonly file: SharedJsonFile;
+
+    constructor(path: string, fs: SharedFileFs) {
+        this.file = new SharedJsonFile(path, fs);
+        this.refresh();
+    }
+
+    get(key: string): ArchivedFact | undefined {
+        this.refresh();
+        return this.rows[key];
+    }
+
+    all(): Readonly<Record<string, ArchivedFact>> {
+        this.refresh();
+        return this.rows;
+    }
+
+    putMany(facts: ArchivedFact[]): void {
+        if (facts.length === 0) return;
+        this.refresh();
+        // An archive that exists but will not parse is refused, never overwritten:
+        // merging into "{}" would drop every row it holds. The throw reaches the
+        // compactor BEFORE any stub is written, so nothing is compacted either.
+        if (this.text && this.text.trim() && !isJson(this.text)) {
+            throw new Error(`fact archive ${this.file.path} is unreadable; refusing to overwrite it`);
+        }
+        const next = mergeArchive(this.text, facts);
+        this.file.write(next);
+        this.text = next;
+        this.rows = parseArchive(next);
+    }
+
+    private refresh(): void {
+        const changed = this.file.readIfChanged();
+        if (!changed) return;
+        this.text = changed.text;
+        this.rows = parseArchive(changed.text);
+        changed.accept();
+    }
+}

package/src/persistence/shared-json-file.ts

@@ -10,6 +10,11 @@
  * The loop guard is the stamp recorded immediately AFTER each of our own writes: the
  * next check stats the file, sees the same mtime+size, and returns without reading a
  * byte. A stat per call is the entire steady-state cost.
+ *
+ * Every overwrite first rotates the previous file into `<file>.bak.1` (shifting
+ * `.bak.1`→`.bak.2`→`.bak.3`, the oldest dropping off), so the last
+ * {@link DEFAULT_BACKUPS} versions of a shared store are always recoverable — a
+ * bad rewrite (from any process) is never the only copy.
  */
 
 export type SharedFileFs = {
@@ -18,6 +23,8 @@ export type SharedFileFs = {
     /** When present, writes land atomically (temp file + rename). */
     renameSync?(from: string, to: string): void;
     unlinkSync?(path: string): void;
+    /** Used to snapshot the current file into a backup before an overwrite. */
+    copyFileSync?(from: string, to: string): void;
     existsSync(path: string): boolean;
     statSync(path: string): { mtimeMs: number; size: number };
 };
@@ -55,14 +62,31 @@ export interface ChangedFile {
     accept(): void;
 }
 
+/** Rotating backups kept beside a shared file by default (`.bak.1` newest … `.bak.3`). */
+export const DEFAULT_BACKUPS = 3;
+
+/** The path of the `n`-th backup of `file` (1 = newest). */
+export function backupFile(file: string, n: number): string {
+    return `${file}.bak.${n}`;
+}
+
+export interface SharedJsonFileOptions {
+    /** Rotating backups to keep before each overwrite. Default {@link DEFAULT_BACKUPS}; 0 disables. */
+    backups?: number;
+}
+
 export class SharedJsonFile {
     /** How the file looked when this process last wrote or absorbed it. */
     private stamp: FileStamp | null = null;
+    private readonly backups: number;
 
     constructor(
         readonly path: string,
         private readonly fs: SharedFileFs,
-    ) {}
+        opts: SharedJsonFileOptions = {},
+    ) {
+        this.backups = Math.max(0, Math.floor(opts.backups ?? DEFAULT_BACKUPS));
+    }
 
     /**
      * The file's text when it changed since we last touched it — and on first use,
@@ -104,6 +128,7 @@ export class SharedJsonFile {
      * file open), the write falls back to writing in place.
      */
     write(text: string): void {
+        this.rotateBackups();
         const rename = this.fs.renameSync?.bind(this.fs);
         let written = false;
         if (rename) {
@@ -128,4 +153,32 @@ export class SharedJsonFile {
             this.stamp = null;
         }
     }
+
+    /**
+     * Shift `.bak.(n-1)` → `.bak.n` down to `.bak.1`, then copy the current file to
+     * `.bak.1`. Best effort: a backup that cannot be written never blocks the write
+     * it protects.
+     */
+    private rotateBackups(): void {
+        if (this.backups === 0 || !this.fs.existsSync(this.path)) return;
+        try {
+            for (let i = this.backups; i > 1; i--) {
+                const from = backupFile(this.path, i - 1);
+                if (this.fs.existsSync(from)) this.moveFile(from, backupFile(this.path, i));
+            }
+            const newest = backupFile(this.path, 1);
+            if (this.fs.copyFileSync) this.fs.copyFileSync(this.path, newest);
+            else this.fs.writeFileSync(newest, this.fs.readFileSync(this.path, "utf8"));
+        } catch {
+            /* best effort */
+        }
+    }
+
+    private moveFile(from: string, to: string): void {
+        if (this.fs.renameSync) {
+            this.fs.renameSync(from, to);
+            return;
+        }
+        this.fs.writeFileSync(to, this.fs.readFileSync(from, "utf8"));
+    }
 }