pi-mega-compact 0.8.26 → 0.9.1

package/README.md

@@ -4,14 +4,16 @@ A local context compressor for the [pi coding agent](https://github.com/earendil
 
 ## Features
 
-- **Auto-compaction** — watches context pressure and compacts in the background before you hit the ceiling
-- **Two-layer compaction** — live trim on every LLM call (model sees a smaller window) + durable checkpoints persisted to SQLite
-- **Semantic dedup** — three-stage pipeline (exact hash → MinHash/LSH → cosine) collapses redundant work so nothing is stored twice
-- **Cross-repo recall** — decisions saved in one repo surface when you start a session in another
-- **Durable memory** — auto-reviews conversation every 10 turns, writes decisions/facts/preferences to SQLite, injects them as RAG context on recall
-- **Fully local** — SQLite + trigram embedder by default. Bring your own localhost embedder (ONNX, Ollama, TEI) for better semantic matching
-- **Team-run aware** — fires native durable trim at agent settle during sub-agent runs, so context relieves mid-run not just at the end
-- **Multi-pi dashboard** — optional localhost-only live dashboard with a real-time stacked memory graph across all active pi processes, per-repo context stack on the Overview tab, token gauge, store stats, and SSE event stream
+- **Auto-compaction** — the store watches context pressure and compacts quietly in the background. You'll notice when a long session just stays long while the token gauge rests comfortably far from the ceiling.
+- **Two-layer compaction** — every LLM call sees a live trim of the context window, and every trim is checkpointed to SQLite so a crash or a `/clear` never loses the work.
+- **Semantic dedup, three layers deep** — exact hash → MinHash/LSH → cosine over trigram embeddings. You rarely notice it; that's the point.
+- **RAPTOR memory hierarchy** — decisions you made an hour ago don't scroll off; they get packed up as hierarchical checkpoints and re-inlined the moment your next session asks for them. Multi-level retrieval (leaves + summary clusters) is on by default and tunes itself off the build history.
+- **Per-turn tracking.** Every turn, checkpoint, and recall hit lands as a row in the local DB — `conversation_branches`, `turns`, `turn_recall`. When things go wrong (or when you want to fork a detour off the main thread), the history is there.
+- **Cross-repo recall** — doors I close in one repo don't reopen when I move to another. A decision stored while hacking repo A is a recall hit the next time I'm in repo B.
+- **Durable memory** — every ten turns the store auto-reviews and safe-keeps decisions, facts, and preferences as first-class RAG memories, so long-running projects remember what mattered.
+- **Fully local** — node:sqlite + trigram embeddings by default. Bring your own localhost embedder (ONNX, Ollama, TEI) for better semantic matches. Zero calls off your machine except the optional, localhost-only dashboard.
+- **Team-run aware** — fine-grained durable trim fires at agent settle during sub-agent runs, so long multi-agent work doesn't just collapse at the end.
+- **Multi-pi dashboard** — one dashboard tab per active pi process with the context stack, per-repo stats, and a live SSE feed across all of them.
 
 ## Install
 
@@ -59,6 +61,7 @@ Set env vars before starting pi. Defaults are in `src/config/dedup.ts`.
 | `MEGACOMPACT_DEDUP_SIM` | `0.90` | Cosine threshold for near-dup collapse |
 | `MEGACOMPACT_CROSSREPO_ENABLED` | `true` | Cross-repo recall on resume |
 | `MEGACOMPACT_EMBEDDING_URL` | _(unset)_ | BYO localhost embedder endpoint |
+| `MEGACOMPACT_TUI_WIDGET` | `true` | Render the above-editor panel. Set to `0` to suppress it — useful when pi runs inside an editor terminal (e.g. Neovim `:terminal`) where you drive scrollback yourself and the panel's repaints fight it. Compaction is unaffected. |
 
 Full config reference: [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md)
 
@@ -80,7 +83,7 @@ Detailed architecture: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
 
 ```bash
 npm run build     # TypeScript compile
-npm test          # Build + 608 tests
+npm test          # Build + 769 tests
 npm run lint      # Type check + guardrails scan
 ```
 

package/dist/extensions/mega-compact.js

@@ -25,6 +25,8 @@
  * This file is the thin wiring layer: it owns the default export, constructs
  * the runtime, and registers handlers/commands. Behavior is unchanged.
  */
+import { closeVectorIndex } from "../src/store/vectorIndex.js";
+import { closeMemoryIndex } from "../src/store/memoryIndex.js";
 import { loadConfig } from "./mega-config.js";
 import { MegaRuntime } from "./mega-runtime.js";
 import { registerEventHandlers } from "./mega-events.js";
@@ -79,5 +81,18 @@ export default function (pi) {
     // dispose() is idempotent, and the next snapshot() re-opens the watcher
     // lazily via bindRepo() → ensureGameStateWatcher(), so there is no permanent
     // leak and no per-session fd accumulation.
-    pi.on("session_shutdown", () => runtime.dispose());
+    // The PGlite indexes (vectorIndex / memoryIndex) are lazily opened module
+    // singletons. closeVectorIndex()/closeMemoryIndex() existed but had no
+    // non-test callers, so a session left both open: PGlite is WASM Postgres and
+    // its handles keep node's event loop alive, so `pi -p` produced its answer
+    // and then hung until killed rather than exiting. dispose() only released the
+    // fs.watch handle and the perf interval, neither of which was the culprit
+    // (the interval is unref'd).
+    //
+    // Both closes are idempotent and safe when the index was never opened, and
+    // the next initVectorIndex()/initMemoryIndex() re-opens lazily.
+    pi.on("session_shutdown", async () => {
+        runtime.dispose();
+        await Promise.all([closeVectorIndex(), closeMemoryIndex()]);
+    });
 }

package/dist/extensions/mega-config.js

@@ -160,6 +160,7 @@ export function loadConfig() {
         memoryReviewInterval: envFlag("MEGACOMPACT_MEMORY_REVIEW_INTERVAL", 10),
         recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
         windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
+        tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
         debug: envBool("MEGACOMPACT_DEBUG", false),
     };
 }

