peon-mem 1.0.0

package/dist/embedding-store.d.ts

@@ -0,0 +1,43 @@
+import { type EmbeddingClient, type EmbeddingVector } from "./embeddings.js";
+import type { MemoryRecord } from "./types.js";
+/**
+ * Sidecar vector store for memory embeddings.
+ *
+ * Vectors live in `<memoryDir>/brain/embeddings.jsonl`, keyed by record id, kept
+ * OUT of memories.jsonl so the structured brain stays human-readable. Each entry
+ * carries the content hash + model it was computed from, so a vector is only
+ * recomputed when the record's content changes or the embedding model changes.
+ */
+export interface StoredEmbedding {
+    id: string;
+    model: string;
+    hash: string;
+    vector: EmbeddingVector;
+}
+export interface SyncResult {
+    vectorById: Map<string, EmbeddingVector>;
+    computed: number;
+    reused: number;
+    pruned: number;
+}
+export declare class EmbeddingStore {
+    private readonly filePath;
+    private cache?;
+    private constructor();
+    static open(memoryDir: string): Promise<EmbeddingStore>;
+    load(): Promise<Map<string, StoredEmbedding>>;
+    /**
+     * Ensure every record has a current embedding. Recomputes only what changed,
+     * prunes vectors for deleted records, persists the result, and returns the
+     * id → vector map ready for hybrid ranking. Embedding failures degrade to an
+     * empty map rather than throwing (retrieval falls back to lexical-only).
+     */
+    sync(records: MemoryRecord[], client: EmbeddingClient | null): Promise<SyncResult>;
+    /** Read vectors without recomputing — used by read-only retrieval paths. */
+    vectorById(): Promise<Map<string, EmbeddingVector>>;
+    private persist;
+}
+/** Serialize a vector as base64 of its float32 bytes — ~4x smaller + faster to parse than JSON float64. */
+export declare function encodeVector(vector: EmbeddingVector): string;
+/** Decode a base64 float32 vector back to number[]; null on malformed/misaligned input. */
+export declare function decodeVector(b64: string): number[] | null;

package/dist/embedding-store.js

