opencode-episodic-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 robertn702
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# opencode-episodic-memory
+
+Semantic search over your past [OpenCode](https://opencode.ai) conversations.
+Remember past discussions, decisions, and patterns across sessions.
+
+Inspired by [obra/episodic-memory](https://github.com/obra/episodic-memory),
+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.
+
+## 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
+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.
+
+## Install
+
+```bash
+bun install   # first embed downloads the model (~100 MB, cached afterwards)
+```
+
+```jsonc
+// ~/.config/opencode/opencode.json
+{
+  "plugin": ["/path/to/opencode-episodic-memory/plugin/episodic-memory.ts"]
+}
+```
+
+Copy the skill so the agent knows when to search:
+
+```bash
+cp -r skills/remembering-conversations ~/.config/opencode/skills/
+```
+
+Then backfill existing history and restart OpenCode:
+
+```bash
+bun run src/cli.ts sync
+```
+
+## CLI
+
+```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
+```
+
+`--after`/`--before` take `YYYY-MM-DD` (midnight UTC). `--after D` is inclusive
+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_read`** — `session_id` (+ optional `indexed`). Full transcript from the live store, falling back to indexed excerpts.
+
+## Excluding conversations
+
+Any conversation containing this marker is archived nowhere and indexed nowhere:
+
+```
+DO NOT INDEX THIS CHAT
+```
+
+Note: the marker is matched as a bare substring anywhere in any message part, so
+this also excludes conversations that merely *quote* the phrase (such as
+discussions about this tool itself). This is broader than upstream's full
+instruction-tag match — the intent is the same, but our matching is literal.
+
+## Configuration (env vars)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `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 |
+
+## Not yet implemented (deliberate)
+
+- LLM-generated per-session summaries embedded instead of raw exchange text
+  (upstream does this; deferred until search quality data says it's needed —
+  would use OpenCode provider auth via `client.session.prompt`)
+- Multi-concept AND search, MCP server wrapper for non-OpenCode clients
+- ANN index (see design note above)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "opencode-episodic-memory",
+  "version": "0.1.0",
+  "description": "Semantic search over past OpenCode conversations. Port of obra/episodic-memory to OpenCode primitives.",
+  "type": "module",
+  "license": "MIT",
+  "author": "robertn702",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/robertn702/opencode-episodic-memory"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "episodic-memory",
+    "semantic-search",
+    "embeddings",
+    "transformersjs"
+  ],
+  "exports": {
+    ".": "./plugin/episodic-memory.ts",
+    "./cli": "./src/cli.ts"
+  },
+  "files": [
+    "plugin",
+    "src",
+    "skills"
+  ],
+  "bin": {
+    "opencode-episodic": "./src/cli.ts"
+  },
+  "scripts": {
+    "spike": "bun run spikes/spike.ts",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun test"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.2.0",
+    "@opencode-ai/plugin": "^1.18.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^7.0.2"
+  },
+  "trustedDependencies": [
+    "onnxruntime-node",
+    "protobufjs"
+  ]
+}

package/plugin/episodic-memory.ts

@@ -0,0 +1,161 @@
+// OpenCode plugin: episodic memory over past conversations.
+// - 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 } from "../src/reader";
+import { openIndex, search, textSearch } from "../src/store";
+import { syncSession, syncAll, pruneOrphans } from "../src/indexer";
+import { embedQuery } from "../src/embed";
+import { hasExcludeMarker } from "../src/parser";
+
+// 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);
+
+export const EpisodicMemory: Plugin = async ({ client }) => {
+  const log = (level: "info" | "warn" | "error", message: string) =>
+    client.app
+      .log({ body: { service: "episodic-memory", level, message } })
+      .catch(() => {});
+
+  // Debounce concurrent reindex runs for the same session.
+  const inflight = new Map<string, Promise<void>>();
+  function reindex(sessionId?: string) {
+    const key = sessionId ?? "__all__";
+    if (inflight.has(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
+        }
+        await log("info", `reindexed ${key}`);
+      } catch (e) {
+        await log("warn", `reindex failed for ${key}: ${e}`);
+      } finally {
+        inflight.delete(key);
+      }
+    })();
+    inflight.set(key, p);
+    return p;
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.idle") {
+        // event is narrowed to EventSessionIdle here; properties.sessionID is typed.
+        reindex(event.properties.sessionID); // fire-and-forget; never block the session
+      }
+    },
+
+    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.",
+        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"),
+          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)"),
+        },
+        async execute(args) {
+          const index = openIndex();
+          const after = parseDateArg(args.after);
+          if (!after.ok) return after.error;
+          const before = parseDateArg(args.before);
+          if (!before.ok) return before.error;
+          const opts = {
+            limit: Math.min(Math.max(args.limit ?? 10, 1), 50),
+            after: after.ms,
+            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.";
+          }
+          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");
+        },
+      }),
+
+      episodic_read: 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.",
+        args: {
+          session_id: tool.schema.string().describe("Session ID, e.g. ses_..."),
+          indexed: tool.schema.boolean().optional().describe("Force reading from the index instead of the live session store"),
+        },
+        async execute(args) {
+          if (!args.indexed) {
+            try {
+              const source = openSource();
+              const s = getSession(source, args.session_id);
+              if (s) {
+                const transcript = getTranscript(source, args.session_id);
+                if (hasExcludeMarker(transcript)) {
+                  return "Session is marked private (exclusion marker present); transcript withheld.";
+                }
+                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);
+              }
+            } catch {
+              // 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);
+          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);
+        },
+      }),
+    },
+  };
+};
+
+export default EpisodicMemory;