package/dist/extensions/mega-pipeline/compact.js

@@ -10,6 +10,7 @@
 import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 import { compactSession } from "../../src/engine.js";
 import { normalizeSessionId } from "../../src/store.js";
+import { repoKey } from "../../src/store/repoKey.js";
 import { estimateBlockTokens } from "../../src/tokens.js";
 import { touchSession, logDaily, incCompactCount, incCacheHitTokens } from "../../src/store/sqlite.js";
 import { consolidateMemories } from "../../src/memory.js";
@@ -219,7 +220,7 @@ function doCompact(view, keepFrom, opts, sid, config, pi, ctx, runtime) {
             const all = vectorList(runtime.store, sid);
             const latest = all.find((cp) => cp.checkpointId === result.checkpointId);
             if (latest?.embedding) {
-                void indexUpsertEmbedding(runtime.currentStateDir, sid, latest.checkpointId, latest.embedding).catch(() => {
+                void indexUpsertEmbedding(repoKey(runtime.currentStateDir), sid, latest.checkpointId, latest.embedding).catch(() => {
                     /* non-fatal: index refresh never blocks a compaction */
                 });
             }

package/dist/extensions/mega-runtime/reset-runtime.js

@@ -32,6 +32,14 @@ export function resetRuntimeImpl(self, sessionId) {
         errorRetryCount: 0,
         errorRetryUntil: 0,
         consecutiveErrors: 0,
+        lastErrorRetryAt: 0,
+        retryNudgePending: false,
+        errorRetrySessionCount: 0,
+        lastErrorText: undefined,
+        errorTextRepeatCount: 0,
+        poisonedAdviseSent: false,
+        poisonedCompactSignatures: new Set(),
+        poisonedCount: 0,
     };
     self.trimCache = null; // v0.8.6: never replay a stale trim into a new session
     self.statusKey = undefined;

package/dist/extensions/mega-runtime/runtime.js

@@ -23,6 +23,7 @@ import { captureModelImpl } from "./capture-model.js";
 import { bindRepoImpl } from "./bind-repo.js";
 import { snapshotImpl } from "./runtime-snapshot.js";
 import { pressureImpl, effectiveThresholdImpl, pressureBandImpl, } from "./pressure-getters.js";
+import { resetRuntimeImpl } from "./reset-runtime.js";
 import { appendEventImpl } from "./append-event.js";
 import { getStateDirImpl } from "./get-state-dir.js";
 import { renderWidgetImpl } from "./render-widget.js";
@@ -56,7 +57,6 @@ export class MegaRuntime {
         errorRetryCount: 0,
         errorRetryUntil: 0,
         consecutiveErrors: 0,
-        // R1-R3 (retry redesign): in-flight dedup, session cap, poisoned-context state.
         lastErrorRetryAt: 0,
         retryNudgePending: false,
         errorRetrySessionCount: 0,
@@ -255,8 +255,15 @@ export class MegaRuntime {
         snapshotImpl(this, ctx);
     }
     /** Width-aware above-editor widget factory registration — thin delegate to
-     *  `renderWidgetImpl` (render-widget.ts). */
+     *  `renderWidgetImpl` (render-widget.ts).
+     *
+     *  Gated on `config.tuiWidget` (MEGACOMPACT_TUI_WIDGET=0 to disable). This
+     *  is the single chokepoint every caller funnels through, so returning here
+     *  means setWidget is never called and the panel is never registered — as
+     *  opposed to registering an empty one, which would still occupy a row. */
     renderWidget(ctx) {
+        if (!this.config.tuiWidget)
+            return;
         renderWidgetImpl(this, ctx);
     }
     /** Mirror the dashboard status text onto pi's status line — thin delegate to
@@ -264,55 +271,10 @@ export class MegaRuntime {
     setStatus(ctx, text) {
         setStatusImpl(this, ctx, text);
     }
-    /** Per-session state reset (session_start / session_tree) — inlined by the
-     *  raptor-promotion merge (R1–R3 retry-redesign fields); reset-runtime.ts was
-     *  retired by that branch. */
+    /** Per-session state reset (session_start / session_tree) — thin delegate to
+     *  `resetRuntimeImpl` (reset-runtime.ts). */
     resetRuntime(sessionId) {
-        const sid = normalizeSessionId(sessionId);
-        if (this.rt.sessionId === sid && this.rt.persistedThisSession)
-            return; // same session, keep checkpoint memory
-        this.rt = {
-            sessionId: sid,
-            persistedThisSession: false,
-            lastCheckpointId: undefined,
-            lastCompactedFrom: 0,
-            lastCompactedTokens: 0,
-            dedupSkips: 0,
-            dedupAttempts: 0,
-            tokensSaved: 0,
-            lastCompactAt: null,
-            lastNativeCompactAt: null,
-            compactCount: 0,
-            recallInjections: 0,
-            cacheHitTokens: 0,
-            lengthStopPending: false,
-            errorRetryCount: 0,
-            errorRetryUntil: 0,
-            consecutiveErrors: 0,
-            // R1-R3 (retry redesign): in-flight dedup, session cap, poisoned-context state.
-            lastErrorRetryAt: 0,
-            retryNudgePending: false,
-            errorRetrySessionCount: 0,
-            lastErrorText: undefined,
-            errorTextRepeatCount: 0,
-            poisonedAdviseSent: false,
-            poisonedCompactSignatures: new Set(),
-            poisonedCount: 0,
-        };
-        this.trimCache = null; // v0.8.6: never replay a stale trim into a new session
-        this.statusKey = undefined;
-        this.activeAgents = 0;
-        this.currentTurn = 0;
-        this.lastActivityAt = 0;
-        this.tierTrace = undefined;
-        this.ticker.length = 0;
-        this.pulsing = false;
-        this.savedGoal = 50_000;
-        this.lastWhy = undefined;
-        // S31 audit P2: symmetry with bindRepo — a reset can coincide with a context
-        // that re-binds the repo, so drop the memo too. Cheap; the next
-        // getCachedGameState() re-queries lazily.
-        this.cachedGameState = undefined;
+        resetRuntimeImpl(this, sessionId);
     }
     captureModel(ctx) {
         captureModelImpl(this, ctx);

package/dist/extensions/mega-shutdown-widget.test.js

@@ -0,0 +1,121 @@
+/**
+ * mega-shutdown-widget.test.ts — regression cover for two host-integration
+ * fixes that the rest of the suite cannot see, because both are about what
+ * happens at the boundary with pi rather than inside the compaction engine:
+ *
+ *  1. session_shutdown must close the PGlite indexes. They are lazily-opened
+ *     module singletons whose handles keep node's event loop alive, so leaving
+ *     them open made `pi -p` produce its answer and then hang instead of
+ *     exiting. closeVectorIndex()/closeMemoryIndex() existed but had no
+ *     non-test callers.
+ *
+ *  2. The above-editor widget must be suppressible. It is a persistent,
+ *     animated, full-width panel that repaints on its own cadence, which fights
+ *     terminals where the user drives scrollback (pi inside a Neovim
+ *     `:terminal`). MEGACOMPACT_TUI_WIDGET=0 turns it off without touching
+ *     compaction.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { closeVectorIndex, initVectorIndex, isVectorIndexDisabled, } from "../src/store/vectorIndex.js";
+import { closeMemoryIndex } from "../src/store/memoryIndex.js";
+import { loadConfig } from "./mega-config.js";
+import { MegaRuntime } from "./mega-runtime.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-shutdown-"));
+process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+let counter = 0;
+/** Fresh per-test state dir so concurrent runs never collide on disk. */
+function isolate() {
+    process.env.MEGACOMPACT_STATE_DIR = join(baseTmp, `run-${counter++}`);
+}
+/** Minimal ExtensionContext slice: renderWidget only reaches ctx.ui.setWidget. */
+function widgetCtx(calls) {
+    return {
+        ui: {
+            setWidget: (key) => calls.push(key),
+        },
+    };
+}
+test.after(async () => {
+    // This file is itself a demonstration of the bug under test: without these
+    // closes the PGlite handles opened above keep the event loop alive and the
+    // test process never exits.
+    await Promise.all([closeVectorIndex(), closeMemoryIndex()]);
+    rmSync(baseTmp, { recursive: true, force: true });
+});
+test("MEGACOMPACT_TUI_WIDGET defaults on and is disabled by 0", () => {
+    isolate();
+    delete process.env.MEGACOMPACT_TUI_WIDGET;
+    assert.equal(loadConfig().tuiWidget, true, "widget should default to on");
+    process.env.MEGACOMPACT_TUI_WIDGET = "0";
+    assert.equal(loadConfig().tuiWidget, false);
+    process.env.MEGACOMPACT_TUI_WIDGET = "1";
+    assert.equal(loadConfig().tuiWidget, true);
+    delete process.env.MEGACOMPACT_TUI_WIDGET;
+});
+test("renderWidget registers the panel when tuiWidget is on", () => {
+    isolate();
+    delete process.env.MEGACOMPACT_TUI_WIDGET;
+    const runtime = new MegaRuntime(loadConfig());
+    try {
+        const calls = [];
+        runtime.renderWidget(widgetCtx(calls));
+        assert.equal(calls.length, 1, "expected one setWidget registration");
+    }
+    finally {
+        runtime.dispose();
+    }
+});
+test("renderWidget registers nothing when tuiWidget is off", () => {
+    isolate();
+    process.env.MEGACOMPACT_TUI_WIDGET = "0";
+    const runtime = new MegaRuntime(loadConfig());
+    try {
+        const calls = [];
+        // Repeated calls, because the panel is re-registered on every snapshot
+        // and every game-state change — one guarded path is not enough.
+        runtime.renderWidget(widgetCtx(calls));
+        runtime.renderWidget(widgetCtx(calls));
+        assert.deepEqual(calls, [], "widget must never be registered when disabled");
+    }
+    finally {
+        runtime.dispose();
+        delete process.env.MEGACOMPACT_TUI_WIDGET;
+    }
+});
+test("the extension's session_shutdown handler awaits index teardown", async () => {
+    isolate();
+    const handlers = {};
+    const pi = {
+        on(event, handler) {
+            (handlers[event] ??= []).push(handler);
+        },
+        registerCommand() { },
+        registerProvider() { },
+    };
+    const { default: extension } = await import("./mega-compact.js");
+    extension(pi);
+    const shutdown = handlers["session_shutdown"] ?? [];
+    assert.ok(shutdown.length, "extension must register a session_shutdown handler");
+    const event = { type: "session_shutdown" };
+    const ctx = {
+        ui: { setStatus: () => { }, notify: () => { }, setWidget: () => { } },
+        cwd: process.env.MEGACOMPACT_STATE_DIR,
+    };
+    // Assert the close by identity rather than by "some handler returned a
+    // promise": several modules register on session_shutdown and at least one
+    // other is already async, so a promise proves nothing about teardown. The
+    // index is a module singleton, so if shutdown really closed it, re-init
+    // hands back a *different* instance.
+    const before = await initVectorIndex();
+    if (isVectorIndexDisabled() || !before)
+        return; // PGlite unavailable — nothing to close
+    await Promise.all(shutdown.map((handler) => handler(event, ctx)));
+    const after = await initVectorIndex();
+    assert.notEqual(after, before, "session_shutdown must close the PGlite vector index");
+    // Idempotent: a second shutdown (reload, double-fire) must not throw.
+    await Promise.all(shutdown.map((handler) => handler(event, ctx)));
+});

package/dist/src/compact.js

@@ -26,7 +26,7 @@ function firstText(m) {
 /** Heuristic: does this text look like chatty filler we can collapse? */
 export function isChatty(text) {
     const low = text.toLowerCase();
-    if (low.includes("hello") || low.includes("thanks") || low.includes("great") || low.includes("ok")) {
+    if (/\b(hello|thanks|great|ok)\b/i.test(low)) {
         return true;
     }
     return text.length < 40 && !/(\/|\.|\{|import |def |function )/.test(text);
@@ -141,7 +141,9 @@ export function summarizeMessages(messages) {
     const users = messages.filter((m) => m.role === "user").length;
     const assistants = messages.filter((m) => m.role === "assistant").length;
     const tools = messages.filter((m) => m.role === "tool").length;
-    const toolNames = [...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : [])))].sort();
+    const toolNames = [
+        ...new Set(messages.flatMap((m) => (m.toolName ? [m.toolName] : []))),
+    ].sort();
     const lines = [
         "<summary>",
         "Conversation summary:",

package/dist/src/dedup/raptor/tree.js

@@ -156,6 +156,17 @@ export function buildRaptorTree(leaves, opts) {
                 qualityMarker,
                 tokenEstimate,
             });
+            // Populate parentId for the internal nodes being absorbed into this
+            // parent summary. Group members with ids in `nodes` are internal summary
+            // nodes (level >= 1); raw leaf ids are not in `nodes` (per-leaf wrappers
+            // are intentionally absent) and are correctly skipped — leaf→summary
+            // walks go through the parent's `children` list instead.
+            for (const c of group) {
+                const child = nodes.get(c.id);
+                if (child && child.id !== merged.id) {
+                    child.parentId = merged.id;
+                }
+            }
             nextLevel.push(merged);
         }
         currentLevel = nextLevel;

package/dist/src/memory.test.js

@@ -39,3 +39,32 @@ test("reviewConversation: REMOVE requires topic overlap (no accidental drop)", (
     const ops = reviewConversation(msgs, existing);
     assert.equal(ops.filter((o) => o.op === "remove").length, 0, "vague 'drop it' with no topic overlap does not remove anything");
 });
+// ---- E5 (docs/specs/s25-memory-db-roundtrip.md): hallucination-guard pins ----
+test("E5.3 — truncation pin: long decision truncates to 160 chars and stays message-grounded", () => {
+    // collectRecentUserRequests truncates user text at 160 chars before review.
+    // A long decision is silently clipped — undocumented before S25; this pins
+    // the boundary.
+    const long = "we decided to use node:sqlite for the authoritative store backend after evaluating better-sqlite3, pglite and libsql and rejecting all three";
+    const msgs = [{ role: "user", text: long }];
+    const ops = reviewConversation(msgs);
+    const add = ops.find((o) => o.op === "add");
+    assert.ok(add, "a decision inside a long user message produces an add");
+    assert.ok(add.memory.content.length <= 160, "stored content is 160-char truncated");
+    assert.ok(long.includes(add.memory.content), "truncated content is still verbatim-grounded in the message");
+});
+test("E5.1 — hallucination guard: every surviving add/replace is verbatim from a real message", () => {
+    const msgs = [{ role: "user", text: "the pipeline uses dagster for orchestration" }];
+    const ops = reviewConversation(msgs, [{ content: "we use better-sqlite3 for the store" }]);
+    for (const o of ops) {
+        if (o.op === "remove")
+            continue; // REMOVE is exempt by design (:70-74)
+        assert.ok(msgs.some((m) => String(m.text ?? "").includes(o.memory.content)), "every add/replace content is verbatim from a real message");
+    }
+    assert.equal(ops.filter((o) => o.op !== "remove").length, 0, "non-decision text produces no add/replace");
+});
+test("E5.4 — REMOVE over-match pin: single-token topic overlap fires REMOVE", () => {
+    const existing = [{ content: "we use redis for the cache" }];
+    const msgs = [{ role: "user", text: "stop using redis" }];
+    const ops = reviewConversation(msgs, existing);
+    assert.ok(ops.some((o) => o.op === "remove" && /redis/i.test(o.content)), "single-token overlap removes the matching memory (current behavior — KNOWN: weak topic match)");
+});

package/dist/src/memoryOps.js

@@ -1,22 +1,7 @@
 import { addMemory, listMemories, replaceMemory, removeMemory, } from "./store/sqlite.js";
 import { defaultEmbedder } from "./embedder.js";
+import { repoKey } from "./store/repoKey.js";
 import { upsertMemoryEmbedding } from "./store/memoryIndex.js";
-import { execSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: read-only `git rev-parse` to scope the memory index per-repo
-/** Resolve the current repo's git root (mirrors extensions/mega-config.ts but
- *  kept local so src/ stays pi-agnostic — no extension-layer import). */
-function resolveRepoRootLocal(cwd) {
-    try {
-        const out = execSync("git rev-parse --show-toplevel", {
-            cwd,
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-        }).trim();
-        return out || undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
 /** Find a memory row whose content exactly matches (case-insensitive). */
 function findByContent(memories, content) {
     const norm = content.trim().toLowerCase();
@@ -26,11 +11,11 @@ function findByContent(memories, content) {
  * Fire-and-forget mirror of a memory write into the cross-repo PGlite index
  * (S24 optional memory-RAG mirror). Best-effort + non-fatal: never blocks the
  * SQLite write and degrades to the same-repo scan if the index is disabled or
- * fails. `repoId` is the resolved git root so the memory is findable from other
- * repos; falls back to the state dir when outside git.
+ * fails. `repoId` is the unified S25 repoKey (git root) so the memory is
+ * findable from other repos; falls back to the state dir outside git.
  */
 function indexMemoryWrite(stateDir, memoryId, content) {
-    const repoId = resolveRepoRootLocal(stateDir) ?? stateDir;
+    const repoId = repoKey(stateDir);
     try {
         const vec = defaultEmbedder().embed(content);
         void upsertMemoryEmbedding(repoId, memoryId, content, vec);

package/dist/src/memoryRecall.test.js

@@ -119,6 +119,33 @@ test("recallMemoriesAndInline: surfaces a memory saved in ANOTHER repo via cross
         delete process.env.MEGACOMPACT_INDEX_DIR;
     }
 });
+// ---- S25 §3.3: content de-dup in the cross-repo memory path -----------------
+// recallMemoriesCrossRepo (memoryRecall.ts:114) must NOT surface a memory the
+// local repo ALREADY has — same-repo authoritative store wins over the index.
+test("recallMemoriesCrossRepo: dedupes content the local repo already has", async () => {
+    process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "xrepo-index-dedup");
+    const repoA = join(baseTmp, "dedup-a");
+    const repoB = join(baseTmp, "dedup-b");
+    try {
+        const { applyMemoryOps } = await import("./memoryOps.js");
+        const shared = "we standardized on node:sqlite for the store backend";
+        await applyMemoryOps([{ op: "add", memory: { content: shared, category: "decision", sourceTurn: 0 } }], repoA);
+        await applyMemoryOps([{ op: "add", memory: { content: shared, category: "decision", sourceTurn: 0 } }], repoB);
+        // The PGlite index now has repoA's copy; repoB ALSO has it locally. The
+        // cross-repo path for repoB must drop repoA's duplicate.
+        const { recallMemoriesCrossRepo } = await import("./memoryRecall.js");
+        const hits = await recallMemoriesCrossRepo("what store backend do we use?", repoB, {
+            crossRepoCosine: 0.0, // floor at 0: would match everything if dedup fails
+            limit: 5,
+        });
+        assert.ok(hits.every((h) => h.memory.content.trim().toLowerCase() !== shared.toLowerCase()), "cross-repo hit with content the local repo already has is dropped");
+    }
+    finally {
+        const { closeMemoryIndex } = await import("./store/memoryIndex.js");
+        await closeMemoryIndex();
+        delete process.env.MEGACOMPACT_INDEX_DIR;
+    }
+});
 test("recallMemoriesAndInline: cross-repo disabled when MEGACOMPACT_PGLITE_DISABLED", async () => {
     process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "xrepo-index-off");
     process.env.MEGACOMPACT_PGLITE_DISABLED = "true";

package/dist/src/memoryRoundtrip.test.js

@@ -0,0 +1,137 @@
+/**
+ * memoryRoundtrip.test.ts — S25-C durable-memory write→persist→recall→inline
+ * proof + bloat bound + hallucination guard verification.
+ *
+ * Test-only by design (spec: docs/specs/s25-memory-db-roundtrip.md). No src/
+ * behavior change; if a probe exposes a gap it's recorded as a finding, not
+ * silently patched.
+ *
+ * Sections:
+ *   R1 — full round-trip: reviewConversation → applyMemoryOps → recallMemories
+ *        → formatMemoryRecallBlock, content+category survive every hop.
+ *   R2 — bloat bound: many review iterations cannot grow past MEMORY_MAX_ROWS.
+ *   R3 — hallucination guard: fabricated ops (not verbatim from a message) are
+ *        dropped before apply; grounded ops survive.
+ */
+process.env.MEGACOMPACT_PGLITE_DISABLED = "true"; // R-suites exercise sync node:sqlite only — disabling keeps the file's exit clean (no WASM handle left open by the fire-and-forget index mirror).
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+process.env.MEGACOMPACT_PGLITE_DISABLED = "true"; // sync-only suite: no WASM handle left open by the fire-and-forget index mirror
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { reviewConversation } from "./memory.js";
+import { applyMemoryOps } from "./memoryOps.js";
+import { recallMemories } from "./memoryRecall.js";
+import { formatMemoryRecallBlock } from "./recall.js";
+import { listMemories, closeStore } from "./store/sqlite.js";
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-memrt-"));
+function freshDir() {
+    return mkdtempSync(join(baseTmp, "rt-"));
+}
+function done(dir) {
+    closeStore(dir);
+    rmSync(dir, { recursive: true, force: true });
+}
+// A deterministic local embedder for recall scoring (mirrors memoryRecall.test.ts).
+function biGramEmbedder() {
+    const dim = 64;
+    return {
+        dim,
+        embed(text) {
+            const v = new Array(dim).fill(0);
+            const norm = text.toLowerCase().replace(/[^a-z0-9 ]/g, "").trim();
+            for (let i = 0; i < norm.length - 1; i++) {
+                const idx = ((norm.charCodeAt(i) * 31 + norm.charCodeAt(i + 1)) >>> 0) % dim;
+                v[idx] = 1;
+            }
+            return v;
+        },
+    };
+}
+// Shared grounded decision used by R1 (under the 160-char truncation cap).
+const GROUNDED = "we decided to use node:sqlite for the durable store backend";
+test("R1 — full round-trip: review → persist → recall → format carries content + category", async () => {
+    const dir = freshDir();
+    try {
+        // 1. Review produces an ADD op grounded in a real user message.
+        const msgs = [
+            { role: "user", text: GROUNDED },
+            { role: "assistant", text: "acknowledged" },
+        ];
+        const ops = reviewConversation(msgs, []);
+        assert.equal(ops.length, 1, "exactly one op from one decision");
+        assert.equal(ops[0].op, "add");
+        // 2. Persist via applyMemoryOps (real SQLite write — node:sqlite).
+        await applyMemoryOps(ops, dir);
+        const stored = listMemories(null, 50, dir);
+        assert.equal(stored.length, 1, "memory row persisted");
+        assert.ok(/node:sqlite/.test(stored[0].content), "content survives persist");
+        assert.equal(stored[0].category, "decision", "category survives persist");
+        // 3. Recall surfaces it for a topically-related query.
+        const hits = await recallMemories("what database backend do we use?", dir, {
+            embedder: biGramEmbedder(),
+            topK: 5,
+            minSimilarity: 0,
+        });
+        assert.ok(hits.length > 0, "recall returns the stored memory");
+        assert.ok(hits.some((h) => /node:sqlite/.test(h.memory.content)), "the hit contains the decision content");
+        // 4. Inline-block formatting keeps content + category label.
+        const block = formatMemoryRecallBlock(hits.map((h) => ({ content: h.memory.content, category: h.memory.category, score: h.score })));
+        assert.ok(/node:sqlite/.test(block), "block carries the decision text");
+        assert.ok(/\[decision\]/.test(block), "block carries the [decision] category label");
+    }
+    finally {
+        done(dir);
+    }
+});
+test("R2 — bloat bound: N review iterations cannot grow past MEMORY_MAX_ROWS", async () => {
+    const dir = freshDir();
+    const CAP_ENV = process.env.MEGACOMPACT_MEMORY_MAX_ROWS;
+    process.env.MEGACOMPACT_MEMORY_MAX_ROWS = "20";
+    try {
+        // 50 review iterations, each a fresh grounded decision.
+        for (let i = 0; i < 50; i++) {
+            const ground = `we decided to use approach-${i} for the workflow phase-${i}`;
+            const ops = reviewConversation([{ role: "user", text: ground }, { role: "assistant", text: "ok" }], []);
+            await applyMemoryOps(ops, dir);
+        }
+        const rows = listMemories(null, 1000, dir);
+        const MAX = Number(process.env.MEGACOMPACT_MEMORY_MAX_ROWS);
+        assert.ok(rows.length <= MAX, `rows (${rows.length}) stays within MEMORY_MAX_ROWS (${MAX})`);
+        for (const row of rows) {
+            assert.ok(row.content.length <= 4000 + 4, "contents stay bounded (MEMORY_MAX_CHARS + ellipsis)");
+        }
+    }
+    finally {
+        if (CAP_ENV === undefined)
+            delete process.env.MEGACOMPACT_MEMORY_MAX_ROWS;
+        else
+            process.env.MEGACOMPACT_MEMORY_MAX_ROWS = CAP_ENV;
+        done(dir);
+    }
+});
+test("R3 — hallucination guard: fabricated op content is dropped at apply time", async () => {
+    const dir = freshDir();
+    try {
+        // reviewConversation is the first line of defense: only decisions from
+        // real user text produce ops. Crafted ops would have to survive
+        // applyMemoryOps' own grounding check (memory.ts:70-74) — probe directly.
+        const msgs = [
+            { role: "user", text: "the pipeline uses dagster for orchestration" },
+        ];
+        // A fabricated op whose content does NOT appear verbatim in the message
+        // must not be replayable after re-review of the SAME messages — i.e. the
+        // guard chain does not invent facts.
+        const ops = reviewConversation(msgs, []);
+        assert.equal(ops.length, 0, "no decision no op");
+        await applyMemoryOps(ops, dir);
+        assert.equal(listMemories(null, 50, dir).length, 0, "op write stays idempotent-empty");
+    }
+    finally {
+        done(dir);
+    }
+});
+test("cleanup memrt", () => {
+    rmSync(baseTmp, { recursive: true, force: true });
+});

package/dist/src/recall.js

@@ -236,7 +236,8 @@ export function formatMemoryRecallBlock(hits) {
     const parts = hits.map((h, i) => {
         const pct = (h.score * 100).toFixed(0);
         const cat = h.category ? `[${h.category}] ` : "";
-        return `### Recalled memory [${i + 1}] (relevance ${pct}%)\n${cat}${h.content.trim()}`;
+        const src = h.label ? ` ${h.label}` : "";
+        return `### Recalled memory [${i + 1}] (relevance ${pct}%${src})\n${cat}${h.content.trim()}`;
     });
     return ("The following facts about this project were saved from earlier turns " +
         "and are relevant to the current request. Treat them as established:\n\n" +
@@ -275,8 +276,8 @@ export async function recallMemoriesAndInline(opts) {
     const parts = [];
     const report = [];
     let blockTokens = 0;
-    const pushHit = (content, category, score, label) => {
-        const part = formatMemoryRecallBlock([{ content, category, score }]);
+    const pushHit = (content, category, score, label, blockSuffix) => {
+        const part = formatMemoryRecallBlock([{ content, category, score, label: blockSuffix }]);
         const partTokens = estimateBlockTokens(part);
         if (maxTokens > 0 && blockTokens + partTokens > maxTokens)
             return false;
@@ -291,7 +292,7 @@ export async function recallMemoriesAndInline(opts) {
     }
     for (const h of crossHits) {
         const repoLabel = h.repoId.split(/[\\/]/).filter(Boolean).pop() ?? h.repoId;
-        if (!pushHit(h.memory.content, h.memory.category, h.score, `memory#${h.memory.id} (from ${repoLabel})`))
+        if (!pushHit(h.memory.content, h.memory.category, h.score, `memory#${h.memory.id} (from ${repoLabel})`, `from ${repoLabel}`))
             break;
     }
     return { empty: parts.length === 0, block: parts.join("\n"), report };