opencode-episodic-memory 0.1.3 → 0.2.0

package/README.md

@@ -18,7 +18,7 @@ of the OpenCode memory-plugin landscape? See
 
 1. **Read** — sessions/messages/parts from OpenCode's `~/.local/share/opencode/opencode.db` (read-only)
 2. **Parse** — condensed exchanges (user text, assistant text, tool names; no reasoning blobs or tool output)
-3. **Embed** — local, offline embeddings via Transformers.js (`Snowflake/snowflake-arctic-embed-m-v1.5` q8, 768 dims; retrieval prefix on search queries). Chosen by empirical eval on a real corpus — see [docs/embedding-model-eval.md](docs/embedding-model-eval.md)
+3. **Embed** — local, offline embeddings via Transformers.js in a persistent system-Node sidecar (`Snowflake/snowflake-arctic-embed-m-v1.5` q8, 768 dims; retrieval prefix on search queries). Chosen by empirical eval on a real corpus — see [docs/embedding-model-eval.md](docs/embedding-model-eval.md)
 4. **Index** — plain SQLite at `~/.local/share/opencode-episodic-memory/index.db`; brute-force cosine over Float32 blobs, plus a built-in FTS5 BM25 index for lexical/hybrid search
 5. **Recall** — native plugin tools `episodic_search` / `episodic_read`, plus a `remembering-conversations` skill that teaches the agent when to search
 6. **Stay fresh** — the plugin re-indexes each session on the `session.idle` event
