@mem-weave/server 0.2.0

package/dist/db/schema.js

@@ -0,0 +1,185 @@
+export const SCHEMA_SQL = `
+PRAGMA journal_mode = WAL;
+PRAGMA synchronous = NORMAL;
+PRAGMA foreign_keys = ON;
+PRAGMA busy_timeout = 5000;
+
+CREATE TABLE IF NOT EXISTS tenants (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  api_key_hash TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  settings_json TEXT NOT NULL DEFAULT '{}'
+);
+
+CREATE TABLE IF NOT EXISTS devices (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  type TEXT NOT NULL,
+  api_key_hash TEXT NOT NULL,
+  last_seen_at INTEGER,
+  registered_at INTEGER NOT NULL,
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  device_id TEXT,
+  source TEXT NOT NULL,
+  title TEXT NOT NULL,
+  summary TEXT,
+  started_at INTEGER NOT NULL,
+  ended_at INTEGER,
+  observation_count INTEGER NOT NULL DEFAULT 0,
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
+  FOREIGN KEY (device_id) REFERENCES devices(id) ON DELETE SET NULL
+);
+
+CREATE TABLE IF NOT EXISTS memories (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  tier TEXT NOT NULL,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  concepts_json TEXT NOT NULL DEFAULT '[]',
+  concepts_text TEXT NOT NULL DEFAULT '',
+  files_json TEXT NOT NULL DEFAULT '[]',
+  importance INTEGER NOT NULL,
+  confidence REAL NOT NULL,
+  strength REAL NOT NULL,
+  source TEXT NOT NULL,
+  scope_level TEXT NOT NULL,
+  source_client TEXT,
+  source_device_id TEXT,
+  source_session_id TEXT,
+  tau REAL NOT NULL,
+  access_count INTEGER NOT NULL DEFAULT 0,
+  last_accessed_at INTEGER,
+  last_reinforced_at INTEGER,
+  last_decay_at INTEGER,
+  reinforcement_score REAL NOT NULL DEFAULT 0,
+  promoted_at INTEGER,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  deleted_at INTEGER,
+  eviction_reason TEXT,
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS memory_scopes (
+  memory_id TEXT NOT NULL,
+  tenant_id TEXT NOT NULL,
+  key TEXT NOT NULL,
+  value TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  PRIMARY KEY(memory_id, key, value),
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  from_memory_id TEXT NOT NULL,
+  to_memory_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+  strength REAL NOT NULL,
+  reason TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
+  FOREIGN KEY (from_memory_id) REFERENCES memories(id) ON DELETE CASCADE,
+  FOREIGN KEY (to_memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS observations (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  tenant_id TEXT NOT NULL,
+  hook_type TEXT NOT NULL,
+  tool_name TEXT,
+  tool_input TEXT,
+  tool_output TEXT,
+  timestamp INTEGER NOT NULL,
+  memory_id TEXT,
+  processed INTEGER NOT NULL DEFAULT 0,
+  FOREIGN KEY (session_id) REFERENCES sessions(id) ON DELETE CASCADE,
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE SET NULL
+);
+
+CREATE TABLE IF NOT EXISTS access_logs (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  memory_id TEXT NOT NULL,
+  session_id TEXT,
+  device_id TEXT,
+  source TEXT NOT NULL,
+  query TEXT,
+  rank INTEGER,
+  score REAL,
+  used_in_context INTEGER NOT NULL DEFAULT 0,
+  accessed_at INTEGER NOT NULL,
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE,
+  FOREIGN KEY (memory_id) REFERENCES memories(id) ON DELETE CASCADE
+);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+  title,
+  summary,
+  content,
+  concepts_text,
+  content='memories',
+  content_rowid='rowid'
+);
+
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memory_fts(rowid, title, summary, content, concepts_text)
+  VALUES (new.rowid, new.title, new.summary, new.content, new.concepts_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memory_fts(memory_fts, rowid, title, summary, content, concepts_text)
+  VALUES ('delete', old.rowid, old.title, old.summary, old.content, old.concepts_text);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memory_fts(memory_fts, rowid, title, summary, content, concepts_text)
+  VALUES ('delete', old.rowid, old.title, old.summary, old.content, old.concepts_text);
+  INSERT INTO memory_fts(rowid, title, summary, content, concepts_text)
+  VALUES (new.rowid, new.title, new.summary, new.content, new.concepts_text);
+END;
+
+CREATE INDEX IF NOT EXISTS idx_memories_tenant_tier_strength ON memories(tenant_id, tier, strength DESC);
+CREATE INDEX IF NOT EXISTS idx_memories_tenant_type_created ON memories(tenant_id, type, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_memory_scopes_tenant_key_value ON memory_scopes(tenant_id, key, value);
+CREATE INDEX IF NOT EXISTS idx_memory_scopes_memory_id ON memory_scopes(memory_id);
+CREATE INDEX IF NOT EXISTS idx_edges_from ON edges(from_memory_id);
+CREATE INDEX IF NOT EXISTS idx_edges_to ON edges(to_memory_id);
+CREATE INDEX IF NOT EXISTS idx_access_logs_memory_time ON access_logs(memory_id, accessed_at DESC);
+CREATE INDEX IF NOT EXISTS idx_access_logs_tenant_time ON access_logs(tenant_id, accessed_at DESC);
+
+CREATE TABLE IF NOT EXISTS consolidation_runs (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  started_at INTEGER NOT NULL,
+  ended_at INTEGER NOT NULL,
+  promoted_count INTEGER NOT NULL DEFAULT 0,
+  evicted_count INTEGER NOT NULL DEFAULT 0,
+  merged_count INTEGER NOT NULL DEFAULT 0,
+  edges_created_count INTEGER NOT NULL DEFAULT 0,
+  contradiction_found_count INTEGER NOT NULL DEFAULT 0,
+  promoted_ids TEXT NOT NULL DEFAULT '[]',
+  evicted_ids TEXT NOT NULL DEFAULT '[]',
+  merged_pairs TEXT NOT NULL DEFAULT '[]',
+  dry_run INTEGER NOT NULL DEFAULT 0,
+  summary TEXT NOT NULL DEFAULT '',
+  FOREIGN KEY (tenant_id) REFERENCES tenants(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_consolidation_runs_tenant_time
+  ON consolidation_runs(tenant_id, started_at DESC);
+`;

