pi-mega-compact 0.6.0 → 0.6.2

package/src/memoryOps.test.ts

@@ -10,7 +10,6 @@ import {
   replaceMemory,
   referenceMemory,
   MEMORY_MAX_CHARS,
-  MEMORY_MAX_ROWS,
 } from "./store/sqlite.js";
 
 const baseTmp = mkdtempSync(join(tmpdir(), "mc-memops-"));
@@ -79,31 +78,53 @@ test("S24: replaceMemory also truncates oversized content", () => {
 });
 
 test("S24: addMemory evicts LRU rows past MEMORY_MAX_ROWS per repo", () => {
-  const dir = join(baseTmp, "lru");
-  const n = MEMORY_MAX_ROWS;
-  const seeds = n - 2;
-  for (let i = 0; i < seeds; i++) addMemory({ content: `seed-${i}`, category: "note" }, null, dir);
-  const keep1 = addMemory({ content: "keep-recent-1", category: "note" }, null, dir);
-  const keep2 = addMemory({ content: "keep-recent-2", category: "note" }, null, dir);
-  // Mark the two as referenced so the LRU eviction spares them (they get a
-  // higher last_referenced than the un-referenced seeds).
-  assert.ok(referenceMemory(keep1, dir), "reference keep1");
-  assert.ok(referenceMemory(keep2, dir), "reference keep2");
-  // Insert 3 more — 3 over the cap across the inserts. The two referenced rows
-  // must survive; only un-referenced (oldest) seeds should be evicted.
-  addMemory({ content: "new-1", category: "note" }, null, dir);
-  addMemory({ content: "new-2", category: "note" }, null, dir);
-  addMemory({ content: "new-3", category: "note" }, null, dir);
-  const rows = listMemories(null, 1000, dir);
-  assert.equal(rows.length, n, "row count clamped to MEMORY_MAX_ROWS");
-  assert.ok(rows.some((m) => /keep-recent-1/.test(m.content)), "referenced row survived");
-  assert.ok(rows.some((m) => /keep-recent-2/.test(m.content)), "referenced row survived");
-  assert.ok(rows.some((m) => /new-3/.test(m.content)), "newest row present");
-  const seedRows = rows.filter((m) => /seed-/.test(m.content));
-  // 3 rows were evicted (the inserts pushed 3 past the cap); all evicted rows
-  // must be un-referenced seeds — the referenced rows survived above.
-  assert.equal(seedRows.length, seeds - 3, "exactly 3 oldest un-referenced seeds evicted");
-  assert.ok(!seedRows.some((m) => /seed-0/.test(m.content)), "oldest un-referenced seed evicted");
+  // Use a small env cap for a fast, deterministic LRU check (the production
+  // default is 500; this exercises the same code path).
+  process.env.MEGACOMPACT_MEMORY_MAX_ROWS = "10";
+  try {
+    const dir = join(baseTmp, "lru");
+    const n = 10;
+    const seeds = n - 2;
+    for (let i = 0; i < seeds; i++) addMemory({ content: `seed-${i}`, category: "note" }, null, dir);
+    const keep1 = addMemory({ content: "keep-recent-1", category: "note" }, null, dir);
+    const keep2 = addMemory({ content: "keep-recent-2", category: "note" }, null, dir);
+    // Mark the two as referenced so the LRU eviction spares them (they get a
+    // higher last_referenced than the un-referenced seeds).
+    assert.ok(referenceMemory(keep1, dir), "reference keep1");
+    assert.ok(referenceMemory(keep2, dir), "reference keep2");
+    // Insert 3 more — 3 over the cap across the inserts. The two referenced rows
+    // must survive; only un-referenced (oldest) seeds should be evicted.
+    addMemory({ content: "new-1", category: "note" }, null, dir);
+    addMemory({ content: "new-2", category: "note" }, null, dir);
+    addMemory({ content: "new-3", category: "note" }, null, dir);
+    const rows = listMemories(null, 1000, dir);
+    assert.equal(rows.length, n, "row count clamped to MEMORY_MAX_ROWS");
+    assert.ok(rows.some((m) => /keep-recent-1/.test(m.content)), "referenced row survived");
+    assert.ok(rows.some((m) => /keep-recent-2/.test(m.content)), "referenced row survived");
+    assert.ok(rows.some((m) => /new-3/.test(m.content)), "newest row present");
+    const seedRows = rows.filter((m) => /seed-/.test(m.content));
+    // 3 rows were evicted (the inserts pushed 3 past the cap); all evicted rows
+    // must be un-referenced seeds — the referenced rows survived above.
+    assert.equal(seedRows.length, seeds - 3, "exactly 3 oldest un-referenced seeds evicted");
+    assert.ok(!seedRows.some((m) => /seed-0/.test(m.content)), "oldest un-referenced seed evicted");
+  } finally {
+    delete process.env.MEGACOMPACT_MEMORY_MAX_ROWS;
+  }
+});
+
+test("S24: MEGACOMPACT_MEMORY_MAX_CHARS env override truncates content", () => {
+  process.env.MEGACOMPACT_MEMORY_MAX_CHARS = "50";
+  try {
+    const dir = join(baseTmp, "cap-env");
+    const id = addMemory({ content: "x".repeat(500), category: "note" }, null, dir);
+    const rows = listMemories(null, 50, dir);
+    const row = rows.find((m) => m.id === id);
+    assert.ok(row, "row present");
+    assert.equal(row!.content.length, 50 + "…[truncated]".length, "truncated to env cap + marker");
+    assert.ok(row!.content.endsWith("…[truncated]"), "marker appended");
+  } finally {
+    delete process.env.MEGACOMPACT_MEMORY_MAX_CHARS;
+  }
 });
 
 test("cleanup memops", () => {

package/src/memoryOps.ts

@@ -12,6 +12,24 @@ import {
   removeMemory,
   type MemoryRecord,
 } from "./store/sqlite.js";
+import { defaultEmbedder } from "./embedder.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: string): string | undefined {
+  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: MemoryRecord[], content: string): MemoryRecord | undefined {
@@ -19,6 +37,23 @@ function findByContent(memories: MemoryRecord[], content: string): MemoryRecord
   return memories.find((m) => m.content.trim().toLowerCase() === norm);
 }
 
+/**
+ * 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.
+ */
+function indexMemoryWrite(stateDir: string, memoryId: number, content: string): void {
+  const repoId = resolveRepoRootLocal(stateDir) ?? stateDir;
+  try {
+    const vec = defaultEmbedder().embed(content);
+    void upsertMemoryEmbedding(repoId, memoryId, content, vec);
+  } catch {
+    /* non-fatal — embedding/index failure must never break the SQLite write */
+  }
+}
+
 /**
  * Apply add/replace/remove ops to the memories table. Replaces are matched by
  * existing content; removes by content. Idempotent: an add that already exists
@@ -32,7 +67,7 @@ export async function applyMemoryOps(ops: MemoryOp[], stateDir: string): Promise
     if (op.op === "add") {
       // Skip if an identical memory already exists.
       if (findByContent(existing, op.memory.content)) continue;
-      addMemory(
+      const id = addMemory(
         {
           kind: op.memory.category,
           content: op.memory.content,
@@ -44,6 +79,8 @@ export async function applyMemoryOps(ops: MemoryOp[], stateDir: string): Promise
         repo,
         stateDir,
       );
+      // S24: mirror into the cross-repo index (fire-and-forget; non-fatal).
+      indexMemoryWrite(stateDir, id, op.memory.content);
     } else if (op.op === "replace") {
       const match = findByContent(existing, op.targetContent);
       if (match) {
@@ -53,9 +90,11 @@ export async function applyMemoryOps(ops: MemoryOp[], stateDir: string): Promise
           category: op.memory.category,
           sourceTurn: op.memory.sourceTurn,
         }, stateDir);
+        // S24: re-mirror under the same memory id (fire-and-forget; non-fatal).
+        indexMemoryWrite(stateDir, match.id, op.memory.content);
       } else {
         // Target missing (e.g. earlier in-conversation contradiction) → add.
-        addMemory(
+        const id = addMemory(
           {
             kind: op.memory.category,
             content: op.memory.content,
@@ -66,6 +105,7 @@ export async function applyMemoryOps(ops: MemoryOp[], stateDir: string): Promise
           repo,
           stateDir,
         );
+        indexMemoryWrite(stateDir, id, op.memory.content);
       }
     } else {
       const match = findByContent(existing, op.content);

package/src/memoryRecall.test.ts

@@ -98,3 +98,61 @@ test("recallMemories: fresher reference beats older at equal similarity", async
 test("cleanup memrec", () => {
   rmSync(baseTmp, { recursive: true, force: true });
 });
+
+// ---- S24: cross-repo memory recall (PGlite mirror) ---------------------------
+test("recallMemoriesAndInline: surfaces a memory saved in ANOTHER repo via cross-repo index", async () => {
+  // Isolate the global PGlite index to a temp dir shared by both "repos".
+  process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "xrepo-index");
+  const repoA = join(baseTmp, "repo-a");
+  const repoB = join(baseTmp, "repo-b");
+  try {
+    // repoA owns a decision about the store backend.
+    const { applyMemoryOps } = await import("./memoryOps.js");
+    await applyMemoryOps(
+      [{ op: "add", memory: { content: "we standardized on node:sqlite for the store backend", category: "decision", sourceTurn: 0 } }],
+      repoA,
+    );
+    // repoB is a fresh session with NO local memory about the store backend.
+    const { recallMemoriesAndInline } = await import("./recall.js");
+    const res = await recallMemoriesAndInline({
+      query: "what store backend do we use?",
+      stateDir: repoB,
+      limit: 5,
+      crossRepo: true,
+      crossRepoCosine: 0.3,
+    });
+    assert.ok(!res.empty, "cross-repo recall found the other repo's memory");
+    assert.ok(/node:sqlite/.test(res.block), "the node:sqlite decision was recalled from repo A");
+    assert.ok(res.report.some((r) => /from /.test(r)), "report labels the memory as cross-repo");
+  } 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";
+  const repoA = join(baseTmp, "repo-a2");
+  const repoB = join(baseTmp, "repo-b2");
+  try {
+    const { applyMemoryOps } = await import("./memoryOps.js");
+    await applyMemoryOps(
+      [{ op: "add", memory: { content: "we standardized on node:sqlite for the store backend", category: "decision", sourceTurn: 0 } }],
+      repoA,
+    );
+    const { recallMemoriesAndInline } = await import("./recall.js");
+    const res = await recallMemoriesAndInline({
+      query: "what store backend do we use?",
+      stateDir: repoB,
+      limit: 5,
+      crossRepo: true,
+    });
+    // Index disabled → no cross-repo hit; repoB has no local memory → empty.
+    assert.equal(res.empty, true, "cross-repo recall degrades to empty when disabled");
+  } finally {
+    delete process.env.MEGACOMPACT_PGLITE_DISABLED;
+    delete process.env.MEGACOMPACT_INDEX_DIR;
+  }
+});

package/src/memoryRecall.ts

@@ -81,3 +81,55 @@ export async function recallMemories(
   }
   return top;
 }
+
+/**
+ * Cross-repo memory recall (S24): augments the same-repo `recallMemories` with
+ * HNSW NN over the global PGlite `memory_index` (other repos' memories). Content
+ * is read inline from the index hit (the recall process can't open other repos'
+ * SQLite dirs), so no other-repo db access is required. Returns hits sorted by
+ * descending cosine, above `crossRepoCosine`. De-duped by content against
+ * `sameRepoContent` so we never surface a memory the same-repo scan already has.
+ * Non-fatal: any index failure returns []. Best-effort + PREVENT-PI-004 (local
+ * WASM only).
+ */
+export async function recallMemoriesCrossRepo(
+  query: string,
+  stateDir: string,
+  opts: RecallMemoriesOptions & { crossRepoCosine?: number; limit?: number } = {},
+): Promise<Array<{ memory: MemoryRecord; score: number; repoId: string }>> {
+  const embedder = opts.embedder ?? defaultEmbedder();
+  const queryVec = embedder.embed(query);
+  const { searchMemoriesAsync } = await import("./store/memoryIndex.js");
+  const k = opts.limit ?? 5;
+  const floor = opts.crossRepoCosine ?? 0.3;
+  const hits = await searchMemoriesAsync(queryVec, { k });
+  if (!hits.length) return [];
+  // Mark same-repo content as already-covered so we don't duplicate it.
+  const sameRepo = new Set(
+    listMemories(opts.repo ?? null, 1000, stateDir).map((m) => m.content.trim().toLowerCase()),
+  );
+  const out: Array<{ memory: MemoryRecord; score: number; repoId: string }> = [];
+  for (const h of hits) {
+    if (h.score < floor) continue;
+    if (sameRepo.has(h.content.trim().toLowerCase())) continue;
+    out.push({
+      memory: {
+        id: h.memoryId,
+        repo: h.repoId,
+        kind: "note",
+        content: h.content,
+        tags: [],
+        createdAt: 0,
+        lastRecalledAt: null,
+        category: null,
+        target: null,
+        lastReferenced: null,
+        sourceTurn: null,
+      } as MemoryRecord,
+      score: h.score,
+      repoId: h.repoId,
+    });
+  }
+  out.sort((a, b) => b.score - a.score);
+  return out;
+}

package/src/recall.ts

@@ -159,6 +159,10 @@ export interface MemoryRecallInjectOptions {
   recallMaxTokens?: number;
   /** Cosine threshold; default 0.2. */
   minSimilarity?: number;
+  /** When true, augment same-repo recall with cross-repo PGlite NN (S24). */
+  crossRepo?: boolean;
+  /** Stricter cosine floor for cross-repo memory hits (S24). Default 0.3. */
+  crossRepoCosine?: number;
 }
 
 /** Format one memory hit for the recall block. Category + score for traceability. */
@@ -184,28 +188,49 @@ export async function recallMemoriesAndInline(
 ): Promise<{ empty: boolean; block: string; report: string[] }> {
   const limit = opts.limit ?? 5;
   const maxTokens = opts.recallMaxTokens ?? 0;
-  const { recallMemories } = await import("./memoryRecall.js");
+  const { recallMemories, recallMemoriesCrossRepo } = await import("./memoryRecall.js");
   const hits = await recallMemories(opts.query, opts.stateDir, {
     topK: limit,
     minSimilarity: opts.minSimilarity ?? 0.2,
   });
-  if (hits.length === 0) return { empty: true, block: "", report: [] };
+
+  // S24 cross-repo augmentation: if same-repo recall is thin, pull additional
+  // memories from OTHER repos via the PGlite HNSW index. Non-fatal: a failure
+  // degrades to the same-repo hits only.
+  const crossHits: Array<{ memory: any; score: number; repoId: string }> = [];
+  if (opts.crossRepo && hits.length < limit) {
+    try {
+      const x = await recallMemoriesCrossRepo(opts.query, opts.stateDir, {
+        repo: null,
+        limit: limit - hits.length,
+        crossRepoCosine: opts.crossRepoCosine ?? 0.3,
+      });
+      for (const h of x) crossHits.push(h);
+    } catch {
+      /* non-fatal — cross-repo failure → same-repo only */
+    }
+  }
+  if (hits.length === 0 && crossHits.length === 0) return { empty: true, block: "", report: [] };
 
   // Same incremental token cap pattern as checkpoint recall.
   const parts: string[] = [];
   const report: string[] = [];
   let blockTokens = 0;
-  for (const h of hits) {
-    const part = formatMemoryRecallBlock([
-      { content: h.memory.content, category: h.memory.category, score: h.score },
-    ]);
+  const pushHit = (content: string, category: string | null, score: number, label: string) => {
+    const part = formatMemoryRecallBlock([{ content, category, score }]);
     const partTokens = estimateBlockTokens(part);
-    if (maxTokens > 0 && blockTokens + partTokens > maxTokens) break;
+    if (maxTokens > 0 && blockTokens + partTokens > maxTokens) return false;
     parts.push(part);
-    report.push(
-      `  • memory#${h.memory.id} (${(h.score * 100).toFixed(0)}%): ${h.memory.content.slice(0, 60).replace(/\n/g, " ")}…`,
-    );
+    report.push(`  • ${label} (${(score * 100).toFixed(0)}%): ${content.slice(0, 60).replace(/\n/g, " ")}…`);
     blockTokens += partTokens;
+    return true;
+  };
+  for (const h of hits) {
+    if (!pushHit(h.memory.content, h.memory.category, h.score, `memory#${h.memory.id}`)) break;
+  }
+  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})`)) break;
   }
   return { empty: parts.length === 0, block: parts.join("\n"), report };
 }

package/src/store/memoryIndex.test.ts

@@ -0,0 +1,61 @@
+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 { defaultEmbedder } from "../embedder.js";
+import {
+  upsertMemoryEmbedding,
+  searchMemoriesAsync,
+  initMemoryIndex,
+  closeMemoryIndex,
+  isMemoryIndexDisabled,
+} from "./memoryIndex.js";
+
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-memidx-"));
+
+test("memoryIndex: disabled when MEGACOMPACT_PGLITE_DISABLED", async () => {
+  process.env.MEGACOMPACT_PGLITE_DISABLED = "true";
+  try {
+    assert.equal(isMemoryIndexDisabled(), true, "kill-switch honored");
+    const hits = await searchMemoriesAsync(defaultEmbedder().embed("anything"), { k: 3 });
+    assert.deepEqual(hits, [], "search returns [] when disabled");
+  } finally {
+    delete process.env.MEGACOMPACT_PGLITE_DISABLED;
+  }
+});
+
+test("memoryIndex: cross-repo upsert + NN search returns the right repo's memory", async () => {
+  // Isolate the global PGlite dir so concurrent test runs don't collide.
+  process.env.MEGACOMPACT_INDEX_DIR = join(baseTmp, "index");
+  const repoA = "/tmp/repo-a";
+  const repoB = "/tmp/repo-b";
+  try {
+    await initMemoryIndex();
+    // Two memories in different repos, with clearly distinct content so their
+    // trigram embeddings separate.
+    const vecA = defaultEmbedder().embed("We standardized on node:sqlite for the store backend");
+    const vecB = defaultEmbedder().embed("The deployment target is a raspberry pi in the closet");
+    await upsertMemoryEmbedding(repoA, 1, "We standardized on node:sqlite for the store backend", vecA);
+    await upsertMemoryEmbedding(repoB, 7, "The deployment target is a raspberry pi in the closet", vecB);
+
+    // Query close to A's content → top hit should be A's memory, not B's.
+    const q = defaultEmbedder().embed("standardized node:sqlite store backend choice");
+    const hits = await searchMemoriesAsync(q, { k: 3 });
+    assert.ok(hits.length >= 1, "at least one hit");
+    assert.equal(hits[0].repoId, repoA, "nearest neighbor is repo A");
+    assert.equal(hits[0].memoryId, 1, "correct memory id");
+    assert.ok(hits[0].score > 0.5, "high cosine for the matching memory");
+
+    // Scope to repoB only → A must not appear.
+    const scoped = await searchMemoriesAsync(q, { k: 3, repoId: repoB });
+    assert.ok(scoped.every((h) => h.repoId === repoB), "scoped search stays within repoB");
+  } finally {
+    await closeMemoryIndex();
+    delete process.env.MEGACOMPACT_INDEX_DIR;
+  }
+});
+
+test("memoryIndex: cleanup", () => {
+  rmSync(baseTmp, { recursive: true, force: true });
+});

package/src/store/memoryIndex.ts

@@ -0,0 +1,235 @@
+/**
+ * memoryIndex.ts — cross-repo async vector index for durable memories (S24).
+ *
+ * A REDUNDANT, additive, ASYNC index layered over the authoritative node:sqlite
+ * `memories` table. The same-repo linear cosine scan over the in-repo memories
+ * (src/memoryRecall.ts) stays the DEFAULT recall path; this global PGlite index
+ * exists only to provide real cross-repo nearest-neighbor memory recall — so a
+ * decision you saved in repo A can be inlined as RAG context when you start a
+ * session in repo B. It is best-effort and non-fatal: any init/write failure
+ * degrades to the same-repo scan and must NEVER break memory write, recall, or
+ * extension load.
+ *
+ * PREVENT-PI-004: PGlite is WASM Postgres — fully local, zero network. Memory
+ * remains AUTHORITATIVE in SQLite; this index only holds (repo_id, memory_id,
+ * content, embedding) for NN lookup and is rebuilt from SQLite at any time.
+ *
+ * Topology mirrors vectorIndex.ts (Slice 2): ONE global PGlite DB, `repo_id` is
+ * a first-class column. `searchMemoriesAsync(q, k, {repoId?})` → omit repoId for
+ * cross-repo NN, pass repoId to scope to a single repo. Hit content is stored
+ * inline because the recall process cannot open every other repo's SQLite dir.
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, rmSync, existsSync } from "node:fs";
+
+// PGlite + pgvector are script-free WASM (no native build) → survive pi's
+// install-script block. Imported lazily so a missing/broken package degrades
+// gracefully instead of crashing module load.
+import { PGlite, type PGlite as PGliteInstance } from "@electric-sql/pglite";
+import { vector } from "@electric-sql/pglite-pgvector";
+
+/** Vector dimension produced by the default TrigramEmbedder (src/embedder.ts). */
+export const MEMORY_INDEX_DIM = 512;
+
+/** A single cross-repo memory hit returned by the async index. */
+export interface MemoryIndexHit {
+  repoId: string;
+  memoryId: number;
+  /** Inline content so recall can read it without opening the other repo's db. */
+  content: string;
+  /** Cosine similarity in [0,1] (1 = identical). */
+  score: number;
+}
+
+let db: PGliteInstance | undefined;
+let initPromise: Promise<PGliteInstance | undefined> | undefined;
+let disabled = false;
+let warned = false;
+
+function indexDir(): string {
+  const override = process.env.MEGACOMPACT_INDEX_DIR;
+  if (override && override.trim() !== "") return join(override, "memory");
+  try {
+    return join(homedir(), ".pi", "mega-compact-vector", "memory");
+  } catch {
+    return join("/tmp", ".mega-compact-vector", "memory");
+  }
+}
+
+function logWarn(msg: string): void {
+  // Never throw — degradation is the whole point. One warning per process.
+  if (warned) return;
+  warned = true;
+  try {
+    console.warn(`[mega-compact:memoryIndex] ${msg} (falling back to same-repo scan)`);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Honor the emergency kill-switch (shared with the checkpoint index). */
+export function isMemoryIndexDisabled(): boolean {
+  return (
+    disabled ||
+    process.env.MEGACOMPACT_PGLITE_DISABLED === "true" ||
+    process.env.MEGACOMPACT_PGLITE_DISABLED === "1"
+  );
+}
+
+/**
+ * Lazily open + schema-init the global PGlite DB. Idempotent and safe to call
+ * from many places. Returns undefined when disabled/unavailable so callers can
+ * fall back to the synchronous scan. Never throws.
+ */
+export function initMemoryIndex(): Promise<PGliteInstance | undefined> {
+  if (isMemoryIndexDisabled()) return Promise.resolve(undefined);
+  if (db) return Promise.resolve(db);
+  if (initPromise) return initPromise;
+  initPromise = openPgLite(/* retryOnCorrupt */ true);
+  return initPromise;
+}
+
+/**
+ * Open + schema-init PGlite. When `retryOnCorrupt` is true, a WASM-level abort
+ * (typically from a corrupted/torn data dir) triggers a delete + one retry.
+ */
+async function openPgLite(
+  retryOnCorrupt: boolean,
+): Promise<PGliteInstance | undefined> {
+  try {
+    const dir = indexDir();
+    mkdirSync(dir, { recursive: true });
+    const pg = await new PGlite({
+      dataDir: dir,
+      extensions: { vector },
+    });
+    await pg.exec("CREATE EXTENSION IF NOT EXISTS vector;");
+    await pg.exec(`
+      CREATE TABLE IF NOT EXISTS memory_index (
+        repo_id    TEXT NOT NULL,
+        memory_id  INTEGER NOT NULL,
+        content    TEXT NOT NULL,
+        embedding  vector(${MEMORY_INDEX_DIM}) NOT NULL,
+        PRIMARY KEY (repo_id, memory_id)
+      );
+    `);
+    await pg.exec(
+      "CREATE INDEX IF NOT EXISTS memory_index_hnsw ON memory_index USING hnsw (embedding vector_cosine_ops);",
+    );
+    db = pg;
+    return pg;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (retryOnCorrupt && (msg.includes("Aborted") || msg.includes("RuntimeError"))) {
+      try {
+        const dir = indexDir();
+        if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+        initPromise = undefined;
+        return openPgLite(/* retryOnCorrupt */ false);
+      } catch {
+        /* self-heal failed — fall through to disable */
+      }
+    }
+    disabled = true;
+    logWarn(`init failed: ${msg}`);
+    return undefined;
+  }
+}
+
+function toVectorLiteral(v: number[]): string {
+  const parts = v.map((x) => (Number.isFinite(x) ? x : 0));
+  return `[${parts.join(",")}]`;
+}
+
+/**
+ * Best-effort upsert of one memory embedding into the global index.
+ * Dimension-mismatched vectors (e.g. a BYO embedder with dim ≠ 512) are skipped.
+ * Fire-and-forget: callers must NOT await this on the sync write path. Never
+ * throws. `content` is stored inline so cross-repo recall can read it directly.
+ */
+export async function upsertMemoryEmbedding(
+  repoId: string,
+  memoryId: number,
+  content: string,
+  embedding: number[],
+): Promise<void> {
+  if (isMemoryIndexDisabled()) return;
+  if (!embedding || embedding.length !== MEMORY_INDEX_DIM) return;
+  try {
+    const pg = await initMemoryIndex();
+    if (!pg) return;
+    const lit = toVectorLiteral(embedding);
+    await pg.query(
+      `INSERT INTO memory_index (repo_id, memory_id, content, embedding)
+       VALUES ($1, $2, $3, $4::vector)
+       ON CONFLICT (repo_id, memory_id)
+       DO UPDATE SET content = EXCLUDED.content, embedding = EXCLUDED.embedding;`,
+      [repoId, memoryId, content, lit],
+    );
+  } catch (err) {
+    disabled = true;
+    logWarn(`upsert failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+export interface SearchMemoriesAsyncOpts {
+  /** When provided, scope the NN search to a single repo; omit for cross-repo. */
+  repoId?: string;
+  /** Max hits (default 5). */
+  k?: number;
+}
+
+/**
+ * Cross-repo (or single-repo) HNSW nearest-neighbor memory search. Returns hits
+ * sorted by descending similarity. Never throws — on any failure returns [].
+ */
+export async function searchMemoriesAsync(
+  query: number[],
+  opts: SearchMemoriesAsyncOpts = {},
+): Promise<MemoryIndexHit[]> {
+  if (isMemoryIndexDisabled() || !query || query.length !== MEMORY_INDEX_DIM) return [];
+  const k = opts.k ?? 5;
+  const repoId = opts.repoId;
+  try {
+    const pg = await initMemoryIndex();
+    if (!pg) return [];
+    const lit = toVectorLiteral(query);
+    const params: unknown[] = [lit, k];
+    let sql =
+      "SELECT repo_id, memory_id, content, 1 - (embedding <=> $1::vector) AS score " +
+      "FROM memory_index";
+    if (repoId) {
+      sql += " WHERE repo_id = $3";
+      params.push(repoId);
+    }
+    sql += " ORDER BY embedding <=> $1::vector LIMIT $2";
+    const res = await pg.query(sql, params);
+    return res.rows.map((r: any) => ({
+      repoId: r.repo_id as string,
+      memoryId: Number(r.memory_id),
+      content: r.content as string,
+      score: r.score as number,
+    }));
+  } catch (err) {
+    disabled = true;
+    logWarn(`search failed: ${err instanceof Error ? err.message : String(err)}`);
+    return [];
+  }
+}
+
+/** Close the index (test teardown / shutdown). Safe to call when unopened. */
+export async function closeMemoryIndex(): Promise<void> {
+  if (db) {
+    try {
+      await db.close();
+    } catch {
+      /* ignore */
+    }
+  }
+  db = undefined;
+  initPromise = undefined;
+  disabled = false;
+  warned = false;
+}