package/skills/remembering-conversations/SKILL.md

@@ -0,0 +1,53 @@
+---
+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.
+---
+
+# Remembering Conversations
+
+You have episodic memory: every past OpenCode session is indexed and searchable
+via two native tools.
+
+## When to search
+
+Search proactively when:
+
+- The user references prior work: "like we did with X", "the conversation about Y",
+  "what did we decide about Z", "we tried that before"
+- You're about to propose an approach the user may have already evaluated or rejected
+- A bug or error message feels familiar ("didn't we see this before?")
+- The user asks about their own history: "when did we set up X", "which repo was Y in"
+
+Do NOT search for questions answerable from the current codebase or the current
+conversation — the index is for cross-session recall, not code search.
+
+## How
+
+1. `episodic_search` with a natural-language query describing the *topic and intent*,
+   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.
+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.
+
+## Answering
+
+- Cite what you found with its date and session title ("on 2026-07-19, in
+  'Fix login User-Agent to get past the bot wall', we concluded...").
+- Distinguish "we decided X" from "we tried X and abandoned it" — the transcript
+  usually records the verdict; report it accurately.
+- If search returns nothing relevant, say "I don't have a past conversation about
+  that" rather than confabulating.
+
+## Limits
+
+- Only OpenCode sessions are indexed (anything before the OpenCode switch is not,
+  unless it lives in `opencode.db`).
+- Conversations containing the marker `DO NOT INDEX THIS CHAT` are excluded — that
+  includes conversations *about* this tool itself that quote the marker.
+- Excerpts embed user/assistant text and tool names, not tool output.

package/src/cli.ts

@@ -0,0 +1,187 @@
+#!/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
+//     --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)
+//   stats                          Index statistics
+//   doctor                         Diagnose setup
+import { existsSync } from "node:fs";
+import { openSource, sourceDbPath, getSession, getTranscript } from "./reader";
+import { openIndex, indexDbPath, search, textSearch, stats, type SearchHit } from "./store";
+import { syncAll } from "./indexer";
+import { embed, embedQuery } from "./embed";
+import { hasExcludeMarker } from "./parser";
+
+const [, , command, ...rest] = process.argv;
+
+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)`);
+    process.exit(1);
+  }
+  return ms;
+};
+
+function fmtDate(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+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`);
+  }
+}
+
+async function main() {
+  switch (command) {
+    case "sync": {
+      const source = openSource();
+      const index = openIndex();
+      const r = await syncAll(source, index, {
+        force: hasFlag("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}`
+      );
+      break;
+    }
+
+    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 index = openIndex();
+      const opts = {
+        limit: Number(flag("limit") ?? 10),
+        after: dateMs(flag("after")),
+        before: dateMs(flag("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");
+      } else {
+        printHits(hits);
+      }
+      break;
+    }
+
+    case "read": {
+      const id = positional()[0];
+      if (!id) { console.error("usage: opencode-episodic read <session-id> [--indexed]"); process.exit(1); }
+      if (hasFlag("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 (rows.length === 0) { console.error("no indexed content for", id); process.exit(1); }
+        for (const r of rows) console.log(r.text, "\n---");
+        break;
+      }
+      const source = openSource();
+      const s = getSession(source, id);
+      if (!s) { console.error("session not found:", id); process.exit(1); }
+      const transcript = getTranscript(source, id);
+      if (hasExcludeMarker(transcript)) {
+        console.error("session is marked private (exclusion marker present); transcript withheld");
+        process.exit(1);
+      }
+      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();
+      }
+      break;
+    }
+
+    case "stats": {
+      const index = openIndex();
+      const s = stats(index);
+      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:");
+      for (const row of s.byDirectory) {
+        console.log(`  ${row.n}\t${row.directory}`);
+      }
+      break;
+    }
+
+    case "doctor": {
+      let ok = true;
+      const src = sourceDbPath();
+      if (existsSync(src)) console.log(`✓ source DB: ${src}`);
+      else { console.error(`✗ source DB missing: ${src}`); ok = false; }
+      try {
+        const source = openSource();
+        const n = source.prepare<{ n: number }, []>("SELECT COUNT(*) n FROM session").get()?.n ?? 0;
+        console.log(`✓ source readable: ${n} sessions`);
+      } catch (e) { console.error(`✗ source unreadable: ${e}`); ok = false; }
+      try {
+        const idx = openIndex();
+        console.log(`✓ index writable: ${indexDbPath()}`);
+        idx.close();
+      } catch (e) { console.error(`✗ index not writable: ${e}`); ok = false; }
+      try {
+        const v = await embed(["doctor check"]);
+        console.log(`✓ embedder: ${v[0].length} dims`);
+      } catch (e) { console.error(`✗ embedder failed: ${e}`); ok = false; }
+      process.exit(ok ? 0 : 1);
+    }
+
+    default:
+      console.log("commands: sync | search | read | stats | doctor");
+      process.exit(command ? 1 : 0);
+  }
+}
+
+await main();

package/src/embed.ts

@@ -0,0 +1,62 @@
+// 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";
+
+export const DEFAULT_MODEL = "Snowflake/snowflake-arctic-embed-m-v1.5";
+
+// BGE/Snowflake convention (identical prompt for both): prefix QUERIES only.
+// Idempotent via embedQuery().
+export const QUERY_PREFIX = "Represent this sentence for searching relevant passages: ";
+
+// Upstream measured retrieval quality peaks at 2000 chars; longer inputs
+// degrade embeddings (and this model's window is 512 tokens anyway).
+export const MAX_CHARS = 2000;
+
+let cached: Promise<FeatureExtractionPipeline> | null = null;
+
+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; });
+  }
+  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 vectors: Float32Array[] = [];
+  for (let i = 0; i < texts.length; i++) {
+    vectors.push(flat.subarray(i * dims, (i + 1) * dims));
+  }
+  return vectors;
+}
+
+/** Embed documents (conversation chunks). No prefix. */
+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]);
+}