package/dist/injection/bundler.js

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+export function createContentHash(phase, memoryIds) {
+    const sorted = [...memoryIds].sort();
+    const input = `${phase}:${sorted.join(',')}`;
+    return createHash('sha256').update(input).digest('hex').slice(0, 16);
+}
+export function buildStablePack(memories, options) {
+    const filtered = memories.filter(m => m.tier === 'long' || (m.tier === 'medium' && m.strength >= 0.4));
+    const sorted = [...filtered].sort((a, b) => {
+        if (a.tier === 'long' && b.tier !== 'long')
+            return -1;
+        if (a.tier !== 'long' && b.tier === 'long')
+            return 1;
+        return b.strength * b.importance - a.strength * a.importance;
+    });
+    return finalizePack(sorted, options);
+}
+export function buildDeltaPack(candidates, options) {
+    const filtered = candidates.filter(c => !options.alreadyInjected.has(c.id));
+    const sorted = [...filtered].sort((a, b) => b.strength * b.importance - a.strength * a.importance);
+    return finalizePack(sorted, options);
+}
+function finalizePack(memories, options) {
+    const selected = [];
+    let tokens = 0;
+    for (const m of memories) {
+        const cost = Math.max(20, Math.ceil((m.title.length + m.summary.length) / 3));
+        if (tokens + cost > options.budget)
+            break;
+        selected.push(m);
+        tokens += cost;
+    }
+    const memoryIds = selected.map(m => m.id);
+    return {
+        memoryIds,
+        contentHash: createContentHash('session_start', memoryIds),
+        estimatedTokens: tokens
+    };
+}

package/dist/injection/formatter.js

