opencode-episodic-memory 0.1.3 → 0.3.0

package/README.md

@@ -18,9 +18,9 @@ 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)
-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
+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` by default; optional libSQL/Turso remote storage can combine source-scoped indexes across devices
+5. **Recall** — native plugin tools `episodic_search` / `episodic_read_window` / `episodic_read_session`, 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
 
 Design note: `bun:sqlite` cannot load dynamic extensions, so sqlite-vec is not
@@ -35,7 +35,7 @@ tends to match injected boilerplate on this corpus.
 ## Install
 
 ```bash
-opencode plugin opencode-episodic-memory@0.1.3 -g
+opencode plugin opencode-episodic-memory@0.3.0 -g
 ```
 
 This adds the plugin to your OpenCode config (`-g` = global config; omit it
@@ -48,11 +48,17 @@ Or edit `~/.config/opencode/opencode.json` manually:
 
 ```jsonc
 {
-  "plugin": ["opencode-episodic-memory@0.1.3"]
+  "plugin": ["opencode-episodic-memory@0.3.0"]
 }
 ```
 
-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_window`, `episodic_read_session`, 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):
@@ -69,13 +75,13 @@ OpenCode has downloaded the plugin (i.e. after first launch), copy it out of
 the package cache (the path contains your pinned version):
 
 ```bash
-cp -r ~/.cache/opencode/packages/opencode-episodic-memory@0.1.3/node_modules/opencode-episodic-memory/skills/remembering-conversations ~/.config/opencode/skills/
+cp -r ~/.cache/opencode/packages/opencode-episodic-memory@0.3.0/node_modules/opencode-episodic-memory/skills/remembering-conversations ~/.config/opencode/skills/
 ```
 
 Then backfill existing history and restart OpenCode:
 
 ```bash
-bunx opencode-episodic-memory@0.1.3 sync
+bunx opencode-episodic-memory@0.3.0 sync
 ```
 
 ## CLI
@@ -84,15 +90,16 @@ The package ships an `opencode-episodic` binary (requires `bun` on PATH).
 Invoke it through the package spec — pin it to match your plugin version:
 
 ```bash
-bunx opencode-episodic-memory@0.1.3 sync [--force]          # index new/changed sessions
-bunx opencode-episodic-memory@0.1.3 search "query"          # semantic (vector) search
-bunx opencode-episodic-memory@0.1.3 search q --text "terms"  # lexical BM25 (all terms AND-matched, token-based)
-bunx opencode-episodic-memory@0.1.3 search q --hybrid       # fuse vector + BM25 (RRF; opt-in)
-bunx opencode-episodic-memory@0.1.3 search q --after 2026-07-01 --limit 5
-bunx opencode-episodic-memory@0.1.3 read <session-id>       # full transcript (live store)
-bunx opencode-episodic-memory@0.1.3 read <id> --indexed     # indexed excerpts (survives deletion)
-bunx opencode-episodic-memory@0.1.3 stats                   # index statistics
-bunx opencode-episodic-memory@0.1.3 doctor                  # diagnose setup
+bunx opencode-episodic-memory@0.3.0 sync [--force]          # index new/changed sessions
+bunx opencode-episodic-memory@0.3.0 search "query"          # semantic (vector) search
+bunx opencode-episodic-memory@0.3.0 search q --text "terms"  # lexical BM25 (all terms AND-matched, token-based)
+bunx opencode-episodic-memory@0.3.0 search q --hybrid       # fuse vector + BM25 (RRF; opt-in)
+bunx opencode-episodic-memory@0.3.0 search q --after 2026-07-01 --limit 5
+bunx opencode-episodic-memory@0.3.0 read <session-id>       # full transcript (live store)
+bunx opencode-episodic-memory@0.3.0 read <id> --indexed     # local indexed excerpts
+bun run src/cli.ts read <id> --indexed --source laptop     # remote indexed excerpts (development/source checkout)
+bunx opencode-episodic-memory@0.3.0 stats                   # index statistics
+bunx opencode-episodic-memory@0.3.0 doctor                  # diagnose setup
 ```
 
 `--after`/`--before` take `YYYY-MM-DD` (midnight UTC). `--after D` is inclusive