package/src/indexer.ts

@@ -0,0 +1,93 @@
+// Incremental, idempotent indexer. Watermark = session.time_updated; a session
+// is re-embedded only when the source changed since we last indexed it.
+import type { Database } from "bun:sqlite";
+import { getTranscript, listSessions, type SourceSession } from "./reader";
+import { parseTranscript, exchangeText } from "./parser";
+import { embed } from "./embed";
+import { getIndexedSession, replaceSessionChunks } from "./store";
+
+export interface SyncResult {
+  scanned: number;
+  indexed: number;
+  skippedFresh: number;
+  excluded: number;
+  empty: number;
+  pruned: number;
+}
+
+export async function syncSession(
+  source: Database,
+  index: Database,
+  s: SourceSession,
+  force = false
+): Promise<"indexed" | "fresh" | "excluded" | "empty"> {
+  const prior = getIndexedSession(index, s.id);
+  if (!force && prior && prior.source_time_updated >= s.time_updated) return "fresh";
+
+  const { exchanges, excluded } = parseTranscript(getTranscript(source, s.id));
+  const meta = {
+    id: s.id, project_id: s.project_id, parent_id: s.parent_id,
+    title: s.title, directory: s.directory,
+    time_created: s.time_created, source_time_updated: s.time_updated,
+  };
+
+  if (excluded) {
+    replaceSessionChunks(index, meta, [], "excluded");
+    return "excluded";
+  }
+  if (exchanges.length === 0) {
+    replaceSessionChunks(index, meta, [], "empty");
+    return "empty";
+  }
+
+  const date = new Date(s.time_created).toISOString().slice(0, 10);
+  const texts = exchanges.map((e) => exchangeText(s.title, date, e));
+  const vectors = await embed(texts);
+  replaceSessionChunks(
+    index,
+    meta,
+    exchanges.map((e, i) => ({ seq: i, time_created: e.time, text: texts[i], embedding: vectors[i] }))
+  );
+  return "indexed";
+}
+
+export async function syncAll(
+  source: Database,
+  index: Database,
+  opts: { force?: boolean; onProgress?: (done: number, total: number, title: string) => void } = {}
+): Promise<SyncResult> {
+  const sessions = listSessions(source);
+  const result: SyncResult = { scanned: sessions.length, indexed: 0, skippedFresh: 0, excluded: 0, empty: 0, pruned: 0 };
+  for (let i = 0; i < sessions.length; i++) {
+    const s = sessions[i];
+    const r = await syncSession(source, index, s, opts.force);
+    if (r === "indexed") result.indexed++;
+    else if (r === "fresh") result.skippedFresh++;
+    else if (r === "excluded") result.excluded++;
+    else result.empty++;
+    opts.onProgress?.(i + 1, sessions.length, s.title);
+  }
+
+  // Prune index rows whose session no longer exists in the source DB;
+  // otherwise their stale (possibly wrong-dims) chunks linger forever.
+  result.pruned = pruneOrphans(source, index, sessions);
+
+  return result;
+}
+
+// Delete index rows (sessions + chunks) whose session has been removed from the
+// source DB. Extracted so the plugin's full-reindex path can call it without
+// re-running the whole sync. Pass already-fetched sessions to avoid a redundant
+// query in syncAll; omitted, it re-reads the source.
+export function pruneOrphans(source: Database, index: Database, knownSource?: SourceSession[]): number {
+  const sourceIds = new Set((knownSource ?? listSessions(source)).map((s) => s.id));
+  const indexedIds = index.prepare<{ id: string }, []>("SELECT id FROM sessions").all();
+  let pruned = 0;
+  for (const { id } of indexedIds) {
+    if (sourceIds.has(id)) continue;
+    index.run("DELETE FROM chunks WHERE session_id = ?", [id]);
+    index.run("DELETE FROM sessions WHERE id = ?", [id]);
+    pruned++;
+  }
+  return pruned;
+}

