@rohirik/openltm-core 2.8.0

package/src/dedup.ts

@@ -0,0 +1,12 @@
+/**
+ * Dedup key normalization for memory deduplication.
+ * Produces a stable string key from arbitrary content.
+ */
+export function normalizeKey(content: string): string {
+  return content
+    .toLowerCase()
+    .replace(/[^\w\s]/g, " ")   // strip punctuation
+    .replace(/\s+/g, " ")       // collapse whitespace
+    .trim()
+    .substring(0, 200);          // cap length
+}

package/src/embeddings.ts

@@ -0,0 +1,386 @@
+/**
+ * embeddings.ts — Provider-agnostic embedding utilities for LTM semantic search.
+ * Embedding writes/reads now go through src/dao/embeddings.ts (memory_embeddings table).
+ * Embedding generation now goes through src/providers/embeddingProvider.ts.
+ * Falls back gracefully (returns null) when no provider is configured.
+ */
+import type { Database } from "bun:sqlite";
+import type { EmbeddingProvider } from "./providers/embeddingProvider.js";
+import { setEmbedding, listMemoryIdsMissingEmbedding } from "./dao/embeddings.js";
+
+// --- Provider config (retained for LLM/auto-relate path) ---
+
+type EmbedProvider = "gemini" | "openai" | "openrouter" | "cohere" | "ollama";
+
+interface ProviderConfig {
+  provider: EmbedProvider;
+  apiKey?: string;
+  model: string;
+  baseUrl?: string;
+}
+
+// Caches — stable within a process lifetime (restart required for config changes)
+let _llmConfigCache: ProviderConfig | null | undefined = undefined;
+let _embeddingProviderCache: Promise<EmbeddingProvider> | null = null;
+
+/** Shared loader for both embed and llm provider configs. */
+function loadConfig(type: "embed" | "llm"): ProviderConfig | null {
+  try {
+    const { getDb } = require("./shared-db.js") as typeof import("./shared-db.js");
+    const db = getDb();
+    const t = type;
+    const KEYS = [
+      `ltm.${t}.provider`,
+      "ltm.gemini.apiKey", `ltm.gemini.${t}Model`,
+      "ltm.openai.apiKey", `ltm.openai.${t}Model`,
+      "ltm.openrouter.apiKey", `ltm.openrouter.${t}Model`,
+      `ltm.cohere.apiKey`, `ltm.cohere.${t}Model`,
+      `ltm.ollama.${t}Model`, "ltm.ollama.baseUrl",
+    ];
+    const placeholders = KEYS.map(() => "?").join(",");
+    const rows = db.query<{ key: string; value: string }, string[]>(
+      `SELECT key, value FROM settings WHERE key IN (${placeholders})`
+    ).all(...KEYS);
+    const s = Object.fromEntries(rows.map(r => [r.key, r.value])) as Record<string, string | undefined>;
+
+    const envProvider = t === "embed" ? process.env.LTM_EMBED_PROVIDER : process.env.LTM_LLM_PROVIDER;
+    const provider = (envProvider ?? s[`ltm.${t}.provider`] ?? "gemini") as EmbedProvider;
+
+    const DEFAULTS: Record<EmbedProvider, { model: string }> = {
+      gemini:     { model: t === "embed" ? "gemini-embedding-2-preview" : "gemini-2.0-flash-lite" },
+      openai:     { model: t === "embed" ? "text-embedding-3-small" : "gpt-4o-mini" },
+      openrouter: { model: t === "embed" ? "openai/text-embedding-3-large" : "google/gemini-2.0-flash-001" },
+      cohere:     { model: t === "embed" ? "embed-v4.0" : "command-r-plus" },
+      ollama:     { model: t === "embed" ? "nomic-embed-text" : "llama3.2" },
+    };
+
+    switch (provider) {
+      case "gemini":
+        return { provider, apiKey: process.env.GEMINI_API_KEY ?? s["ltm.gemini.apiKey"], model: s[`ltm.gemini.${t}Model`] ?? DEFAULTS.gemini.model };
+      case "openai":
+        return { provider, apiKey: process.env.OPENAI_API_KEY ?? s["ltm.openai.apiKey"], model: s[`ltm.openai.${t}Model`] ?? DEFAULTS.openai.model };
+      case "openrouter":
+        return { provider, apiKey: process.env.OPENROUTER_API_KEY ?? s["ltm.openrouter.apiKey"], model: s[`ltm.openrouter.${t}Model`] ?? DEFAULTS.openrouter.model, baseUrl: "https://openrouter.ai/api/v1" };
+      case "cohere":
+        return { provider, apiKey: process.env.COHERE_API_KEY ?? s["ltm.cohere.apiKey"], model: s[`ltm.cohere.${t}Model`] ?? DEFAULTS.cohere.model };
+      case "ollama":
+        return { provider, model: s[`ltm.ollama.${t}Model`] ?? DEFAULTS.ollama.model, baseUrl: s["ltm.ollama.baseUrl"] ?? "http://localhost:11434" };
+      default:
+        return null;
+    }
+  } catch {
+    return null;
+  }
+}
+
+/** Returns the embedding provider, lazily initialised once per process. */
+async function getEmbeddingProvider(): Promise<EmbeddingProvider> {
+  if (!_embeddingProviderCache) {
+    _embeddingProviderCache = (async () => {
+      const [{ loadConfig }, { loadProvider }] = await Promise.all([
+        import("./config.js"),
+        import("./providers/embeddingProvider.js"),
+      ]);
+      const cfg = await loadConfig();
+      return loadProvider(cfg.embeddings);
+    })();
+  }
+  return _embeddingProviderCache;
+}
+
+export function getLlmConfig(): ProviderConfig | null {
+  if (_llmConfigCache !== undefined) return _llmConfigCache;
+  _llmConfigCache = loadConfig("llm");
+  return _llmConfigCache;
+}
+
+// --- Math utils ---
+
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length) return 0;
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    const ai = a[i] as number;
+    const bi = b[i] as number;
+    dot += ai * bi;
+    normA += ai * ai;
+    normB += bi * bi;
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+export function vecToBlob(v: Float32Array): Buffer {
+  return Buffer.from(v.buffer);
+}
+
+export function blobToVec(b: Buffer): Float32Array {
+  return new Float32Array(b.buffer, b.byteOffset, b.byteLength / 4);
+}
+
+// --- Provider-specific embed implementations ---
+
+// Cached Gemini client + the key it was initialized with
+interface GeminiGenerativeModel {
+  embedContent(text: string): Promise<{ embedding: { values: number[] } }>;
+}
+interface GeminiAIClient {
+  getGenerativeModel(params: { model: string }): GeminiGenerativeModel;
+}
+let _genAI: GeminiAIClient | null = null;
+let _genAIKey: string | undefined;
+
+async function embedGemini(text: string, cfg: ProviderConfig): Promise<Float32Array | null> {
+  if (!cfg.apiKey) return null;
+  if (!_genAI || _genAIKey !== cfg.apiKey) {
+    // Dynamic import to avoid compile-time dependency on optional package
+    const genAiModule = await (Function('return import("@google/generative-ai")')() as Promise<{
+      GoogleGenerativeAI: new (apiKey: string) => GeminiAIClient;
+    }>);
+    const { GoogleGenerativeAI } = genAiModule;
+    _genAI = new GoogleGenerativeAI(cfg.apiKey);
+    _genAIKey = cfg.apiKey;
+  }
+  const model = _genAI.getGenerativeModel({ model: cfg.model });
+  const result = await model.embedContent(text);
+  return new Float32Array(result.embedding.values);
+}
+
+async function embedOpenAICompat(text: string, cfg: ProviderConfig): Promise<Float32Array | null> {
+  if (!cfg.apiKey) return null;
+  const baseUrl = cfg.baseUrl ?? "https://api.openai.com/v1";
+  const res = await fetch(`${baseUrl}/embeddings`, {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${cfg.apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ model: cfg.model, input: text }),
+  });
+  if (!res.ok) throw new Error(`${cfg.provider} API error: ${res.status} ${await res.text()}`);
+  const json = await res.json() as { data: Array<{ embedding: number[] }> };
+  return new Float32Array(json.data[0]!.embedding);
+}
+
+async function embedCohere(text: string, cfg: ProviderConfig): Promise<Float32Array | null> {
+  if (!cfg.apiKey) return null;
+  const res = await fetch("https://api.cohere.com/v2/embed", {
+    method: "POST",
+    headers: { "Authorization": `Bearer ${cfg.apiKey}`, "Content-Type": "application/json" },
+    body: JSON.stringify({ model: cfg.model, texts: [text], input_type: "search_document", embedding_types: ["float"] }),
+  });
+  if (!res.ok) throw new Error(`cohere API error: ${res.status} ${await res.text()}`);
+  const json = await res.json() as { embeddings: { float: number[][] } };
+  return new Float32Array(json.embeddings.float[0]!);
+}
+
+async function embedOllama(text: string, cfg: ProviderConfig): Promise<Float32Array | null> {
+  const res = await fetch(`${cfg.baseUrl}/api/embed`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model: cfg.model, input: text }),
+  });
+  if (!res.ok) throw new Error(`ollama API error: ${res.status} ${await res.text()}`);
+  const json = await res.json() as { embeddings: number[][] };
+  return new Float32Array(json.embeddings[0]!);
+}
+
+// --- Public API ---
+
+/**
+ * Embed text using the configured provider (from config.json embeddings block).
+ * Returns null when provider is disabled or the API call fails.
+ */
+export async function embedText(text: string): Promise<Float32Array | null> {
+  try {
+    const provider = await getEmbeddingProvider();
+    if (!await provider.available()) return null;
+    return provider.generate(text);
+  } catch (e) {
+    process.stderr.write(`[embeddings] embedText error: ${e}\n`);
+    return null;
+  }
+}
+
+/**
+ * Embed a memory by ID and write the embedding to the memory_embeddings table.
+ */
+export async function embedMemory(db: Database, id: number): Promise<void> {
+  const row = db.query<{ content: string }, [number]>(
+    `SELECT content FROM memories WHERE id=?`
+  ).get(id);
+  if (!row) return;
+
+  const provider = await getEmbeddingProvider();
+  if (!await provider.available()) return;
+
+  const vec = await provider.generate(row.content);
+  if (!vec) return;
+
+  await setEmbedding(db, id, vecToBlob(vec), provider.model, provider.dim);
+}
+
+/**
+ * Back-fill: embed all active memories that have no row in memory_embeddings.
+ */
+export async function backfill(db: Database): Promise<void> {
+  const provider = await getEmbeddingProvider();
+  if (!await provider.available()) {
+    process.stderr.write(`[embeddings] Back-fill skipped: provider '${provider.name}' not available\n`);
+    return;
+  }
+
+  const ids = listMemoryIdsMissingEmbedding(db, 1000);
+  process.stderr.write(`[embeddings] Back-filling ${ids.length} memories...\n`);
+
+  const BATCH = 20;
+  let done = 0;
+  for (let i = 0; i < ids.length; i += BATCH) {
+    const batch = ids.slice(i, i + BATCH);
+    await Promise.all(batch.map(async id => {
+      const row = db.query<{ content: string }, [number]>(
+        `SELECT content FROM memories WHERE id=?`
+      ).get(id);
+      if (!row) return;
+      const vec = await provider.generate(row.content);
+      if (vec) {
+        await setEmbedding(db, id, vecToBlob(vec), provider.model, provider.dim);
+        done++;
+      }
+    }));
+    process.stderr.write(`[embeddings] ${Math.min(i + BATCH, ids.length)}/${ids.length} done\n`);
+    if (i + BATCH < ids.length) await Bun.sleep(200);
+  }
+  process.stderr.write(`[embeddings] Back-fill complete: ${done}/${ids.length} embedded\n`);
+}
+
+// --- Semantic similarity search ---
+
+export type SimilarMemory = { id: number; content: string; similarity: number };
+
+/**
+ * Find the top-N most similar memories to the given text using stored embeddings.
+ */
+export async function getSimilarMemories(text: string, topN = 5, threshold = 0.5): Promise<SimilarMemory[]> {
+  const vec = await embedText(text);
+  if (!vec) return [];
+
+  const { getDb } = await import("./shared-db.js");
+  const db = getDb();
+
+  // Fast path: sqlite-vec vec0 KNN. Over-fetch so post-filtering on status and
+  // threshold still yields topN. Falls through to brute force when the index is
+  // unavailable or empty (e.g. a DB that predates the vec backfill).
+  const { getCapabilities } = await import("./extensions.js");
+  if (getCapabilities().vec) {
+    const { knnVec } = await import("./vec/index.js");
+    const hits = knnVec(db, vecToBlob(vec), Math.max(topN * 4, topN + 10));
+    if (hits.length > 0) {
+      const byId = new Map(hits.map(h => [h.id, h.similarity]));
+      const ids = hits.map(h => h.id);
+      const placeholders = ids.map(() => "?").join(",");
+      const rows = db.query<{ id: number; content: string }, number[]>(
+        `SELECT id, content FROM memories WHERE status='active' AND id IN (${placeholders})`
+      ).all(...ids);
+      return rows
+        .map(row => ({ id: row.id, content: row.content, similarity: byId.get(row.id) ?? 0 }))
+        .filter(r => r.similarity >= threshold)
+        .sort((a, b) => b.similarity - a.similarity)
+        .slice(0, topN);
+    }
+  }
+
+  // Brute-force JS cosine fallback.
+  const rows = db.query<{ id: number; content: string; embedding: Buffer }, []>(
+    `SELECT m.id, m.content, e.embedding
+     FROM memories m JOIN memory_embeddings e ON e.memory_id = m.id
+     WHERE m.status = 'active'`
+  ).all();
+
+  return rows
+    .map(row => ({ id: row.id, content: row.content, similarity: cosineSimilarity(vec, blobToVec(row.embedding)) }))
+    .filter(r => r.similarity >= threshold)
+    .sort((a, b) => b.similarity - a.similarity)
+    .slice(0, topN);
+}
+
+// --- Relation classification ---
+
+type AutoRelationType = "supports" | "contradicts" | "refines" | "related_to";
+
+const CLASSIFY_PROMPT = `You are a memory relation classifier. Given two facts (A and B), respond with exactly ONE word:
+- "supports" — B reinforces or agrees with A
+- "contradicts" — B conflicts with or contradicts A
+- "refines" — B adds detail or nuance to A
+- "related_to" — B is on the same topic but no clear support/conflict/refinement
+- "none" — B has no meaningful relation to A
+
+Respond with exactly one of: supports, contradicts, refines, related_to, none`;
+
+const VALID_RELATIONS = new Set<string>(["supports", "contradicts", "refines", "related_to"]);
+
+export async function callLlm(
+  cfg: ProviderConfig,
+  userMessage: string,
+  options?: { systemPrompt?: string; maxTokens?: number; raw?: boolean },
+): Promise<string | null> {
+  const body = {
+    model: cfg.model,
+    messages: [
+      { role: "system", content: options?.systemPrompt ?? CLASSIFY_PROMPT },
+      { role: "user", content: userMessage },
+    ],
+    max_tokens: options?.maxTokens ?? 10,
+    temperature: 0,
+  };
+
+  try {
+    let url: string;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+
+    if (cfg.provider === "gemini") {
+      url = `https://generativelanguage.googleapis.com/v1beta/openai/chat/completions`;
+      headers["Authorization"] = `Bearer ${cfg.apiKey ?? ""}`;
+    } else if (cfg.provider === "ollama") {
+      url = `${cfg.baseUrl}/v1/chat/completions`;
+    } else {
+      // openai / openrouter
+      url = cfg.baseUrl ? `${cfg.baseUrl}/chat/completions` : "https://api.openai.com/v1/chat/completions";
+      headers["Authorization"] = `Bearer ${cfg.apiKey ?? ""}`;
+    }
+
+    const res = await fetch(url, { method: "POST", headers, body: JSON.stringify(body) });
+    if (!res.ok) return null;
+    const json = await res.json() as { choices?: Array<{ message?: { content?: string } }> };
+    const content = json.choices?.[0]?.message?.content ?? null;
+    if (content === null) return null;
+    return options?.raw ? content.trim() : content.trim().toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Classify the relation between two memory strings using a lightweight LLM call.
+ * Returns null if no LLM provider configured or call fails.
+ */
+export async function classifyRelation(a: string, b: string): Promise<AutoRelationType | null> {
+  const cfg = getLlmConfig();
+  if (!cfg) return null;
+
+  const userMessage = `Memory A: ${a}\n\nMemory B: ${b}`;
+  const raw = await callLlm(cfg, userMessage);
+  if (!raw || !VALID_RELATIONS.has(raw)) return null;
+  return raw as AutoRelationType;
+}
+
+// CLI: bun embeddings.ts --backfill
+if (import.meta.main) {
+  void (async () => {
+    const args = process.argv.slice(2);
+    if (args.includes("--backfill")) {
+      const { getDb } = await import("./shared-db.js");
+      const db = getDb();
+      await backfill(db);
+    } else {
+      process.stderr.write("Usage: bun embeddings.ts --backfill\n");
+    }
+  })();
+}

package/src/events/index.ts

@@ -0,0 +1,130 @@
+/**
+ * events/index.ts — Honker pub/sub for graph-app liveness.
+ *
+ * Long-lived processes (the graph server) call `startLtmListener()` once; the
+ * loop drains `listen("ltm")` and hands each notification payload to the
+ * supplied callback (which drives the existing WebSocket `broadcast()`). Any
+ * writer — hooks, the janitor, the worker — calls `notifyLtm()` after a commit
+ * to push a liveness event to every connected listener with no polling.
+ *
+ * Dormant + inert when Honker is unavailable: `notifyLtm()` returns false and
+ * `startLtmListener()` returns a non-running handle, so the caller keeps its
+ * existing fs.watch + 3s-debounce file-watcher fallback.
+ */
+import { getHonker } from "../lib/honker.js";
+import type { HonkerTransaction } from "../lib/honkerTypes.js";
+import { getSetting } from "../shared-db.js";
+import { SETTING_KEYS } from "../janitor/providers/types.js";
+
+export const LTM_CHANNEL = "ltm";
+
+/** Liveness event `type` for a memory created in another agent process. */
+export const MEMORY_ADDED = "memory_added";
+
+/** A liveness event pushed to graph-app — `type` mirrors the WS message kind. */
+export interface LtmLiveEvent {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+export interface LtmListenerHandle {
+  /** Whether the listen loop is running (false without Honker). */
+  readonly running: boolean;
+  /** Stop the loop and wait for it to settle. */
+  stop(): Promise<void>;
+}
+
+const INERT: LtmListenerHandle = { running: false, stop: async () => {} };
+
+/**
+ * Push a liveness event on the "ltm" channel. Returns false when Honker is
+ * unavailable (caller's file-watcher fallback still fires). Best-effort: a
+ * notify failure never throws.
+ */
+export function notifyLtm(event: LtmLiveEvent, opts?: { tx?: HonkerTransaction }): boolean {
+  const h = getHonker();
+  if (!h) return false;
+  try {
+    h.notify(LTM_CHANNEL, event, opts?.tx ? { tx: opts.tx } : undefined);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Start the "ltm" channel listen loop. Each notification's payload is passed to
+ * `onEvent`. No-op (inert handle) when Honker is unavailable.
+ */
+export function startLtmListener(
+  onEvent: (event: LtmLiveEvent) => void,
+  opts?: { pollMs?: number },
+): LtmListenerHandle {
+  const h = getHonker();
+  if (!h) return INERT;
+
+  const controller = new AbortController();
+  const loop = (async () => {
+    const listenOpts = { signal: controller.signal, ...(opts?.pollMs != null ? { pollMs: opts.pollMs } : {}) };
+    for await (const note of h.listen(LTM_CHANNEL, listenOpts)) {
+      if (controller.signal.aborted) return;
+      const payload = note.payload;
+      if (payload && typeof payload === "object" && "type" in payload) {
+        try { onEvent(payload as LtmLiveEvent); } catch { /* dispatch best-effort */ }
+      }
+    }
+  })();
+  loop.catch(() => {});
+
+  return {
+    running: true,
+    stop: async () => {
+      controller.abort();
+      await loop.catch(() => {});
+    },
+  };
+}
+
+/**
+ * Whether opt-in cross-process memory sync is enabled (setting
+ * `ltm.crossProcessSync`, default "off"). Cross-process push additionally
+ * requires a live Honker handle — this only reports the user's intent.
+ */
+export function isCrossProcessSyncEnabled(): boolean {
+  return getSetting(SETTING_KEYS.CROSS_PROCESS_SYNC) === "on";
+}
+
+/**
+ * Push a `memory_added` event so sibling agent processes (Claude Code,
+ * OpenCode, Pi) sharing one openltm.db can react to a memory created elsewhere.
+ * No-op unless the `ltm.crossProcessSync` flag is on AND Honker is available.
+ * Returns true only when the notify was actually sent.
+ */
+export function notifyMemoryAdded(
+  memory: { id: number; project_scope?: string | null },
+  opts?: { tx?: HonkerTransaction },
+): boolean {
+  if (!isCrossProcessSyncEnabled()) return false;
+  return notifyLtm(
+    { type: MEMORY_ADDED, id: memory.id, project_scope: memory.project_scope ?? null, pid: process.pid },
+    opts,
+  );
+}
+
+/**
+ * Adapter-facing listener: invoke `onMemoryAdded` for each `memory_added` event
+ * raised by another process (ignores this process's own events by pid). Inert
+ * (non-running handle) unless the flag is on AND Honker is available, so an
+ * adapter can call this unconditionally and degrade to a no-op.
+ */
+export function startCrossProcessSync(
+  onMemoryAdded: (event: LtmLiveEvent) => void,
+  opts?: { pollMs?: number },
+): LtmListenerHandle {
+  if (!isCrossProcessSyncEnabled()) return INERT;
+  return startLtmListener(event => {
+    if (event.type !== MEMORY_ADDED) return;
+    if (event["pid"] === process.pid) return; // drop our own echo
+    onMemoryAdded(event);
+  }, opts);
+}

package/src/extensions.ts

@@ -0,0 +1,140 @@
+/**
+ * extensions.ts — Loadable SQLite extension capability probe + activation.
+ *
+ * Bun's bundled SQLite is compiled WITHOUT dynamic extension loading, so
+ * db.loadExtension() throws "does not support dynamic extension loading".
+ * We switch the process to a system extension-enabled libsqlite3 via
+ * Database.setCustomSQLite() (a process-global static that MUST run before the
+ * first Database is opened), then loadExtension() per-connection.
+ *
+ * Everything degrades gracefully: any failure (no system sqlite, missing
+ * binary, force-disabled via env) leaves the capability false and callers
+ * fall back to the pure-JS / FTS-only paths. This module NEVER throws.
+ */
+import { Database } from "bun:sqlite";
+import { existsSync } from "fs";
+
+export interface Capabilities {
+  /** A system extension-enabled SQLite is active for this process. */
+  customSqlite: boolean;
+  /** sqlite-vec (vec0 virtual tables / KNN) is loaded. */
+  vec: boolean;
+  /** Honker (durable queue / scheduler / pub-sub) extension is loaded. */
+  honker: boolean;
+}
+
+const CAPS_NONE: Capabilities = { customSqlite: false, vec: false, honker: false };
+
+let _caps: Capabilities | null = null;
+let _customSqliteApplied = false;
+
+// Probe order: explicit override first, then common Homebrew / Linux locations.
+function systemSqliteCandidates(): string[] {
+  const out: string[] = [];
+  const override = process.env["LTM_SQLITE_LIB"];
+  if (override) out.push(override);
+  out.push(
+    "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib",
+    "/usr/local/opt/sqlite/lib/libsqlite3.dylib",
+    "/usr/lib/x86_64-linux-gnu/libsqlite3.so.0",
+    "/usr/lib/aarch64-linux-gnu/libsqlite3.so.0",
+    "/usr/lib64/libsqlite3.so.0",
+  );
+  return out;
+}
+
+function envDisabled(name: string): boolean {
+  const v = process.env[name];
+  return v === "1" || v === "true";
+}
+
+/** Locate a system extension-enabled libsqlite3, or null if none found. */
+export function locateSystemSqlite(): string | null {
+  for (const p of systemSqliteCandidates()) {
+    try {
+      if (existsSync(p)) return p;
+    } catch {
+      /* ignore unreadable candidate */
+    }
+  }
+  return null;
+}
+
+/**
+ * Switch the process to a system extension-enabled SQLite. Idempotent and
+ * never throws. Must run before the first Database is constructed to take
+ * effect. Returns true if a custom sqlite is (now) active.
+ *
+ * Skipped entirely when BOTH vec and honker are force-disabled — there is no
+ * reason to leave Bun's bundled SQLite in that case.
+ */
+export function ensureCustomSqlite(): boolean {
+  if (_customSqliteApplied) return true;
+  if (envDisabled("LTM_DISABLE_VEC") && envDisabled("LTM_DISABLE_HONKER")) return false;
+  const lib = locateSystemSqlite();
+  if (!lib) return false;
+  try {
+    (Database as unknown as { setCustomSQLite: (p: string) => void }).setCustomSQLite(lib);
+    _customSqliteApplied = true;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function loadVec(db: Database): boolean {
+  try {
+    // Resolve the loadable path synchronously and load it directly — avoids
+    // any async-import concern in synchronous DB-init paths.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require("sqlite-vec") as { getLoadablePath?: () => string };
+    const path = mod.getLoadablePath?.();
+    if (!path) return false;
+    db.loadExtension(path);
+    db.query("SELECT vec_version()").get();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function loadHonker(db: Database): boolean {
+  const ext = process.env["LTM_HONKER_EXT"];
+  if (!ext || !existsSync(ext)) return false;
+  try {
+    db.loadExtension(ext);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Load available extensions into the given connection and cache the resulting
+ * capabilities for the process. Never throws.
+ *
+ * @param opts.vec    attempt sqlite-vec (default true; env LTM_DISABLE_VEC wins)
+ * @param opts.honker attempt Honker (default false; env LTM_DISABLE_HONKER wins,
+ *                    and a libhonker_ext path must be set via LTM_HONKER_EXT)
+ */
+export function loadExtensions(db: Database, opts?: { vec?: boolean; honker?: boolean }): Capabilities {
+  const wantVec = (opts?.vec ?? true) && !envDisabled("LTM_DISABLE_VEC");
+  const wantHonker = (opts?.honker ?? false) && !envDisabled("LTM_DISABLE_HONKER");
+
+  const customSqlite = ensureCustomSqlite();
+  const vec = customSqlite && wantVec ? loadVec(db) : false;
+  const honker = customSqlite && wantHonker ? loadHonker(db) : false;
+
+  _caps = { customSqlite, vec, honker };
+  return _caps;
+}
+
+/** Return the cached capabilities, or all-false if loadExtensions hasn't run. */
+export function getCapabilities(): Capabilities {
+  return _caps ?? { ...CAPS_NONE };
+}
+
+/** Test-only: clear cached capability state (does NOT undo setCustomSQLite). */
+export function resetCapabilitiesForTesting(): void {
+  _caps = null;
+}