@@ -0,0 +1,169 @@
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { contentHash } from "./embeddings.js";
+export class EmbeddingStore {
+    filePath;
+    // mtime-keyed cache so the (multi-MB) sidecar isn't re-read+parsed on every prompt's
+    // read-only retrieval. Invalidated by mtime change (incl. our own atomic persist).
+    cache;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    static async open(memoryDir) {
+        const filePath = join(memoryDir, "brain", "embeddings.jsonl");
+        await mkdir(dirname(filePath), { recursive: true });
+        const store = new EmbeddingStore(filePath);
+        return store;
+    }
+    async load() {
+        let mtimeMs = 0;
+        try {
+            mtimeMs = (await stat(this.filePath)).mtimeMs;
+        }
+        catch {
+            mtimeMs = 0; // missing file → treat as empty, mtime 0
+        }
+        if (this.cache && this.cache.mtimeMs === mtimeMs)
+            return this.cache.map;
+        const raw = await readFile(this.filePath, "utf8").catch(() => "");
+        const map = new Map();
+        for (const line of raw.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            try {
+                const stored = parseStoredLine(JSON.parse(trimmed));
+                if (stored)
+                    map.set(stored.id, stored);
+            }
+            catch {
+                // skip malformed lines — never let a bad vector block retrieval
+            }
+        }
+        this.cache = { mtimeMs, map };
+        return map;
+    }
+    /**
+     * Ensure every record has a current embedding. Recomputes only what changed,
+     * prunes vectors for deleted records, persists the result, and returns the
+     * id → vector map ready for hybrid ranking. Embedding failures degrade to an
+     * empty map rather than throwing (retrieval falls back to lexical-only).
+     */
+    async sync(records, client) {
+        if (!client) {
+            return { vectorById: new Map(), computed: 0, reused: 0, pruned: 0 };
+        }
+        const existing = await this.load();
+        const liveIds = new Set(records.map((record) => record.id));
+        const pruned = [...existing.keys()].filter((id) => !liveIds.has(id)).length;
+        const toCompute = [];
+        let reused = 0;
+        for (const record of records) {
+            const prior = existing.get(record.id);
+            if (prior && prior.model === client.model && prior.hash === contentHash(embeddingText(record))) {
+                reused += 1;
+            }
+            else {
+                toCompute.push(record);
+            }
+        }
+        const result = new Map();
+        for (const record of records) {
+            const prior = existing.get(record.id);
+            if (prior && prior.model === client.model && prior.hash === contentHash(embeddingText(record))) {
+                result.set(record.id, prior);
+            }
+        }
+        let computed = 0;
+        if (toCompute.length > 0) {
+            try {
+                const vectors = await client.embed(toCompute.map((record) => embeddingText(record)));
+                toCompute.forEach((record, i) => {
+                    result.set(record.id, {
+                        id: record.id,
+                        model: client.model,
+                        hash: contentHash(embeddingText(record)),
+                        vector: vectors[i] ?? []
+                    });
+                });
+                computed = toCompute.length;
+            }
+            catch {
+                // On a hard failure, keep whatever we already had and continue lexical-only.
+            }
+        }
+        // Only touch disk when the vector set actually changed.
+        if (computed > 0 || pruned > 0) {
+            await this.persist(records, result);
+        }
+        const vectorById = new Map();
+        for (const [id, stored] of result)
+            vectorById.set(id, stored.vector);
+        return { vectorById, computed, reused, pruned };
+    }
+    /** Read vectors without recomputing — used by read-only retrieval paths. */
+    async vectorById() {
+        const stored = await this.load();
+        const map = new Map();
+        for (const [id, value] of stored)
+            map.set(id, value.vector);
+        return map;
+    }
+    async persist(records, result) {
+        // Write in record order for stable diffs; only persist vectors we actually have.
+        const lines = records
+            .map((record) => result.get(record.id))
+            .filter((value) => Boolean(value))
+            // Persist the vector as base64 float32 (`vec`), ~4x smaller and ~4x faster to parse than a
+            // JSON float64 array. Legacy `vector`-array lines are still read on load and get re-encoded
+            // to `vec` here on their next persist (lazy migration; no separate migration step needed).
+            .map((value) => JSON.stringify({ id: value.id, model: value.model, hash: value.hash, vec: encodeVector(value.vector) }));
+        // Atomic write (tmp + rename) so a crash mid-write can't truncate the sidecar.
+        const tmp = `${this.filePath}.tmp`;
+        await writeFile(tmp, lines.length > 0 ? `${lines.join("\n")}\n` : "", "utf8");
+        await rename(tmp, this.filePath);
+        this.cache = undefined; // invalidate; next load() re-reads the fresh file
+    }
+}
+/** Embed the record type alongside content so type acts as a soft semantic anchor. */
+function embeddingText(record) {
+    const entities = record.entities.length > 0 ? ` ${record.entities.join(" ")}` : "";
+    return `${record.type}: ${record.content}${entities}`;
+}
+/** Serialize a vector as base64 of its float32 bytes — ~4x smaller + faster to parse than JSON float64. */
+export function encodeVector(vector) {
+    return Buffer.from(new Float32Array(vector).buffer).toString("base64");
+}
+/** Decode a base64 float32 vector back to number[]; null on malformed/misaligned input. */
+export function decodeVector(b64) {
+    try {
+        const buf = Buffer.from(b64, "base64");
+        if (buf.byteLength === 0 || buf.byteLength % 4 !== 0)
+            return null;
+        return Array.from(new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse one sidecar line into a StoredEmbedding, accepting BOTH the current base64-float32 `vec`
+ * form and the legacy JSON-array `vector` form (so old sidecars keep working until re-persisted).
+ */
+function parseStoredLine(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const record = value;
+    if (typeof record.id !== "string" || typeof record.model !== "string" || typeof record.hash !== "string")
+        return null;
+    let vector = null;
+    if (typeof record.vec === "string") {
+        vector = decodeVector(record.vec);
+    }
+    else if (Array.isArray(record.vector) && record.vector.every((entry) => typeof entry === "number")) {
+        vector = record.vector;
+    }
+    if (!vector)
+        return null;
+    return { id: record.id, model: record.model, hash: record.hash, vector };
+}

package/dist/embeddings.d.ts

@@ -0,0 +1,93 @@
+import type { PeonConfig } from "./config.js";
+/**
+ * Peon embeddings layer.
+ *
+ * Provides vector embeddings for memory records so retrieval can rank by meaning,
+ * not just keyword overlap. Designed local-first:
+ *
+ *   - "local" mode (default): deterministic hashed character-trigram embeddings.
+ *     No API key, no network, fully offline. Captures fuzzy/lexical similarity
+ *     (typos, substrings, shared word stems) in vector space. Deterministic, so
+ *     tests are stable and identical content always yields identical vectors.
+ *
+ *   - "api" mode: real semantic embeddings via the OpenRouter embeddings endpoint.
+ *     Falls back to local embeddings on any failure so the pipeline never breaks.
+ *
+ *   - "off" mode: no embeddings; retrieval stays purely lexical.
+ */
+export type EmbeddingVector = number[];
+export declare const LOCAL_EMBEDDING_DIM = 256;
+export declare const LOCAL_EMBEDDING_MODEL = "peon-local-trigram-v1";
+export interface EmbeddingClient {
+    readonly model: string;
+    embed(texts: string[]): Promise<EmbeddingVector[]>;
+}
+/** Cosine similarity of two vectors. Returns 0 for empty/mismatched/zero vectors. */
+export declare function cosineSimilarity(a: EmbeddingVector, b: EmbeddingVector): number;
+/** L2-normalize a vector in place-safe fashion (returns a new array). */
+export declare function l2normalize(vector: EmbeddingVector): EmbeddingVector;
+/**
+ * Deterministic local embedding: hashed character trigrams folded into a fixed
+ * dimensional, L2-normalized vector. Two texts that share character trigrams end
+ * up with a high cosine similarity, giving robust fuzzy lexical matching offline.
+ */
+export declare function localEmbed(text: string, dim?: number): EmbeddingVector;
+/** Stable content hash used to detect when a record's embedding must be recomputed. */
+export declare function contentHash(text: string): string;
+export declare class LocalEmbeddingClient implements EmbeddingClient {
+    private readonly dim;
+    readonly model = "peon-local-trigram-v1";
+    constructor(dim?: number);
+    embed(texts: string[]): Promise<EmbeddingVector[]>;
+}
+export interface OpenRouterEmbeddingClientOptions {
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare class OpenRouterEmbeddingClient implements EmbeddingClient {
+    readonly model: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly baseUrl;
+    constructor(options: OpenRouterEmbeddingClientOptions);
+    embed(texts: string[]): Promise<EmbeddingVector[]>;
+}
+export interface OllamaEmbeddingClientOptions {
+    model: string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Local semantic embeddings via an Ollama server (default http://127.0.0.1:11434).
+ * Same quality class as API embeddings but ~30ms on-machine instead of a ~1.3s remote
+ * round-trip, zero API spend, fully offline. Model is part of the cache/sidecar hash,
+ * so switching models auto-triggers document re-embeds through the existing sync path.
+ */
+export declare class OllamaEmbeddingClient implements EmbeddingClient {
+    readonly model: string;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: OllamaEmbeddingClientOptions);
+    embed(texts: string[]): Promise<EmbeddingVector[]>;
+}
+/**
+ * Resilient client that tries the API client first and transparently falls back
+ * to local embeddings on any error, so a flaky network never blocks memory writes.
+ */
+export declare class FallbackEmbeddingClient implements EmbeddingClient {
+    private readonly primary;
+    private readonly fallback;
+    private readonly onFallback?;
+    readonly model: string;
+    constructor(primary: EmbeddingClient, fallback?: EmbeddingClient, onFallback?: ((error: unknown) => void) | undefined);
+    embed(texts: string[]): Promise<EmbeddingVector[]>;
+}
+export type EmbeddingMode = PeonConfig["embeddingMode"];
+export interface CreateEmbeddingClientOptions {
+    config: Pick<PeonConfig, "embeddingMode" | "embeddingModel" | "openRouterApiKey" | "ollamaBaseUrl" | "provider" | "llmApiKey" | "llmBaseUrl">;
+    onFallback?: (error: unknown) => void;
+}
+/** Build the embedding client implied by config, or null when embeddings are off. */
+export declare function createEmbeddingClient(options: CreateEmbeddingClientOptions): EmbeddingClient | null;

package/dist/embeddings.js

@@ -0,0 +1,345 @@
+import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export const LOCAL_EMBEDDING_DIM = 256;
+export const LOCAL_EMBEDDING_MODEL = "peon-local-trigram-v1";
+/** Cosine similarity of two vectors. Returns 0 for empty/mismatched/zero vectors. */
+export function cosineSimilarity(a, b) {
+    if (a.length === 0 || a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    const sim = dot / (Math.sqrt(normA) * Math.sqrt(normB));
+    return Number.isFinite(sim) ? sim : 0;
+}
+/** L2-normalize a vector in place-safe fashion (returns a new array). */
+export function l2normalize(vector) {
+    let norm = 0;
+    for (const value of vector)
+        norm += value * value;
+    norm = Math.sqrt(norm);
+    if (norm === 0)
+        return vector.slice();
+    return vector.map((value) => value / norm);
+}
+/**
+ * Deterministic local embedding: hashed character trigrams folded into a fixed
+ * dimensional, L2-normalized vector. Two texts that share character trigrams end
+ * up with a high cosine similarity, giving robust fuzzy lexical matching offline.
+ */
+export function localEmbed(text, dim = LOCAL_EMBEDDING_DIM) {
+    const vector = new Array(dim).fill(0);
+    const normalized = ` ${text.toLowerCase().replace(/\s+/g, " ").trim()} `;
+    if (normalized.trim().length === 0)
+        return vector;
+    // Character trigrams capture morphology and tolerate typos/substrings.
+    for (let i = 0; i + 3 <= normalized.length; i += 1) {
+        const gram = normalized.slice(i, i + 3);
+        const bucket = fnv1aInt(gram) % dim;
+        // Signed contribution reduces hash-collision cancellation bias.
+        const sign = (fnv1aInt(`sign:${gram}`) & 1) === 0 ? 1 : -1;
+        vector[bucket] += sign;
+    }
+    // Whole-token bucketing adds a coarse lexical signal on top of trigrams.
+    for (const token of normalized.split(" ").filter((t) => t.length > 1)) {
+        const bucket = fnv1aInt(`tok:${token}`) % dim;
+        vector[bucket] += 2;
+    }
+    return l2normalize(vector);
+}
+/** Stable content hash used to detect when a record's embedding must be recomputed. */
+export function contentHash(text) {
+    return fnv1aHex(text.trim());
+}
+export class LocalEmbeddingClient {
+    dim;
+    model = LOCAL_EMBEDDING_MODEL;
+    constructor(dim = LOCAL_EMBEDDING_DIM) {
+        this.dim = dim;
+    }
+    async embed(texts) {
+        return texts.map((text) => localEmbed(text, this.dim));
+    }
+}
+/**
+ * Module-level LRU for SINGLE-text embeddings (query-shaped calls). Every prompt's retrieval
+ * embeds the user query via a remote round-trip — serve telemetry measured it at ~1.4s of the
+ * injection latency — and the same queries recur constantly (hook boilerplate like "recent
+ * project context…", "Continue", repeated user questions). Same model+text is deterministic, so
+ * caching is correctness-free; it cuts BOTH the latency and the OpenRouter spend, and makes eval
+ * reruns of the same qrels deterministic (removes live-query-embedding noise from ledger A/Bs).
+ * Keyed by model + contentHash(text); capped; daemon-lifetime (stores are cached per project).
+ */
+const QUERY_EMBED_CACHE_MAX = 512; // ~12KB/vector → ≤ ~6MB in memory
+const queryEmbedCache = new Map();
+// PERSISTED across restarts/processes: an append-only JSONL sidecar (base64 float32), so repeat
+// queries stay free-and-fast after a daemon restart and eval scripts reuse the daemon's vectors
+// (zero marginal OpenRouter spend for known queries). Append-only by design — never rewritten or
+// deleted; on load we read the TAIL (newest wins) so unbounded growth can't hurt startup.
+const QUERY_EMBED_CACHE_FILE = process.env.PEON_QUERY_EMBED_CACHE ||
+    join(homedir(), "Library", "Application Support", "Peon", "query-embeddings.jsonl");
+const PERSIST_READ_TAIL_BYTES = 8 * 1024 * 1024;
+let persistedLoaded = false;
+function b64encode(vector) {
+    return Buffer.from(new Float32Array(vector).buffer).toString("base64");
+}
+function b64decode(b64) {
+    try {
+        const buf = Buffer.from(b64, "base64");
+        if (buf.byteLength === 0 || buf.byteLength % 4 !== 0)
+            return null;
+        return Array.from(new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4));
+    }
+    catch {
+        return null;
+    }
+}
+function loadPersistedOnce() {
+    if (persistedLoaded)
+        return;
+    persistedLoaded = true;
+    try {
+        const size = statSync(QUERY_EMBED_CACHE_FILE).size;
+        const fd = openSync(QUERY_EMBED_CACHE_FILE, "r");
+        try {
+            const len = Math.min(size, PERSIST_READ_TAIL_BYTES);
+            const buf = Buffer.alloc(len);
+            readSync(fd, buf, 0, len, size - len);
+            let text = buf.toString("utf8");
+            if (len < size)
+                text = text.slice(text.indexOf("\n") + 1); // drop partial first line
+            for (const line of text.split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const row = JSON.parse(line);
+                    const vec = typeof row.v === "string" ? b64decode(row.v) : null;
+                    if (row.k && vec)
+                        queryEmbedCache.set(row.k, vec); // newest wins (later lines overwrite)
+                }
+                catch { /* skip bad line */ }
+            }
+            // enforce the in-memory cap (keep the newest entries)
+            while (queryEmbedCache.size > QUERY_EMBED_CACHE_MAX) {
+                const oldest = queryEmbedCache.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                queryEmbedCache.delete(oldest);
+            }
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch { /* no cache file yet / unreadable → start empty */ }
+}
+function cacheKey(model, text) {
+    return `${model}:${contentHash(text)}`;
+}
+function cacheGet(key) {
+    loadPersistedOnce();
+    const hit = queryEmbedCache.get(key);
+    if (hit) {
+        // refresh recency (Map preserves insertion order → delete+set = LRU touch)
+        queryEmbedCache.delete(key);
+        queryEmbedCache.set(key, hit);
+    }
+    return hit;
+}
+function cachePut(key, vector) {
+    if (queryEmbedCache.size >= QUERY_EMBED_CACHE_MAX) {
+        const oldest = queryEmbedCache.keys().next().value;
+        if (oldest !== undefined)
+            queryEmbedCache.delete(oldest);
+    }
+    queryEmbedCache.set(key, vector);
+    try {
+        mkdirSync(dirname(QUERY_EMBED_CACHE_FILE), { recursive: true });
+        appendFileSync(QUERY_EMBED_CACHE_FILE, JSON.stringify({ k: key, v: b64encode(vector) }) + "\n");
+    }
+    catch { /* persistence is best-effort — never fail an embed over it */ }
+}
+export class OpenRouterEmbeddingClient {
+    model;
+    apiKey;
+    fetchImpl;
+    baseUrl;
+    constructor(options) {
+        this.apiKey = options.apiKey;
+        this.model = options.model;
+        this.baseUrl = (options.baseUrl ?? "https://openrouter.ai/api/v1").replace(/\/$/, "");
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        // Cache single-text (query) calls — the per-prompt hot path. Batch (document sync) calls
+        // pass through untouched.
+        const key = texts.length === 1 ? cacheKey(this.model, texts[0]) : null;
+        if (key) {
+            const hit = cacheGet(key);
+            if (hit)
+                return [hit];
+        }
+        const response = await this.fetchImpl(this.baseUrl + "/embeddings", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ model: this.model, input: texts })
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => "");
+            throw new Error(`OpenRouter embeddings failed with ${response.status}${body ? `: ${body}` : ""}`);
+        }
+        const json = (await response.json());
+        const data = json.data ?? [];
+        if (data.length !== texts.length) {
+            throw new Error(`OpenRouter embeddings returned ${data.length} vectors for ${texts.length} inputs.`);
+        }
+        // Preserve input order even if the API returns an index field out of order.
+        const ordered = [...data].sort((left, right) => (left.index ?? 0) - (right.index ?? 0));
+        const vectors = ordered.map((item, i) => {
+            const vector = item.embedding;
+            if (!Array.isArray(vector) || vector.length === 0) {
+                throw new Error(`OpenRouter embeddings returned an empty vector at index ${i}.`);
+            }
+            return l2normalize(vector);
+        });
+        if (key && vectors.length === 1)
+            cachePut(key, vectors[0]);
+        return vectors;
+    }
+}
+/**
+ * Local semantic embeddings via an Ollama server (default http://127.0.0.1:11434).
+ * Same quality class as API embeddings but ~30ms on-machine instead of a ~1.3s remote
+ * round-trip, zero API spend, fully offline. Model is part of the cache/sidecar hash,
+ * so switching models auto-triggers document re-embeds through the existing sync path.
+ */
+export class OllamaEmbeddingClient {
+    model;
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.model = options.model;
+        this.baseUrl = (options.baseUrl ?? "http://127.0.0.1:11434").replace(/\/$/, "");
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const key = texts.length === 1 ? cacheKey(this.model, texts[0]) : null;
+        if (key) {
+            const hit = cacheGet(key);
+            if (hit)
+                return [hit];
+        }
+        // Chunk large batches — a whole-brain re-embed (thousands of texts) in one request
+        // overwhelms the local server; ~64 per call keeps each request small and streams progress.
+        const CHUNK = 64;
+        const vectors = [];
+        for (let start = 0; start < texts.length; start += CHUNK) {
+            const slice = texts.slice(start, start + CHUNK);
+            const response = await this.fetchImpl(`${this.baseUrl}/api/embed`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ model: this.model, input: slice })
+            });
+            if (!response.ok) {
+                const body = await response.text().catch(() => "");
+                throw new Error(`Ollama embeddings failed with ${response.status}${body ? `: ${body}` : ""}`);
+            }
+            const json = (await response.json());
+            const data = json.embeddings ?? [];
+            if (data.length !== slice.length) {
+                throw new Error(`Ollama embeddings returned ${data.length} vectors for ${slice.length} inputs.`);
+            }
+            for (let i = 0; i < data.length; i += 1) {
+                const vector = data[i];
+                if (!Array.isArray(vector) || vector.length === 0) {
+                    throw new Error(`Ollama embeddings returned an empty vector at index ${start + i}.`);
+                }
+                vectors.push(l2normalize(vector));
+            }
+        }
+        if (key && vectors.length === 1)
+            cachePut(key, vectors[0]);
+        return vectors;
+    }
+}
+/**
+ * Resilient client that tries the API client first and transparently falls back
+ * to local embeddings on any error, so a flaky network never blocks memory writes.
+ */
+export class FallbackEmbeddingClient {
+    primary;
+    fallback;
+    onFallback;
+    model;
+    constructor(primary, fallback = new LocalEmbeddingClient(), onFallback) {
+        this.primary = primary;
+        this.fallback = fallback;
+        this.onFallback = onFallback;
+        this.model = primary.model;
+    }
+    async embed(texts) {
+        try {
+            return await this.primary.embed(texts);
+        }
+        catch (error) {
+            this.onFallback?.(error);
+            return this.fallback.embed(texts);
+        }
+    }
+}
+/** Build the embedding client implied by config, or null when embeddings are off. */
+export function createEmbeddingClient(options) {
+    const { config } = options;
+    if (config.embeddingMode === "off")
+        return null;
+    if (config.embeddingMode === "ollama") {
+        // Local semantic embeddings. Fall back to the API client (if configured) then trigram-local,
+        // so a stopped Ollama service degrades instead of breaking retrieval.
+        const ollama = new OllamaEmbeddingClient({
+            model: config.embeddingModel ?? "nomic-embed-text",
+            baseUrl: config.ollamaBaseUrl
+        });
+        const fallback = config.openRouterApiKey && config.embeddingModel && config.embeddingModel.includes("/")
+            ? new FallbackEmbeddingClient(new OpenRouterEmbeddingClient({ apiKey: config.openRouterApiKey, model: config.embeddingModel }), new LocalEmbeddingClient(), options.onFallback)
+            : new LocalEmbeddingClient();
+        return new FallbackEmbeddingClient(ollama, fallback, options.onFallback);
+    }
+    const apiKey = config.llmApiKey ?? config.openRouterApiKey;
+    const embeddable = config.provider !== "anthropic"; // Anthropic has no embeddings API — local fallback
+    if (config.embeddingMode === "api" && apiKey && config.embeddingModel && embeddable) {
+        const primary = new OpenRouterEmbeddingClient({
+            apiKey,
+            model: config.embeddingModel,
+            baseUrl: config.llmBaseUrl
+        });
+        return new FallbackEmbeddingClient(primary, new LocalEmbeddingClient(), options.onFallback);
+    }
+    // Default and "api"-without-credentials both resolve to deterministic local embeddings.
+    return new LocalEmbeddingClient();
+}
+function fnv1aInt(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i += 1) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+function fnv1aHex(value) {
+    return fnv1aInt(value).toString(16).padStart(8, "0");
+}