package/src/parser.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from "bun:test";
+import { parseTranscript, exchangeText, EXCLUDE_MARKER } from "./parser";
+import type { SourceMessage } from "./reader";
+
+const msg = (role: string, timeCreated: number, parts: SourceMessage["parts"]): SourceMessage =>
+  ({ id: `${role}-${timeCreated}`, role, timeCreated, parts });
+
+describe("parseTranscript", () => {
+  test("builds exchanges from user/assistant pairs with tool names", () => {
+    const { exchanges, excluded } = parseTranscript([
+      msg("assistant", 1, [{ type: "text", text: "dropped: no user context" }]),
+      msg("user", 2, [{ type: "text", text: "how do I fix the redirect?" }]),
+      msg("assistant", 3, [
+        { type: "reasoning", text: "thinking..." },
+        { type: "text", text: "Change the callback URL." },
+        { type: "tool", tool: "edit" },
+        { type: "tool", tool: "bash" },
+      ]),
+      msg("user", 4, [{ type: "text", text: "thanks" }]),
+      msg("assistant", 5, [{ type: "text", text: "anytime" }]),
+    ]);
+    expect(excluded).toBe(false);
+    expect(exchanges).toHaveLength(2);
+    expect(exchanges[0].user).toBe("how do I fix the redirect?");
+    expect(exchanges[0].assistant).toBe("Change the callback URL.");
+    expect(exchanges[0].tools).toEqual(["edit", "bash"]);
+    expect(exchanges[1].tools).toEqual([]);
+  });
+
+  test("user turns without text are skipped", () => {
+    const { exchanges } = parseTranscript([
+      msg("user", 1, [{ type: "tool", tool: "read" }]), // pure tool-result turn
+      msg("user", 2, [{ type: "text", text: "real question" }]),
+    ]);
+    expect(exchanges).toHaveLength(1);
+    expect(exchanges[0].user).toBe("real question");
+  });
+
+  test("exclusion marker anywhere opts out the whole transcript", () => {
+    const { exchanges, excluded } = parseTranscript([
+      msg("user", 1, [{ type: "text", text: "hi" }]),
+      msg("assistant", 2, [{ type: "text", text: `note: ${EXCLUDE_MARKER}` }]),
+    ]);
+    expect(excluded).toBe(true);
+    expect(exchanges).toHaveLength(0);
+  });
+});
+
+describe("exchangeText", () => {
+  test("includes date, title, participants, deduped tools", () => {
+    const text = exchangeText("My session", "2026-07-22", {
+      user: "q", assistant: "a", tools: ["bash", "bash", "edit"], time: 0,
+    });
+    expect(text).toStartWith("2026-07-22 — My session\nUser: q\nAssistant: a");
+    expect(text).toContain("Tools used: bash, edit");
+  });
+
+  test("caps at 4000 chars", () => {
+    const text = exchangeText("t", "2026-07-22", {
+      user: "x".repeat(10000), assistant: "", tools: [], time: 0,
+    });
+    expect(text.length).toBe(4000);
+  });
+});

package/src/parser.ts