@@ -0,0 +1,23 @@
+export function formatMemoriesAsXml(phase, memories) {
+    const sorted = [...memories].sort((a, b) => {
+        const tierOrder = { long: 0, medium: 1, short: 2 };
+        const aOrder = tierOrder[a.tier] ?? 2;
+        const bOrder = tierOrder[b.tier] ?? 2;
+        if (aOrder !== bOrder)
+            return aOrder - bOrder;
+        return b.strength * b.importance - a.strength * a.importance;
+    });
+    const header = `<memory-context phase="${escapeAttr(phase)}" count="${sorted.length}">`;
+    const items = sorted.map(m => `  <memory id="${escapeAttr(m.id)}" type="${escapeAttr(m.type)}" tier="${escapeAttr(m.tier)}" strength="${m.strength.toFixed(2)}" importance="${m.importance}">\n` +
+        `    <title>${escapeText(m.title)}</title>\n` +
+        `    <summary>${escapeText(m.summary)}</summary>\n` +
+        `  </memory>`);
+    const footer = `</memory-context>`;
+    return [header, ...items, footer].join('\n');
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeText(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}

package/dist/prompts/compression.js

@@ -0,0 +1,43 @@
+export const COMPRESSION_SYSTEM = `You are a memory compression engine for an AI coding agent. Your job is to extract the essential information from a tool usage observation and compress it into structured data.
+
+Output EXACTLY this JSON with no additional text:
+{
+  "shouldCreateMemory": true,
+  "type": "fact|decision|preference|event|project_context|lesson|code_pattern|bug|workflow",
+  "title": "Short descriptive title (max 80 chars)",
+  "summary": "One-line summary (max 200 chars)",
+  "content": "2-3 sentence narrative of what happened and why it matters",
+  "concepts": ["technical concept or pattern"],
+  "files": ["path/to/file"],
+  "importance": 5,
+  "confidence": 0.8,
+  "scopeLevel": "project",
+  "scopes": [
+    { "key": "project", "value": "project-name" },
+    { "key": "domain", "value": "domain-name" },
+    { "key": "topic", "value": "topic-name" }
+  ],
+  "candidateEdges": [
+    { "targetHint": "related memory title or concept", "type": "related_to", "reason": "why related", "confidence": 0.7 }
+  ]
+}
+
+Rules:
+- Be concise but preserve ALL technically relevant details.
+- File paths must be exact.
+- Importance: 1-3 for routine reads, 4-6 for edits/commands, 7-9 for architectural decisions, 10 for breaking changes.
+- Concepts should be reusable search terms.
+- Strip any secrets, tokens, or credentials from the output.
+- If the observation is not worth remembering, set shouldCreateMemory to false.`;
+export function buildCompressionPrompt(observation) {
+    const parts = [`Timestamp: ${observation.timestamp}`, `Hook: ${observation.hookType}`];
+    if (observation.toolName)
+        parts.push(`Tool: ${observation.toolName}`);
+    if (observation.toolInput)
+        parts.push(`Input:\n${observation.toolInput.slice(0, 4000)}`);
+    if (observation.toolOutput)
+        parts.push(`Output:\n${observation.toolOutput.slice(0, 8000)}`);
+    if (observation.userPrompt)
+        parts.push(`User prompt:\n${observation.userPrompt.slice(0, 2000)}`);
+    return parts.join('\n\n');
+}

package/dist/prompts/edge-extract.js

@@ -0,0 +1,21 @@
+export const EDGE_EXTRACT_SYSTEM = `You are a relationship extraction engine for a memory graph. Given a new memory and a list of existing memories, identify relationships between them.
+
+Output EXACTLY this JSON array with no additional text:
+[
+  {
+    "targetMemoryId": "existing_memory_id",
+    "type": "causes|enables|contradicts|supersedes|references|related_to|before|after|duplicates|refines",
+    "reason": "Why this relationship exists",
+    "confidence": 0.85
+  }
+]
+
+Rules:
+- Only output relationships with confidence >= 0.6.
+- If no relationship exists, output an empty array [].
+- Be conservative: only create edges when there is a clear, meaningful relationship.`;
+export function buildEdgeExtractPrompt(newMemory, existingMemories) {
+    const newSection = `New memory:\nTitle: ${newMemory.title}\nContent: ${newMemory.content}\nConcepts: ${newMemory.concepts.join(', ')}`;
+    const existingSection = existingMemories.map(m => `[${m.id}] Title: ${m.title}\nSummary: ${m.summary}\nConcepts: ${m.concepts.join(', ')}`).join('\n\n');
+    return `${newSection}\n\nExisting memories:\n${existingSection}`;
+}

package/dist/prompts/value-gate.js

@@ -0,0 +1,27 @@
+export const VALUE_GATE_SYSTEM = `You are a value gate for an AI coding agent's memory system. Given a raw observation, determine whether it contains information worth remembering.
+
+Output EXACTLY this JSON with no additional text:
+{
+  "shouldCreateMemory": true,
+  "reason": "Why this is worth remembering",
+  "suggestedTypes": ["decision"],
+  "priority": "high"
+}
+
+Rules:
+- shouldCreateMemory = true for: explicit user requests to remember, architectural decisions, bug root causes, user preferences, project conventions, workflow patterns.
+- shouldCreateMemory = false for: routine file reads, simple grep searches, repeated successful commands with no new information, transient state.
+- priority: "high" for decisions/bugs/preferences, "medium" for project context/lessons, "low" for uncertain cases.
+- suggestedTypes should be the most likely MemoryType(s) from: fact, decision, preference, event, project_context, lesson, code_pattern, bug, workflow.`;
+export function buildValueGatePrompt(observation) {
+    const parts = [`Hook: ${observation.hookType}`];
+    if (observation.toolName)
+        parts.push(`Tool: ${observation.toolName}`);
+    if (observation.toolInput)
+        parts.push(`Input:\n${observation.toolInput.slice(0, 2000)}`);
+    if (observation.toolOutput)
+        parts.push(`Output:\n${observation.toolOutput.slice(0, 4000)}`);
+    if (observation.userPrompt)
+        parts.push(`User prompt:\n${observation.userPrompt.slice(0, 1000)}`);
+    return parts.join('\n\n');
+}

package/dist/providers/embedding/index.js

@@ -0,0 +1,36 @@
+/**
+ * Embedding provider abstraction (matches design spec §9.5).
+ *
+ * Implementations:
+ * - `NoopEmbeddingProvider`: returns a deterministic dummy vector (zeros or hash-derived)
+ * - `OpenaiCompatibleEmbeddingProvider`: POSTs to /v1/embeddings
+ * - `LocalXenovaEmbeddingProvider`: uses @xenova/transformers (not bundled in v1;
+ *   this is a stub that explains the install path)
+ */
+import { NoopEmbeddingProvider } from './noop.js';
+import { OpenaiCompatibleEmbeddingProvider } from './openai-compatible.js';
+import { LocalXenovaEmbeddingProvider } from './local-xenova.js';
+export { NoopEmbeddingProvider, OpenaiCompatibleEmbeddingProvider, LocalXenovaEmbeddingProvider };
+export function createEmbeddingProvider(options) {
+    switch (options.kind) {
+        case 'openai-compatible':
+            return new OpenaiCompatibleEmbeddingProvider({
+                baseUrl: options.baseUrl ?? 'https://api.openai.com/v1',
+                apiKey: options.apiKey ?? '',
+                model: options.model ?? 'text-embedding-3-small',
+                dimensions: options.dimensions ?? 1536,
+                timeoutMs: options.timeoutMs ?? 30000
+            });
+        case 'local-xenova':
+            return new LocalXenovaEmbeddingProvider({
+                model: options.model ?? 'Xenova/nomic-embed-text-v1',
+                dimensions: options.dimensions ?? 768
+            });
+        case 'noop':
+        default:
+            return new NoopEmbeddingProvider({
+                dimensions: options.dimensions ?? 768,
+                model: options.model ?? 'noop'
+            });
+    }
+}

package/dist/providers/embedding/local-xenova.js

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import { logger } from '../../server/logger.js';
+/**
+ * Local-xenova embedding provider.
+ *
+ * Uses `@xenova/transformers` (Hugging Face Transformers.js) running in-process.
+ * The dependency is **optional** — we dynamically import it on first use. If the
+ * package is not installed, this provider falls back to a deterministic noop
+ * embedding (with a one-time `console.warn`) so the rest of the system stays
+ * functional. The user can opt back in by running:
+ *
+ *   npm install @xenova/transformers
+ *
+ * Models are loaded lazily on the first `embed()` / `embedBatch()` call and
+ * cached for the lifetime of this provider instance. The first call may be slow
+ * (~10–60s) while the model weights are fetched from the HF Hub and cached
+ * under `node_modules/@xenova/transformers/.cache/`.
+ */
+export class LocalXenovaEmbeddingProvider {
+    model;
+    dimensions;
+    timeoutMs;
+    fallbackOnError;
+    /**
+     * Cached pipeline. `null` until the first embed call. We cache the *promise*
+     * (not the resolved value) so concurrent callers share one load.
+     */
+    extractorPromise = null;
+    /** Set to true after we've warned the user about the missing dep. Avoids spam. */
+    warnedMissingDep = false;
+    constructor(options) {
+        this.model = options.model;
+        this.dimensions = options.dimensions;
+        this.timeoutMs = options.timeoutMs ?? 60_000;
+        this.fallbackOnError = options.fallbackOnError ?? true;
+    }
+    async embed(text) {
+        const results = await this.embedBatch([text]);
+        return results[0];
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        let extractor;
+        try {
+            extractor = await this.getExtractor();
+        }
+        catch (err) {
+            return this.handleError(err, texts);
+        }
+        // Type-narrowed access to the dynamic module. The library's official types
+        // are not always present, so we keep the surface narrow and adapt at runtime.
+        const pipeline = extractor;
+        try {
+            const out = await Promise.race([
+                pipeline(texts, { pooling: 'mean', normalize: true }),
+                this.timeoutAfter(this.timeoutMs)
+            ]);
+            const flat = this.toNumberArray(out.data);
+            // Per-text rows. The xenova pipeline returns [batch, dim] for batches
+            // and [dim] for single inputs. Normalize to [text][dim].
+            const rows = texts.length === 1
+                ? [this.coerceLength(flat)]
+                : this.splitRows(flat, texts.length);
+            return rows.map((row) => this.coerceLength(row));
+        }
+        catch (err) {
+            return this.handleError(err, texts);
+        }
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    async getExtractor() {
+        if (this.extractorPromise)
+            return this.extractorPromise;
+        this.extractorPromise = (async () => {
+            // Dynamic import: the package is an optional dependency.
+            const mod = await import('@xenova/transformers').catch((err) => {
+                throw new XenovaMissingError(`@xenova/transformers is not installed. Run \`npm install @xenova/transformers\` to enable local embeddings. (cause: ${err.message})`);
+            });
+            const pipeline = mod.pipeline;
+            if (typeof pipeline !== 'function') {
+                throw new XenovaMissingError('@xenova/transformers was loaded but exposes no `pipeline` function — incompatible version?');
+            }
+            return await pipeline('feature-extraction', this.model);
+        })();
+        return this.extractorPromise;
+    }
+    handleError(err, texts) {
+        if (err instanceof XenovaMissingError) {
+            if (!this.warnedMissingDep) {
+                logger.warn({ err: err.message }, 'local-xenova unavailable, falling back to noop embeddings');
+                this.warnedMissingDep = true;
+            }
+            // Reset so a future install can pick it up.
+            this.extractorPromise = null;
+        }
+        else {
+            logger.warn({ err: err.message }, 'local-xenova embedding failed');
+            // Reset so transient errors (network blip, OOM) can recover.
+            this.extractorPromise = null;
+        }
+        if (!this.fallbackOnError)
+            throw err;
+        return Promise.resolve(texts.map((t) => deriveFallbackVector(t, this.dimensions)));
+    }
+    toNumberArray(data) {
+        const out = new Array(data.length);
+        for (let i = 0; i < data.length; i++)
+            out[i] = data[i];
+        return out;
+    }
+    splitRows(flat, expectedRows) {
+        if (flat.length === 0 || expectedRows === 0)
+            return [];
+        const dim = Math.floor(flat.length / expectedRows);
+        const rows = new Array(expectedRows);
+        for (let r = 0; r < expectedRows; r++) {
+            rows[r] = flat.slice(r * dim, (r + 1) * dim);
+        }
+        return rows;
+    }
+    /**
+     * Coerce a vector to the configured `dimensions`. If shorter, pad with zeros.
+     * If longer, truncate. Matches the graceful-degrade style of vector-search.ts.
+     */
+    coerceLength(vec) {
+        if (vec.length === this.dimensions)
+            return vec;
+        if (vec.length > this.dimensions)
+            return vec.slice(0, this.dimensions);
+        const padded = new Array(this.dimensions).fill(0);
+        for (let i = 0; i < vec.length; i++)
+            padded[i] = vec[i];
+        return padded;
+    }
+    timeoutAfter(ms) {
+        return new Promise((_, reject) => {
+            const t = setTimeout(() => reject(new Error(`local-xenova timed out after ${ms}ms`)), ms);
+            // Don't keep the event loop alive just for the timeout.
+            if (typeof t.unref === 'function')
+                t.unref();
+        });
+    }
+}
+class XenovaMissingError extends Error {
+    name = 'XenovaMissingError';
+}
+/**
+ * Deterministic vector derived from a SHA-256 hash of the input. Used as the
+ * fallback when `@xenova/transformers` is unavailable. The algorithm is
+ * intentionally identical to `NoopEmbeddingProvider` so the search engine sees
+ * a stable embedding space across both code paths.
+ */
+function deriveFallbackVector(text, dimensions) {
+    const out = new Array(dimensions);
+    let counter = 0;
+    let i = 0;
+    while (i < dimensions) {
+        const hash = createHash('sha256').update(`${text}::${counter++}`).digest();
+        for (let b = 0; b < hash.length && i < dimensions; b++, i++) {
+            // Map byte to [-1, 1] deterministically.
+            out[i] = (hash[b] / 255) * 2 - 1;
+        }
+    }
+    return out;
+}

package/dist/providers/embedding/noop.js

@@ -0,0 +1,40 @@
+import { createHash } from 'node:crypto';
+/**
+ * Deterministic no-op embedding provider. Produces vectors derived from a SHA-256
+ * hash of the input text. The output is NOT semantically meaningful — it only
+ * exists to make the rest of the pipeline testable when no real embedding
+ * service is available. Use the same algorithm for "missing" embeddings so
+ * the search engine has something deterministic to compare against.
+ */
+export class NoopEmbeddingProvider {
+    dimensions;
+    model;
+    constructor(options) {
+        this.dimensions = options.dimensions;
+        this.model = options.model;
+    }
+    async embed(text) {
+        return deriveDeterministicVector(text, this.dimensions);
+    }
+    async embedBatch(texts) {
+        return texts.map((t) => deriveDeterministicVector(t, this.dimensions));
+    }
+}
+/**
+ * Deterministically derive a fixed-length vector from a string.
+ * Repeats and hashes the text in chunks, then normalizes to [-1, 1].
+ * The same input always produces the same vector.
+ */
+function deriveDeterministicVector(text, dimensions) {
+    const out = new Array(dimensions);
+    let counter = 0;
+    let i = 0;
+    while (i < dimensions) {
+        const hash = createHash('sha256').update(`${text}::${counter++}`).digest();
+        for (let b = 0; b < hash.length && i < dimensions; b++, i++) {
+            // Map byte to [-1, 1] deterministically.
+            out[i] = (hash[b] / 255) * 2 - 1;
+        }
+    }
+    return out;
+}

package/dist/providers/embedding/openai-compatible.js

@@ -0,0 +1,46 @@
+/**
+ * Embedding provider that calls an OpenAI-compatible /v1/embeddings endpoint.
+ */
+export class OpenaiCompatibleEmbeddingProvider {
+    model;
+    dimensions;
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.model = options.model;
+        this.dimensions = options.dimensions;
+        this.timeoutMs = options.timeoutMs;
+    }
+    async embed(text) {
+        const results = await this.embedBatch([text]);
+        return results[0];
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const url = `${this.baseUrl}/embeddings`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.apiKey}`
+            },
+            body: JSON.stringify({
+                model: this.model,
+                input: texts
+            }),
+            signal: AbortSignal.timeout(this.timeoutMs)
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Embedding API error ${res.status}: ${text.slice(0, 200)}`);
+        }
+        const json = await res.json();
+        // Order by index to be safe
+        const sorted = json.data.slice().sort((a, b) => a.index - b.index);
+        return sorted.map((d) => d.embedding);
+    }
+}

package/dist/providers/llm/index.js

@@ -0,0 +1,12 @@
+import { OpenaiLlmProvider } from './openai.js';
+import { NoopLlmProvider } from './noop.js';
+export function createLlmProvider(kind, config) {
+    switch (kind) {
+        case 'openai-compatible':
+            return new OpenaiLlmProvider(config);
+        case 'noop':
+            return new NoopLlmProvider();
+        default:
+            throw new Error('Unknown LLM provider kind: ' + kind);
+    }
+}

package/dist/providers/llm/noop.js

@@ -0,0 +1,5 @@
+export class NoopLlmProvider {
+    async call(_systemPrompt, _userPrompt) {
+        return '';
+    }
+}