@@ -100,8 +107,9 @@ of day D; `--before D` is exclusive of day D (i.e. up to the start of that day).
 
 ## Agent tools
 
-- **`episodic_search`** — `query` (+ optional `text`, `mode: vector|text|hybrid`, `after`, `before`, `limit`). `vector` (default) is semantic; `text` is lexical BM25; `hybrid` fuses both via RRF (opt-in — can surface lexical noise). Returns dated excerpts with session IDs and scores.
-- **`episodic_read`** — `session_id` (+ optional `indexed`). Full transcript from the live store, falling back to indexed excerpts.
+- **`episodic_search`** — `query` (+ optional `text`, `mode: vector|text|hybrid`, `after`, `before`, `limit`). `vector` (default) is semantic; `text` is lexical BM25; `hybrid` fuses both via RRF (opt-in — can surface lexical noise). Returns dated excerpts with session IDs, scores, and message anchors. Legacy results without an anchor require a normal sync before bounded window reads.
+- **`episodic_read_window`** — `session_id`, `anchor_message_id` (+ optional `source_id`, required in remote mode; `before`, `after`, each 0-20, default 3). Reads a bounded chronological window from the privacy-gated live source transcript. Deleted, private, stale, or legacy-anchored sessions cannot provide a window.
+- **`episodic_read_session`** — `session_id` (+ optional `source_id`, required in remote mode; `indexed`). Reads the full session transcript from the live store, falling back to indexed excerpts. Prefer `episodic_search` -> `episodic_read_window` -> `episodic_read_session`, stopping once enough context has been recovered.
 
 ## Excluding conversations
 
@@ -122,7 +130,60 @@ 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_INDEX_URL` | unset | Opt-in libSQL/Turso index URL; activates remote vector-only mode |
+| `EPISODIC_INDEX_AUTH_TOKEN` | unset | Required for remote network URLs; passed to `@libsql/client` |
+| `EPISODIC_SOURCE_ID` | unset | Required in remote mode; stable device/source identity |
 | `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.
+
+### Optional shared remote index
+
+Set all three variables on each device (use a distinct, stable source ID per
+device):
+
+```bash
+export EPISODIC_INDEX_URL='libsql://your-index.turso.io'
+export EPISODIC_INDEX_AUTH_TOKEN='...'
+export EPISODIC_SOURCE_ID='laptop'
+```
+
+This is an explicit privacy boundary: sync still reads OpenCode locally and
+generates embeddings locally, but it **uploads condensed chunk text, session
+metadata, anchors, and embedding vectors** to the configured database. Do not
+configure it unless that database is appropriate for this conversation data.
+Sessions containing `DO NOT INDEX THIS CHAT` upload neither content nor a
+metadata tombstone; an existing row for that source/session is removed.
+Absolute local `file:` libSQL URLs are supported without a token for hermetic
+testing; network
+URLs must use `https:`, `wss:`, or TLS-enabled `libsql:` and require a token
+supplied only through `EPISODIC_INDEX_AUTH_TOKEN` (not embedded in the URL).
+For `libsql:`, omit `tls` or use exactly one lowercase `tls=1` parameter.
+The remote schema is freshly created or validates/adopts a compatible existing
+schema and does not use FTS, so remote mode supports vector search only. `--text`,
+`--hybrid`, and plugin `text`/`hybrid` modes fail clearly in remote mode.
+Remote cosine search reads embedding candidates in bounded pages and hydrates
+only the final result set.
+
+Remote search includes the source ID in each hit. Bounded live reads are only
+valid for the current source; another device's hits remain available as indexed
+excerpts through `episodic_read_session` with that hit's `source_id`.
+
+Network failures are surfaced by the CLI and doctor; plugin background reindex
+logs failures and never silently falls back to a local index (which would split
+history). To return to local-only mode, unset `EPISODIC_INDEX_URL`,
+`EPISODIC_INDEX_AUTH_TOKEN`, and `EPISODIC_SOURCE_ID`; the existing local index
+is selected unchanged. Re-run `sync` if the local index needs rebuilding.
 
 ## Not yet implemented (deliberate)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-episodic-memory",
