opencode-episodic-memory 0.1.2 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # opencode-episodic-memory
 
+[![skills.sh](https://skills.sh/b/robertn702/opencode-episodic-memory)](https://skills.sh/robertn702/opencode-episodic-memory)
+
 Semantic search over your past [OpenCode](https://opencode.ai) conversations.
 Remember past discussions, decisions, and patterns across sessions.
 
@@ -8,67 +10,95 @@ rebuilt for OpenCode primitives — native plugin tools instead of an MCP server
 plugin events instead of hooks, and OpenCode's own session database as the
 source.
 
+Wondering how this compares to opencode-mem, codemem, memsearch, and the rest
+of the OpenCode memory-plugin landscape? See
+[docs/alternatives.md](docs/alternatives.md).
+
 ## How it works
 
 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
+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
 
 Design note: `bun:sqlite` cannot load dynamic extensions, so sqlite-vec is not
 usable inside OpenCode plugins. Brute-force cosine is single-digit milliseconds
 at this scale (thousands of chunks) and has zero native-dependency risk. The
-store layer is the single swap point if a real ANN index is ever needed.
+store layer is the single swap point if a real ANN index is ever needed. FTS5 is
+compiled into `bun:sqlite` (not a loadable extension), so lexical BM25 ranking
+is available; search is vector-only by default, with lexical and hybrid
+(reciprocal-rank-fusion) modes opt-in — hybrid is off by default because BM25
+tends to match injected boilerplate on this corpus.
 
 ## Install
 
 ```bash
-bun install   # first embed downloads the model (~100 MB, cached afterwards)
+opencode plugin opencode-episodic-memory@0.1.3 -g
 ```
 
+This adds the plugin to your OpenCode config (`-g` = global config; omit it
+to install for the current project only). **Pin the version** — OpenCode
+caches npm plugins and never re-resolves a bare name / `@latest`
+([anomalyco/opencode#25293](https://github.com/anomalyco/opencode/issues/25293)).
+To update later, re-run with the new version and `--force`.
+
+Or edit `~/.config/opencode/opencode.json` manually:
+
 ```jsonc
-// ~/.config/opencode/opencode.json
 {
-  "plugin": ["/path/to/opencode-episodic-memory/plugin/episodic-memory.ts"]
+  "plugin": ["opencode-episodic-memory@0.1.3"]
 }
 ```
 
-Or from npm — pin the version. OpenCode caches npm plugins and never
-re-resolves a bare name / `@latest`
-([anomalyco/opencode#25293](https://github.com/anomalyco/opencode/issues/25293)),
-so to update later you bump the pin:
+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.
 
-```jsonc
-{
-  "plugin": ["opencode-episodic-memory@0.1.1"]
-}
+Install the skill so the agent knows when to search, via the
+[`skills` CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add robertn702/opencode-episodic-memory -g
 ```
 
-Copy the skill so the agent knows when to search:
+(`-g` installs to `~/.config/opencode/skills/`; omit it to install into the
+current project. `npx skills update` picks up future skill changes.)
+
+Alternatively, copy it manually — it's included in the npm package; once
+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 skills/remembering-conversations ~/.config/opencode/skills/
+cp -r ~/.cache/opencode/packages/opencode-episodic-memory@0.1.3/node_modules/opencode-episodic-memory/skills/remembering-conversations ~/.config/opencode/skills/
 ```
 
 Then backfill existing history and restart OpenCode:
 
 ```bash
-bun run src/cli.ts sync
+bunx opencode-episodic-memory@0.1.3 sync
 ```
 
 ## CLI
 
+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
-bun run src/cli.ts sync [--force]          # index new/changed sessions
-bun run src/cli.ts search "query"          # semantic search
-bun run src/cli.ts search q --text "exact" # require substring
-bun run src/cli.ts search q --after 2026-07-01 --limit 5
-bun run src/cli.ts read <session-id>       # full transcript (live store)
-bun run src/cli.ts read <id> --indexed     # indexed excerpts (survives deletion)
-bun run src/cli.ts stats                   # index statistics
-bun run src/cli.ts doctor                  # diagnose setup
+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
 ```
 
 `--after`/`--before` take `YYYY-MM-DD` (midnight UTC). `--after D` is inclusive
@@ -76,7 +106,7 @@ 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`, `after`, `before`, `limit`). Returns dated excerpts with session IDs and similarity scores.
+- **`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.
 
 ## Excluding conversations
@@ -99,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)
 
@@ -108,6 +150,28 @@ instruction-tag match — the intent is the same, but our matching is literal.
 - Multi-concept AND search, MCP server wrapper for non-OpenCode clients
 - ANN index (see design note above)
 
+## Development
+
+To hack on the plugin itself, clone the repo and point OpenCode at the local
+entrypoint instead of the npm package:
+
+```bash
+git clone https://github.com/robertn702/opencode-episodic-memory.git
+cd opencode-episodic-memory
+bun install
+```
+
+```jsonc
+// ~/.config/opencode/opencode.json
+{
+  "plugin": ["/path/to/opencode-episodic-memory/plugin/episodic-memory.ts"]
+}
+```
+
+Inside the repo, run the CLI as `bun run src/cli.ts <command>` (same
+subcommands as above), tests with `bun test`, and typechecking with
+`bun run typecheck`.
+
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-episodic-memory",
-  "version": "0.1.2",
-  "description": "Semantic search over past OpenCode conversations. Port of obra/episodic-memory to OpenCode primitives.",
+  "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",
   "author": "robertn702",
@@ -25,7 +25,8 @@
   "files": [
     "plugin",
     "src",
-    "skills"
+    "skills",
+    "!src/*.test.ts"
   ],
   "bin": {
     "opencode-episodic": "src/cli.ts"

package/plugin/episodic-memory.ts

@@ -2,26 +2,11 @@
 // - Native tools: episodic_search, episodic_read
 // - Incremental reindex on session.idle (fire-and-forget, debounced)
 import { type Plugin, tool } from "@opencode-ai/plugin";
-import { openSource, getSession, getTranscript, transcriptHasMarker } from "../src/reader";
-import { openIndex, search, textSearch } from "../src/store";
+import { openSource, getSession, getTranscriptChecked } from "../src/reader";
+import { openIndex, search, textSearch, isIndexEmpty } from "../src/store";
 import { syncSession, syncAll, pruneOrphans } from "../src/indexer";
 import { embedQuery } from "../src/embed";
-
-// Discriminated result so callers handle the parse error explicitly (no cast to
-// strip the error arm off a union). `ms` is undefined when no date was given.
-type ParsedDate = { ok: true; ms?: number } | { ok: false; error: string };
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-// Require strict YYYY-MM-DD, then round-trip to reject impossible calendar dates
-// (`new Date("2024-02-31")` silently normalizes to March 2 rather than failing).
-const parseDateArg = (s?: string): ParsedDate => {
-  if (!s) return { ok: true };
-  const ms = new Date(s).getTime();
-  if (!DATE_RE.test(s) || Number.isNaN(ms) || new Date(ms).toISOString().slice(0, 10) !== s) {
-    return { ok: false, error: `Invalid date "${s}" (expected YYYY-MM-DD).` };
-  }
-  return { ok: true, ms };
-};
-const fmtDate = (ms: number) => new Date(ms).toISOString().slice(0, 10);
+import { parseDateArg, formatHits, renderTranscript } from "../src/format";
 
 export const EpisodicMemory: Plugin = async ({ client }) => {
   const log = (level: "info" | "warn" | "error", message: string) =>
@@ -75,7 +60,7 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
         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)"),
-          mode: tool.schema.enum(["vector", "text"]).optional().describe("'vector' (default) semantic search; 'text' exact substring only"),
+          mode: tool.schema.enum(["vector", "text", "hybrid"]).optional().describe("'vector' (default) semantic search, scores are cosine (~0.4–0.7); 'text' lexical BM25; 'hybrid' fuses both via RRF (may surface lexical noise) — note hybrid hits carry fused RRF scores (~0.03), a DIFFERENT scale from cosine, so don't judge them against the vector thresholds"),
           after: tool.schema.string().optional().describe("Only conversations after YYYY-MM-DD"),
           before: tool.schema.string().optional().describe("Only conversations before YYYY-MM-DD"),
           limit: tool.schema.number().optional().describe("Max results, 1-50 (default 10)"),
@@ -92,21 +77,27 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
             before: before.ms,
             text: args.text,
           };
-          const hits =
-            args.mode === "text"
-              ? textSearch(index, args.query, opts)
-              : search(index, (await embedQuery(args.query))[0], opts);
-          if (hits.length === 0) {
-            const chunkCount = index.prepare<{ n: number }, []>("SELECT COUNT(*) n FROM chunks").get()?.n ?? 0;
-            if (chunkCount === 0) 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");
           }
-          return hits
-            .map((h) => {
-              const snippet = h.text.replace(/\s+/g, " ").slice(0, 400);
-              return `## ${fmtDate(h.time_created)} — ${h.title}\nsession: ${h.session_id}  score: ${h.score.toFixed(3)}\n${h.directory}\n> ${snippet}`;
-            })
-            .join("\n\n");
+          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");
         },
       }),
 
@@ -123,27 +114,18 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
               const source = openSource();
               const s = getSession(source, args.session_id);
               if (s) {
-                // Authoritative gate: raw part blobs (a marker in an
-                // unparseable blob would be invisible to the parsed-text scan).
-                if (transcriptHasMarker(source, args.session_id)) {
+                // Privacy gate lives inside getTranscriptChecked (authoritative
+                // raw-blob scan before any read).
+                const checked = getTranscriptChecked(source, args.session_id);
+                if (checked.excluded) {
                   return "Session is marked private (exclusion marker present); transcript withheld.";
                 }
-                const transcript = getTranscript(source, args.session_id);
-                const lines: string[] = [`# ${s.title}`, `${fmtDate(s.time_created)} — ${s.directory} — ${s.id}`, ""];
-                for (const m of transcript) {
-                  const text = m.parts
-                    .filter((p) => p.type === "text" && p.text)
-                    .map((p) => p.text)
-                    .join("\n");
-                  const tools = m.parts.filter((p) => p.type === "tool" && p.tool).map((p) => p.tool);
-                  if (!text && tools.length === 0) continue;
-                  lines.push(`## ${m.role}`);
-                  if (text) lines.push(text);
-                  if (tools.length) lines.push(`*(tools: ${tools.join(", ")})*`, "");
-                }
-                return lines.join("\n").slice(0, 50000);
+                return renderTranscript(s, checked.messages).slice(0, 50000);
               }
-            } catch {
+            } 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}`);
               // fall through to indexed copy
             }
           }

package/skills/remembering-conversations/SKILL.md

@@ -27,7 +27,8 @@ conversation — the index is for cross-session recall, not code search.
    not exact keywords ("migrating from Claude Code to OpenCode", not "claude opencode").
    - Narrow with `after`/`before` dates or an exact `text` substring when you know one
      (an error string, a flag name, a file path).
-   - `mode: "text"` for exact-phrase lookup only.
+   - `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

package/src/cli.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env bun
 // opencode-episodic <command> [options]
 //   sync [--force]                 Index new/changed sessions from opencode.db
-//   search <query> [options]       Semantic search over indexed conversations
-//     --text "phrase"              Exact substring match instead of vector
+//   search <query> [options]       Semantic (vector) search over indexed conversations
+//     --text "terms"               Lexical BM25 search for these terms (all AND-matched) instead of vector
+//     --hybrid                     Fuse vector + BM25 (RRF); off by default (see AGENTS.md)
 //     --after YYYY-MM-DD           Only conversations after this date
 //     --before YYYY-MM-DD          Only conversations before this date
 //     --limit N                    Max results (default 10)
@@ -10,66 +11,66 @@
 //   stats                          Index statistics
 //   doctor                         Diagnose setup
 import { existsSync } from "node:fs";
-import { openSource, sourceDbPath, getSession, getTranscript, transcriptHasMarker } from "./reader";
-import { openIndex, indexDbPath, search, textSearch, stats, type SearchHit } from "./store";
+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;
+const USAGE = "commands: sync | search | read | stats | doctor";
 
-function flag(name: string): string | null {
-  const i = rest.indexOf(`--${name}`);
-  return i >= 0 ? rest[i + 1] ?? null : null;
-}
-function hasFlag(name: string): boolean {
-  return rest.includes(`--${name}`);
-}
-const VALUE_FLAGS = new Set(["--text", "--after", "--before", "--limit"]);
-function positional(): string[] {
-  const out: string[] = [];
-  for (let i = 0; i < rest.length; i++) {
-    const t = rest[i];
-    if (t.startsWith("--")) {
-      if (VALUE_FLAGS.has(t)) {
-        const next = rest[i + 1];
-        if (next === undefined || next.startsWith("--")) {
-          console.error(`error: ${t} requires a value`);
-          process.exit(1);
-        }
-        i++; // only value flags consume the next token
-      }
-      continue;
-    }
-    out.push(t);
-  }
-  return out;
-}
-const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-// Require strict YYYY-MM-DD, then round-trip to reject impossible calendar dates
-// (`new Date("2024-02-31")` silently normalizes to March 2 rather than failing).
-const dateMs = (s: string | null): number | undefined => {
-  if (!s) return undefined;
-  const ms = new Date(s).getTime();
-  if (!DATE_RE.test(s) || Number.isNaN(ms) || new Date(ms).toISOString().slice(0, 10) !== s) {
-    console.error(`error: invalid date "${s}" (expected YYYY-MM-DD)`);
+// parseArgs (node:util, supported in Bun) over the tokens after the command.
+// strict:true rejects unknown flags and missing values — we map those throws to
+// the same error+usage+exit(1) the hand-rolled parser used. `search` joins the
+// positionals with spaces as its query.
+function parseCli() {
+  try {
+    return parseArgs({
+      args: rest,
+      options: {
+        text: { type: "string" },
+        after: { type: "string" },
+        before: { type: "string" },
+        limit: { type: "string" },
+        force: { type: "boolean" },
+        indexed: { type: "boolean" },
+        hybrid: { type: "boolean" },
+      },
+      allowPositionals: true,
+      strict: true,
+    });
+  } catch (e) {
+    console.error(`error: ${e instanceof Error ? e.message : e}`);
+    console.error(USAGE);
     process.exit(1);
   }
-  return ms;
-};
+}
+const { values, positionals } = parseCli();
 
-function fmtDate(ms: number): string {
-  return new Date(ms).toISOString().slice(0, 10);
+// Map the shared parseDateArg union onto CLI semantics: print the error and
+// exit non-zero. `values.*` is undefined for an absent flag (→ no date filter).
+function dateArg(s: string | undefined): number | undefined {
+  const r = parseDateArg(s);
+  if (!r.ok) { console.error(`error: ${r.error}`); process.exit(1); }
+  return r.ms;
 }
 
-function printHits(hits: SearchHit[]): void {
-  if (hits.length === 0) { console.log("No results."); return; }
-  for (const h of hits) {
-    const snippet = h.text.replace(/\s+/g, " ").slice(0, 220);
-    console.log(`## ${fmtDate(h.time_created)} — ${h.title}`);
-    console.log(`session: ${h.session_id}  score: ${h.score.toFixed(3)}`);
-    console.log(`${h.directory}`);
-    console.log(`> ${snippet}\n`);
+// Parse/validate --limit (default 10). Same hard error+exit(1) pattern as an
+// invalid date: without this, Number("abc") → NaN silently yields "No results.",
+// and a negative limit slices from the end of the ranked list. Must be a
+// positive integer; clamped to 1000 (a CLI sanity ceiling — plenty for a human
+// debugging session).
+function limitArg(s: string | undefined): number {
+  if (s === undefined) return 10;
+  const n = Number.parseInt(s, 10);
+  if (!Number.isFinite(n) || n < 1) {
+    console.error(`error: invalid --limit "${s}" (expected a positive integer).`);
+    console.error(USAGE);
+    process.exit(1);
   }
+  return Math.min(n, 1000);
 }
 
 async function main() {
@@ -78,7 +79,7 @@ async function main() {
       const source = openSource();
       const index = openIndex();
       const r = await syncAll(source, index, {
-        force: hasFlag("force"),
+        force: values.force,
         onProgress: (done, total, title) =>
           process.stderr.write(`\r[${done}/${total}] ${title.slice(0, 60)}                    `),
       });
@@ -90,30 +91,36 @@ async function main() {
     }
 
     case "search": {
-      const query = positional().join(" ");
-      if (!query) { console.error("usage: opencode-episodic search <query> [--text p] [--after d] [--before d] [--limit n]"); process.exit(1); }
+      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: Number(flag("limit") ?? 10),
-        after: dateMs(flag("after")),
-        before: dateMs(flag("before")),
+        limit: limitArg(values.limit),
+        after: dateArg(values.after),
+        before: dateArg(values.before),
       };
-      const textFlag = flag("text");
-      const hits = textFlag
-        ? textSearch(index, textFlag, opts)
-        : search(index, (await embedQuery(query))[0], opts);
-      if (hits.length === 0 && stats(index).chunks === 0) {
-        console.log("No results. The index is empty — run: bun run src/cli.ts sync");
+      const hits = values.text
+        ? textSearch(index, values.text, opts)
+        : search(
+            index,
+            (await embedQuery(query))[0],
+            values.hybrid ? { ...opts, queryText: query, hybrid: true } : opts
+          );
+      if (hits.length === 0) {
+        console.log(isIndexEmpty(index)
+          ? "No results. The index is empty — run: bun run src/cli.ts sync"
+          : "No results.");
       } else {
-        printHits(hits);
+        // Hybrid hits carry RRF scores (~0.03), not cosine — label them "rrf".
+        console.log(formatHits(hits, 220, values.hybrid ? "rrf" : "score"));
       }
       break;
     }
 
     case "read": {
-      const id = positional()[0];
+      const id = positionals[0];
       if (!id) { console.error("usage: opencode-episodic read <session-id> [--indexed]"); process.exit(1); }
-      if (hasFlag("indexed")) {
+      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")
@@ -125,23 +132,14 @@ async function main() {
       const source = openSource();
       const s = getSession(source, id);
       if (!s) { console.error("session not found:", id); process.exit(1); }
-      // Authoritative gate: raw part blobs (a marker in an unparseable blob
-      // would be invisible to the parsed-text scan).
-      if (transcriptHasMarker(source, id)) {
+      // Privacy gate lives inside getTranscriptChecked (authoritative raw-blob
+      // scan before any read).
+      const checked = getTranscriptChecked(source, id);
+      if (checked.excluded) {
         console.error("session is marked private (exclusion marker present); transcript withheld");
         process.exit(1);
       }
-      const transcript = getTranscript(source, id);
-      console.log(`# ${s.title}\n${fmtDate(s.time_created)} — ${s.directory} — ${s.id}\n`);
-      for (const m of transcript) {
-        const text = m.parts.filter((p) => p.type === "text" && p.text).map((p) => p.text).join("\n");
-        const tools = m.parts.filter((p) => p.type === "tool" && p.tool).map((p) => p.tool);
-        if (!text && tools.length === 0) continue;
-        console.log(`## ${m.role}`);
-        if (text) console.log(text);
-        if (tools.length) console.log(`*(tools: ${tools.join(", ")})*`);
-        console.log();
-      }
+      console.log(renderTranscript(s, checked.messages));
       break;
     }
 
@@ -159,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));
+}