@seanhogg/builderforce-memory-mcp 2026.10.3 → 2026.10.22

package/dist/persistence/fact-archive.js

@@ -0,0 +1,85 @@
+/**
+ * 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 } from "../compaction.js";
+import { SharedJsonFile } from "./shared-json-file.js";
+function isJson(text) {
+    try {
+        JSON.parse(text);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Process-local archive — the default for a backend with no disk mirror. */
+export class MemoryFactArchive {
+    rows = Object.create(null);
+    get(key) {
+        return this.rows[key];
+    }
+    all() {
+        return this.rows;
+    }
+    putMany(facts) {
+        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 {
+    rows = {};
+    text = null;
+    file;
+    constructor(path, fs) {
+        this.file = new SharedJsonFile(path, fs);
+        this.refresh();
+    }
+    get(key) {
+        this.refresh();
+        return this.rows[key];
+    }
+    all() {
+        this.refresh();
+        return this.rows;
+    }
+    putMany(facts) {
+        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);
+    }
+    refresh() {
+        const changed = this.file.readIfChanged();
+        if (!changed)
+            return;
+        this.text = changed.text;
+        this.rows = parseArchive(changed.text);
+        changed.accept();
+    }
+}
+//# sourceMappingURL=fact-archive.js.map

package/dist/persistence/fact-archive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact-archive.js","sourceRoot":"","sources":["../../src/persistence/fact-archive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAqB,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAqB,MAAM,uBAAuB,CAAC;AAE1E,SAAS,MAAM,CAAC,IAAY;IACxB,IAAI,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC;AAWD,6EAA6E;AAC7E,MAAM,OAAO,iBAAiB;IACT,IAAI,GAAiC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAiC,CAAC;IAE1G,GAAG,CAAC,GAAW;QACX,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,GAAG;QACC,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,OAAO,CAAC,KAAqB;QACzB,KAAK,MAAM,CAAC,IAAI,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChD,CAAC;CACJ;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAe;IAChB,IAAI,GAAiC,EAAE,CAAC;IACxC,IAAI,GAAkB,IAAI,CAAC;IAClB,IAAI,CAAiB;IAEtC,YAAY,IAAY,EAAE,EAAgB;QACtC,IAAI,CAAC,IAAI,GAAG,IAAI,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACzC,IAAI,CAAC,OAAO,EAAE,CAAC;IACnB,CAAC;IAED,GAAG,CAAC,GAAW;QACX,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAED,GAAG;QACC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO,IAAI,CAAC,IAAI,CAAC;IACrB,CAAC;IAED,OAAO,CAAC,KAAqB;QACzB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,2EAA2E;QAC3E,yEAAyE;QACzE,wEAAwE;QACxE,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,CAAC,IAAI,CAAC,IAAI,0CAA0C,CAAC,CAAC;QAC9F,CAAC;QACD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC;IAEO,OAAO;QACX,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;QAC1C,IAAI,CAAC,OAAO;YAAE,OAAO;QACrB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACvC,OAAO,CAAC,MAAM,EAAE,CAAC;IACrB,CAAC;CACJ"}

package/dist/persistence/shared-json-file.d.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 = {
     readFileSync(path: string, enc: "utf8"): string;
@@ -17,6 +22,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;
@@ -39,12 +46,21 @@ export interface ChangedFile {
      */
     accept(): void;
 }
+/** Rotating backups kept beside a shared file by default (`.bak.1` newest … `.bak.3`). */
+export declare const DEFAULT_BACKUPS = 3;
+/** The path of the `n`-th backup of `file` (1 = newest). */
+export declare function backupFile(file: string, n: number): string;
+export interface SharedJsonFileOptions {
+    /** Rotating backups to keep before each overwrite. Default {@link DEFAULT_BACKUPS}; 0 disables. */
+    backups?: number;
+}
 export declare class SharedJsonFile {
     readonly path: string;
     private readonly fs;
     /** How the file looked when this process last wrote or absorbed it. */
     private stamp;
-    constructor(path: string, fs: SharedFileFs);
+    private readonly backups;
+    constructor(path: string, fs: SharedFileFs, opts?: SharedJsonFileOptions);
     /**
      * The file's text when it changed since we last touched it — and on first use,
      * which IS the boot hydration (one routine, so disk and memory never diverge by
@@ -61,5 +77,12 @@ export declare class SharedJsonFile {
      * file open), the write falls back to writing in place.
      */
     write(text: string): void;
+    /**
+     * 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;
+    private moveFile;
 }
 //# sourceMappingURL=shared-json-file.d.ts.map

package/dist/persistence/shared-json-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared-json-file.d.ts","sourceRoot":"","sources":["../../src/persistence/shared-json-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,YAAY,GAAG;IACvB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAChD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,iEAAiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D,CAAC;AAUF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;CAClB;AAED,qBAAa,cAAc;IAKnB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE;IALvB,uEAAuE;IACvE,OAAO,CAAC,KAAK,CAA0B;gBAG1B,IAAI,EAAE,MAAM,EACJ,EAAE,EAAE,YAAY;IAGrC;;;;OAIG;IACH,aAAa,IAAI,WAAW,GAAG,IAAI;IAyBnC;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAyB5B"}
+{"version":3,"file":"shared-json-file.d.ts","sourceRoot":"","sources":["../../src/persistence/shared-json-file.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,YAAY,GAAG;IACvB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAChD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,iEAAiE;IACjE,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,UAAU,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,2EAA2E;IAC3E,YAAY,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D,CAAC;AAUF;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED,qEAAqE;AACrE,MAAM,WAAW,WAAW;IACxB,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,IAAI,IAAI,CAAC;CAClB;AAED,0FAA0F;AAC1F,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,MAAM,WAAW,qBAAqB;IAClC,mGAAmG;IACnG,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,cAAc;IAMnB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,OAAO,CAAC,QAAQ,CAAC,EAAE;IANvB,uEAAuE;IACvE,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAGpB,IAAI,EAAE,MAAM,EACJ,EAAE,EAAE,YAAY,EACjC,IAAI,GAAE,qBAA0B;IAKpC;;;;OAIG;IACH,aAAa,IAAI,WAAW,GAAG,IAAI;IAyBnC;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IA2BzB;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAerB,OAAO,CAAC,QAAQ;CAOnB"}

package/dist/persistence/shared-json-file.js

@@ -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.
  */
 /**
  * FNV-1a over the file text. Non-cryptographic on purpose: this only has to separate
@@ -25,14 +30,22 @@ export function contentHash(text) {
     }
     return (h >>> 0).toString(16);
 }
+/** 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, n) {
+    return `${file}.bak.${n}`;
+}
 export class SharedJsonFile {
     path;
     fs;
     /** How the file looked when this process last wrote or absorbed it. */
     stamp = null;
-    constructor(path, fs) {
+    backups;
+    constructor(path, fs, opts = {}) {
         this.path = path;
         this.fs = fs;
+        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,
@@ -77,6 +90,7 @@ export class SharedJsonFile {
      * file open), the write falls back to writing in place.
      */
     write(text) {
+        this.rotateBackups();
         const rename = this.fs.renameSync?.bind(this.fs);
         let written = false;
         if (rename) {
@@ -106,5 +120,36 @@ 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.
+     */
+    rotateBackups() {
+        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 */
+        }
+    }
+    moveFile(from, to) {
+        if (this.fs.renameSync) {
+            this.fs.renameSync(from, to);
+            return;
+        }
+        this.fs.writeFileSync(to, this.fs.readFileSync(from, "utf8"));
+    }
 }
 //# sourceMappingURL=shared-json-file.js.map

package/dist/persistence/shared-json-file.js.map

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

package/dist/restore.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Restore — bringing the full text of a compaction stub back from an export.
+ *
+ * A stub written before compaction archived its originals is the ONLY copy left:
+ * the text is gone (`contentLost`). The text often still exists elsewhere — a
+ * memory export (`[{ key, content }]`), or the Evermind coordinator's `mem:` record
+ * dump (`[{ id, text }]`) — and this module decides which record restores which
+ * stub. Pure and dependency-free; the `memory_restore` tool does the I/O.
+ *
+ * Matching, in order:
+ *   1. by key — a record's `key`, or its `id` with any `mem:` prefix dropped;
+ *   2. by text — the record's first line starts with the stub's pointer line (the
+ *      original first line the stub kept). Only a UNIQUE match restores; two stubs
+ *      sharing a pointer are reported ambiguous rather than guessed.
+ */
+import { type ArchivedFact } from "./compaction.js";
+/** One record from a restore source, normalised. */
+export interface RestoreRecord {
+    /** The memory key the record names, when it names one. */
+    key?: string;
+    /** The full text. */
+    content: string;
+}
+/** A stub that may be restored. */
+export interface RestoreTarget {
+    key: string;
+    /** The stored stub body. */
+    stub: string;
+}
+export interface RestoreMatch {
+    key: string;
+    content: string;
+    via: "key" | "text";
+}
+export interface RestorePlan {
+    matches: RestoreMatch[];
+    /** Records that matched no target. */
+    unmatched: number;
+    /** Targets more than one stub could claim by text, left alone. */
+    ambiguous: string[];
+}
+/**
+ * Parse a restore source: a JSON array, an object wrapping one (`{ entries: [...] }`
+ * and similar), or JSON Lines. Rows without text, or whose text is itself a stub,
+ * are dropped — restoring a stub with a stub restores nothing.
+ */
+export declare function parseRestoreSource(text: string): RestoreRecord[];
+/** Shortest pointer line a text match may rest on — below it, a prefix proves nothing. */
+export declare const MIN_POINTER_CHARS = 12;
+/** Decide which record restores which stub. */
+export declare function planRestore(records: RestoreRecord[], targets: RestoreTarget[]): RestorePlan;
+/** The Evermind version a stub names (`[absorbed→Evermind v7] …` → 7), 0 when unreadable. */
+export declare function stubVersion(stub: string): number;
+/** The archive row that makes a restored stub lossless again. */
+export declare function restoredArchive(match: RestoreMatch, stub: string, now?: number): ArchivedFact;
+//# sourceMappingURL=restore.d.ts.map

package/dist/restore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"restore.d.ts","sourceRoot":"","sources":["../src/restore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAA+C,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEjG,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC1B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,KAAK,GAAG,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,SAAS,EAAE,MAAM,EAAE,CAAC;CACvB;AA6BD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAgBhE;AAID,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,+CAA+C;AAC/C,wBAAgB,WAAW,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,OAAO,EAAE,aAAa,EAAE,GAAG,WAAW,CA0B3F;AAKD,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,SAAa,GAAG,YAAY,CAEjG"}

package/dist/restore.js

@@ -0,0 +1,118 @@
+/**
+ * Restore — bringing the full text of a compaction stub back from an export.
+ *
+ * A stub written before compaction archived its originals is the ONLY copy left:
+ * the text is gone (`contentLost`). The text often still exists elsewhere — a
+ * memory export (`[{ key, content }]`), or the Evermind coordinator's `mem:` record
+ * dump (`[{ id, text }]`) — and this module decides which record restores which
+ * stub. Pure and dependency-free; the `memory_restore` tool does the I/O.
+ *
+ * Matching, in order:
+ *   1. by key — a record's `key`, or its `id` with any `mem:` prefix dropped;
+ *   2. by text — the record's first line starts with the stub's pointer line (the
+ *      original first line the stub kept). Only a UNIQUE match restores; two stubs
+ *      sharing a pointer are reported ambiguous rather than guessed.
+ */
+import { STUB_PREFIX, firstLine, isStub, stubPointer } from "./compaction.js";
+/** Array-valued properties a wrapped export may keep its rows under. */
+const WRAPPER_KEYS = ["entries", "memories", "records", "items", "data", "facts"];
+function rowsOf(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    if (parsed && typeof parsed === "object") {
+        const obj = parsed;
+        for (const k of WRAPPER_KEYS) {
+            const v = obj[k];
+            if (Array.isArray(v))
+                return v;
+        }
+        // A lone record (a one-line JSON Lines file parses as plain JSON).
+        if (typeof obj["content"] === "string" || typeof obj["text"] === "string")
+            return [obj];
+    }
+    return [];
+}
+function toRecord(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const r = raw;
+    const content = typeof r["content"] === "string" ? r["content"] : typeof r["text"] === "string" ? r["text"] : null;
+    if (content === null || !content.trim() || isStub(content))
+        return null;
+    const named = typeof r["key"] === "string" ? r["key"] : typeof r["id"] === "string" ? r["id"] : undefined;
+    const key = named?.replace(/^mem:/, "").trim();
+    return key ? { key, content } : { content };
+}
+/**
+ * Parse a restore source: a JSON array, an object wrapping one (`{ entries: [...] }`
+ * and similar), or JSON Lines. Rows without text, or whose text is itself a stub,
+ * are dropped — restoring a stub with a stub restores nothing.
+ */
+export function parseRestoreSource(text) {
+    let rows;
+    try {
+        rows = rowsOf(JSON.parse(text));
+    }
+    catch {
+        rows = [];
+        for (const line of text.split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            try {
+                rows.push(JSON.parse(line));
+            }
+            catch {
+                /* not a record */
+            }
+        }
+    }
+    return rows.map(toRecord).filter((r) => r !== null);
+}
+const norm = (s) => s.toLowerCase().replace(/\s+/g, " ").trim();
+/** Shortest pointer line a text match may rest on — below it, a prefix proves nothing. */
+export const MIN_POINTER_CHARS = 12;
+/** Decide which record restores which stub. */
+export function planRestore(records, targets) {
+    const byKey = new Map(targets.map((t) => [t.key, t]));
+    const pointers = targets.map((t) => ({ key: t.key, pointer: norm(stubPointer(t.stub)) }));
+    const matched = new Map();
+    const ambiguous = new Set();
+    let unmatched = 0;
+    for (const r of records) {
+        if (r.key && byKey.has(r.key)) {
+            if (!matched.has(r.key))
+                matched.set(r.key, { key: r.key, content: r.content, via: "key" });
+            continue;
+        }
+        const head = norm(firstLine(r.content, 100_000));
+        const hits = pointers.filter((p) => p.pointer.length >= MIN_POINTER_CHARS && head.startsWith(p.pointer));
+        if (hits.length === 1) {
+            const key = hits[0].key;
+            if (!matched.has(key))
+                matched.set(key, { key, content: r.content, via: "text" });
+            continue;
+        }
+        if (hits.length > 1)
+            for (const h of hits)
+                ambiguous.add(h.key);
+        else
+            unmatched++;
+    }
+    // A key claimed unambiguously by key-match stays restored even if a text match was ambiguous.
+    const matches = [...matched.values()];
+    for (const m of matches)
+        ambiguous.delete(m.key);
+    return { matches, unmatched, ambiguous: [...ambiguous] };
+}
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const STUB_VERSION = new RegExp(`^\\s*${escapeRegExp(STUB_PREFIX)} v(\\d+)\\]`);
+/** The Evermind version a stub names (`[absorbed→Evermind v7] …` → 7), 0 when unreadable. */
+export function stubVersion(stub) {
+    const m = STUB_VERSION.exec(stub);
+    return m ? Number(m[1]) : 0;
+}
+/** The archive row that makes a restored stub lossless again. */
+export function restoredArchive(match, stub, now = Date.now()) {
+    return { key: match.key, content: match.content, stub, version: stubVersion(stub), archivedAt: now };
+}
+//# sourceMappingURL=restore.js.map

package/dist/restore.js.map

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

package/dist/tools.d.ts

@@ -14,6 +14,7 @@
  * store back into context is more expensive than inlining it.
  */
 import type { MemoryBackend } from "./backend.js";
+import { type RecallProbe } from "./compaction.js";
 import type { ExperienceHost } from "./experience/host.js";
 import { type MemoryTool } from "./tool-core.js";
 export type { MemoryTool, ToolResult } from "./tool-core.js";
@@ -37,6 +38,18 @@ export interface MemoryToolsOptions {
      * beside the memory tools. See {@link createExperienceHost}.
      */
     experience?: ExperienceHost | null;
+    /**
+     * The local model `memory_compact` proves absorption with before it stubs a
+     * fact (see `planLosslessCompaction`). Null/absent → compaction stubs nothing
+     * and says why. The bins pass `lazyRecallProbe()` (the configured Evermind).
+     */
+    recallProbe?: RecallProbe | null;
+    /**
+     * Reads a restore source by path for `memory_restore`. Only hosts that may read
+     * their own disk pass it (the stdio bin); without it the tool takes inline JSON
+     * only, so a networked server never reads a caller-named file.
+     */
+    readRestoreFile?: (path: string) => Promise<string>;
 }
 /**
  * Builds the memory tool set bound to `backend`. Write tools are included only

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAwD,MAAM,cAAc,CAAC;AAGxG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAkB,KAAK,UAAU,EAAmB,MAAM,gBAAgB,CAAC;AAElF,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IAC/B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CACtC;AA2DD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,GAAE,kBAAuB,GAAG,UAAU,EAAE,CAiOpG"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAyC,MAAM,cAAc,CAAC;AACzF,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,EAAkB,KAAK,UAAU,EAAmB,MAAM,gBAAgB,CAAC;AAElF,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IAC/B,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvD;AAiDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,IAAI,GAAE,kBAAuB,GAAG,UAAU,EAAE,CAyJpG"}

package/dist/tools.js

@@ -14,7 +14,8 @@
  * store back into context is more expensive than inlining it.
  */
 import { z } from "zod";
-import { DEFAULT_STUB_CHARS, planCompaction } from "./compaction.js";
+import { CONTENT_LOST_LABEL } from "./compaction.js";
+import { appendCompactionTools } from "./compaction-tools.js";
 import { buildExperienceTools } from "./experience/tools.js";
 import { appendGatewayCostTools } from "./gateway-tools.js";
 import { clip, fail, ok } from "./tool-core.js";
@@ -32,6 +33,8 @@ const RANKER_LINE = {
     embedding: "Ranked by: semantic recall (SSM embedding fused with lexical).",
     lexical: "Ranked by: lexical recall (fallback - no embedding model loaded).",
 };
+/** A stub whose original is gone is surfaced WITH the label, never as a plain fact. */
+const lostLabel = (h) => (h.contentLost ? ` ${CONTENT_LOST_LABEL}` : "");
 function renderHits(hits, maxChars, method) {
     const ranker = method ? `\n${RANKER_LINE[method]}` : "";
     if (hits.length === 0)
@@ -40,7 +43,7 @@ function renderHits(hits, maxChars, method) {
         .map((h) => {
         const tags = h.tags?.length ? ` tags=[${h.tags.join(", ")}]` : "";
         const score = h.score != null ? ` score=${h.score.toFixed(3)}` : "";
-        return `• ${h.key}${score}${tags}\n  ${clip(h.content, maxChars)}`;
+        return `• ${h.key}${score}${tags}${lostLabel(h)}\n  ${clip(h.content, maxChars)}`;
     })
         .join("\n") + ranker);
 }
@@ -54,18 +57,6 @@ async function rankedRecall(backend, query, topK) {
         return backend.recallRanked(query, topK);
     return { hits: await backend.recall(query, topK) };
 }
-const SKIP_REASONS = {
-    not_found: "not found",
-    already_compacted: "already compacted",
-    not_smaller: "already shorter than its stub",
-};
-/** One-line compaction receipt: what shrank, what it saved, and what was left alone. */
-function renderCompaction(compacted, bytesSaved, skipped) {
-    const lines = [`Compacted ${compacted} memory(ies), ${bytesSaved} character(s) reclaimed.`];
-    for (const s of skipped)
-        lines.push(`• skipped ${s.key} — ${SKIP_REASONS[s.reason]}`);
-    return lines.join("\n");
-}
 /**
  * Builds the memory tool set bound to `backend`. Write tools are included only
  * when `writable` is not false AND the backend actually implements them.
@@ -119,7 +110,9 @@ export function buildMemoryTools(backend, opts = {}) {
                     if (!key)
                         return fail("key is required.");
                     const hit = await backend.get(key);
-                    return hit ? ok(`• ${hit.key}\n  ${hit.content}`) : ok(`No memory found for key "${key}".`);
+                    return hit
+                        ? ok(`• ${hit.key}${lostLabel(hit)}\n  ${hit.content}`)
+                        : ok(`No memory found for key "${key}".`);
                 }
                 catch (err) {
                     return fail(`get failed: ${String(err)}`);
@@ -190,81 +183,9 @@ export function buildMemoryTools(backend, opts = {}) {
             },
         });
     }
-    // memory_compact — the FIRST-CLASS compaction path. It writes through the live
-    // store (get → plan → remember), so a durable backend's in-memory state and its
-    // on-disk snapshot agree afterwards. Compacting the snapshot file behind the
-    // server's back instead is what races: the server still holds the full bodies and
-    // re-snapshots over them on its next write. Requires read + write, so it is
-    // registered alongside the other write tools.
-    if (writable && backend.remember) {
-        tools.push({
-            name: "memory_compact",
-            description: "Shrink memories that have already been absorbed elsewhere (folded into a model, " +
-                "summarised into a longer-lived note) down to a one-line pointer stub, reclaiming the " +
-                "context they were eating. Call this AFTER something durable has learned the facts — " +
-                "never as a way to tidy up, because the full body is gone afterwards. Already-compacted " +
-                "keys are skipped, so repeating the call is safe.",
-            inputSchema: {
-                keys: z.array(z.string()).min(1).describe("Exact keys of the memories to compact."),
-                stub: z
-                    .string()
-                    .optional()
-                    .describe("Explicit replacement body applied to every listed key. Omit to generate " +
-                    "'[absorbed→Evermind vN] <first line>' from each entry's own first line."),
-                version: z
-                    .number()
-                    .int()
-                    .min(0)
-                    .optional()
-                    .describe("Version of the model that absorbed these facts; appears in the generated stub."),
-                maxChars: z
-                    .number()
-                    .int()
-                    .min(20)
-                    .max(500)
-                    .optional()
-                    .describe(`Max characters of the generated pointer line (default ${DEFAULT_STUB_CHARS}).`),
-            },
-            handler: async (args) => {
-                try {
-                    const raw = args["keys"];
-                    const keys = Array.isArray(raw) ? raw.map((k) => String(k)).filter(Boolean) : [];
-                    if (keys.length === 0)
-                        return fail("keys is required.");
-                    // ONE read pass: the hit carries both the body the plan reasons about
-                    // and the tags/importance the rewrite must preserve.
-                    const hits = new Map();
-                    for (const key of keys) {
-                        const hit = await backend.get(key);
-                        if (hit)
-                            hits.set(key, hit);
-                    }
-                    const plan = planCompaction(keys.map((key) => ({ key, content: hits.get(key)?.content })), {
-                        stub: typeof args["stub"] === "string" ? args["stub"] : undefined,
-                        version: args["version"] == null ? undefined : Number(args["version"]),
-                        maxChars: args["maxChars"] == null ? undefined : Number(args["maxChars"]),
-                    });
-                    // Preserve tags/importance — compaction shortens a body, it does not
-                    // reclassify the fact.
-                    const writes = plan.writes.map((w) => {
-                        const prev = hits.get(w.key);
-                        return { key: w.key, content: w.content, tags: prev?.tags, importance: prev?.importance };
-                    });
-                    if (writes.length > 0) {
-                        if (backend.rememberMany)
-                            await backend.rememberMany(writes);
-                        else
-                            for (const w of writes)
-                                await backend.remember(w);
-                    }
-                    return ok(renderCompaction(plan.writes.length, plan.bytesSaved, plan.skipped));
-                }
-                catch (err) {
-                    return fail(`compact failed: ${String(err)}`);
-                }
-            },
-        });
-    }
+    // memory_compact + memory_restore — the lossless compaction pair (compaction-tools.ts).
+    if (writable && backend.remember)
+        appendCompactionTools(tools, backend, opts);
     if (writable && backend.forget) {
         tools.push({
             name: "memory_forget",