@@ -0,0 +1,78 @@
+// Turn a raw transcript into condensed exchanges suitable for embedding.
+// Keeps user text, assistant text, and tool *names* (not tool output, which is
+// bulky and low-signal). Skips reasoning blobs and step markers.
+import type { SourceMessage, SourcePart } from "./reader";
+
+export const EXCLUDE_MARKER = "DO NOT INDEX THIS CHAT";
+
+// True if any text part in the conversation contains the opt-out marker.
+// Used both at index time (skip embedding) and at read time (refuse to return
+// the transcript), so a markered chat is never surfaced verbatim.
+export function hasExcludeMarker(messages: SourceMessage[]): boolean {
+  for (const m of messages) {
+    for (const p of m.parts) {
+      if (p.text?.includes(EXCLUDE_MARKER)) return true;
+    }
+  }
+  return false;
+}
+
+export interface Exchange {
+  user: string;
+  assistant: string;
+  tools: string[];
+  time: number;
+}
+
+const SKIP_PART_TYPES = new Set(["reasoning", "step-start", "step-finish", "file", "patch", "snapshot"]);
+
+function textOf(parts: SourcePart[]): string {
+  return parts
+    .filter((p) => p.type === "text" && p.text)
+    .map((p) => p.text!.trim())
+    .filter(Boolean)
+    .join("\n");
+}
+
+function toolNames(parts: SourcePart[]): string[] {
+  return parts
+    .filter((p) => p.type === "tool" && p.tool && !SKIP_PART_TYPES.has(p.type))
+    .map((p) => p.tool!);
+}
+
+export function parseTranscript(messages: SourceMessage[]): {
+  exchanges: Exchange[];
+  excluded: boolean;
+} {
+  // Honor the opt-out marker anywhere in the conversation.
+  if (hasExcludeMarker(messages)) return { exchanges: [], excluded: true };
+
+  const exchanges: Exchange[] = [];
+  let current: Exchange | null = null;
+
+  for (const m of messages) {
+    if (m.role === "user") {
+      const text = textOf(m.parts);
+      if (!text) continue; // e.g. pure tool-result turns
+      current = { user: text, assistant: "", tools: [], time: m.timeCreated };
+      exchanges.push(current);
+    } else if (m.role === "assistant" && current) {
+      const text = textOf(m.parts);
+      if (text) current.assistant = current.assistant ? `${current.assistant}\n${text}` : text;
+      current.tools.push(...toolNames(m.parts));
+    }
+    // assistant messages before the first user message are dropped (no context)
+  }
+
+  return { exchanges: exchanges.filter((e) => e.user || e.assistant), excluded: false };
+}
+
+// Text stored per chunk (also displayed by episodic_read). Capped at 4000 chars
+// to keep storage sane; the embedding step (embed.ts) further truncates to 2000
+// chars where retrieval quality peaks. The head of an exchange carries the
+// most signal.
+export function exchangeText(sessionTitle: string, date: string, e: Exchange): string {
+  const tools = e.tools.length ? `\nTools used: ${[...new Set(e.tools)].join(", ")}` : "";
+  const body = `User: ${e.user}\nAssistant: ${e.assistant}${tools}`;
+  return `${date} — ${sessionTitle}\n${body}`.slice(0, 4000);
+}

package/src/reader.ts

@@ -0,0 +1,120 @@
+// Read-only access to OpenCode's session store (opencode.db).
+// Schema (verified 2026-07-22): session / message / part tables, JSON blobs in `data`.
+import { Database } from "bun:sqlite";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_SOURCE_DB = join(homedir(), ".local/share/opencode/opencode.db");
+
+export interface SourceSession {
+  id: string;
+  project_id: string;
+  parent_id: string | null;
+  title: string;
+  directory: string;
+  time_created: number;
+  time_updated: number;
+}
+
+export interface SourcePart {
+  type: string;
+  text?: string;
+  tool?: string;
+}
+
+export interface SourceMessage {
+  id: string;
+  role: string;
+  timeCreated: number;
+  parts: SourcePart[];
+}
+
+export function openSource(path: string = sourceDbPath()): Database {
+  return new Database(path, { readonly: true });
+}
+
+export function sourceDbPath(): string {
+  return process.env.EPISODIC_SOURCE_DB ?? DEFAULT_SOURCE_DB;
+}
+
+export function listSessions(db: Database): SourceSession[] {
+  return db
+    .prepare<SourceSession, []>(
+      `SELECT id, project_id, parent_id, title, directory, time_created, time_updated
+       FROM session WHERE time_archived IS NULL ORDER BY time_created`
+    )
+    .all();
+}
+
+export function getSession(db: Database, sessionId: string): SourceSession | null {
+  return (
+    db
+      .prepare<SourceSession, [string]>(
+        `SELECT id, project_id, parent_id, title, directory, time_created, time_updated
+         FROM session WHERE id = ?`
+      )
+      .get(sessionId) ?? null
+  );
+}
+
+// JSON.parse returns `any`; these guards validate shape at runtime so no type
+// assertion is needed. Malformed rows degrade gracefully (unknown type/role) —
+// including a corrupt `data` blob whose JSON.parse throws, so one bad row can't
+// abort the whole transcript read.
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function safeParse(data: string): unknown {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return undefined;
+  }
+}
+
+function parsePart(data: string): SourcePart {
+  const raw = safeParse(data);
+  if (!isRecord(raw)) return { type: "unknown" };
+  return {
+    type: typeof raw.type === "string" ? raw.type : "unknown",
+    text: typeof raw.text === "string" ? raw.text : undefined,
+    tool: typeof raw.tool === "string" ? raw.tool : undefined,
+  };
+}
+
+function parseRole(data: string): string {
+  const raw = safeParse(data);
+  return isRecord(raw) && typeof raw.role === "string" ? raw.role : "unknown";
+}
+
+export function getTranscript(db: Database, sessionId: string): SourceMessage[] {
+  const messages = db
+    .prepare<{ id: string; time_created: number; data: string }, [string]>(
+      `SELECT id, time_created, data FROM message
+       WHERE session_id = ? ORDER BY time_created, id`
+    )
+    .all(sessionId);
+
+  const parts = db
+    .prepare<{ message_id: string; data: string }, [string]>(
+      `SELECT message_id, data FROM part
+       WHERE session_id = ? ORDER BY time_created, id`
+    )
+    .all(sessionId);
+
+  const partsByMsg = new Map<string, SourcePart[]>();
+  for (const p of parts) {
+    const d = parsePart(p.data);
+    let list = partsByMsg.get(p.message_id);
+    if (!list) partsByMsg.set(p.message_id, (list = []));
+    list.push(d);
+  }
+
+  return messages.map((m) => ({
+    id: m.id,
+    role: parseRole(m.data),
+    timeCreated: m.time_created,
+    parts: partsByMsg.get(m.id) ?? [],
+  }));
+}