-  "version": "0.1.3",
+  "version": "0.3.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",
@@ -39,6 +39,7 @@
     "prepublishOnly": "bun run typecheck && bun test && bun run verify:entrypoint"
   },
   "dependencies": {
+    "@libsql/client": "^0.18.0",
     "@huggingface/transformers": "^4.2.0",
     "@opencode-ai/plugin": "^1.18.4",
     "zod": "^4.4.3"

package/plugin/episodic-memory.ts

@@ -1,47 +1,58 @@
 // OpenCode plugin: episodic memory over past conversations.
-// - Native tools: episodic_search, episodic_read
+// - Native tools: episodic_search, episodic_read_window, episodic_read_session
 // - Incremental reindex on session.idle (fire-and-forget, debounced)
 import { type Plugin, tool } from "@opencode-ai/plugin";
-import { openSource, getSession, getTranscriptChecked } from "../src/reader";
-import { openIndex, search, textSearch, isIndexEmpty } from "../src/store";
+import { openSource, getSession, getTranscriptChecked, getTranscriptContext } from "../src/reader";
+import { canLiveRead, openConfiguredIndex, remoteIndexConfig, type IndexStore } from "../src/store";
 import { syncSession, syncAll, pruneOrphans } from "../src/indexer";
 import { embedQuery } from "../src/embed";
-import { parseDateArg, formatHits, renderTranscript } from "../src/format";
+import { parseDateArg, formatHits, renderTranscript, renderTranscriptContext } from "../src/format";
 
 export const EpisodicMemory: Plugin = async ({ client }) => {
   const log = (level: "info" | "warn" | "error", message: string) =>
     client.app
       .log({ body: { service: "episodic-memory", level, message } })
       .catch(() => {});
+  let configuredIndex: Promise<IndexStore> | undefined;
+  const getIndex = () => configuredIndex ??= openConfiguredIndex().catch((error) => {
+    configuredIndex = undefined;
+    throw error;
+  });
 
   // Debounce concurrent reindex runs for the same session.
   const inflight = new Map<string, Promise<void>>();
+  const pending = new Set<string>();
   function reindex(sessionId?: string) {
     const key = sessionId ?? "__all__";
-    if (inflight.has(key)) return inflight.get(key)!;
+    if (inflight.has(key)) {
+      pending.add(key);
+      return inflight.get(key)!;
+    }
     const p = (async () => {
-      try {
-        const source = openSource();
-        const index = openIndex();
-        if (sessionId) {
-          const s = getSession(source, sessionId);
-          if (s) await syncSession(source, index, s);
-          // Cheap (two small SELECTs + rare DELETEs), so prune on every idle:
-          // the syncAll path below effectively never fires (session.idle always
-          // carries a sessionID), and without this, deleted conversations would
-          // linger in the index — searchable and readable — for plugin-only users.
-          pruneOrphans(source, index);
-        } else {
-          await syncAll(source, index); // syncAll prunes source-deleted orphans
+      do {
+        pending.delete(key);
+        try {
+          const source = openSource();
+          const index = await getIndex();
+          if (sessionId) {
+            const s = getSession(source, sessionId);
+            if (s) await syncSession(source, index, s);
+            // Cheap (two small SELECTs + rare DELETEs), so prune on every idle:
+            // the syncAll path below effectively never fires (session.idle always
+            // carries a sessionID), and without this, deleted conversations would
+            // linger in the index — searchable and readable — for plugin-only users.
+            await pruneOrphans(source, index);
+          } else {
+            await syncAll(source, index); // syncAll prunes source-deleted orphans
+          }
+          await log("info", `reindexed ${key}`);
+        } catch (e) {
+          await log("warn", `reindex failed for ${key}: ${e}`);
         }
-        await log("info", `reindexed ${key}`);
-      } catch (e) {
-        await log("warn", `reindex failed for ${key}: ${e}`);
-      } finally {
-        inflight.delete(key);
-      }
+      } while (pending.has(key));
     })();
     inflight.set(key, p);
+    p.finally(() => inflight.delete(key));
     return p;
   }
 
@@ -56,7 +67,7 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
     tool: {
       episodic_search: tool({
         description:
-          "Semantic search over your PAST OpenCode conversations. Use when the user references prior work, past decisions, or previous sessions (e.g. 'how did we handle X', 'the conversation about Y', 'what did we decide about Z'). Returns dated excerpts with session IDs; follow up with episodic_read for the full conversation.",
+          "Semantic search over your PAST OpenCode conversations. Use when the user references prior work, past decisions, or previous sessions (e.g. 'how did we handle X', 'the conversation about Y', 'what did we decide about Z'). Returns dated excerpts, session IDs, and anchors. Prefer episodic_search -> episodic_read_window for a bounded live window -> episodic_read_session only when the full session is needed.",
         args: {
           query: tool.schema.string().describe("Natural-language description of what you're looking for"),
           text: tool.schema.string().optional().describe("Exact substring to require in results (ANDed with semantic ranking)"),
@@ -66,7 +77,7 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
           limit: tool.schema.number().optional().describe("Max results, 1-50 (default 10)"),
         },
         async execute(args) {
-          const index = openIndex();
+          const index = await getIndex();
           const after = parseDateArg(args.after);
           if (!after.ok) return after.error;
           const before = parseDateArg(args.before);
@@ -77,30 +88,74 @@ 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 = async () => await index.isEmpty()
+            ? "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 = await index.textSearch(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 index.remote
+              ? "Semantic search unavailable: the embedding backend failed. Remote indexes support vector search only; run `bun run src/cli.ts doctor` for details."
+              : '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"
+            ? await index.search(vector, { ...opts, queryText: args.query, hybrid: true })
+            : await index.search(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");
         },
       }),
 
-      episodic_read: tool({
+      episodic_read_window: tool({
         description:
-          "Read the full transcript of a past OpenCode conversation, given a session ID (from episodic_search results). Reconstructs from the live session store; falls back to indexed excerpts if the session was deleted.",
+          "Read a bounded live-source message window around an anchor from episodic_search. Use the returned session_id and anchor_message_id; this cannot read deleted sessions or indexed-only excerpts.",
+        args: {
+          session_id: tool.schema.string().describe("Session ID from episodic_search, e.g. ses_..."),
+          source_id: tool.schema.string().optional().describe("Source ID shown by remote episodic_search results; required for remote indexes"),
+          anchor_message_id: tool.schema.string().describe("Anchor message ID from episodic_search"),
+          before: tool.schema.number().optional().describe("Messages before the anchor, 0-20 (default 3)"),
+          after: tool.schema.number().optional().describe("Messages after the anchor, 0-20 (default 3)"),
+        },
+        async execute(args) {
+          const remote = remoteIndexConfig();
+          if (!canLiveRead(remote, args.source_id)) {
+            throw new Error("This indexed hit belongs to another source (or has no source_id). Its excerpt is searchable, but live windows are only available for the current source.");
+          }
+          const source = openSource();
+          const context = getTranscriptContext(source, args.session_id, args.anchor_message_id, args.before, args.after);
+          if (!context.ok) {
+            if (context.reason === "unknown_session") throw new Error(`No live conversation found for session ${args.session_id}.`);
+            if (context.reason === "excluded") throw new Error("Session is marked private (exclusion marker present); context withheld.");
+            if (context.reason === "invalid_anchor") throw new Error(`Anchor message ${args.anchor_message_id} is stale or invalid for session ${args.session_id}.`);
+            throw new Error("before and after must be non-negative integers no greater than 20.");
+          }
+          return renderTranscriptContext(context.session, context);
+        },
+      }),
+
+      episodic_read_session: tool({
+        description:
+          "Read the full transcript of a past OpenCode session, given a session ID (from episodic_search results). Use after episodic_read_window when the bounded window is insufficient. Reconstructs from the live session store; falls back to indexed excerpts if the session was deleted.",
         args: {
           session_id: tool.schema.string().describe("Session ID, e.g. ses_..."),
+          source_id: tool.schema.string().optional().describe("Source ID shown by remote episodic_search results"),
           indexed: tool.schema.boolean().optional().describe("Force reading from the index instead of the live session store"),
         },
         async execute(args) {
-          if (!args.indexed) {
+          const remote = remoteIndexConfig();
+          if (remote && args.source_id === undefined) {
+            throw new Error("source_id is required for episodic_read_session with a remote index.");
+          }
+          const foreign = !canLiveRead(remote, args.source_id);
+          if (!args.indexed && !foreign) {
             try {
               const source = openSource();
               const s = getSession(source, args.session_id);
@@ -116,14 +171,12 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
             } catch (e) {
               // Log before falling through — a bare swallow would also hide
               // structural Zod drift, which is meant to be loud.
-              await log("warn", `episodic_read live-store read failed for ${args.session_id}: ${e}`);
+              await log("warn", `episodic_read_session live-store read failed for ${args.session_id}: ${e}`);
               // fall through to indexed copy
             }
           }
-          const index = openIndex();
-          const rows = index
-            .prepare<{ text: string }, [string]>("SELECT text FROM chunks WHERE session_id = ? ORDER BY seq")
-            .all(args.session_id);
+          const index = await getIndex();
+          const rows = await index.readIndexed(args.session_id, args.source_id);
           if (rows.length === 0) return `No conversation found for session ${args.session_id}.`;
           return `(indexed excerpts — live session unavailable)\n\n${rows.map((r) => r.text).join("\n\n---\n\n")}`.slice(0, 50000);
         },

package/skills/remembering-conversations/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: remembering-conversations
-description: Recall past OpenCode conversations when the user references previous work, past decisions, or earlier sessions — "how did we handle X", "the conversation about Y", "what did we decide", "we tried this before", "last week we...". Use the episodic_search and episodic_read tools to search semantically and read full transcripts.
+description: Recall past OpenCode conversations when the user references previous work, past decisions, or earlier sessions — "how did we handle X", "the conversation about Y", "what did we decide", "we tried this before", "last week we...". Use episodic_search, then episodic_read_window for a bounded window, and episodic_read_session only when the full session is needed.
 ---
 
 # Remembering Conversations
 
 You have episodic memory: every past OpenCode session is indexed and searchable
-via two native tools.
+via three native tools.
 
 ## When to search
 
@@ -29,12 +29,17 @@ conversation — the index is for cross-session recall, not code search.
      (an error string, a flag name, a file path).
    - `mode: "text"` for lexical BM25 search: every query word must appear (token-based
      AND, BM25-ranked) — not phrase/adjacency or substring matching.
-2. Skim the returned excerpts (date, session title, score). Similarity scores are
-   NOT calibrated probabilities: ≥ ~0.55 is a strong match, 0.4–0.55 is likely
-   relevant, < ~0.35 is weak or merely adjacent — judge by the snippet, not the
-   number, and say when the corpus doesn't really contain the topic.
-3. `episodic_read` with the session ID for the full transcript when an excerpt
-   isn't enough.
+2. Skim the returned excerpts (date, session title, score, and anchor). Vector
+   similarity scores are NOT calibrated probabilities: ≥ ~0.55 is a strong
+   match, 0.4–0.55 is likely relevant, and < ~0.35 is weak or merely adjacent.
+   These thresholds apply only to vector results. For hybrid results, use the
+   snippet and the `rrf` label instead; RRF scores are on a different scale.
+   Say when the corpus doesn't really contain the topic.
+3. `episodic_read_window` with the result's session ID and anchor message ID to
+   inspect a small chronological window first. It is live-source only: private,
+   deleted, stale, and legacy unanchored results cannot expand.
+4. `episodic_read_session` with the session ID only when that window isn't enough
+   and the full session transcript is needed.
 
 ## Answering
 

package/src/cli.ts

@@ -7,15 +7,15 @@
 //     --after YYYY-MM-DD           Only conversations after this date
 //     --before YYYY-MM-DD          Only conversations before this date
 //     --limit N                    Max results (default 10)
-//   read <session-id> [--indexed]  Print a readable transcript (live DB, or --indexed for index copy)
+//   read <session-id> [--indexed --source source-id]  Print a readable transcript
 //   stats                          Index statistics
 //   doctor                         Diagnose setup
 import { existsSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { openSource, sourceDbPath, getSession, getTranscriptChecked } from "./reader";
-import { openIndex, indexDbPath, search, textSearch, stats, isIndexEmpty } from "./store";
+import { openConfiguredIndex, indexDbPath, type IndexStore } 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;
@@ -37,6 +37,7 @@ function parseCli() {
         force: { type: "boolean" },
         indexed: { type: "boolean" },
         hybrid: { type: "boolean" },
+        source: { type: "string" },
       },
       allowPositionals: true,
       strict: true,
@@ -73,16 +74,21 @@ function limitArg(s: string | undefined): number {
   return Math.min(n, 1000);
 }
 
+async function withConfiguredIndex<T>(fn: (index: IndexStore) => Promise<T>): Promise<T> {
+  const index = await openConfiguredIndex();
+  try { return await fn(index); }
+  finally { index.close(); }
+}
+
 async function main() {
   switch (command) {
     case "sync": {
       const source = openSource();
-      const index = openIndex();
-      const r = await syncAll(source, index, {
+      const r = await withConfiguredIndex((index) => syncAll(source, index, {
         force: values.force,
         onProgress: (done, total, title) =>
           process.stderr.write(`\r[${done}/${total}] ${title.slice(0, 60)}                    `),
-      });
+      }));
       process.stderr.write("\n");
       console.log(
         `scanned=${r.scanned} indexed=${r.indexed} fresh=${r.skippedFresh} excluded=${r.excluded} empty=${r.empty} pruned=${r.pruned}`
@@ -93,21 +99,22 @@ async function main() {
     case "search": {
       const query = positionals.join(" ");
       if (!query) { console.error("usage: opencode-episodic search <query> [--text p] [--hybrid] [--after d] [--before d] [--limit n]"); process.exit(1); }
-      const index = openIndex();
       const opts = {
         limit: limitArg(values.limit),
         after: dateArg(values.after),
         before: dateArg(values.before),
       };
-      const hits = values.text
-        ? textSearch(index, values.text, opts)
-        : search(
-            index,
+      const { hits, empty } = await withConfiguredIndex(async (index) => {
+        const hits = values.text
+          ? await index.textSearch(values.text, opts)
+          : await index.search(
             (await embedQuery(query))[0],
             values.hybrid ? { ...opts, queryText: query, hybrid: true } : opts
           );
+        return { hits, empty: hits.length === 0 && await index.isEmpty() };
+      });
       if (hits.length === 0) {
-        console.log(isIndexEmpty(index)
+        console.log(empty
           ? "No results. The index is empty — run: bun run src/cli.ts sync"
           : "No results.");
       } else {
@@ -119,12 +126,13 @@ async function main() {
 
     case "read": {
       const id = positionals[0];
-      if (!id) { console.error("usage: opencode-episodic read <session-id> [--indexed]"); process.exit(1); }
+      if (!id) { console.error("usage: opencode-episodic read <session-id> [--indexed --source source-id]"); process.exit(1); }
       if (values.indexed) {
-        const index = openIndex();
-        const rows = index
-          .prepare<{ seq: number; text: string }, [string]>("SELECT seq, text FROM chunks WHERE session_id = ? ORDER BY seq")
-          .all(id);
+        if (process.env.EPISODIC_INDEX_URL && !values.source) {
+          console.error("error: --source is required for remote indexed reads.");
+          process.exit(1);
+        }
+        const rows = await withConfiguredIndex((index) => index.readIndexed(id, values.source));
         if (rows.length === 0) { console.error("no indexed content for", id); process.exit(1); }
         for (const r of rows) console.log(r.text, "\n---");
         break;
@@ -144,8 +152,7 @@ async function main() {
     }
 
     case "stats": {
-      const index = openIndex();
-      const s = stats(index);
+      const s = await withConfiguredIndex((index) => index.stats());
       console.log(`sessions: ${s.sessions} (${s.excluded} excluded/empty), chunks: ${s.chunks}`);
       if (s.oldest) console.log(`range: ${fmtDate(Number(s.oldest))} → ${fmtDate(Number(s.newest))}`);
       console.log("\nTop directories:");
@@ -157,6 +164,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; }
@@ -166,8 +201,8 @@ async function main() {
         console.log(`✓ source readable: ${n} sessions`);
       } catch (e) { console.error(`✗ source unreadable: ${e}`); ok = false; }
       try {
-        const idx = openIndex();
-        console.log(`✓ index writable: ${indexDbPath()}`);
+        const idx = await openConfiguredIndex();
+        console.log(`✓ index writable: ${idx.remote ? "remote index" : indexDbPath()}`);
         idx.close();
       } catch (e) { console.error(`✗ index not writable: ${e}`); ok = false; }
       try {

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));
+}