gnosys 5.12.2 → 5.13.0

package/dist/index.js

@@ -1752,10 +1752,17 @@ regTool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic
         };
     }
     try {
-        const results = await hybridSearch.hybridSearch(query, limit || 15, mode || "hybrid");
+        const requestedMode = mode || "hybrid";
+        const results = await hybridSearch.hybridSearch(query, limit || 15, requestedMode);
+        // v5.12.3: hybrid used to degrade to keyword-only silently when the
+        // semantic leg can't run (embeddings are only built by gnosys_reindex,
+        // and DB mode also needs the store-local query embedder). Say so loudly.
+        const degradeWarning = requestedMode !== "keyword" && !hybridSearch.canRunSemantic()
+            ? `⚠️ Semantic embeddings unavailable — ${requestedMode} search ran keyword-only. Run gnosys_reindex to build embeddings and enable semantic recall.\n\n`
+            : "";
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No results for "${query}". Try gnosys_reindex to build embeddings, or different keywords.` }],
+                content: [{ type: "text", text: `${degradeWarning}No results for "${query}". Try different keywords.` }],
             };
         }
         const formatted = results
@@ -1774,7 +1781,7 @@ regTool("gnosys_hybrid_search", "Search memories using hybrid keyword + semantic
             content: [
                 {
                     type: "text",
-                    text: `Found ${results.length} results for "${query}" (${embCount} embeddings indexed):\n\n${formatted}`,
+                    text: `${degradeWarning}Found ${results.length} results for "${query}" (${embCount} embeddings indexed):\n\n${formatted}`,
                 },
             ],
         };
@@ -1802,10 +1809,19 @@ regTool("gnosys_semantic_search", "Search memories using semantic similarity onl
         };
     }
     try {
+        // v5.12.3: semantic search without a working semantic leg either
+        // returns nothing or (in DB mode) keyword hits mislabeled as semantic —
+        // refuse with the exact reason instead.
+        if (!hybridSearch.canRunSemantic()) {
+            return {
+                content: [{ type: "text", text: `⚠️ Semantic embeddings unavailable — semantic search cannot run. Run gnosys_reindex to build embeddings, then retry.` }],
+                isError: true,
+            };
+        }
         const results = await hybridSearch.hybridSearch(query, limit || 15, "semantic");
         if (results.length === 0) {
             return {
-                content: [{ type: "text", text: `No semantic results for "${query}". Run gnosys_reindex first to build embeddings.` }],
+                content: [{ type: "text", text: `No semantic results for "${query}". Try a broader query.` }],
             };
         }
         const formatted = results
@@ -1837,11 +1853,18 @@ regTool("gnosys_reindex", "Rebuild all semantic embeddings from every memory fil
         // Also rebuild FTS5 index
         await reindexAllStores();
         const count = await hybridSearch.reindex();
+        // v5.13.0: also (re)build the central-DB embedding column — the
+        // vectors DB-mode hybrid/semantic search actually reads.
+        const dbResult = await hybridSearch.reindexCentralDb();
+        const parts = [`${count} file-store memories embedded`];
+        if (dbResult.total > 0) {
+            parts.push(`${dbResult.embedded}/${dbResult.total} central-DB memories embedded`);
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: `Reindex complete: ${count} memories embedded. Hybrid search is now available.`,
+                    text: `Reindex complete: ${parts.join(", ")}. Hybrid search is now available.`,
                 },
             ],
         };
@@ -3169,6 +3192,14 @@ async function initHeavyDeps() {
     const embeddings = new GnosysEmbeddings(writeTarget.store.getStorePath());
     hybridSearch = new GnosysHybridSearch(search, embeddings, resolver, writeTarget.store.getStorePath(), gnosysDb || undefined);
     askEngine = new GnosysAsk(hybridSearch, config, resolver, writeTarget.store.getStorePath());
+    // v5.13.0: write-time embeddings (serve mode only) — new and updated
+    // memories get vectors without waiting for a manual reindex. Best-effort:
+    // queued writes drain on an unref'd timer and never block a tool call.
+    if (centralDb?.isAvailable() && centralDb.isMigrated()) {
+        const { enableWriteTimeEmbedding } = await import("./lib/embedQueue.js");
+        enableWriteTimeEmbedding(() => centralDb, embeddings);
+        console.error("Write-time embeddings: enabled (central DB)");
+    }
     const embCount = embeddings.hasEmbeddings() ? embeddings.count() : 0;
     console.error(`Hybrid search: ${embCount > 0 ? `ready (${embCount} embeddings)` : "available (run gnosys_reindex to build embeddings)"}`);
     console.error(`Ask engine: ${askEngine.isLLMAvailable ? `ready (${askEngine.providerName}/${askEngine.modelName})` : "disabled (configure LLM provider)"}`);

package/dist/lib/archive.js

@@ -23,6 +23,7 @@ import { statSync } from "fs";
 import { syncMemoryToDb, syncDearchiveToDb } from "./dbWrite.js";
 import { enableWAL } from "./lock.js";
 import { auditLog } from "./audit.js";
+import { ftsTerms, ftsAndQuery, ftsOrQuery } from "./ftsQuery.js";
 // ─── Archive Manager ────────────────────────────────────────────────────
 export class GnosysArchive {
     db = null;
@@ -217,8 +218,8 @@ export class GnosysArchive {
     searchArchive(query, limit = 20) {
         if (!this.db)
             return [];
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         const stmt = this.db.prepare(`
       SELECT
@@ -235,7 +236,12 @@ export class GnosysArchive {
       LIMIT ?
     `);
         try {
-            return stmt.all(safeQuery, limit);
+            // v5.12.3: AND first (precision), OR retry when AND finds nothing —
+            // multi-word queries previously required every term to match.
+            const results = stmt.all(ftsAndQuery(terms), limit);
+            if (results.length > 0 || terms.length === 1)
+                return results;
+            return stmt.all(ftsOrQuery(terms), limit);
         }
         catch {
             // FTS5 query syntax failed — try LIKE fallback
@@ -251,7 +257,7 @@ export class GnosysArchive {
         WHERE content LIKE ? OR title LIKE ? OR tags LIKE ?
         LIMIT ?
       `);
-            const pattern = `%${safeQuery}%`;
+            const pattern = `%${terms.join(" ")}%`;
             return likeStmt.all(pattern, pattern, pattern, limit);
         }
     }

