gnosys 5.12.3 → 5.13.0

package/dist/index.js

@@ -1853,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.`,
                 },
             ],
         };
@@ -3185,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/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

@@ -1253,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>;

package/dist/lib/embedDb.js

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function embeddingText(m) {
+    let tags = m.tags || "";
+    try {
+        const parsed = JSON.parse(tags);
+        if (Array.isArray(parsed)) {
+            tags = parsed.join(" ");
+        }
+        else if (parsed && typeof parsed === "object") {
+            tags = Object.values(parsed).flat().join(" ");
+        }
+    }
+    catch {
+        // already a plain string
+    }
+    return `${m.title}\n${m.relevance || ""}\n${tags}\n${m.content}`;
+}
+/** View a Float32Array as the Buffer shape memories.embedding stores. */
+export function float32ToBuffer(vec) {
+    return Buffer.from(vec.buffer, vec.byteOffset, vec.byteLength);
+}
+/**
+ * (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 async function backfillCentralDbEmbeddings(db, embeddings, opts = {}) {
+    if (!db.isAvailable() || !db.isMigrated())
+        return { embedded: 0, total: 0 };
+    const rows = db.getMemoriesForEmbedding(opts.mode || "missing", opts.limit);
+    const total = rows.length;
+    if (total === 0)
+        return { embedded: 0, total: 0 };
+    const batchSize = opts.batchSize || 32;
+    let embedded = 0;
+    for (let i = 0; i < rows.length; i += batchSize) {
+        const batch = rows.slice(i, i + batchSize);
+        const vectors = await embeddings.embedBatch(batch.map(embeddingText));
+        for (let j = 0; j < batch.length; j++) {
+            db.updateEmbedding(batch[j].id, float32ToBuffer(vectors[j]));
+            embedded++;
+            opts.onProgress?.(embedded, total, batch[j].id);
+        }
+    }
+    return { embedded, total };
+}
+/**
+ * Embed one memory and store its vector. Returns false if the memory
+ * doesn't exist; throws on embedder failure — callers decide how loud.
+ */
+export async function embedMemoryIntoDb(db, embeddings, id) {
+    const mem = db.getMemory(id);
+    if (!mem)
+        return false;
+    const vec = await embeddings.embed(embeddingText({
+        id: mem.id,
+        title: mem.title,
+        relevance: mem.relevance,
+        tags: mem.tags,
+        content: mem.content,
+    }));
+    db.updateEmbedding(id, float32ToBuffer(vec));
+    return true;
+}

package/dist/lib/embedQueue.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Write-time embedding queue (v5.13.0).
+ *
+ * Keeps memories.embedding fresh as memories are written, so semantic
+ * search doesn't drift stale between reindexes. Disabled by default —
+ * the MCP server enables it once its long-lived central-DB handle and
+ * embeddings instance exist. CLI one-shot processes stay disabled (they
+ * exit before the model could load) and rely on reindex / Dream backfill.
+ *
+ * Contract: a memory write must NEVER block on or fail because of
+ * embedding. queueMemoryEmbedding returns immediately; the drain runs on
+ * an unref'd timer, lazily imports the embedder path, logs at most one
+ * stderr warning per process on failure, and drops rather than retries.
+ */
+import type { GnosysDB } from "./db.js";
+import type { GnosysEmbeddings } from "./embeddings.js";
+/** Turn on write-time embedding (serve mode). Getter is called at drain time. */
+export declare function enableWriteTimeEmbedding(dbGetter: () => GnosysDB | null, embeddings: GnosysEmbeddings): void;
+/** Turn off and clear the queue (tests, shutdown). */
+export declare function disableWriteTimeEmbedding(): void;
+export declare function isWriteTimeEmbeddingEnabled(): boolean;
+/**
+ * Queue a memory for embedding. No-op unless enabled. Never throws,
+ * never blocks — safe to call from any write path.
+ */
+export declare function queueMemoryEmbedding(id: string): void;
+/** Await in-flight embedding work. Used by tests and graceful shutdown. */
+export declare function flushWriteTimeEmbeddings(): Promise<void>;

package/dist/lib/embedQueue.js

@@ -0,0 +1,80 @@
+/**
+ * Write-time embedding queue (v5.13.0).
+ *
+ * Keeps memories.embedding fresh as memories are written, so semantic
+ * search doesn't drift stale between reindexes. Disabled by default —
+ * the MCP server enables it once its long-lived central-DB handle and
+ * embeddings instance exist. CLI one-shot processes stay disabled (they
+ * exit before the model could load) and rely on reindex / Dream backfill.
+ *
+ * Contract: a memory write must NEVER block on or fail because of
+ * embedding. queueMemoryEmbedding returns immediately; the drain runs on
+ * an unref'd timer, lazily imports the embedder path, logs at most one
+ * stderr warning per process on failure, and drops rather than retries.
+ */
+let getDb = null;
+let embedder = null;
+const pending = new Set();
+let drainPromise = null;
+let warnedOnce = false;
+/** Turn on write-time embedding (serve mode). Getter is called at drain time. */
+export function enableWriteTimeEmbedding(dbGetter, embeddings) {
+    getDb = dbGetter;
+    embedder = embeddings;
+}
+/** Turn off and clear the queue (tests, shutdown). */
+export function disableWriteTimeEmbedding() {
+    getDb = null;
+    embedder = null;
+    pending.clear();
+}
+export function isWriteTimeEmbeddingEnabled() {
+    return getDb !== null && embedder !== null;
+}
+/**
+ * Queue a memory for embedding. No-op unless enabled. Never throws,
+ * never blocks — safe to call from any write path.
+ */
+export function queueMemoryEmbedding(id) {
+    if (!getDb || !embedder || !id)
+        return;
+    pending.add(id);
+    if (!drainPromise) {
+        drainPromise = new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                drain().finally(() => {
+                    drainPromise = null;
+                    resolve();
+                });
+            }, 25);
+            timer.unref?.();
+        });
+    }
+}
+/** Await in-flight embedding work. Used by tests and graceful shutdown. */
+export async function flushWriteTimeEmbeddings() {
+    while (drainPromise) {
+        await drainPromise;
+    }
+}
+async function drain() {
+    while (pending.size > 0) {
+        const id = pending.values().next().value;
+        pending.delete(id);
+        const db = getDb?.();
+        if (!db || !embedder)
+            return;
+        try {
+            const { embedMemoryIntoDb } = await import("./embedDb.js");
+            await embedMemoryIntoDb(db, embedder, id);
+        }
+        catch (err) {
+            if (!warnedOnce) {
+                warnedOnce = true;
+                console.error(`Gnosys: write-time embedding failed (${err instanceof Error ? err.message : err}). ` +
+                    `New memories will be embedded by the next gnosys_reindex or Dream run instead.`);
+            }
+            return; // drop this round; anything still pending waits for the next queue call
+        }
+    }
+}

package/dist/lib/hybridSearch.d.ts

@@ -20,6 +20,8 @@ export declare class GnosysHybridSearch {
     private storePath;
     /** v2.0: When set, hybrid search uses SQLite directly */
     private dbSearch;
+    /** v5.13.0: kept for central-DB embedding backfill (reindexCentralDb) */
+    private gnosysDb;
     constructor(search: GnosysSearch, embeddings: GnosysEmbeddings, resolver: GnosysResolver, storePath: string, gnosysDb?: GnosysDB);
     /**
      * Main hybrid search entry point.
@@ -48,6 +50,17 @@ export declare class GnosysHybridSearch {
      * Returns count of files indexed.
      */
     reindex(onProgress?: (current: number, total: number, filePath: string) => void): Promise<number>;
+    /**
+     * v5.13.0: (re)build the central-DB memories.embedding column — the
+     * vectors GnosysDbSearch actually reads. Before this, reindex only
+     * embedded file-store memories into the store-local embeddings.db, so
+     * DB-mode semantic search could never activate. Returns counts; no-op
+     * ({0,0}) when no migrated central DB is attached.
+     */
+    reindexCentralDb(onProgress?: (current: number, total: number, id: string) => void): Promise<{
+        embedded: number;
+        total: number;
+    }>;
     /**
      * Load full content for search results (used by Ask engine).
      * Handles both active memories and archived memories.
@@ -59,11 +72,10 @@ export declare class GnosysHybridSearch {
     hasEmbeddings(): boolean;
     /**
      * True when hybrid/semantic search can actually run its semantic leg.
-     * In DB mode this requires BOTH stored vectors in the central DB and the
-     * store-local embeddings.db used to embed the query text — the central
-     * count alone can be non-zero on a machine that only syncs gnosys.db,
-     * in which case hybridSearch() silently runs keyword-only (embedQuery
-     * is never constructed).
+     * Mirrors the embedQuery gate in hybridSearch(): in DB mode, stored
+     * central-DB vectors are what matter (the query embedder loads the
+     * local model on demand); in legacy file mode, the store-local
+     * embeddings.db must be populated.
      */
     canRunSemantic(): boolean;
     /**

package/dist/lib/hybridSearch.js

@@ -19,6 +19,8 @@ export class GnosysHybridSearch {
     storePath;
     /** v2.0: When set, hybrid search uses SQLite directly */
     dbSearch = null;
+    /** v5.13.0: kept for central-DB embedding backfill (reindexCentralDb) */
+    gnosysDb = null;
     constructor(search, embeddings, resolver, storePath, gnosysDb) {
         this.search = search;
         this.embeddings = embeddings;
@@ -27,6 +29,7 @@ export class GnosysHybridSearch {
         // v2.0: If GnosysDB is migrated, create a DB search adapter
         if (gnosysDb?.isAvailable() && gnosysDb?.isMigrated()) {
             this.dbSearch = new GnosysDbSearch(gnosysDb);
+            this.gnosysDb = gnosysDb;
         }
     }
     /**
@@ -36,7 +39,11 @@ export class GnosysHybridSearch {
     async hybridSearch(query, limit = 15, mode = "hybrid") {
         // v2.0 DB-backed fast path: run entirely from gnosys.db
         if (this.dbSearch) {
-            const embedQuery = this.embeddings.hasEmbeddings()
+            // v5.13.0: gate the semantic leg on stored central-DB vectors — the
+            // query embedder loads the local model on demand, so the store-local
+            // embeddings.db (the old gate) is irrelevant in DB mode. A machine
+            // that only syncs gnosys.db gets semantic search once vectors exist.
+            const embedQuery = this.dbSearch.hasEmbeddings()
                 ? (text) => this.embeddings.embed(text)
                 : undefined;
             return this.dbSearch.hybridSearch(query, limit, mode, embedQuery);
@@ -230,6 +237,22 @@ export class GnosysHybridSearch {
         }
         return indexed;
     }
+    /**
+     * v5.13.0: (re)build the central-DB memories.embedding column — the
+     * vectors GnosysDbSearch actually reads. Before this, reindex only
+     * embedded file-store memories into the store-local embeddings.db, so
+     * DB-mode semantic search could never activate. Returns counts; no-op
+     * ({0,0}) when no migrated central DB is attached.
+     */
+    async reindexCentralDb(onProgress) {
+        if (!this.gnosysDb)
+            return { embedded: 0, total: 0 };
+        const { backfillCentralDbEmbeddings } = await import("./embedDb.js");
+        return backfillCentralDbEmbeddings(this.gnosysDb, this.embeddings, {
+            mode: "all",
+            onProgress,
+        });
+    }
     /**
      * Load full content for search results (used by Ask engine).
      * Handles both active memories and archived memories.
@@ -286,15 +309,14 @@ export class GnosysHybridSearch {
     }
     /**
      * True when hybrid/semantic search can actually run its semantic leg.
-     * In DB mode this requires BOTH stored vectors in the central DB and the
-     * store-local embeddings.db used to embed the query text — the central
-     * count alone can be non-zero on a machine that only syncs gnosys.db,
-     * in which case hybridSearch() silently runs keyword-only (embedQuery
-     * is never constructed).
+     * Mirrors the embedQuery gate in hybridSearch(): in DB mode, stored
+     * central-DB vectors are what matter (the query embedder loads the
+     * local model on demand); in legacy file mode, the store-local
+     * embeddings.db must be populated.
      */
     canRunSemantic() {
         if (this.dbSearch) {
-            return this.dbSearch.hasEmbeddings() && this.embeddings.hasEmbeddings();
+            return this.dbSearch.hasEmbeddings();
         }
         return this.embeddings.hasEmbeddings();
     }

package/dist/lib/reindexCommand.js

@@ -24,7 +24,33 @@ export async function runReindexCommand(getResolver) {
         const count = await hybridSearch.reindex((current, total, filePath) => {
             process.stdout.write(`\r  Indexing: ${current}/${total} — ${filePath.substring(0, 60)}`);
         });
+        // v5.13.0: also (re)build the central-DB embedding column — the vectors
+        // DB-mode hybrid/semantic search actually reads. Own handle: the
+        // resolver-based hybridSearch above only covers file stores.
+        let dbEmbedded = 0;
+        let dbTotal = 0;
+        const { GnosysDB } = await import("./db.js");
+        const centralDb = GnosysDB.openCentral();
+        try {
+            if (centralDb.isAvailable() && centralDb.isMigrated()) {
+                const { backfillCentralDbEmbeddings } = await import("./embedDb.js");
+                const result = await backfillCentralDbEmbeddings(centralDb, embeddings, {
+                    mode: "all",
+                    onProgress: (current, total, id) => {
+                        process.stdout.write(`\r  Central DB: ${current}/${total} — ${id.substring(0, 40)}          `);
+                    },
+                });
+                dbEmbedded = result.embedded;
+                dbTotal = result.total;
+            }
+        }
+        finally {
+            centralDb.close();
+        }
         console.log(`\n\nReindex complete: ${count} memories embedded.`);
+        if (dbTotal > 0) {
+            console.log(`Central DB: ${dbEmbedded}/${dbTotal} memories embedded.`);
+        }
         console.log("Hybrid and semantic search are now available.");
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gnosys",
-  "version": "5.12.3",
+  "version": "5.13.0",
   "description": "Gnosys — Persistent Memory for AI Agents. Sandbox-first runtime, central SQLite brain, federated search, Dream Mode, Web Knowledge Base, Obsidian export.",
   "type": "module",
   "main": "dist/index.js",