@bubstack/moe-memory 0.1.0

package/dist/doctor.js

@@ -0,0 +1,98 @@
+import { MIN_CODEX_VERSION, parseCodexCliVersion, versionMeetsMinimum } from "./codex-support.js";
+function parseFeatureState(featuresOutput, feature) {
+    const line = featuresOutput
+        .split(/\r?\n/)
+        .map((entry) => entry.trim())
+        .find((entry) => entry.startsWith(`${feature} `));
+    if (!line) {
+        return undefined;
+    }
+    const lastColumn = line.split(/\s+/).at(-1);
+    if (lastColumn === "true")
+        return true;
+    if (lastColumn === "false")
+        return false;
+    return undefined;
+}
+function parseMcpState(mcpListOutput) {
+    const line = mcpListOutput
+        .split(/\r?\n/)
+        .map((entry) => entry.trim())
+        .find((entry) => entry.startsWith("moe-memory "));
+    if (!line) {
+        return "missing";
+    }
+    return line.includes(" enabled") ? "enabled" : "disabled";
+}
+function formatHookTrustState(hookTrustState) {
+    switch (hookTrustState) {
+        case "trusted":
+            return "trusted";
+        case "untrusted":
+            return "untrusted; open /hooks in Codex, review the Moe Memory hook, and press t to trust it.";
+        case "modified":
+            return "modified since it was trusted; open /hooks in Codex, review the Moe Memory hook, and press t to trust it again.";
+        case "not_found":
+            return "not found; confirm the Moe Memory plugin is installed and enabled.";
+        case "unknown":
+            return "unknown; could not inspect Codex hooks. Open /hooks in Codex to verify trust.";
+    }
+}
+export function buildCodexDoctorReport(inputs) {
+    const version = parseCodexCliVersion(inputs.codexVersionOutput);
+    const versionOk = version !== undefined && versionMeetsMinimum(version);
+    const pluginHooksEnabled = parseFeatureState(inputs.featuresOutput, "plugin_hooks");
+    const pluginsEnabled = parseFeatureState(inputs.featuresOutput, "plugins");
+    const mcpState = parseMcpState(inputs.mcpListOutput);
+    const issues = [];
+    if (!versionOk) {
+        issues.push(`Codex must be upgraded with codex update (minimum ${MIN_CODEX_VERSION}).`);
+    }
+    if (pluginsEnabled === false) {
+        issues.push("Codex plugins are disabled; run codex features enable plugins.");
+    }
+    if (pluginHooksEnabled !== true) {
+        issues.push("Codex plugin hooks are not enabled; run codex features enable plugin_hooks.");
+    }
+    if (!inputs.sessionsDirExists) {
+        issues.push("Codex sessions directory does not exist yet; start at least one Codex session.");
+    }
+    if (mcpState !== "enabled") {
+        issues.push("Moe Memory MCP server is not enabled in codex mcp list.");
+    }
+    if (inputs.hookTrustState === "untrusted" || inputs.hookTrustState === "modified") {
+        issues.push("Moe Memory Codex hook is not trusted; open /hooks in Codex and press t to trust it.");
+    }
+    else if (inputs.hookTrustState === "not_found") {
+        issues.push("Moe Memory Codex hook was not found; confirm the plugin is installed and enabled.");
+    }
+    else if (inputs.hookTrustState === "unknown") {
+        issues.push("Moe Memory Codex hook trust could not be verified.");
+    }
+    const lines = [
+        "Moe Memory Codex Doctor",
+        "================================",
+        "",
+        `Codex version: ${inputs.codexVersionOutput.trim() || "(not found)"} ${versionOk ? `(ok; minimum ${MIN_CODEX_VERSION})` : `(requires minimum ${MIN_CODEX_VERSION})`}`,
+        `Codex home: ${inputs.codexHome}`,
+        `Codex sessions: ${inputs.sessionsDirExists ? "found" : "missing"}`,
+        `Plugins feature: ${pluginsEnabled === true ? "enabled" : pluginsEnabled === false ? "disabled" : "unknown"}`,
+        `Plugin hooks feature: ${pluginHooksEnabled === true ? "enabled" : pluginHooksEnabled === false ? "disabled" : "unknown"}`,
+        `Moe Memory MCP: ${mcpState}`,
+        `Index database: ${inputs.dbPath}`,
+        `Hook/background sync log: ${inputs.logPath}`,
+        "",
+        `Hook trust: ${formatHookTrustState(inputs.hookTrustState)}`,
+    ];
+    if (issues.length > 0) {
+        lines.push("", "Issues:");
+        for (const issue of issues) {
+            lines.push(`- ${issue}`);
+        }
+    }
+    return {
+        ok: issues.length === 0,
+        text: `${lines.join("\n")}\n`,
+    };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/embedding-migration.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Embedding migration.
+ *
+ * The encoder was upgraded from all-MiniLM-L6-v2 to bge-small-en-v1.5. Existing
+ * databases have vec_exchanges rows produced by the old encoder. This module
+ * provides the primitives for an incremental, lock-protected, resumable
+ * background migration that re-embeds stale rows in batches during sync.
+ *
+ *   EMBEDDING_VERSION   — bumped any time the encoder pipeline changes
+ *   acquire/release lock — file-based with PID-liveness fallback
+ *   pickStaleBatch       — find rows whose embedding_version is behind
+ *   recordReembedded     — atomic update of vec_exchanges + version bump
+ *
+ * This mechanism is the single strongest argument for building the merged
+ * package on episodic-memory's foundation: private-journal-mcp had no version
+ * stamp at all, and its startup scan keyed purely on the ABSENCE of a sidecar,
+ * so it would never have re-embedded a stale one.
+ */
+import type Database from "better-sqlite3";
+import { acquireFileLock, type FileLockHandle, releaseFileLock } from "./file-lock.js";
+/**
+ * Bump when anything in the embedding pipeline changes (model, dtype, prefix).
+ *
+ * 1 → 2 on the merge with private-journal-mcp. Journal entries were embedded
+ * upstream with `Xenova/all-MiniLM-L6-v2` and exchanges with
+ * `Xenova/bge-small-en-v1.5`. Both are 384-dimensional, so a unified vec0
+ * column accepts either vector without complaint and a mixed corpus ranks
+ * wrongly with no error — which is exactly the event this constant exists for.
+ */
+export declare const EMBEDDING_VERSION = 2;
+/**
+ * Lock primitives for the migration are the same as for sync (#97) and any
+ * other once-per-machine background task — see src/file-lock.ts for the shape.
+ * Re-exported here so existing call sites keep their original import names.
+ */
+export type MigrationLockHandle = FileLockHandle;
+export declare const acquireMigrationLock: typeof acquireFileLock;
+export declare const releaseMigrationLock: typeof releaseFileLock;
+export interface StaleRow {
+    id: string;
+    user_message: string;
+    assistant_message: string;
+    tools: string | null;
+}
+/**
+ * Return up to `limit` rows whose embedding_version is older than
+ * EMBEDDING_VERSION, joined with their tool names so the caller can
+ * reproduce the production exchange-text format.
+ */
+export declare function pickStaleBatch(db: Database.Database, limit: number): StaleRow[];
+/**
+ * Replace a row's vec_exchanges embedding and stamp its embedding_version
+ * atomically. Wrap each batch's calls in a single transaction at the caller
+ * for durability; this function executes its statements in order without
+ * starting its own transaction.
+ */
+export declare function recordReembedded(db: Database.Database, id: string, embedding: number[]): void;
+/**
+ * Count rows whose embedding is older than the current version.
+ * Used to decide whether migration is needed and to report progress.
+ */
+export declare function countStale(db: Database.Database): number;
+/** Path of the migration lock under the index directory. */
+export declare function getMigrationLockPath(indexDir: string): string;
+/**
+ * Run a single migration batch: re-embed up to `batchSize` rows whose
+ * embedding_version is behind. Lock-protected; exits silently if another
+ * process holds the lock.
+ *
+ * Returns the number of rows re-embedded (0 if nothing to do or locked out).
+ */
+export declare function runMigrationBatch(db: Database.Database, indexDir: string, batchSize: number, embedFn: (user: string, assistant: string, toolNames?: string[]) => Promise<number[]>): Promise<number>;
+//# sourceMappingURL=embedding-migration.d.ts.map

package/dist/embedding-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-migration.d.ts","sourceRoot":"","sources":["../src/embedding-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEvF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC;AACjD,eAAO,MAAM,oBAAoB,wBAAkB,CAAC;AACpD,eAAO,MAAM,oBAAoB,wBAAkB,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,EAAE,CAe/E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAO7F;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAKxD;AAED,4DAA4D;AAC5D,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,GACpF,OAAO,CAAC,MAAM,CAAC,CAmCjB"}

package/dist/embedding-migration.js

@@ -0,0 +1,120 @@
+/**
+ * Embedding migration.
+ *
+ * The encoder was upgraded from all-MiniLM-L6-v2 to bge-small-en-v1.5. Existing
+ * databases have vec_exchanges rows produced by the old encoder. This module
+ * provides the primitives for an incremental, lock-protected, resumable
+ * background migration that re-embeds stale rows in batches during sync.
+ *
+ *   EMBEDDING_VERSION   — bumped any time the encoder pipeline changes
+ *   acquire/release lock — file-based with PID-liveness fallback
+ *   pickStaleBatch       — find rows whose embedding_version is behind
+ *   recordReembedded     — atomic update of vec_exchanges + version bump
+ *
+ * This mechanism is the single strongest argument for building the merged
+ * package on episodic-memory's foundation: private-journal-mcp had no version
+ * stamp at all, and its startup scan keyed purely on the ABSENCE of a sidecar,
+ * so it would never have re-embedded a stale one.
+ */
+import path from "node:path";
+import { acquireFileLock, releaseFileLock } from "./file-lock.js";
+/**
+ * Bump when anything in the embedding pipeline changes (model, dtype, prefix).
+ *
+ * 1 → 2 on the merge with private-journal-mcp. Journal entries were embedded
+ * upstream with `Xenova/all-MiniLM-L6-v2` and exchanges with
+ * `Xenova/bge-small-en-v1.5`. Both are 384-dimensional, so a unified vec0
+ * column accepts either vector without complaint and a mixed corpus ranks
+ * wrongly with no error — which is exactly the event this constant exists for.
+ */
+export const EMBEDDING_VERSION = 2;
+export const acquireMigrationLock = acquireFileLock;
+export const releaseMigrationLock = releaseFileLock;
+/**
+ * Return up to `limit` rows whose embedding_version is older than
+ * EMBEDDING_VERSION, joined with their tool names so the caller can
+ * reproduce the production exchange-text format.
+ */
+export function pickStaleBatch(db, limit) {
+    return db
+        .prepare(`
+    SELECT
+      e.id,
+      e.user_message,
+      e.assistant_message,
+      GROUP_CONCAT(DISTINCT tc.tool_name) AS tools
+    FROM exchanges e
+    LEFT JOIN tool_calls tc ON tc.exchange_id = e.id
+    WHERE e.embedding_version < ?
+    GROUP BY e.id
+    LIMIT ?
+  `)
+        .all(EMBEDDING_VERSION, limit);
+}
+/**
+ * Replace a row's vec_exchanges embedding and stamp its embedding_version
+ * atomically. Wrap each batch's calls in a single transaction at the caller
+ * for durability; this function executes its statements in order without
+ * starting its own transaction.
+ */
+export function recordReembedded(db, id, embedding) {
+    db.prepare("DELETE FROM vec_exchanges WHERE id = ?").run(id);
+    db.prepare("INSERT INTO vec_exchanges (id, embedding) VALUES (?, ?)").run(id, Buffer.from(new Float32Array(embedding).buffer));
+    db.prepare("UPDATE exchanges SET embedding_version = ? WHERE id = ?").run(EMBEDDING_VERSION, id);
+}
+/**
+ * Count rows whose embedding is older than the current version.
+ * Used to decide whether migration is needed and to report progress.
+ */
+export function countStale(db) {
+    const row = db
+        .prepare("SELECT COUNT(*) AS c FROM exchanges WHERE embedding_version < ?")
+        .get(EMBEDDING_VERSION);
+    return row.c;
+}
+/** Path of the migration lock under the index directory. */
+export function getMigrationLockPath(indexDir) {
+    return path.join(indexDir, ".embedding-migration.lock");
+}
+/**
+ * Run a single migration batch: re-embed up to `batchSize` rows whose
+ * embedding_version is behind. Lock-protected; exits silently if another
+ * process holds the lock.
+ *
+ * Returns the number of rows re-embedded (0 if nothing to do or locked out).
+ */
+export async function runMigrationBatch(db, indexDir, batchSize, embedFn) {
+    const remaining = countStale(db);
+    if (remaining === 0)
+        return 0;
+    const lockPath = getMigrationLockPath(indexDir);
+    const lock = acquireMigrationLock(lockPath);
+    if (!lock) {
+        console.error(`moe-memory: another process is migrating embeddings (${remaining} rows still stale); skipping`);
+        return 0;
+    }
+    try {
+        const rows = pickStaleBatch(db, batchSize);
+        if (rows.length === 0)
+            return 0;
+        console.error(`moe-memory: re-embedding batch of ${rows.length} (${remaining} stale total)...`);
+        // Compute embeddings outside the transaction (async work),
+        // then write atomically (one transaction per batch for durability).
+        const embeddings = [];
+        for (const row of rows) {
+            const tools = row.tools ? row.tools.split(",") : undefined;
+            const vec = await embedFn(row.user_message, row.assistant_message, tools);
+            embeddings.push({ id: row.id, vec });
+        }
+        const writeTx = db.transaction((items) => {
+            for (const item of items)
+                recordReembedded(db, item.id, item.vec);
+        });
+        writeTx(embeddings);
+        return embeddings.length;
+    }
+    finally {
+        releaseMigrationLock(lock);
+    }
+}
+//# sourceMappingURL=embedding-migration.js.map

package/dist/embedding-migration.js.map

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

package/dist/embeddings.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The one embedding layer.
+ *
+ * Reconciled from two upstream `embeddings.ts` files that did the same job with
+ * incompatible shapes and two releases of the same library — `@xenova/transformers`
+ * is the former name of `@huggingface/transformers`.
+ *
+ *   WON  episodic-memory: module-level functions over a module-level pipeline,
+ *        `@huggingface/transformers` ^4, `Xenova/bge-small-en-v1.5` at dtype q8,
+ *        2000-char truncation, the asymmetric BGE query prefix, and the two
+ *        import-time `env` mutations that keep transformers.js off stdout.
+ *   LOST private-journal-mcp: an `EmbeddingService` singleton with a private
+ *        constructor and a `private readonly modelName`, on `@xenova/transformers` ^2
+ *        with `Xenova/all-MiniLM-L6-v2`, no dtype, no truncation, and no
+ *        query/passage asymmetry. One process, one model, forever — which
+ *        blocks a per-record-type encoder and blocks swapping the encoder in a
+ *        test.
+ *
+ * Three things were carried FORWARD from the losing side, because they were
+ * better there:
+ *
+ *   - the memoised init promise, so two concurrent callers load the model once;
+ *   - the init timeout with retry-on-failure (the promise is cleared so the
+ *     next call retries rather than awaiting a dead promise);
+ *   - `resetEmbeddings()`, the seam its two timeout tests need.
+ *
+ * And one thing was FIXED: `env.cacheDir` is pinned. Upstream set neither
+ * `cacheDir` nor a local model path, so the first `initEmbeddings()` fetched the
+ * model into whatever transformers.js defaults to — under pnpm a path inside
+ * the content-addressed store, shared across the workspace and possibly
+ * read-only in a container.
+ *
+ * ⚠️ Anything that changes model, dtype, prefix, pooling, normalisation or
+ * truncation MUST bump EMBEDDING_VERSION in embedding-migration.ts. Two
+ * encoders' vectors are dimensionally identical at 384 and semantically
+ * incomparable, so a mixed corpus does not error — it just ranks wrongly.
+ */
+export { EMBEDDING_DIMENSIONS } from "./constants.js";
+export declare const BGE_QUERY_PREFIX = "Represent this sentence for searching relevant passages: ";
+export declare function initEmbeddings(): Promise<void>;
+/**
+ * Drop the loaded model and the init memo. Test seam — the two timeout tests
+ * inherited from private-journal-mcp need to make loading fail, then succeed.
+ */
+export declare function resetEmbeddings(): void;
+export declare function generateEmbedding(text: string): Promise<number[]>;
+/**
+ * Prepend the BGE retrieval prefix to a query string. Idempotent: returns
+ * the input unchanged if the prefix is already present.
+ */
+export declare function withQueryPrefix(query: string): string;
+/**
+ * Generate an embedding for a search QUERY. Adds the model-specific prefix
+ * before embedding, which gives a small but consistent recall lift on
+ * retrieval tasks. Document/passage embeddings stay unmodified — that's the
+ * asymmetric pattern BGE models are trained for.
+ *
+ * BOTH record types' queries route through here. private-journal-mcp embedded
+ * its queries with the same call it used for documents, which under an
+ * asymmetric encoder costs recall with no error and no log line.
+ */
+export declare function generateQueryEmbedding(query: string): Promise<number[]>;
+/**
+ * Document embedding for a conversation exchange (a harvested transcript turn).
+ */
+export declare function generateExchangeEmbedding(userMessage: string, assistantMessage: string, toolNames?: string[]): Promise<number[]>;
+/**
+ * Document embedding for a journal entry (deliberately written by the user).
+ *
+ * Same encoder, same normalisation, same truncation as an exchange — that is
+ * the whole point of the merge — but named separately because the two record
+ * types are separately queryable and a future divergence should be visible
+ * here rather than hidden behind a shared call.
+ */
+export declare function generateEntryEmbedding(text: string): Promise<number[]>;
+/** The signature both stores accept, so tests can inject a deterministic encoder. */
+export type EmbedFn = (text: string) => Promise<number[]>;
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../src/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AA0BtD,eAAO,MAAM,gBAAgB,8DAA8D,CAAC;AAyD5F,wBAAsB,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,CAIpD;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAcvE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE7E;AAED;;GAEG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,EACxB,SAAS,CAAC,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CASnB;AAED;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAE5E;AAED,qFAAqF;AACrF,MAAM,MAAM,OAAO,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC"}

package/dist/embeddings.js

@@ -0,0 +1,180 @@
+/**
+ * The one embedding layer.
+ *
+ * Reconciled from two upstream `embeddings.ts` files that did the same job with
+ * incompatible shapes and two releases of the same library — `@xenova/transformers`
+ * is the former name of `@huggingface/transformers`.
+ *
+ *   WON  episodic-memory: module-level functions over a module-level pipeline,
+ *        `@huggingface/transformers` ^4, `Xenova/bge-small-en-v1.5` at dtype q8,
+ *        2000-char truncation, the asymmetric BGE query prefix, and the two
+ *        import-time `env` mutations that keep transformers.js off stdout.
+ *   LOST private-journal-mcp: an `EmbeddingService` singleton with a private
+ *        constructor and a `private readonly modelName`, on `@xenova/transformers` ^2
+ *        with `Xenova/all-MiniLM-L6-v2`, no dtype, no truncation, and no
+ *        query/passage asymmetry. One process, one model, forever — which
+ *        blocks a per-record-type encoder and blocks swapping the encoder in a
+ *        test.
+ *
+ * Three things were carried FORWARD from the losing side, because they were
+ * better there:
+ *
+ *   - the memoised init promise, so two concurrent callers load the model once;
+ *   - the init timeout with retry-on-failure (the promise is cleared so the
+ *     next call retries rather than awaiting a dead promise);
+ *   - `resetEmbeddings()`, the seam its two timeout tests need.
+ *
+ * And one thing was FIXED: `env.cacheDir` is pinned. Upstream set neither
+ * `cacheDir` nor a local model path, so the first `initEmbeddings()` fetched the
+ * model into whatever transformers.js defaults to — under pnpm a path inside
+ * the content-addressed store, shared across the workspace and possibly
+ * read-only in a container.
+ *
+ * ⚠️ Anything that changes model, dtype, prefix, pooling, normalisation or
+ * truncation MUST bump EMBEDDING_VERSION in embedding-migration.ts. Two
+ * encoders' vectors are dimensionally identical at 384 and semantically
+ * incomparable, so a mixed corpus does not error — it just ranks wrongly.
+ */
+import { env, pipeline } from "@huggingface/transformers";
+import { getModelCacheDir } from "./paths.js";
+export { EMBEDDING_DIMENSIONS } from "./constants.js";
+// Disable progress callbacks to prevent stdout pollution in MCP context.
+// In MCP, stdout is reserved for JSON-RPC communication. These two are
+// import-time side effects on the library's shared `env`, deliberately: every
+// entry point that reaches the encoder needs them, including the journal half.
+env.allowLocalModels = true;
+env.useBrowserCache = false;
+/**
+ * Embedding model configuration.
+ *
+ * Using BAAI's bge-small-en-v1.5 (via Xenova's ONNX export) instead of the
+ * older all-MiniLM-L6-v2 — measured +6.34 R@1 on a 17K-corpus retrieval test
+ * against real production data. Same 384 dimensions, so vec_exchanges schema
+ * is unchanged.
+ *
+ * `Xenova/` here is a Hugging Face org namespace inside a model id, not a
+ * vendor brand. It is resolved over the network and must not be swept.
+ *
+ * BGE models recommend prepending a task prefix to QUERY embeddings only
+ * (passages/documents go through unmodified). See `withQueryPrefix` and
+ * `generateQueryEmbedding` below.
+ */
+const MODEL_ID = "Xenova/bge-small-en-v1.5";
+const MODEL_DTYPE = "q8";
+export const BGE_QUERY_PREFIX = "Represent this sentence for searching relevant passages: ";
+/** Longer inputs degrade mean-pooled embeddings; 2000 chars measured best. */
+const MAX_INPUT_CHARS = 2000;
+const DEFAULT_INIT_TIMEOUT_MS = 180_000;
+let embeddingPipeline = null;
+let initPromise = null;
+function initTimeoutMs() {
+    const raw = Number(process.env.MOE_MEMORY_MODEL_INIT_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_INIT_TIMEOUT_MS;
+}
+async function loadPipeline() {
+    const timeoutAfter = initTimeoutMs();
+    let timeoutId;
+    const timeout = new Promise((_resolve, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(`Embedding model loading timed out after ${timeoutAfter / 1000}s. ` +
+            `The model cache is ${getModelCacheDir()}; a stale lock or a failed ` +
+            `partial download there is the usual cause. Remove it and retry.`)), timeoutAfter);
+    });
+    try {
+        // Pin the cache so the download lands somewhere writable that moves with
+        // MOE_MEMORY_CONFIG_DIR. Set here rather than at import time so nothing
+        // creates directories just by loading this module.
+        env.cacheDir = getModelCacheDir();
+        console.error("Loading embedding model (first run may take time)...");
+        embeddingPipeline = await Promise.race([
+            pipeline("feature-extraction", MODEL_ID, {
+                dtype: MODEL_DTYPE,
+                progress_callback: () => { },
+            }),
+            timeout,
+        ]);
+        console.error("Embedding model loaded");
+    }
+    catch (error) {
+        // Clear the memo so the next call retries instead of awaiting a dead promise.
+        initPromise = null;
+        embeddingPipeline = null;
+        throw error;
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}
+export async function initEmbeddings() {
+    if (embeddingPipeline)
+        return;
+    if (!initPromise)
+        initPromise = loadPipeline();
+    return initPromise;
+}
+/**
+ * Drop the loaded model and the init memo. Test seam — the two timeout tests
+ * inherited from private-journal-mcp need to make loading fail, then succeed.
+ */
+export function resetEmbeddings() {
+    embeddingPipeline = null;
+    initPromise = null;
+}
+export async function generateEmbedding(text) {
+    await initEmbeddings();
+    const pipe = embeddingPipeline;
+    if (!pipe)
+        throw new Error("Embedding model not initialized");
+    // Truncate to avoid token limits (512 tokens max for bge-small).
+    const truncated = text.substring(0, MAX_INPUT_CHARS);
+    const output = await pipe(truncated, {
+        pooling: "mean",
+        normalize: true,
+    });
+    return Array.from(output.data);
+}
+/**
+ * Prepend the BGE retrieval prefix to a query string. Idempotent: returns
+ * the input unchanged if the prefix is already present.
+ */
+export function withQueryPrefix(query) {
+    if (query.startsWith(BGE_QUERY_PREFIX))
+        return query;
+    return BGE_QUERY_PREFIX + query;
+}
+/**
+ * Generate an embedding for a search QUERY. Adds the model-specific prefix
+ * before embedding, which gives a small but consistent recall lift on
+ * retrieval tasks. Document/passage embeddings stay unmodified — that's the
+ * asymmetric pattern BGE models are trained for.
+ *
+ * BOTH record types' queries route through here. private-journal-mcp embedded
+ * its queries with the same call it used for documents, which under an
+ * asymmetric encoder costs recall with no error and no log line.
+ */
+export async function generateQueryEmbedding(query) {
+    return generateEmbedding(withQueryPrefix(query));
+}
+/**
+ * Document embedding for a conversation exchange (a harvested transcript turn).
+ */
+export async function generateExchangeEmbedding(userMessage, assistantMessage, toolNames) {
+    // Combine user question, assistant answer, and tools used for better searchability
+    let combined = `User: ${userMessage}\n\nAssistant: ${assistantMessage}`;
+    if (toolNames && toolNames.length > 0) {
+        combined += `\n\nTools: ${toolNames.join(", ")}`;
+    }
+    return generateEmbedding(combined);
+}
+/**
+ * Document embedding for a journal entry (deliberately written by the user).
+ *
+ * Same encoder, same normalisation, same truncation as an exchange — that is
+ * the whole point of the merge — but named separately because the two record
+ * types are separately queryable and a future divergence should be visible
+ * here rather than hidden behind a shared call.
+ */
+export async function generateEntryEmbedding(text) {
+    return generateEmbedding(text);
+}
+//# sourceMappingURL=embeddings.js.map

package/dist/embeddings.js.map

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

package/dist/file-lock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * File-based exclusive locks. Thin wrapper around the `proper-lockfile`
+ * package, which uses an atomic mkdir + mtime-heartbeat protocol that is
+ * race-free under concurrent stale-stealers — the failure mode that pure
+ * "openSync(wx) + PID file" implementations cannot fully close without
+ * advisory locking (flock/fcntl).
+ *
+ * Used by long-running background work that must not run more than once at a
+ * time on a given machine: the embedding migration (#73) and
+ * `sync --background` (#97).
+ *
+ * On disk for a held lock at `<lockPath>`:
+ *   <lockPath>             — diagnostic file containing the holder's PID
+ *   <lockPath>.lock/       — proper-lockfile's mutex directory (mkdir-atomic)
+ *
+ * Stale recovery is mtime-based with a 10-minute threshold: if the holder
+ * crashed without releasing, the .lock/ directory's mtime stops advancing,
+ * and a contender past the threshold steals it atomically. The protocol's
+ * atomicity guarantee is the package's contract — see proper-lockfile's
+ * README for the underlying analysis (the same approach used by npm itself).
+ *
+ * Error policy:
+ *   - `null` means lock contention.
+ *   - Unexpected I/O errors (EACCES, ENOSPC, EMFILE, etc.) are thrown so
+ *     callers can surface disk problems rather than mask them as "locked".
+ */
+export interface FileLockHandle {
+    path: string;
+    release: () => void;
+}
+export declare function acquireFileLock(lockPath: string): FileLockHandle | null;
+export declare function releaseFileLock(handle: FileLockHandle): void;
+/**
+ * Read the recorded holder PID from a lock file's diagnostic content.
+ * Returns null if the file doesn't exist or doesn't contain a valid PID.
+ * The PID is informational only — the real mutex lives in `<lockPath>.lock/`.
+ */
+export declare function readLockHolder(lockPath: string): number | null;
+//# sourceMappingURL=file-lock.d.ts.map

package/dist/file-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-lock.d.ts","sourceRoot":"","sources":["../src/file-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAUD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CA6BvE;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAQ5D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO9D"}