package/dist/lib/db.d.ts

@@ -317,6 +317,21 @@ export declare class GnosysDB {
         operation?: string;
         limit?: number;
     }): DbAuditEntry[];
+    /**
+     * v5.13.0: rows needed to (re)build the embedding column. All tiers and
+     * statuses are included — matching FTS, which indexes every row and
+     * filters at query time. Newest-first so capped backfills prioritize
+     * recent memories.
+     */
+    getMemoriesForEmbedding(mode: "missing" | "all", limit?: number): Array<{
+        id: string;
+        title: string;
+        relevance: string | null;
+        tags: string;
+        content: string;
+    }>;
+    /** v5.13.0: memories whose embedding column is NULL (embedding-health check). */
+    countMemoriesMissingEmbedding(): number;
     updateEmbedding(id: string, embedding: Buffer): void;
     getEmbedding(id: string): Buffer | null;
     getAllEmbeddings(): Array<{

package/dist/lib/db.js

@@ -21,6 +21,7 @@ import { enableWAL } from "./lock.js";
 import { getGnosysHome as getGnosysHomeImpl, getCentralDbPath as getCentralDbPathImpl } from "./paths.js";
 import { readMachineConfig } from "./machineConfig.js";
 import { logError } from "./log.js";
+import { ftsTerms, ftsAndQuery, ftsOrQuery } from "./ftsQuery.js";
 import { ulid } from "ulidx";
 // ─── Schema ─────────────────────────────────────────────────────────────
 const SCHEMA_VERSION = 5;
@@ -1088,27 +1089,33 @@ export class GnosysDB {
     }
     // ─── FTS5 Search ────────────────────────────────────────────────────
     searchFts(query, limit = 20) {
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         // v5.8.0 (#7): join memories so callers can render project-prefixed IDs.
         return this.withRecovery(() => {
             try {
-                return this.prep(`
-        SELECT m.id AS id, m.title AS title,
-               snippet(memories_fts, 5, '>>>', '<<<', '...', 40) as snippet,
-               fts.rank AS rank,
-               m.project_id AS project_id
-        FROM memories_fts fts
-        JOIN memories m ON m.id = fts.id
-        WHERE memories_fts MATCH ?
-        ORDER BY fts.rank
-        LIMIT ?
-      `).all(safeQuery, limit);
+                const run = (match) => this.prep(`
+          SELECT m.id AS id, m.title AS title,
+                 snippet(memories_fts, 5, '>>>', '<<<', '...', 40) as snippet,
+                 fts.rank AS rank,
+                 m.project_id AS project_id
+          FROM memories_fts fts
+          JOIN memories m ON m.id = fts.id
+          WHERE memories_fts MATCH ?
+          ORDER BY fts.rank
+          LIMIT ?
+        `).all(match, limit);
+                // v5.12.3: AND first (precision), OR retry when AND finds nothing —
+                // multi-word queries previously required every term to match.
+                const results = run(ftsAndQuery(terms));
+                if (results.length > 0 || terms.length === 1)
+                    return results;
+                return run(ftsOrQuery(terms));
             }
             catch {
                 // FTS5 syntax error — fallback to LIKE
-                const pattern = `%${safeQuery}%`;
+                const pattern = `%${terms.join(" ")}%`;
                 return this.prep(`
         SELECT id, title, substr(content, 1, 200) as snippet, 0 as rank, project_id
         FROM memories WHERE content LIKE ? OR title LIKE ? OR tags LIKE ?
@@ -1118,8 +1125,8 @@ export class GnosysDB {
         });
     }
     discoverFts(query, limit = 20) {
-        const safeQuery = query.replace(/['"]/g, "").trim();
-        if (!safeQuery)
+        const terms = ftsTerms(query);
+        if (terms.length === 0)
             return [];
         // v5.7.1 (#14): join `memories` so callers can render project-prefixed IDs.
         const select = `
@@ -1130,26 +1137,37 @@ export class GnosysDB {
       ORDER BY fts.rank
       LIMIT ?
     `;
-        return this.withRecovery(() => {
+        // Let corruption escape to withRecovery (reopen + retry); plain FTS
+        // syntax failures still degrade gracefully to "no results".
+        const tryRun = (match) => {
             try {
-                const colQuery = `{relevance title tags} : ${safeQuery}`;
-                const results = this.prep(select).all(colQuery, limit);
-                if (results.length > 0)
-                    return results;
-                return this.prep(select).all(safeQuery, limit);
+                return this.prep(select).all(match, limit);
             }
-            catch {
-                try {
-                    return this.prep(select).all(safeQuery, limit);
-                }
-                catch (err) {
-                    // Let corruption escape to withRecovery (reopen + retry); plain FTS
-                    // syntax failures still degrade gracefully to "no results".
-                    if (GnosysDB.isCorruptionError(err))
-                        throw err;
-                    return [];
-                }
+            catch (err) {
+                if (GnosysDB.isCorruptionError(err))
+                    throw err;
+                return [];
             }
+        };
+        // v5.12.3: precision-to-recall ladder. AND on the metadata columns,
+        // AND anywhere, then OR retries — multi-word queries previously
+        // required every term to match, so long queries returned nothing.
+        // Parens scope the column filter to the whole expression (a bare
+        // `{cols} : a b` only filtered the first term).
+        const colScoped = (expr) => `{relevance title tags} : (${expr})`;
+        const andExpr = ftsAndQuery(terms);
+        return this.withRecovery(() => {
+            let results = tryRun(colScoped(andExpr));
+            if (results.length > 0)
+                return results;
+            results = tryRun(andExpr);
+            if (results.length > 0 || terms.length === 1)
+                return results;
+            const orExpr = ftsOrQuery(terms);
+            results = tryRun(colScoped(orExpr));
+            if (results.length > 0)
+                return results;
+            return tryRun(orExpr);
         });
     }
     // ─── Relationships ──────────────────────────────────────────────────
@@ -1235,9 +1253,51 @@ export class GnosysDB {
         });
     }
     // ─── Embeddings ─────────────────────────────────────────────────────
+    /**
+     * v5.13.0: rows needed to (re)build the embedding column. All tiers and
+     * statuses are included — matching FTS, which indexes every row and
+     * filters at query time. Newest-first so capped backfills prioritize
+     * recent memories.
+     */
+    getMemoriesForEmbedding(mode, limit) {
+        const where = mode === "missing" ? "WHERE embedding IS NULL" : "";
+        const lim = limit && limit > 0 ? ` LIMIT ${Math.floor(limit)}` : "";
+        return this.withRecovery(() => this.prep(`SELECT id, title, relevance, tags, content FROM memories ${where} ORDER BY modified DESC${lim}`).all());
+    }
+    /** v5.13.0: memories whose embedding column is NULL (embedding-health check). */
+    countMemoriesMissingEmbedding() {
+        return this.withRecovery(() => {
+            const row = this.prep("SELECT COUNT(*) as cnt FROM memories WHERE embedding IS NULL").get();
+            return row.cnt;
+        });
+    }
     updateEmbedding(id, embedding) {
         this.withRecovery(() => {
-            this.db.prepare("UPDATE memories SET embedding = ? WHERE id = ?").run(embedding, id);
+            const sql = "UPDATE memories SET embedding = ? WHERE id = ?";
+            try {
+                this.db.prepare(sql).run(embedding, id);
+            }
+            catch {
+                // v5.13.0: same failure mode updateMemory works around — the FTS5
+                // AFTER UPDATE trigger's 'delete' command errors on standalone FTS5
+                // tables. embedding isn't an FTS column, so drop the trigger,
+                // update, recreate; the FTS entry itself needs no rebuild.
+                this.db.exec("DROP TRIGGER IF EXISTS memories_fts_au");
+                this.db.prepare(sql).run(embedding, id);
+                try {
+                    this.db.exec(`
+            CREATE TRIGGER IF NOT EXISTS memories_fts_au AFTER UPDATE ON memories BEGIN
+              INSERT INTO memories_fts(memories_fts, id, title, category, tags, relevance, content, summary)
+              VALUES ('delete', old.id, old.title, old.category, old.tags, old.relevance, old.content, old.summary);
+              INSERT INTO memories_fts(id, title, category, tags, relevance, content, summary)
+              VALUES (new.id, new.title, new.category, new.tags, new.relevance, new.content, new.summary);
+            END;
+          `);
+                }
+                catch {
+                    // Trigger recreation failed — not critical
+                }
+            }
         });
     }
     getEmbedding(id) {

package/dist/lib/dbWrite.js

@@ -14,6 +14,7 @@
  * become optional — controlled by config.
  */
 import { fnv1a } from "./db.js";
+import { queueMemoryEmbedding } from "./embedQueue.js";
 /** Coerce Date objects (from gray-matter parsing) to ISO date strings. */
 function toDateStr(value) {
     if (value instanceof Date)
@@ -61,6 +62,9 @@ export function syncMemoryToDb(db, frontmatter, content, sourcePath, projectId,
         project_id: projectId || null,
         scope: scope || "project",
     });
+    // v5.13.0: best-effort write-time embedding (no-op unless the MCP server
+    // enabled the queue). Never blocks or fails the write.
+    queueMemoryEmbedding(frontmatter.id);
 }
 /**
  * Sync a memory update to gnosys.db after it's been updated in .md.
@@ -113,6 +117,14 @@ export function syncUpdateToDb(db, id, updates, newContent) {
     }
     dbUpdates.modified = new Date().toISOString().split("T")[0];
     db.updateMemory(id, dbUpdates);
+    // v5.13.0: re-embed when searchable text changed (title/content/tags/
+    // relevance feed the embedding recipe). No-op unless the queue is enabled.
+    if (newContent !== undefined ||
+        updates.title !== undefined ||
+        updates.tags !== undefined ||
+        updates.relevance !== undefined) {
+        queueMemoryEmbedding(id);
+    }
 }
 /**
  * Sync an archive operation to gnosys.db.

package/dist/lib/dream.d.ts

@@ -79,6 +79,12 @@ export interface DreamReport {
     llmCalls?: DreamLLMCallRecord[];
     totals?: DreamRunRecord["totals"];
     effectiveness?: DreamEffectivenessRecord;
+    /** v5.13.0: embedding coverage found/repaired by the embedding-health phase. */
+    embeddingHealth?: {
+        total: number;
+        missingBefore: number;
+        embedded: number;
+    };
 }
 export interface ReviewSuggestion {
     memoryId: string;
@@ -99,9 +105,12 @@ export declare class GnosysDreamEngine {
     private dreamState;
     private pendingFingerprints;
     private llmCallsMade;
+    /** v5.13.0: explicit dream-state dir (defense against test pollution of ~/.gnosys). */
+    private stateDir?;
     constructor(db: GnosysDB, config: GnosysConfig, dreamConfig?: Partial<DreamConfig>, options?: {
         trigger?: DreamTrigger;
         machineId?: string;
+        stateDir?: string;
     });
     /** Captured at construction if getLLMProvider throws. Used in dream() to write a Layer 2 audit entry. */
     private providerInitError;

package/dist/lib/dream.js

@@ -23,6 +23,7 @@ import { createProvider } from "./llm.js";
 import { notifyDesktop } from "./desktopNotify.js";
 import { syncConfidenceToDb, auditToDb } from "./dbWrite.js";
 import { logError } from "./log.js";
+import { getGnosysHome } from "./paths.js";
 import { estimateCost, acquireDreamLock, estimateTokens, fingerprintMemories, memoryWatermark, readDreamState, writeDreamState, } from "./dreamRunLog.js";
 /** Layer 4 alert threshold: fire desktop notification at this many consecutive provider failures. */
 const DREAM_FAILURE_NOTIFY_THRESHOLD = 3;
@@ -44,6 +45,9 @@ export const DEFAULT_DREAM_CONFIG = {
 };
 // ─── Decay Constants ─────────────────────────────────────────────────────
 const DECAY_LAMBDA = 0.005;
+// v5.13.0: embedding-health backfill cap per dream run. Bounds idle-time
+// work (~128-row batches, local model) — large gaps close over a few runs.
+const EMBEDDING_BACKFILL_MAX_PER_RUN = 512;
 const STALE_THRESHOLD = 0.3;
 // ─── Dream Engine ────────────────────────────────────────────────────────
 export class GnosysDreamEngine {
@@ -55,9 +59,11 @@ export class GnosysDreamEngine {
     startTime = 0;
     trigger;
     machineId;
-    dreamState = readDreamState();
+    dreamState;
     pendingFingerprints = {};
     llmCallsMade = 0;
+    /** v5.13.0: explicit dream-state dir (defense against test pollution of ~/.gnosys). */
+    stateDir;
     constructor(db, config, dreamConfig, options) {
         this.db = db;
         this.config = config;
@@ -68,6 +74,8 @@ export class GnosysDreamEngine {
         };
         this.trigger = options?.trigger ?? "manual";
         this.machineId = options?.machineId;
+        this.stateDir = options?.stateDir;
+        this.dreamState = readDreamState(this.stateDir);
         // Initialize LLM provider for dream operations.
         // v5.4.2: Failure here is no longer silent — when dream tries to actually
         // run (in dream()), we record the unavailability to audit_log so the
@@ -128,7 +136,7 @@ export class GnosysDreamEngine {
                     ...this.dreamState.analyzedFingerprints,
                     ...this.pendingFingerprints,
                 },
-            });
+            }, this.stateDir);
         }
         catch {
             // Best-effort: a failed checkpoint only costs re-analysis on resume.
@@ -261,7 +269,7 @@ export class GnosysDreamEngine {
         this.llmCallsMade = 0;
         this.llmCalls = [];
         this.pendingFingerprints = {};
-        this.dreamState = readDreamState();
+        this.dreamState = readDreamState(this.stateDir);
         const log = onProgress || (() => { });
         const startedAt = new Date().toISOString();
         const report = {
@@ -368,6 +376,92 @@ export class GnosysDreamEngine {
             report.abortReason = check.reason;
             return this.finalize(report);
         }
+        // ─── Phase 1.5: Embedding Health (v5.13.0) ───────────────────────────
+        // Semantic search reads memories.embedding; writes only best-effort
+        // embed. Dream is the safety net: report coverage and backfill missing
+        // vectors during idle time. No LLM involved — local embedding model.
+        {
+            log("embedding-health", "Phase 1.5: Embedding health check...");
+            const embedPhase = this.createPhase("embedding-health");
+            const embedStart = Date.now();
+            report.phases.push(embedPhase);
+            try {
+                const total = this.db.getMemoryCount().total;
+                const missingBefore = this.db.countMemoriesMissingEmbedding();
+                const embeddedCount = this.db.getEmbeddingCount();
+                if (missingBefore === 0) {
+                    embedPhase.status = "skipped";
+                    embedPhase.reason = "all memories embedded";
+                    report.embeddingHealth = { total, missingBefore: 0, embedded: 0 };
+                    log("embedding-health", `All ${total} memories embedded`);
+                }
+                else if (embeddedCount === 0) {
+                    // Embeddings never initialized on this install — that's an explicit
+                    // user choice (reindex downloads the 80 MB model); Dream repairs
+                    // drift, it doesn't opt users in. Report it loudly and move on.
+                    embedPhase.status = "skipped";
+                    embedPhase.reason = "embeddings not initialized — run gnosys_reindex";
+                    report.embeddingHealth = { total, missingBefore, embedded: 0 };
+                    auditToDb(this.db, "dream_embedding_health", undefined, {
+                        missing: missingBefore,
+                        total,
+                        initialized: false,
+                    });
+                    log("embedding-health", `${missingBefore}/${total} memories lack embeddings — run gnosys_reindex to enable semantic search`);
+                }
+                else {
+                    auditToDb(this.db, "dream_embedding_health", undefined, {
+                        missing: missingBefore,
+                        total,
+                        initialized: true,
+                    });
+                    const { backfillCentralDbEmbeddings } = await import("./embedDb.js");
+                    const { GnosysEmbeddings } = await import("./embeddings.js");
+                    // Model-only use — we never touch the embedder's store-local db.
+                    const embedder = new GnosysEmbeddings(getGnosysHome());
+                    let embedded = 0;
+                    try {
+                        // Chunked so shouldStop() (abort / max-runtime) is honored
+                        // between batches; capped per run to bound idle-time work.
+                        while (embedded < EMBEDDING_BACKFILL_MAX_PER_RUN) {
+                            if (this.shouldStop().stop)
+                                break;
+                            const chunk = Math.min(128, EMBEDDING_BACKFILL_MAX_PER_RUN - embedded);
+                            const result = await backfillCentralDbEmbeddings(this.db, embedder, {
+                                mode: "missing",
+                                limit: chunk,
+                            });
+                            embedded += result.embedded;
+                            if (result.embedded === 0)
+                                break;
+                        }
+                    }
+                    finally {
+                        embedder.close();
+                    }
+                    report.embeddingHealth = { total, missingBefore, embedded };
+                    if (embedded > 0) {
+                        auditToDb(this.db, "dream_embedding_backfill", undefined, {
+                            embedded,
+                            remaining: missingBefore - embedded,
+                        });
+                    }
+                    log("embedding-health", `Embedded ${embedded}/${missingBefore} missing (${total} total)`);
+                }
+            }
+            catch (err) {
+                report.errors.push(`Embedding health: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            finally {
+                this.finishPhase(embedPhase, embedStart);
+            }
+            check = this.shouldStop();
+            if (check.stop) {
+                report.aborted = true;
+                report.abortReason = check.reason;
+                return this.finalize(report);
+            }
+        }
         // ─── Phase 2: Self-Critique (Review Suggestions) ─────────────────────
         if (this.dreamConfig.selfCritique) {
             log("critique", "Phase 2: Self-critique...");
@@ -487,7 +581,7 @@ export class GnosysDreamEngine {
                 ...this.dreamState.analyzedFingerprints,
                 ...this.pendingFingerprints,
             },
-        });
+        }, this.stateDir);
         // v5.4.2: A run is considered "successful with LLM work" if any of the
         // LLM-dependent counters moved. Resetting the consecutive-failure count
         // here ensures Layer 4 doesn't keep firing once dream is healthy again.

package/dist/lib/dreamRunLog.d.ts

@@ -9,7 +9,7 @@ export interface DreamRunGateResult {
     details?: Record<string, unknown>;
 }
 export interface DreamRunPhaseRecord {
-    name: "decay" | "critique" | "summaries" | "relationships";
+    name: "decay" | "embedding-health" | "critique" | "summaries" | "relationships";
     status: "ran" | "skipped";
     reason?: string;
     durationMs: number;
@@ -86,7 +86,7 @@ export interface DreamReadOptions {
     status?: DreamRunStatus;
 }
 export declare function getDreamRunsPath(): string;
-export declare function getDreamStatePath(): string;
+export declare function getDreamStatePath(baseDir?: string): string;
 export declare function getDreamLockPath(): string;
 export declare function acquireDreamLock(depth?: number): {
     acquired: true;
@@ -97,8 +97,8 @@ export declare function acquireDreamLock(depth?: number): {
 };
 export declare function estimateTokens(text: string): number;
 export declare function estimateCost(model: string | undefined, inputTokens: number, outputTokens: number): number;
-export declare function readDreamState(): DreamState;
-export declare function writeDreamState(state: DreamState): void;
+export declare function readDreamState(baseDir?: string): DreamState;
+export declare function writeDreamState(state: DreamState, baseDir?: string): void;
 export declare function appendDreamRun(record: DreamRunRecord): void;
 export declare function readDreamRuns(opts?: DreamReadOptions): DreamRunRecord[];
 export declare function fingerprintMemories(kind: "summary" | "critique" | "relationship", memories: DbMemory[]): string;

package/dist/lib/dreamRunLog.js

@@ -20,8 +20,11 @@ const MODEL_PRICES_USD_PER_MILLION = {
 export function getDreamRunsPath() {
     return path.join(getGnosysHome(), "dream-runs.jsonl");
 }
-export function getDreamStatePath() {
-    return path.join(getGnosysHome(), "dream-state.json");
+// v5.13.0: baseDir injection (defense in depth against test pollution) —
+// in-process engines can target an explicit state dir instead of the
+// developer's real ~/.gnosys.
+export function getDreamStatePath(baseDir) {
+    return path.join(baseDir || getGnosysHome(), "dream-state.json");
 }
 export function getDreamLockPath() {
     return path.join(getGnosysHome(), "dream.lock");
@@ -103,9 +106,9 @@ export function estimateCost(model, inputTokens, outputTokens) {
     const cost = (inputTokens / 1_000_000) * fuzzy.input + (outputTokens / 1_000_000) * fuzzy.output;
     return Math.round(cost * 1_000_000) / 1_000_000;
 }
-export function readDreamState() {
+export function readDreamState(baseDir) {
     try {
-        const raw = fs.readFileSync(getDreamStatePath(), "utf8");
+        const raw = fs.readFileSync(getDreamStatePath(baseDir), "utf8");
         const parsed = JSON.parse(raw);
         return {
             ...DEFAULT_STATE,
@@ -117,8 +120,8 @@ export function readDreamState() {
         return { ...DEFAULT_STATE };
     }
 }
-export function writeDreamState(state) {
-    const file = getDreamStatePath();
+export function writeDreamState(state, baseDir) {
+    const file = getDreamStatePath(baseDir);
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, `${JSON.stringify(state, null, 2)}\n`, "utf8");
 }

package/dist/lib/embedDb.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Central-DB embedding utilities (v5.13.0).
+ *
+ * GnosysDbSearch reads vectors from the memories.embedding column of
+ * gnosys.db, but before v5.13.0 nothing ever wrote that column: the
+ * reindex flow embedded file-store memories into the store-local
+ * embeddings.db, so DB-mode hybrid search could never run its semantic
+ * leg. This module owns the column — full backfill for reindex,
+ * missing-only backfill for Dream/maintenance, and single-memory
+ * embedding for the write-time queue.
+ *
+ * Embeddings are derived, rebuildable data: regenerating them is always
+ * safe, and a sync snapshot refresh replacing them is not a loss.
+ */
+import type { GnosysDB } from "./db.js";
+import type { GnosysEmbeddings } from "./embeddings.js";
+/** Row fields needed to build embedding text. */
+export interface EmbeddableMemoryRow {
+    id: string;
+    title: string;
+    relevance: string | null;
+    tags: string;
+    content: string;
+}
+/**
+ * The text recipe — identical to the file-store reindex in hybridSearch.ts
+ * (title, relevance keywords, tags, content) so query-vs-document
+ * similarity behaves the same in both modes.
+ */
+export declare function embeddingText(m: EmbeddableMemoryRow): string;
+/** View a Float32Array as the Buffer shape memories.embedding stores. */
+export declare function float32ToBuffer(vec: Float32Array): Buffer;
+/**
+ * (Re)build the memories.embedding column.
+ *
+ * mode "all" regenerates every memory (reindex semantics); "missing" only
+ * fills NULL rows (write-gap backfill for Dream/maintenance, newest first).
+ * Batched through embedBatch for model efficiency.
+ */
+export declare function backfillCentralDbEmbeddings(db: GnosysDB, embeddings: GnosysEmbeddings, opts?: {
+    mode?: "missing" | "all";
+    batchSize?: number;
+    limit?: number;
+    onProgress?: (current: number, total: number, id: string) => void;
+}): Promise<{
+    embedded: number;
+    total: number;
+}>;
+/**
+ * Embed one memory and store its vector. Returns false if the memory
+ * doesn't exist; throws on embedder failure — callers decide how loud.
+ */
+export declare function embedMemoryIntoDb(db: GnosysDB, embeddings: GnosysEmbeddings, id: string): Promise<boolean>;