opencode-episodic-memory 0.1.1 → 0.1.3

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,56 +10,89 @@ 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
+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"]
 }
 ```
 
-Copy the skill so the agent knows when to search:
+The first embedding run downloads the model (~100 MB, cached afterwards).
+
+Install the skill so the agent knows when to search, via the
+[`skills` CLI](https://github.com/vercel-labs/skills):
 
 ```bash
-cp -r skills/remembering-conversations ~/.config/opencode/skills/
+npx skills add robertn702/opencode-episodic-memory -g
+```
+
+(`-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 ~/.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
@@ -65,7 +100,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
@@ -97,6 +132,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.1",
-  "description": "Semantic search over past OpenCode conversations. Port of obra/episodic-memory to OpenCode primitives.",
+  "version": "0.1.3",
+  "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",
@@ -17,6 +17,7 @@
     "embeddings",
     "transformersjs"
   ],
+  "main": "./plugin/episodic-memory.ts",
   "exports": {
     ".": "./plugin/episodic-memory.ts",
     "./cli": "./src/cli.ts"
@@ -24,7 +25,8 @@
   "files": [
     "plugin",
     "src",
-    "skills"
+    "skills",
+    "!src/*.test.ts"
   ],
   "bin": {
     "opencode-episodic": "src/cli.ts"
@@ -33,7 +35,8 @@
     "spike": "bun run spikes/spike.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run typecheck && bun test"
+    "verify:entrypoint": "bun run spikes/verify-opencode-entrypoint.ts",
+    "prepublishOnly": "bun run typecheck && bun test && bun run verify:entrypoint"
   },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",

package/plugin/episodic-memory.ts

@@ -2,27 +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 } 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";
-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);
+import { parseDateArg, formatHits, renderTranscript } from "../src/format";
 
 export const EpisodicMemory: Plugin = async ({ client }) => {
   const log = (level: "info" | "warn" | "error", message: string) =>
@@ -76,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)"),
@@ -96,18 +80,15 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
           const hits =
             args.mode === "text"
               ? textSearch(index, args.query, opts)
-              : search(index, (await embedQuery(args.query))[0], 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) {
-            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.";
+            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.";
           }
-          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");
+          // Hybrid hits carry RRF scores (~0.03), not cosine — label them "rrf".
+          return formatHits(hits, 400, args.mode === "hybrid" ? "rrf" : "score");
         },
       }),
 
@@ -124,25 +105,18 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
               const source = openSource();
               const s = getSession(source, args.session_id);
               if (s) {
-                const transcript = getTranscript(source, args.session_id);
-                if (hasExcludeMarker(transcript)) {
+                // 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 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,67 +11,66 @@
 //   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 { 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 { hasExcludeMarker } from "./parser";
+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() {
@@ -79,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)}                    `),
       });
@@ -91,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")
@@ -126,21 +132,14 @@ async function main() {
       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)) {
+      // 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);
       }
-      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;
     }
 

package/src/format.ts

@@ -0,0 +1,70 @@
+// Shared presentation layer for the CLI and the plugin. Both stay thin: date
+// parsing, date formatting, transcript→markdown, and search-hit formatting live
+// here so the two front-ends can't drift apart.
+import type { SourceMessage } from "./reader";
+import type { SearchHit } from "./store";
+
+// 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.
+export 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).
+export function 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 };
+}
+
+export function fmtDate(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+// Render a full transcript as markdown:
+//   # title
+//   date — directory — id
+//
+//   ## role
+//   text
+//   *(tools: …)*
+//
+// A blank line follows every rendered message. Callers decide truncation (the
+// plugin caps at 50k chars; the CLI prints in full).
+export function renderTranscript(
+  meta: { title: string; time_created: number; directory: string; id: string },
+  messages: SourceMessage[]
+): string {
+  const lines: string[] = [
+    `# ${meta.title}`,
+    `${fmtDate(meta.time_created)} — ${meta.directory} — ${meta.id}`,
+    "",
+  ];
+  for (const m of messages) {
+    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(", ")})*`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// One search hit as a markdown block. snippetLength defaults to 400 (plugin
+// tool output); the CLI passes 220 to keep terminal output brief. scoreLabel
+// names the score field: "score" for vector (cosine ~0.4–0.7) and BM25, "rrf"
+// for hybrid (fused reciprocal-rank scores ~0.03, a different scale — see
+// AGENTS.md) so the number isn't misread against the cosine thresholds.
+export function formatHit(h: SearchHit, snippetLength = 400, scoreLabel = "score"): string {
+  const snippet = h.text.replace(/\s+/g, " ").slice(0, snippetLength);
+  return `## ${fmtDate(h.time_created)} — ${h.title}\nsession: ${h.session_id}  ${scoreLabel}: ${h.score.toFixed(3)}\n${h.directory}\n> ${snippet}`;
+}
+
+export function formatHits(hits: SearchHit[], snippetLength = 400, scoreLabel = "score"): string {
+  return hits.map((h) => formatHit(h, snippetLength, scoreLabel)).join("\n\n");
+}

package/src/indexer.ts

@@ -1,7 +1,7 @@
 // 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 { getTranscriptChecked, listSessions, type SourceSession } from "./reader";
 import { parseTranscript, exchangeText } from "./parser";
 import { embed } from "./embed";
 import { getIndexedSession, replaceSessionChunks } from "./store";
@@ -24,7 +24,13 @@ export async function syncSession(
   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));
+  // Authoritative opt-out gate lives inside getTranscriptChecked (raw-blob
+  // scan before any read); parseTranscript's own parsed-text check is a
+  // harmless redundant fast path for the non-excluded branch.
+  const checked = getTranscriptChecked(source, s.id);
+  const { exchanges, excluded } = checked.excluded
+    ? { exchanges: [], excluded: true }
+    : parseTranscript(checked.messages);
   const meta = {
     id: s.id, project_id: s.project_id, parent_id: s.parent_id,
     title: s.title, directory: s.directory,