@jbarket/loomai 0.5.0

package/dist/backends/embedding-runtime.js

@@ -0,0 +1,265 @@
+/**
+ * Dense ONNX embedding runtime — vendored from the `fastembed` npm package.
+ *
+ * Why this file exists rather than a dependency: `Anush008/fastembed-js` was
+ * archived on GitHub (last push 2025-12-15, latest publish 2.1.0). It pins
+ * `tar: ^6.2.0`, and the 6.x line carries twelve unpatched advisories
+ * including one critical. There is no upstream release to wait for, and an
+ * `overrides` bump to tar 7 is blocked by exactly one line in the package —
+ * `import tar from "tar"`, which tar 7 (no default export) turns into a hard
+ * SyntaxError at import time.
+ *
+ * So the ~200 lines loom actually used are inlined here, depending directly on
+ * `onnxruntime-node`, `@anush008/tokenizers` and `tar@^7`. Dropped along the
+ * way: `progress` (loom always passed showDownloadProgress: false) and
+ * `@huggingface/hub` (only the unused sparse/SPLADE path needed it).
+ *
+ * BEHAVIOUR IS PRESERVED BIT-FOR-BIT ON PURPOSE. Every vector already stored
+ * in a loom database came out of the upstream package; a "cleanup" that
+ * changed rounding, pooling or the query prefix would silently make old and
+ * new vectors incomparable. Two upstream quirks are therefore kept, each
+ * marked below:
+ *   1. Vectors stay Float32Array end to end (normalisation rounds to f32).
+ *   2. queryEmbed prefixes "query: ", an E5 convention that BGE does not
+ *      actually use. Changing it moves every query in the embedding space.
+ * Parity against fastembed@2.1.0 is asserted in embedding-runtime.parity.test.ts.
+ */
+import { AddedToken, Tokenizer } from '@anush008/tokenizers';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { get as httpsGet } from 'node:https';
+import { extname, join } from 'node:path';
+import * as ort from 'onnxruntime-node';
+import * as tar from 'tar';
+/** Dense models this runtime knows how to fetch and run. */
+export const EmbeddingModel = {
+    AllMiniLML6V2: 'fast-all-MiniLM-L6-v2',
+    BGEBaseEN: 'fast-bge-base-en',
+    BGEBaseENV15: 'fast-bge-base-en-v1.5',
+    BGESmallEN: 'fast-bge-small-en',
+    BGESmallENV15: 'fast-bge-small-en-v1.5',
+    BGESmallZH: 'fast-bge-small-zh-v1.5',
+    MLE5Large: 'fast-multilingual-e5-large',
+};
+/**
+ * Where model tarballs come from. The upstream default is a Qdrant-owned GCS
+ * bucket whose access has broken at least twice (fastembed-js issues #18, #33)
+ * and which nobody maintains any more; the env override exists so a broken
+ * bucket is a config change, not a release.
+ */
+const DEFAULT_MODEL_BASE_URL = 'https://storage.googleapis.com/qdrant-fastembed';
+/**
+ * Loaded dense embedder: a tokenizer plus an ONNX inference session.
+ *
+ * Named for the upstream class so the diff in fastembed.ts stays reviewable.
+ */
+export class FlagEmbedding {
+    tokenizer;
+    session;
+    model;
+    constructor(tokenizer, session, model) {
+        this.tokenizer = tokenizer;
+        this.session = session;
+        this.model = model;
+    }
+    static async init({ model, cacheDir, maxLength = 512, }) {
+        const modelDir = await retrieveModel(model, cacheDir);
+        const tokenizer = loadTokenizer(modelDir, maxLength);
+        // MiniLM and multilingual-e5 ship an unoptimised graph; the BGE family
+        // ships an optimised one. Upstream picks by model, so we do too.
+        const fileName = model === EmbeddingModel.MLE5Large || model === EmbeddingModel.AllMiniLML6V2
+            ? 'model.onnx'
+            : 'model_optimized.onnx';
+        const modelPath = join(modelDir, fileName);
+        if (!existsSync(modelPath)) {
+            throw new Error(`Model file not found at ${modelPath}`);
+        }
+        const session = await ort.InferenceSession.create(modelPath, {
+            executionProviders: ['cpu'],
+            graphOptimizationLevel: 'all',
+        });
+        return new FlagEmbedding(tokenizer, session, model);
+    }
+    async *embed(texts, batchSize = 256) {
+        for (let i = 0; i < texts.length; i += batchSize) {
+            yield await this.runBatch(texts.slice(i, i + batchSize));
+        }
+    }
+    /**
+     * QUIRK PRESERVED: the "query: " prefix is the E5 instruction format. BGE
+     * models want "Represent this sentence for searching relevant passages: "
+     * instead. Upstream applied E5's prefix to every model and loom's stored
+     * vectors were produced under that regime, so it stays until we decide to
+     * re-embed. See t-424.
+     */
+    async queryEmbed(query) {
+        const [vector] = await this.runBatch([`query: ${query}`]);
+        if (!vector) {
+            throw new Error('embedding runtime: queryEmbed produced no vector');
+        }
+        return vector;
+    }
+    async runBatch(texts) {
+        const encoded = await Promise.all(texts.map((text) => this.tokenizer.encode(text)));
+        const ids = [];
+        const mask = [];
+        const typeIds = [];
+        for (const item of encoded) {
+            ids.push(item.getIds().map(BigInt));
+            mask.push(item.getAttentionMask().map(BigInt));
+            typeIds.push(item.getTypeIds().map(BigInt));
+        }
+        // Padding is fixed-length, so every row in the batch has the same length.
+        const width = ids[0]?.length ?? 0;
+        const shape = [texts.length, width];
+        const inputs = {
+            input_ids: new ort.Tensor('int64', ids.flat(), shape),
+            attention_mask: new ort.Tensor('int64', mask.flat(), shape),
+            token_type_ids: new ort.Tensor('int64', typeIds.flat(), shape),
+        };
+        // multilingual-e5 has no token_type_ids input in its graph.
+        if (this.model === EmbeddingModel.MLE5Large) {
+            delete inputs.token_type_ids;
+        }
+        const output = await this.session.run(inputs);
+        const hidden = output.last_hidden_state;
+        if (!hidden) {
+            throw new Error('embedding runtime: model produced no last_hidden_state output');
+        }
+        return cls(hidden.data, hidden.dims).map(normalize);
+    }
+}
+/**
+ * CLS pooling: take the first token's hidden state for each sequence.
+ *
+ * Mirrors qdrant/fastembed a335c88, which removed attention pooling. Slicing a
+ * Float32Array yields a Float32Array — that is load-bearing, see file header.
+ */
+function cls(data, dims) {
+    const [batch = 0, , hiddenSize = 0] = dims;
+    return Array.from({ length: batch }, (_unused, index) => {
+        const start = index * dims[1] * hiddenSize;
+        return data.slice(start, start + hiddenSize);
+    });
+}
+/** L2 normalisation. Stays in Float32Array so results round exactly as before. */
+function normalize(v) {
+    let sum = 0;
+    for (const val of v)
+        sum += val * val;
+    const norm = Math.sqrt(sum);
+    return v.map((val) => val / Math.max(norm, 1e-12));
+}
+function loadTokenizer(modelDir, maxLength) {
+    const config = readJson(modelDir, 'config.json');
+    const tokenizerConfig = readJson(modelDir, 'tokenizer_config.json');
+    const tokensMap = readJson(modelDir, 'special_tokens_map.json');
+    const tokenizerPath = join(modelDir, 'tokenizer.json');
+    if (!existsSync(tokenizerPath)) {
+        throw new Error(`Tokenizer file not found at ${tokenizerPath}`);
+    }
+    const tokenizer = Tokenizer.fromFile(tokenizerPath);
+    tokenizer.setTruncation(Math.min(maxLength, Number(tokenizerConfig['model_max_length'])));
+    tokenizer.setPadding({
+        maxLength: Math.min(maxLength, Number(tokenizerConfig['model_max_length'])),
+        padId: config['pad_token_id'],
+        padToken: tokenizerConfig['pad_token'],
+    });
+    for (const token of Object.values(tokensMap)) {
+        if (typeof token === 'string') {
+            tokenizer.addSpecialTokens([token]);
+        }
+        else if (isAddedTokenMap(token)) {
+            tokenizer.addAddedTokens([
+                new AddedToken(token['content'], true, {
+                    singleWord: token['single_word'],
+                    leftStrip: token['lstrip'],
+                    rightStrip: token['rstrip'],
+                    normalized: token['normalized'],
+                }),
+            ]);
+        }
+    }
+    return tokenizer;
+}
+function readJson(modelDir, fileName) {
+    const path = join(modelDir, fileName);
+    if (!existsSync(path)) {
+        throw new Error(`${fileName} not found at ${path}`);
+    }
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+/**
+ * QUIRK PRESERVED: upstream tests for a `token` key that special_tokens_map
+ * files do not have (they use `content`), so object-valued entries were always
+ * skipped. Every model loom ships uses plain-string entries, making the branch
+ * dead either way — but tightening the check would change tokenization for
+ * some other model, so it stays as it was.
+ */
+function isAddedTokenMap(token) {
+    return (typeof token === 'object' &&
+        token !== null &&
+        'token' in token &&
+        'single_word' in token &&
+        'rstrip' in token &&
+        'lstrip' in token &&
+        'normalized' in token);
+}
+async function retrieveModel(model, cacheDir) {
+    if (!existsSync(cacheDir)) {
+        mkdirSync(cacheDir, { recursive: true });
+    }
+    const modelDir = join(cacheDir, model);
+    if (existsSync(modelDir))
+        return modelDir;
+    const archive = join(cacheDir, `${model}.tar.gz`);
+    await download(archive, model);
+    try {
+        await extract(archive, cacheDir);
+    }
+    finally {
+        if (existsSync(archive))
+            unlinkSync(archive);
+    }
+    return modelDir;
+}
+async function extract(archive, cacheDir) {
+    if (extname(archive) !== '.gz') {
+        throw new Error(`Unsupported file extension: ${archive}`);
+    }
+    await tar.x({ file: archive, cwd: cacheDir });
+}
+function download(outputPath, model) {
+    if (existsSync(outputPath))
+        return Promise.resolve();
+    // The MiniLM archive is published under its sentence-transformers name even
+    // though its directory inside the tarball is the fast-* one.
+    const remoteName = model === EmbeddingModel.AllMiniLML6V2
+        ? `sentence-transformers${model.substring(model.indexOf('-'))}`
+        : model;
+    const base = process.env.LOOM_MODEL_BASE_URL ?? DEFAULT_MODEL_BASE_URL;
+    const url = `${base}/${remoteName}.tar.gz`;
+    return new Promise((resolve, reject) => {
+        const fail = (err) => {
+            // A partial archive on disk would be treated as a complete download on
+            // the next run, so it must not survive a failure.
+            if (existsSync(outputPath))
+                unlinkSync(outputPath);
+            reject(err);
+        };
+        const file = createWriteStream(outputPath);
+        file.on('error', fail);
+        httpsGet(url, { headers: { 'User-Agent': 'loom' } }, (response) => {
+            if (response.statusCode !== 200) {
+                response.resume();
+                fail(new Error(`Model download failed: ${url} returned HTTP ${response.statusCode}. ` +
+                    'Set LOOM_MODEL_BASE_URL to fetch models from a different host.'));
+                return;
+            }
+            response.on('error', fail);
+            response.pipe(file);
+            file.on('finish', () => {
+                file.close((err) => (err ? fail(err) : resolve()));
+            });
+        }).on('error', fail);
+    });
+}

package/dist/backends/episodes.d.ts

@@ -0,0 +1,36 @@
+export interface EpisodeRow {
+    title: string;
+    content: string;
+    created: string;
+    project: string | null;
+    metadata: string;
+}
+export interface TapeOptions {
+    /** Look-back window in hours (default 24). */
+    hours?: number;
+    /** Approximate token budget for the block (default 1500). Oldest are dropped first. */
+    tokenBudget?: number;
+    /** Rough chars-per-token for the budget estimate. */
+    charsPerToken?: number;
+    /** IANA zone for the timestamps (default: TZ env, else America/Chicago). */
+    timeZone?: string;
+    /** "now" override for tests. */
+    nowMs?: number;
+}
+/** "Mon 17:05" in the configured zone — the tape reads as a clock, not ISO. */
+export declare function tapeClock(iso: string, timeZone: string): string;
+/** One line per episode — authored content, trimmed to a single line, never synthesized. */
+export declare function episodeLine(r: EpisodeRow, timeZone: string): string;
+/**
+ * Assemble the tape: oldest→newest, within budget, most-recent kept when over.
+ * Pure selection + ordering. Returns null when there are no episodes.
+ */
+export declare function assembleTape(rows: EpisodeRow[], opts?: TapeOptions): string | null;
+/** Raw episode rows in the window, oldest first. Empty when there is no store. */
+export declare function episodeRows(contextDir: string, opts?: TapeOptions): EpisodeRow[];
+/**
+ * The boot tape for a context: "what happened across all of me in the last
+ * N hours", time-ordered. Null when nothing happened (or no store) — the
+ * identity block is simply omitted then.
+ */
+export declare function tapeForContext(contextDir: string, opts?: TapeOptions): string | null;

package/dist/backends/episodes.js

@@ -0,0 +1,126 @@
+/**
+ * The episode tape (t-142) — the short-term, cross-body memory tier.
+ *
+ * Art runs as many sleeves at once (discord bodies, wakes, lanes, the voice
+ * brain, terminals). They share the stack (loom) but not the last few hours:
+ * what one body did is invisible to the next unless someone judged it worth a
+ * month. Episodes fill that gap. Each body writes a short note — where it was,
+ * what was said or decided, what shipped, what's open — as category `episode`
+ * with a 48h TTL. At boot every body receives the last 24h of episodes as a
+ * plain TIME-ORDERED tape, injected right after identity.
+ *
+ * Deliberately NOT salience-ranked: salience reheats on recall, so a ranked
+ * view surfaces what the last body *searched for*, not what last *happened*.
+ * The tape is the wrong place for cleverness — it is just the tape.
+ *
+ * Like salience, this opens memories.db directly (plain SQL, no embedder) so
+ * identity load stays cheap.
+ */
+import { existsSync } from 'node:fs';
+import BetterSqlite3 from 'better-sqlite3';
+import { resolveSqliteDbPath } from '../config.js';
+import { EPISODE_CATEGORY } from '../categories.js';
+const DEFAULT_HOURS = 24;
+const DEFAULT_TOKEN_BUDGET = 1500;
+const DEFAULT_CHARS_PER_TOKEN = 4;
+const HOUR_MS = 3_600_000;
+function zone(opts) {
+    return opts.timeZone ?? process.env.LOOM_TIMEZONE ?? process.env.TZ ?? 'America/Chicago';
+}
+/** "Mon 17:05" in the configured zone — the tape reads as a clock, not ISO. */
+export function tapeClock(iso, timeZone) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return iso;
+    try {
+        return new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            weekday: 'short',
+            hour: '2-digit',
+            minute: '2-digit',
+            hour12: false,
+        }).format(d).replace(',', '');
+    }
+    catch {
+        return iso;
+    }
+}
+/** Where the body was: metadata.where wins, then project, else unknown. */
+function whereOf(r) {
+    try {
+        const meta = JSON.parse(r.metadata || '{}');
+        if (typeof meta.where === 'string' && meta.where.trim())
+            return meta.where.trim();
+    }
+    catch {
+        /* fall through */
+    }
+    return r.project?.trim() || '?';
+}
+/** One line per episode — authored content, trimmed to a single line, never synthesized. */
+export function episodeLine(r, timeZone) {
+    const body = r.content.replace(/\s+/g, ' ').trim();
+    const clipped = body.length > 600 ? body.slice(0, 597).trimEnd() + '…' : body;
+    return `- **${tapeClock(r.created, timeZone)}** [${whereOf(r)}] ${r.title} — ${clipped}`;
+}
+/**
+ * Assemble the tape: oldest→newest, within budget, most-recent kept when over.
+ * Pure selection + ordering. Returns null when there are no episodes.
+ */
+export function assembleTape(rows, opts = {}) {
+    if (rows.length === 0)
+        return null;
+    const tz = zone(opts);
+    const budgetChars = (opts.tokenBudget ?? DEFAULT_TOKEN_BUDGET) * (opts.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN);
+    const ordered = [...rows].sort((a, b) => Date.parse(a.created) - Date.parse(b.created));
+    const lines = ordered.map((r) => episodeLine(r, tz));
+    // Fill from the newest end backwards so the budget drops the OLDEST first.
+    const kept = [];
+    let used = 0;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (used + line.length > budgetChars && kept.length > 0)
+            break;
+        kept.unshift(line);
+        used += line.length + 1;
+    }
+    const dropped = lines.length - kept.length;
+    const head = dropped > 0 ? `_(${dropped} older episode${dropped === 1 ? '' : 's'} omitted for budget)_\n` : '';
+    return head + kept.join('\n');
+}
+function openMemoriesDb(contextDir) {
+    const dbPath = resolveSqliteDbPath(contextDir);
+    if (!existsSync(dbPath))
+        return null;
+    const db = new BetterSqlite3(dbPath, { readonly: true });
+    db.pragma('busy_timeout = 0');
+    return db;
+}
+/** Raw episode rows in the window, oldest first. Empty when there is no store. */
+export function episodeRows(contextDir, opts = {}) {
+    const db = openMemoriesDb(contextDir);
+    if (!db)
+        return [];
+    try {
+        const now = opts.nowMs ?? Date.now();
+        const since = new Date(now - (opts.hours ?? DEFAULT_HOURS) * HOUR_MS).toISOString();
+        const nowIso = new Date(now).toISOString();
+        return db
+            .prepare(`SELECT title, content, created, project, metadata FROM memories
+         WHERE category = ? AND archived = 0 AND created >= ?
+           AND (expires_at IS NULL OR expires_at > ?)
+         ORDER BY created ASC`)
+            .all(EPISODE_CATEGORY, since, nowIso);
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * The boot tape for a context: "what happened across all of me in the last
+ * N hours", time-ordered. Null when nothing happened (or no store) — the
+ * identity block is simply omitted then.
+ */
+export function tapeForContext(contextDir, opts = {}) {
+    return assembleTape(episodeRows(contextDir, opts), opts);
+}

package/dist/backends/fastembed.d.ts

@@ -0,0 +1,18 @@
+import type { EmbeddingProvider } from './types.js';
+export interface FastEmbedConfig {
+    /** Model identifier, e.g. 'fast-bge-small-en-v1.5' */
+    model: string;
+    /** Directory to cache downloaded ONNX models */
+    cacheDir?: string;
+}
+export declare class FastEmbedProvider implements EmbeddingProvider {
+    private readonly config;
+    readonly dimensions: number;
+    private embedder;
+    private initPromise;
+    constructor(config: FastEmbedConfig);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    embedQuery(text: string): Promise<number[]>;
+    private ensureEmbedder;
+}

package/dist/backends/fastembed.js

@@ -0,0 +1,95 @@
+/**
+ * FastEmbed provider — runs ONNX embedding models in-process.
+ *
+ * No external service required. First call downloads the model to
+ * cacheDir (~30MB for BGE-small-en-v1.5). Subsequent calls use the
+ * cached model. CPU-only by default; portable to any Node machine.
+ *
+ * BGE-family models distinguish query vs passage embeddings. Remember()
+ * paths call embed() (passage). Recall() calls embedQuery() (query).
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { FlagEmbedding } from './embedding-runtime.js';
+/** Known model → dimension mapping. */
+const MODEL_DIMENSIONS = {
+    'fast-all-MiniLM-L6-v2': 384,
+    'fast-bge-base-en': 768,
+    'fast-bge-base-en-v1.5': 768,
+    'fast-bge-small-en': 384,
+    'fast-bge-small-en-v1.5': 384,
+    'fast-bge-small-zh-v1.5': 512,
+    'fast-multilingual-e5-large': 1024,
+};
+export class FastEmbedProvider {
+    config;
+    dimensions;
+    embedder = null;
+    initPromise = null;
+    constructor(config) {
+        this.config = config;
+        const dims = MODEL_DIMENSIONS[config.model];
+        if (dims === undefined) {
+            throw new Error(`Unknown fastembed model: "${config.model}". Known: ${Object.keys(MODEL_DIMENSIONS).join(', ')}`);
+        }
+        this.dimensions = dims;
+    }
+    async embed(text) {
+        const embedder = await this.ensureEmbedder();
+        const vectors = await collectBatches(embedder.embed([text], 1));
+        const vector = vectors[0];
+        if (!vector || vector.length === 0) {
+            throw new Error(`fastembed: embed() produced no vector for a ${text.length}-char input (model ${this.config.model})`);
+        }
+        return vector;
+    }
+    async embedBatch(texts) {
+        if (texts.length === 0)
+            return [];
+        const embedder = await this.ensureEmbedder();
+        const vectors = await collectBatches(embedder.embed(texts, 32));
+        if (vectors.length !== texts.length) {
+            throw new Error(`fastembed: embedBatch() produced ${vectors.length} vectors for ${texts.length} inputs (model ${this.config.model})`);
+        }
+        return vectors;
+    }
+    async embedQuery(text) {
+        const embedder = await this.ensureEmbedder();
+        const vector = await embedder.queryEmbed(text);
+        if (!vector || vector.length === 0) {
+            throw new Error(`fastembed: embedQuery() produced no vector for a ${text.length}-char input (model ${this.config.model})`);
+        }
+        return Array.from(vector);
+    }
+    ensureEmbedder() {
+        if (this.embedder)
+            return Promise.resolve(this.embedder);
+        if (!this.initPromise) {
+            const cacheDir = this.config.cacheDir ?? join(homedir(), '.cache', 'loom', 'fastembed');
+            mkdirSync(cacheDir, { recursive: true });
+            this.initPromise = FlagEmbedding.init({
+                model: this.config.model,
+                cacheDir,
+            }).then((e) => {
+                this.embedder = e;
+                return e;
+            }, (err) => {
+                // Transient failure (e.g. network hiccup during first model
+                // download) must not poison the singleton: clear the cached
+                // promise so the next call retries init from scratch.
+                this.initPromise = null;
+                throw err;
+            });
+        }
+        return this.initPromise;
+    }
+}
+async function collectBatches(gen) {
+    const out = [];
+    for await (const batch of gen) {
+        for (const vector of batch)
+            out.push(Array.from(vector));
+    }
+    return out;
+}

package/dist/backends/glob.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Convert a glob pattern (with `*` wildcards) into a predicate function.
+ * Case-insensitive. `*` matches any sequence of characters.
+ *
+ * Examples:
+ *   "Forgejo sweep*"  → matches "Forgejo sweep — 2026-04-01 (sixty-first)"
+ *   "*loom*"          → matches "loom PR #48 — stall detection"
+ *   "exact title"     → matches only "exact title"
+ */
+export declare function globToMatcher(pattern: string): (value: string) => boolean;

package/dist/backends/glob.js

@@ -0,0 +1,16 @@
+/**
+ * Convert a glob pattern (with `*` wildcards) into a predicate function.
+ * Case-insensitive. `*` matches any sequence of characters.
+ *
+ * Examples:
+ *   "Forgejo sweep*"  → matches "Forgejo sweep — 2026-04-01 (sixty-first)"
+ *   "*loom*"          → matches "loom PR #48 — stall detection"
+ *   "exact title"     → matches only "exact title"
+ */
+export function globToMatcher(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*');
+    const regex = new RegExp(`^${escaped}$`, 'i');
+    return (value) => regex.test(value);
+}

package/dist/backends/index.d.ts

@@ -0,0 +1,6 @@
+import type { MemoryBackend, EmbeddingProvider, KnowledgeBackend } from './types.js';
+export declare function createEmbeddingProvider(): EmbeddingProvider;
+export declare function createBackend(contextDir: string): MemoryBackend;
+/** Close and evict every cached memory backend. For tests and shutdown. */
+export declare function closeAllBackends(): void;
+export declare function createKnowledgeBackend(contextDir: string): KnowledgeBackend;

package/dist/backends/index.js

@@ -0,0 +1,78 @@
+/**
+ * Memory backend factory.
+ *
+ * loom ships a single opinionated stack: SqliteVecBackend
+ * (sqlite + sqlite-vec virtual table) backed by FastEmbedProvider
+ * (BGE-small-en-v1.5 ONNX, CPU-only). Zero external services. One DB
+ * file per agent under the context dir.
+ *
+ * If you ever need a different stack — different embedding model,
+ * remote vector DB, etc — implement the MemoryBackend / EmbeddingProvider
+ * interfaces in types.ts and swap the concrete classes here. There is
+ * deliberately no env-driven backend selector anymore: opinionated.
+ */
+import { resolveSqliteDbPath, resolveKnowledgeDbPath, assertKnowledgePathsNotCoLocated, resolveFastEmbedModel, resolveFastEmbedCacheDir, } from '../config.js';
+import { SqliteVecBackend } from './sqlite-vec.js';
+import { appendRecallObservation } from './recall-log.js';
+import { SqliteKnowledgeBackend } from './sqlite-knowledge.js';
+import { FastEmbedProvider } from './fastembed.js';
+/**
+ * Process-lifetime caches (store-convergence §Lifecycle).
+ *
+ * Tools call createBackend on every invocation; before these caches that
+ * meant a fresh better-sqlite3 handle (leaked — no tool closes) and a fresh
+ * FastEmbedProvider (full ONNX model init) per call. Backends are now cached
+ * per resolved db path and the embedding provider is a singleton per
+ * model+cacheDir. close() on a cached backend evicts it, so explicit close
+ * (e.g. eurorack-import) stays correct — the next createBackend reopens.
+ */
+const backendCache = new Map();
+const embedderCache = new Map();
+export function createEmbeddingProvider() {
+    const model = resolveFastEmbedModel();
+    const cacheDir = resolveFastEmbedCacheDir();
+    const key = `${model}\u0000${cacheDir}`;
+    let provider = embedderCache.get(key);
+    if (!provider) {
+        provider = new FastEmbedProvider({ model, cacheDir });
+        embedderCache.set(key, provider);
+    }
+    return provider;
+}
+export function createBackend(contextDir) {
+    const dbPath = resolveSqliteDbPath(contextDir);
+    const cached = backendCache.get(dbPath);
+    if (cached)
+        return cached;
+    const backend = new SqliteVecBackend({
+        dbPath,
+        // Recall observation log: local-only, <contextDir>/telemetry/recall.jsonl.
+        onRecall: (obs) => appendRecallObservation(contextDir, obs),
+    }, createEmbeddingProvider());
+    // Evict on close so an explicitly closed backend is never handed out again.
+    const originalClose = backend.close.bind(backend);
+    backend.close = () => {
+        backendCache.delete(dbPath);
+        originalClose();
+    };
+    backendCache.set(dbPath, backend);
+    return backend;
+}
+/** Close and evict every cached memory backend. For tests and shutdown. */
+export function closeAllBackends() {
+    for (const backend of [...backendCache.values()]) {
+        try {
+            backend.close(); // evicts itself via the wrapped close
+        }
+        catch {
+            // best-effort shutdown
+        }
+    }
+    backendCache.clear();
+}
+export function createKnowledgeBackend(contextDir) {
+    assertKnowledgePathsNotCoLocated(contextDir);
+    return new SqliteKnowledgeBackend({
+        dbPath: resolveKnowledgeDbPath(contextDir),
+    });
+}