package/src/store.test.ts

@@ -0,0 +1,72 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { openIndex, replaceSessionChunks, search, textSearch, getIndexedSession } from "./store";
+
+const dir = mkdtempSync(join(tmpdir(), "episodic-store-test-"));
+const db = openIndex(join(dir, "index.db"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const meta = {
+  id: "ses_test", project_id: "p", parent_id: null,
+  title: "Test session", directory: "/tmp",
+  time_created: 1000, source_time_updated: 1000,
+};
+
+describe("store", () => {
+  test("replaceSessionChunks + search round-trip ranks by cosine", () => {
+    replaceSessionChunks(db, meta, [
+      { seq: 0, time_created: 1000, text: "alpha chunk", embedding: new Float32Array([1, 0]) },
+      { seq: 1, time_created: 1001, text: "beta chunk", embedding: new Float32Array([0, 1]) },
+    ]);
+    const hits = search(db, new Float32Array([1, 0]));
+    expect(hits).toHaveLength(2);
+    expect(hits[0].text).toBe("alpha chunk");
+    expect(hits[0].score).toBeCloseTo(1);
+    expect(hits[1].score).toBeCloseTo(0);
+    expect(getIndexedSession(db, "ses_test")?.title).toBe("Test session");
+  });
+
+  test("search skips embeddings with mismatched dims instead of crashing", () => {
+    // 4-byte blob while the query is 2 dims (8 bytes) — must be skipped.
+    db.run("INSERT INTO chunks (session_id, seq, time_created, text, embedding) VALUES (?, ?, ?, ?, ?)",
+      ["ses_test", 99, 1002, "stale wrong-dims chunk", new Float32Array([0.5])]);
+    const hits = search(db, new Float32Array([1, 0]));
+    expect(hits.map((h) => h.text)).not.toContain("stale wrong-dims chunk");
+    expect(hits).toHaveLength(2);
+  });
+
+  test("re-embedding a session replaces its chunks", () => {
+    replaceSessionChunks(db, meta, [
+      { seq: 0, time_created: 1000, text: "only chunk now", embedding: new Float32Array([1, 0]) },
+    ]);
+    const hits = search(db, new Float32Array([1, 0]));
+    expect(hits.map((h) => h.text)).toEqual(["only chunk now"]);
+  });
+
+  test("textSearch does exact substring matching", () => {
+    expect(textSearch(db, "only chunk")).toHaveLength(1);
+    expect(textSearch(db, "no such phrase")).toHaveLength(0);
+  });
+
+  test("LIKE wildcards in user input are escaped (treated literally)", () => {
+    replaceSessionChunks(db, meta, [
+      { seq: 0, time_created: 1000, text: "progress at 50% done", embedding: new Float32Array([1, 0]) },
+      { seq: 1, time_created: 1001, text: "snake_case name here", embedding: new Float32Array([0, 1]) },
+      { seq: 2, time_created: 1002, text: "path \\tmp", embedding: new Float32Array([1, 0]) },
+    ]);
+    // % must match literally, not as a wildcard
+    expect(textSearch(db, "50%").map((h) => h.text)).toEqual(["progress at 50% done"]);
+    // _ must match literally, not as a single-char wildcard
+    expect(textSearch(db, "snake_case").map((h) => h.text)).toEqual(["snake_case name here"]);
+    // a bare % should NOT match everything (would if unescaped)
+    expect(textSearch(db, "%")).toHaveLength(1);
+    expect(textSearch(db, "_")).toHaveLength(1);
+    // a literal backslash must match only the row containing one — escapeLike
+    // escapes the escape char itself, so this would break if that were missed
+    expect(textSearch(db, "\\").map((h) => h.text)).toEqual(["path \\tmp"]);
+    // search() text filter should also escape
+    expect(search(db, new Float32Array([1, 0]), { text: "50%" })).toHaveLength(1);
+  });
+});

package/src/store.ts

@@ -0,0 +1,193 @@
+// Index database: plain SQLite (bun:sqlite). Embeddings stored as Float32
+// blobs; similarity is brute-force cosine in JS. At our scale (tens of
+// thousands of chunks) this is single-digit milliseconds per query and has
+// zero native-extension risk. (sqlite-vec was rejected in Phase 0: bun:sqlite
+// cannot load dynamic extensions. Swap in a vec0 backend here if scale ever
+// demands it.)
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_INDEX_DB = join(homedir(), ".local/share/opencode-episodic-memory/index.db");
+
+export function indexDbPath(): string {
+  return process.env.EPISODIC_INDEX_DB ?? DEFAULT_INDEX_DB;
+}
+
+export function openIndex(path: string = indexDbPath()): Database {
+  mkdirSync(dirname(path), { recursive: true });
+  const db = new Database(path);
+  db.run("PRAGMA journal_mode = WAL");
+  db.run(`CREATE TABLE IF NOT EXISTS sessions (
+    id TEXT PRIMARY KEY,
+    project_id TEXT NOT NULL,
+    parent_id TEXT,
+    title TEXT NOT NULL,
+    directory TEXT NOT NULL,
+    time_created INTEGER NOT NULL,
+    source_time_updated INTEGER NOT NULL,
+    indexed_at INTEGER NOT NULL,
+    status TEXT NOT NULL DEFAULT 'indexed'  -- 'indexed' | 'excluded' | 'empty'
+  )`);
+  db.run(`CREATE TABLE IF NOT EXISTS chunks (
+    session_id TEXT NOT NULL,
+    seq INTEGER NOT NULL,
+    time_created INTEGER NOT NULL,
+    text TEXT NOT NULL,
+    embedding BLOB NOT NULL,
+    PRIMARY KEY (session_id, seq)
+  )`);
+  db.run("CREATE INDEX IF NOT EXISTS chunks_time_idx ON chunks(time_created)");
+  return db;
+}
+
+export interface IndexedSession {
+  id: string;
+  project_id: string;
+  parent_id: string | null;
+  title: string;
+  directory: string;
+  time_created: number;
+  source_time_updated: number;
+  indexed_at: number;
+  status: string;
+}
+
+export function getIndexedSession(db: Database, id: string): IndexedSession | null {
+  return db.prepare<IndexedSession, [string]>("SELECT * FROM sessions WHERE id = ?").get(id) ?? null;
+}
+
+export function replaceSessionChunks(
+  db: Database,
+  s: { id: string; project_id: string; parent_id: string | null; title: string; directory: string; time_created: number; source_time_updated: number },
+  chunks: { seq: number; time_created: number; text: string; embedding: Float32Array }[],
+  status: string = "indexed"
+): void {
+  db.transaction(() => {
+    db.run(
+      `INSERT INTO sessions (id, project_id, parent_id, title, directory, time_created, source_time_updated, indexed_at, status)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(id) DO UPDATE SET
+         title=excluded.title, directory=excluded.directory,
+         source_time_updated=excluded.source_time_updated,
+         indexed_at=excluded.indexed_at, status=excluded.status`,
+      [s.id, s.project_id, s.parent_id, s.title, s.directory, s.time_created, s.source_time_updated, Date.now(), status]
+    );
+    db.run("DELETE FROM chunks WHERE session_id = ?", [s.id]);
+    const ins = db.prepare(
+      "INSERT INTO chunks (session_id, seq, time_created, text, embedding) VALUES (?, ?, ?, ?, ?)"
+    );
+    for (const c of chunks) ins.run(s.id, c.seq, c.time_created, c.text, c.embedding);
+  })();
+}
+
+export interface SearchHit {
+  session_id: string;
+  seq: number;
+  time_created: number;
+  text: string;
+  score: number;
+  title: string;
+  directory: string;
+}
+
+// Escape LIKE wildcards so user input can't broaden a substring filter.
+// Backslash escapes itself; used with the `ESCAPE '\'` clause below.
+function escapeLike(s: string): string {
+  return s.replace(/[\\%_]/g, (c) => "\\" + c);
+}
+
+export interface SearchOptions {
+  limit?: number;
+  after?: number; // ms epoch
+  before?: number; // ms epoch
+  text?: string; // exact substring filter (ANDed with vector ranking)
+  minScore?: number;
+}
+
+export function search(db: Database, queryVec: Float32Array, opts: SearchOptions = {}): SearchHit[] {
+  const limit = opts.limit ?? 10;
+  const clauses: string[] = [];
+  const params: (string | number)[] = [];
+  if (opts.after) { clauses.push("c.time_created >= ?"); params.push(opts.after); }
+  if (opts.before) { clauses.push("c.time_created < ?"); params.push(opts.before); }
+  if (opts.text) { clauses.push("c.text LIKE ? ESCAPE '\\'"); params.push(`%${escapeLike(opts.text)}%`); }
+  const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+
+  const rows = db
+    .prepare<{
+      session_id: string; seq: number; time_created: number; text: string;
+      embedding: Uint8Array; title: string; directory: string;
+    }, (string | number)[]>(
+      `SELECT c.session_id, c.seq, c.time_created, c.text, c.embedding, s.title, s.directory
+       FROM chunks c JOIN sessions s ON s.id = c.session_id ${where}`
+    )
+    .all(...params);
+
+  const dims = queryVec.length;
+  const minScore = opts.minScore ?? 0;
+  return rows
+    // Skip vectors from a different embedding model (e.g. mid-migration or
+    // orphaned rows) — a dims mismatch would corrupt the dot product or throw.
+    .filter((r) => r.embedding.byteLength === dims * 4)
+    .map((r) => {
+      const v = new Float32Array(r.embedding.buffer, r.embedding.byteOffset, dims);
+      let dot = 0;
+      for (let i = 0; i < dims; i++) dot += queryVec[i] * v[i];
+      return {
+        session_id: r.session_id, seq: r.seq, time_created: r.time_created,
+        text: r.text, score: dot, title: r.title, directory: r.directory,
+      };
+    })
+    .filter((h) => h.score >= minScore)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+}
+
+export function textSearch(db: Database, query: string, opts: SearchOptions = {}): SearchHit[] {
+  const limit = opts.limit ?? 10;
+  const clauses = ["c.text LIKE ? ESCAPE '\\'"];
+  const params: (string | number)[] = [`%${escapeLike(query)}%`];
+  if (opts.after) { clauses.push("c.time_created >= ?"); params.push(opts.after); }
+  if (opts.before) { clauses.push("c.time_created < ?"); params.push(opts.before); }
+  const rows = db
+    .prepare<Omit<SearchHit, "score">, (string | number)[]>(
+      `SELECT c.session_id, c.seq, c.time_created, c.text, s.title, s.directory
+       FROM chunks c JOIN sessions s ON s.id = c.session_id
+       WHERE ${clauses.join(" AND ")} ORDER BY c.time_created DESC LIMIT ?`
+    )
+    .all(...params, limit);
+  return rows.map((r) => ({ ...r, score: 1 }));
+}
+
+export interface IndexStats {
+  sessions: number;
+  excluded: number;
+  chunks: number;
+  oldest: number | null;
+  newest: number | null;
+  byDirectory: { directory: string; n: number }[];
+}
+
+export function stats(db: Database): IndexStats {
+  // COUNT/MIN/MAX always return exactly one row; guard anyway so the row type
+  // stays non-null without a cast.
+  function one<T>(sql: string): T {
+    const row = db.prepare<T, []>(sql).get();
+    if (!row) throw new Error(`stats query returned no row: ${sql}`);
+    return row;
+  }
+  return {
+    sessions: one<{ n: number }>("SELECT COUNT(*) n FROM sessions").n,
+    excluded: one<{ n: number }>("SELECT COUNT(*) n FROM sessions WHERE status != 'indexed'").n,
+    chunks: one<{ n: number }>("SELECT COUNT(*) n FROM chunks").n,
+    oldest: one<{ t: number | null }>("SELECT MIN(time_created) t FROM chunks").t,
+    newest: one<{ t: number | null }>("SELECT MAX(time_created) t FROM chunks").t,
+    byDirectory: db
+      .prepare<{ directory: string; n: number }, []>(
+        "SELECT directory, COUNT(*) n FROM sessions WHERE status = 'indexed' GROUP BY directory ORDER BY n DESC LIMIT 10"
+      )
+      .all(),
+  };
+}