@@ -52,7 +52,13 @@ Or edit `~/.config/opencode/opencode.json` manually:
 }
 ```
 
-The first embedding run downloads the model (~100 MB, cached afterwards).
+Default sidecar-mode semantic indexing and vector/hybrid search require a system
+**Node 20+** binary (`node` by default). The first embedding run downloads the
+model (~100 MB, cached afterward). The model and its native runtime live in
+that Node sidecar, not inside OpenCode's Bun/TUI process. Explicit
+`EPISODIC_EMBED_MODE=inline` works without Node but is unsafe in affected
+OpenCode/Bun versions. `episodic_read` and lexical text search also remain
+available without Node.
 
 Install the skill so the agent knows when to search, via the
 [`skills` CLI](https://github.com/vercel-labs/skills):
@@ -123,6 +129,18 @@ instruction-tag match — the intent is the same, but our matching is literal.
 | `EPISODIC_SOURCE_DB` | `~/.local/share/opencode/opencode.db` | OpenCode session store |
 | `EPISODIC_INDEX_DB` | `~/.local/share/opencode-episodic-memory/index.db` | Index location |
 | `EPISODIC_EMBED_MODEL` | `Snowflake/snowflake-arctic-embed-m-v1.5` | Transformers.js embedding model |
+| `EPISODIC_EMBED_MODE` | `sidecar` | `sidecar` runs embeddings in Node; `inline` is an explicit escape hatch |
+| `EPISODIC_NODE_BINARY` | `node` | Node 20+ executable used by sidecar mode |
+| `EPISODIC_EMBED_BATCH_SIZE` | `32` | Texts per sidecar request (1-64) |
+| `EPISODIC_EMBED_READY_TIMEOUT_MS` | `600000` | Maximum wait for sidecar/model startup |
+| `EPISODIC_EMBED_REQUEST_TIMEOUT_MS` | `120000` | Maximum wait for a post-startup embedding request |
+
+`EPISODIC_EMBED_MODE=inline` loads Transformers.js native addons directly in
+OpenCode's embedded Bun process. It exists only as an explicit compatibility
+escape hatch and is unsafe with affected OpenCode/Bun releases that can crash
+during native-addon teardown. It is never selected automatically if sidecar
+startup fails. Run `bun run src/cli.ts doctor` to diagnose the selected mode,
+Node version, and a real embedding.
 
 ## Not yet implemented (deliberate)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-episodic-memory",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Semantic search over past OpenCode conversations — local embeddings (Transformers.js), SQLite index, native plugin tools. Inspired by obra/episodic-memory, rebuilt natively for OpenCode.",
   "type": "module",
   "license": "MIT",

package/plugin/episodic-memory.ts

@@ -77,16 +77,25 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
             before: before.ms,
             text: args.text,
           };
-          const hits =
-            args.mode === "text"
-              ? textSearch(index, args.query, opts)
-              : args.mode === "hybrid"
-                ? search(index, (await embedQuery(args.query))[0], { ...opts, queryText: args.query, hybrid: true })
-                : search(index, (await embedQuery(args.query))[0], opts);
-          if (hits.length === 0) {
-            if (isIndexEmpty(index)) return "No matching past conversations found. The index is empty — run `bun run src/cli.ts sync` to index conversations.";
-            return "No matching past conversations found.";
+          const noHits = () => isIndexEmpty(index)
+            ? "No matching past conversations found. The index is empty — run `bun run src/cli.ts sync` to index conversations."
+            : "No matching past conversations found.";
+          if (args.mode === "text") {
+            const hits = textSearch(index, args.query, opts);
+            if (hits.length === 0) return noHits();
+            return formatHits(hits, 400, "score");
           }
+          let vector: Float32Array;
+          try {
+            vector = (await embedQuery(args.query))[0];
+          } catch (e) {
+            await log("warn", `episodic_search embedding failed: ${e instanceof Error ? e.message : e}`);
+            return 'Semantic search unavailable: the embedding backend failed. Use mode: "text" for embedding-free lexical search, or run `bun run src/cli.ts doctor` for details.';
+          }
+          const hits = args.mode === "hybrid"
+            ? search(index, vector, { ...opts, queryText: args.query, hybrid: true })
+            : search(index, vector, opts);
+          if (hits.length === 0) return noHits();
           // Hybrid hits carry RRF scores (~0.03), not cosine — label them "rrf".
           return formatHits(hits, 400, args.mode === "hybrid" ? "rrf" : "score");
         },

package/src/cli.ts

@@ -15,7 +15,7 @@ import { parseArgs } from "node:util";
 import { openSource, sourceDbPath, getSession, getTranscriptChecked } from "./reader";
 import { openIndex, indexDbPath, search, textSearch, stats, isIndexEmpty } from "./store";
 import { syncAll } from "./indexer";
-import { embed, embedQuery } from "./embed";
+import { embed, embedQuery, getEmbedMode } from "./embed";
 import { parseDateArg, fmtDate, renderTranscript, formatHits } from "./format";
 
 const [, , command, ...rest] = process.argv;
@@ -157,6 +157,34 @@ async function main() {
 
     case "doctor": {
       let ok = true;
+      let mode: "sidecar" | "inline";
+      try {
+        mode = getEmbedMode();
+        console.log(`✓ embedding mode: ${mode}`);
+      } catch (e) {
+        console.error(`✗ embedding mode: ${e}`);
+        process.exit(1);
+      }
+      if (mode === "sidecar") {
+        const nodeBinary = process.env.EPISODIC_NODE_BINARY ?? "node";
+        try {
+          const node = Bun.spawnSync([nodeBinary, "--version"], { stdout: "pipe", stderr: "pipe" });
+          const version = new TextDecoder().decode(node.stdout).trim();
+          const match = /^v(\d+)\./.exec(version);
+          if (!node.success || !match || Number(match[1]) < 20) {
+            const detail = new TextDecoder().decode(node.stderr).trim();
+            console.error(`✗ Node 20+ required for sidecar mode (${JSON.stringify(nodeBinary)} ${version || detail || "not found"}). Set EPISODIC_NODE_BINARY to a Node 20+ executable.`);
+            ok = false;
+          } else {
+            console.log(`✓ sidecar Node: ${nodeBinary} ${version}`);
+          }
+        } catch (e) {
+          console.error(`✗ Node 20+ required for sidecar mode (${JSON.stringify(nodeBinary)} could not start: ${e}). Set EPISODIC_NODE_BINARY to a Node 20+ executable.`);
+          ok = false;
+        }
+      } else {
+        console.warn("! inline embedding mode loads native ML addons into Bun; it is unsafe on affected OpenCode/Bun versions. Prefer sidecar mode.");
+      }
       const src = sourceDbPath();
       if (existsSync(src)) console.log(`✓ source DB: ${src}`);
       else { console.error(`✗ source DB missing: ${src}`); ok = false; }

package/src/embed-inline.ts

@@ -0,0 +1,28 @@
+// Explicit escape hatch for hosts where loading native ML addons in Bun is safe.
+// Keep this module dynamically imported by embed.ts so the normal plugin import
+// path cannot load Transformers.js.
+import type { FeatureExtractionPipeline } from "@huggingface/transformers";
+
+import { DEFAULT_MODEL } from "./embed.ts";
+
+let cached: Promise<FeatureExtractionPipeline> | null = null;
+
+async function getEmbedder(): Promise<FeatureExtractionPipeline> {
+  if (!cached) {
+    cached = import("@huggingface/transformers")
+      .then(({ pipeline }) => pipeline("feature-extraction", process.env.EPISODIC_EMBED_MODEL ?? DEFAULT_MODEL, { dtype: "q8" }) as Promise<FeatureExtractionPipeline>);
+    // A rejected promise (for example, a failed model download) must not poison
+    // the cache for the lifetime of the process.
+    cached.catch(() => { cached = null; });
+  }
+  return cached;
+}
+
+export async function embedInline(texts: string[]): Promise<Float32Array[]> {
+  const embedder = await getEmbedder();
+  const output = await embedder(texts, { pooling: "cls", normalize: true });
+  const dimensions: number = output.dims[output.dims.length - 1];
+  // A normalized feature-extraction tensor is Float32Array at runtime.
+  const flat = new Float32Array(output.data as Float32Array);
+  return texts.map((_, index) => flat.subarray(index * dimensions, (index + 1) * dimensions));
+}

package/src/embed-sidecar.mjs

@@ -0,0 +1,110 @@
+// Persistent Node-side embedding server. stdout is reserved for NDJSON protocol
+// messages; all diagnostics (including dependency chatter) go to stderr.
+const originalConsole = globalThis.console;
+globalThis.console = {
+  ...originalConsole,
+  log: (...args) => originalConsole.error(...args),
+  info: (...args) => originalConsole.error(...args),
+  debug: (...args) => originalConsole.error(...args),
+  warn: (...args) => originalConsole.error(...args),
+};
+
+// Keep this fallback synchronized with DEFAULT_MODEL in embed.ts; embed.test.ts
+// guards against accidental drift between the Bun host and Node sidecar.
+const model = process.env.EPISODIC_EMBED_MODEL ?? "Snowflake/snowflake-arctic-embed-m-v1.5";
+const MAX_REQUEST_TEXTS = 64;
+const batchSize = positiveIntegerEnv("EPISODIC_EMBED_BATCH_SIZE", 32, MAX_REQUEST_TEXTS);
+let embedder;
+let queue = Promise.resolve();
+
+function positiveIntegerEnv(name, defaultValue, maximum) {
+  const value = process.env[name];
+  if (value === undefined) return defaultValue;
+  if (!/^[1-9]\d*$/.test(value)) throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed > maximum) {
+    throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  }
+  return parsed;
+}
+
+function send(response) {
+  process.stdout.write(`${JSON.stringify(response)}\n`);
+}
+
+function requestError(id, error) {
+  send({ id, error: error instanceof Error ? error.message : String(error) });
+}
+
+function validRequest(value) {
+  return value && typeof value === "object" && Number.isSafeInteger(value.id)
+    && Array.isArray(value.texts) && value.texts.length <= MAX_REQUEST_TEXTS
+    && value.texts.every((text) => typeof text === "string");
+}
+
+async function embed(texts) {
+  const vectors = [];
+  for (let offset = 0; offset < texts.length; offset += batchSize) {
+    const batch = texts.slice(offset, offset + batchSize);
+    const output = await embedder(batch, { pooling: "cls", normalize: true });
+    const dimensions = output.dims.at(-1);
+    if (!Number.isSafeInteger(dimensions) || dimensions <= 0) throw new Error("model returned invalid embedding dimensions");
+    const data = output.data;
+    if (data.length !== batch.length * dimensions) throw new Error("model returned an invalid embedding batch");
+    for (let index = 0; index < batch.length; index++) {
+      vectors.push(Array.from(data.slice(index * dimensions, (index + 1) * dimensions)));
+    }
+  }
+  return vectors;
+}
+
+async function initialize() {
+  try {
+    const { pipeline } = await import("@huggingface/transformers");
+    embedder = await pipeline("feature-extraction", model, { dtype: "q8" });
+    send({ ready: true });
+  } catch (error) {
+    send({ ready: false, error: error instanceof Error ? error.message : String(error) });
+    process.exitCode = 1;
+    process.stdin.destroy();
+    throw error;
+  }
+}
+
+const initialization = initialize();
+let remainder = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  remainder += chunk;
+  let newline;
+  while ((newline = remainder.indexOf("\n")) >= 0) {
+    const line = remainder.slice(0, newline);
+    remainder = remainder.slice(newline + 1);
+    if (!line) continue;
+    let request;
+    try {
+      request = JSON.parse(line);
+    } catch {
+      requestError(null, "request must be valid JSON");
+      continue;
+    }
+    if (!validRequest(request)) {
+      requestError(request && typeof request === "object" && "id" in request ? request.id : null, `request must have an integer id and at most ${MAX_REQUEST_TEXTS} string texts`);
+      continue;
+    }
+    queue = queue.then(async () => {
+      try {
+        await initialization;
+        send({ id: request.id, vectors: await embed(request.texts) });
+      } catch (error) {
+        requestError(request.id, error);
+      }
+    });
+  }
+});
+process.stdin.on("error", () => process.exit());
+process.stdin.on("end", () => process.exit());
+process.on("SIGTERM", () => process.exit());
+process.on("SIGINT", () => process.exit());
+
+await initialization.catch(() => {});

package/src/embed.ts

@@ -1,14 +1,7 @@
-// Local, offline embeddings via Transformers.js. CLS-pooled + L2-normalized,
-// so cosine similarity is a plain dot product.
-//
-// Model: Snowflake/snowflake-arctic-embed-m-v1.5 (q8) — 768 dims, Apache-2.0,
-// official ONNX export in the model repo. Chosen over Xenova/bge-small-en-v1.5
-// by empirical eval on our real corpus (2026-07-22, see
-// docs/embedding-model-eval.md): equal top-1, better top-3, and far better
-// score separation (negatives max ~0.33 vs bge's ~0.66), so minScore
-// thresholding is meaningful. Asymmetric retriever: queries get a task
-// prefix, documents go through unmodified.
-import { pipeline, type FeatureExtractionPipeline } from "@huggingface/transformers";
+// Local, offline embeddings. The default backend lives in a system-Node
+// sidecar so importing the OpenCode plugin never loads ML native addons into
+// its embedded Bun process.
+import { fileURLToPath } from "node:url";
 
 export const DEFAULT_MODEL = "Snowflake/snowflake-arctic-embed-m-v1.5";
 
@@ -20,34 +13,295 @@ export const QUERY_PREFIX = "Represent this sentence for searching relevant pass
 // degrade embeddings (and this model's window is 512 tokens anyway).
 export const MAX_CHARS = 2000;
 
-let cached: Promise<FeatureExtractionPipeline> | null = null;
+const DEFAULT_BATCH_SIZE = 32;
+const MAX_BATCH_SIZE = 64;
+const DEFAULT_READY_TIMEOUT_MS = 10 * 60 * 1000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 2 * 60 * 1000;
+const MAX_TIMEOUT_MS = 2_147_483_647;
 
-export function getEmbedder(): Promise<FeatureExtractionPipeline> {
-  if (!cached) {
-    // transformers.js declares pipeline<"feature-extraction"> as its task-metadata
-    // record, not the FeatureExtractionPipeline instance it returns at runtime, so
-    // this cast restores the documented return type (matches HuggingFace's examples).
-    cached = pipeline("feature-extraction", process.env.EPISODIC_EMBED_MODEL ?? DEFAULT_MODEL, {
-      dtype: "q8",
-    }) as Promise<FeatureExtractionPipeline>;
-    // A rejected promise (e.g. failed model download) would poison the cache
-    // for the lifetime of the process; reset so the next call retries.
-    cached.catch(() => { if (cached) cached = null; });
+export type EmbedMode = "sidecar" | "inline";
+
+type PendingRequest = {
+  resolve: (vectors: Float32Array[]) => void;
+  reject: (error: Error) => void;
+  count: number;
+};
+
+type Sidecar = {
+  process: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  pending: Map<number, PendingRequest>;
+  ready: Promise<void>;
+  resolveReady: () => void;
+  rejectReady: (error: Error) => void;
+  stderr: string;
+  stdout: string;
+  dimensions: number | null;
+};
+
+class SidecarUnavailableError extends Error {}
+
+let sidecar: Sidecar | null = null;
+let nextRequestId = 1;
+
+export function getEmbedMode(): EmbedMode {
+  const mode = process.env.EPISODIC_EMBED_MODE ?? "sidecar";
+  if (mode === "sidecar" || mode === "inline") return mode;
+  throw new Error(`Invalid EPISODIC_EMBED_MODE ${JSON.stringify(mode)}; expected "sidecar" or "inline".`);
+}
+
+function tail(value: string, addition: string): string {
+  return (value + addition).slice(-8_192);
+}
+
+function positiveIntegerEnv(name: string, defaultValue: number, maximum: number): number {
+  const value = process.env[name];
+  if (value === undefined) return defaultValue;
+  if (!/^[1-9]\d*$/.test(value)) throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed > maximum) {
+    throw new Error(`Invalid ${name} ${JSON.stringify(value)}; expected an integer from 1 to ${maximum}.`);
+  }
+  return parsed;
+}
+
+function sidecarError(message: string, child: Sidecar): Error {
+  const details = child.stderr.trim();
+  return new SidecarUnavailableError(details ? `${message}: ${details}` : message);
+}
+
+function rejectAll(child: Sidecar, error: Error): void {
+  for (const { reject } of child.pending.values()) reject(error);
+  child.pending.clear();
+  child.rejectReady(error);
+}
+
+function sidecarGone(child: Sidecar, error: Error): void {
+  if (sidecar === child) sidecar = null;
+  rejectAll(child, error);
+  child.process.kill();
+}
+
+function protocolFailure(child: Sidecar, message: string): void {
+  const error = new Error(`Embedding sidecar protocol error: ${message}`);
+  sidecarGone(child, error);
+}
+
+function vectorsFromResponse(value: unknown, expectedCount: number, child: Sidecar): Float32Array[] {
+  if (!Array.isArray(value) || value.length !== expectedCount) {
+    throw new Error(`expected ${expectedCount} vectors, got ${Array.isArray(value) ? value.length : "a non-array"}`);
+  }
+
+  const vectors = value.map((vector) => {
+    if (!Array.isArray(vector) || vector.length === 0 || !vector.every((n) => typeof n === "number" && Number.isFinite(n))) {
+      throw new Error("vectors must be non-empty arrays of finite numbers");
+    }
+    if (child.dimensions !== null && vector.length !== child.dimensions) {
+      throw new Error(`expected ${child.dimensions} dimensions, got ${vector.length}`);
+    }
+    return new Float32Array(vector);
+  });
+
+  const dimensions = vectors[0]?.length;
+  if (vectors.some((vector) => vector.length !== dimensions)) throw new Error("vectors have inconsistent dimensions");
+  child.dimensions ??= dimensions ?? null;
+  return vectors;
+}
+
+function handleLine(child: Sidecar, line: string): void {
+  let response: unknown;
+  try {
+    response = JSON.parse(line);
+  } catch {
+    protocolFailure(child, "stdout contained invalid JSON");
+    return;
+  }
+  if (!response || typeof response !== "object" || Array.isArray(response)) {
+    protocolFailure(child, "response must be an object");
+    return;
+  }
+
+  const record = response as Record<string, unknown>;
+  if ("ready" in record) {
+    if (record.ready === true) child.resolveReady();
+    else {
+      sidecarGone(child, new SidecarUnavailableError(`Embedding sidecar failed to start: ${typeof record.error === "string" ? record.error : "unknown error"}`));
+    }
+    return;
+  }
+  if (typeof record.id !== "number" || !Number.isSafeInteger(record.id)) {
+    protocolFailure(child, "response has no valid request id");
+    return;
+  }
+  const pending = child.pending.get(record.id);
+  if (!pending) {
+    protocolFailure(child, `response has unknown request id ${record.id}`);
+    return;
+  }
+  child.pending.delete(record.id);
+  if (typeof record.error === "string") {
+    pending.reject(new Error(`Embedding sidecar request failed: ${record.error}`));
+    return;
+  }
+  try {
+    pending.resolve(vectorsFromResponse(record.vectors, pending.count, child));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    pending.reject(new Error(`Embedding sidecar protocol error: ${message}`));
+    protocolFailure(child, message);
+  }
+}
+
+async function drainStdout(child: Sidecar): Promise<void> {
+  const reader = child.process.stdout.getReader();
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      child.stdout += decoder.decode(value, { stream: true });
+      let newline: number;
+      while ((newline = child.stdout.indexOf("\n")) >= 0) {
+        const line = child.stdout.slice(0, newline);
+        child.stdout = child.stdout.slice(newline + 1);
+        if (line) handleLine(child, line);
+      }
+    }
+    if (child.stdout.trim()) protocolFailure(child, "stdout ended with an incomplete response");
+  } catch (error) {
+    if (sidecar === child) sidecarGone(child, sidecarError(`Could not read embedding sidecar output (${String(error)})`, child));
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+async function drainStderr(child: Sidecar): Promise<void> {
+  const reader = child.process.stderr.getReader();
+  const decoder = new TextDecoder();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      child.stderr = tail(child.stderr, decoder.decode(value, { stream: true }));
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function startSidecar(): Sidecar {
+  if (sidecar) return sidecar;
+  const nodeBinary = process.env.EPISODIC_NODE_BINARY ?? "node";
+  const sidecarPath = fileURLToPath(new URL("./embed-sidecar.mjs", import.meta.url));
+  let resolveReady!: () => void;
+  let rejectReady!: (error: Error) => void;
+  const ready = new Promise<void>((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  // The rejected ready promise is also observed by each request; suppress a
+  // transient unhandled-rejection warning while the first request is starting.
+  ready.catch(() => {});
+
+  let childProcess: Bun.Subprocess<"pipe", "pipe", "pipe">;
+  try {
+    childProcess = Bun.spawn([nodeBinary, sidecarPath], {
+      env: process.env,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      detached: true,
+    });
+  } catch (error) {
+    throw new Error(`Could not start embedding sidecar using ${JSON.stringify(nodeBinary)}. Install Node 20+ or set EPISODIC_NODE_BINARY: ${String(error)}`);
+  }
+  childProcess.unref();
+  const child: Sidecar = { process: childProcess, pending: new Map(), ready, resolveReady, rejectReady, stderr: "", stdout: "", dimensions: null };
+  sidecar = child;
+  void drainStdout(child);
+  void drainStderr(child);
+  void childProcess.exited.then(() => {
+    if (sidecar === child) {
+      sidecar = null;
+      rejectAll(child, sidecarError("Embedding sidecar exited unexpectedly", child));
+    }
+  });
+  return child;
+}
+
+function awaitReady(child: Sidecar, timeoutMs: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      const error = new SidecarUnavailableError(`Embedding sidecar did not become ready within ${timeoutMs}ms`);
+      sidecarGone(child, error);
+      reject(error);
+    }, timeoutMs);
+    child.ready.then(
+      () => {
+        clearTimeout(timeout);
+        resolve();
+      },
+      (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      },
+    );
+  });
+}
+
+async function requestSidecar(texts: string[], readyTimeoutMs: number, requestTimeoutMs: number, retried = false): Promise<Float32Array[]> {
+  let child: Sidecar;
+  try {
+    child = startSidecar();
+    await awaitReady(child, readyTimeoutMs);
+    const id = nextRequestId++;
+    return await new Promise<Float32Array[]>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        sidecarGone(child, new SidecarUnavailableError(`Embedding sidecar request timed out after ${requestTimeoutMs}ms`));
+      }, requestTimeoutMs);
+      const resolveRequest = (vectors: Float32Array[]) => {
+        clearTimeout(timeout);
+        resolve(vectors);
+      };
+      const rejectRequest = (error: Error) => {
+        clearTimeout(timeout);
+        reject(error);
+      };
+      child.pending.set(id, { resolve: resolveRequest, reject: rejectRequest, count: texts.length });
+      if (sidecar !== child) {
+        child.pending.delete(id);
+        rejectRequest(new SidecarUnavailableError("Embedding sidecar became unavailable before the request was sent"));
+        return;
+      }
+      try {
+        child.process.stdin.write(`${JSON.stringify({ id, texts })}\n`);
+      } catch (error) {
+        child.pending.delete(id);
+        const unavailable = new SidecarUnavailableError(`Could not write to embedding sidecar: ${String(error)}`);
+        sidecarGone(child, unavailable);
+        rejectRequest(unavailable);
+      }
+    });
+  } catch (error) {
+    if (!retried && error instanceof SidecarUnavailableError) return requestSidecar(texts, readyTimeoutMs, requestTimeoutMs, true);
+    throw error;
   }
-  return cached;
 }
 
 async function embedRaw(texts: string[]): Promise<Float32Array[]> {
   if (texts.length === 0) return [];
-  const e = await getEmbedder();
-  const out = await e(texts.map((t) => t.slice(0, MAX_CHARS)), { pooling: "cls", normalize: true });
-  const dims: number = out.dims[out.dims.length - 1];
-  // out.data is DataArray (a union incl. bigint typed arrays); a feature-extraction
-  // tensor with normalize:true is a Float32Array at runtime, so this cast is safe.
-  const flat = new Float32Array(out.data as Float32Array);
+  const prepared = texts.map((text) => text.slice(0, MAX_CHARS));
+  if (getEmbedMode() === "inline") {
+    // Unsafe under affected OpenCode/Bun versions: this intentionally loads
+    // Transformers.js only when the caller explicitly opts in.
+    const { embedInline } = await import("./embed-inline.ts");
+    return embedInline(prepared);
+  }
+  const batchSize = positiveIntegerEnv("EPISODIC_EMBED_BATCH_SIZE", DEFAULT_BATCH_SIZE, MAX_BATCH_SIZE);
+  const readyTimeoutMs = positiveIntegerEnv("EPISODIC_EMBED_READY_TIMEOUT_MS", DEFAULT_READY_TIMEOUT_MS, MAX_TIMEOUT_MS);
+  const requestTimeoutMs = positiveIntegerEnv("EPISODIC_EMBED_REQUEST_TIMEOUT_MS", DEFAULT_REQUEST_TIMEOUT_MS, MAX_TIMEOUT_MS);
   const vectors: Float32Array[] = [];
-  for (let i = 0; i < texts.length; i++) {
-    vectors.push(flat.subarray(i * dims, (i + 1) * dims));
+  for (let index = 0; index < prepared.length; index += batchSize) {
+    vectors.push(...await requestSidecar(prepared.slice(index, index + batchSize), readyTimeoutMs, requestTimeoutMs));
   }
   return vectors;
 }
@@ -57,6 +311,5 @@ export const embed = embedRaw;
 
 /** Embed a search query. Prepends the retrieval prefix. */
 export function embedQuery(query: string): Promise<Float32Array[]> {
-  const q = query.startsWith(QUERY_PREFIX) ? query : QUERY_PREFIX + query;
-  return embedRaw([q]);
+  return embedRaw([query.startsWith(QUERY_PREFIX) ? query : QUERY_PREFIX + query]);
 }