opencode-episodic-memory 0.2.0 → 0.3.1

package/README.md

@@ -19,8 +19,8 @@ of the OpenCode memory-plugin landscape? See
 1. **Read** — sessions/messages/parts from OpenCode's `~/.local/share/opencode/opencode.db` (read-only)
 2. **Parse** — condensed exchanges (user text, assistant text, tool names; no reasoning blobs or tool output)
 3. **Embed** — local, offline embeddings via Transformers.js 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
+4. **Index** — plain SQLite at `~/.local/share/opencode-episodic-memory/index.db` by default; optional libSQL/Turso remote storage can combine source-scoped indexes across devices
+5. **Recall** — native plugin tools `episodic_search` / `episodic_read_window` / `episodic_read_session`, plus a `remembering-conversations` skill that teaches the agent when to search
 6. **Stay fresh** — the plugin re-indexes each session on the `session.idle` event
 
 Design note: `bun:sqlite` cannot load dynamic extensions, so sqlite-vec is not
@@ -35,7 +35,7 @@ tends to match injected boilerplate on this corpus.
 ## Install
 
 ```bash
-opencode plugin opencode-episodic-memory@0.1.3 -g
+opencode plugin opencode-episodic-memory@0.3.1 -g
 ```
 
 This adds the plugin to your OpenCode config (`-g` = global config; omit it
@@ -48,7 +48,7 @@ Or edit `~/.config/opencode/opencode.json` manually:
 
 ```jsonc
 {
-  "plugin": ["opencode-episodic-memory@0.1.3"]
+  "plugin": ["opencode-episodic-memory@0.3.1"]
 }
 ```
 
@@ -57,7 +57,7 @@ Default sidecar-mode semantic indexing and vector/hybrid search require a system
 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
+OpenCode/Bun versions. `episodic_read_window`, `episodic_read_session`, and lexical text search also remain
 available without Node.
 
 Install the skill so the agent knows when to search, via the
@@ -75,13 +75,13 @@ OpenCode has downloaded the plugin (i.e. after first launch), copy it out of
 the package cache (the path contains your pinned version):
 
 ```bash
-cp -r ~/.cache/opencode/packages/opencode-episodic-memory@0.1.3/node_modules/opencode-episodic-memory/skills/remembering-conversations ~/.config/opencode/skills/
+cp -r ~/.cache/opencode/packages/opencode-episodic-memory@0.3.1/node_modules/opencode-episodic-memory/skills/remembering-conversations ~/.config/opencode/skills/
 ```
 
 Then backfill existing history and restart OpenCode:
 
 ```bash
-bunx opencode-episodic-memory@0.1.3 sync
+bunx opencode-episodic-memory@0.3.1 sync
 ```
 
 ## CLI
@@ -90,15 +90,16 @@ The package ships an `opencode-episodic` binary (requires `bun` on PATH).
 Invoke it through the package spec — pin it to match your plugin version:
 
 ```bash
-bunx opencode-episodic-memory@0.1.3 sync [--force]          # index new/changed sessions
-bunx opencode-episodic-memory@0.1.3 search "query"          # semantic (vector) search
-bunx opencode-episodic-memory@0.1.3 search q --text "terms"  # lexical BM25 (all terms AND-matched, token-based)
-bunx opencode-episodic-memory@0.1.3 search q --hybrid       # fuse vector + BM25 (RRF; opt-in)
-bunx opencode-episodic-memory@0.1.3 search q --after 2026-07-01 --limit 5
-bunx opencode-episodic-memory@0.1.3 read <session-id>       # full transcript (live store)
-bunx opencode-episodic-memory@0.1.3 read <id> --indexed     # indexed excerpts (survives deletion)
-bunx opencode-episodic-memory@0.1.3 stats                   # index statistics
-bunx opencode-episodic-memory@0.1.3 doctor                  # diagnose setup
+bunx opencode-episodic-memory@0.3.1 sync [--force]          # index new/changed sessions
+bunx opencode-episodic-memory@0.3.1 search "query"          # semantic (vector) search
+bunx opencode-episodic-memory@0.3.1 search q --text "terms"  # lexical BM25 (all terms AND-matched, token-based)
+bunx opencode-episodic-memory@0.3.1 search q --hybrid       # fuse vector + BM25 (RRF; opt-in)
+bunx opencode-episodic-memory@0.3.1 search q --after 2026-07-01 --limit 5
+bunx opencode-episodic-memory@0.3.1 read <session-id>       # full transcript (live store)
+bunx opencode-episodic-memory@0.3.1 read <id> --indexed     # local indexed excerpts
+bun run src/cli.ts read <id> --indexed --source laptop     # remote indexed excerpts (development/source checkout)
+bunx opencode-episodic-memory@0.3.1 stats                   # index statistics
+bunx opencode-episodic-memory@0.3.1 doctor                  # diagnose setup
 ```
 
 `--after`/`--before` take `YYYY-MM-DD` (midnight UTC). `--after D` is inclusive
@@ -106,8 +107,9 @@ of day D; `--before D` is exclusive of day D (i.e. up to the start of that day).
 
 ## Agent tools
 
-- **`episodic_search`** — `query` (+ optional `text`, `mode: vector|text|hybrid`, `after`, `before`, `limit`). `vector` (default) is semantic; `text` is lexical BM25; `hybrid` fuses both via RRF (opt-in — can surface lexical noise). Returns dated excerpts with session IDs and scores.
-- **`episodic_read`** — `session_id` (+ optional `indexed`). Full transcript from the live store, falling back to indexed excerpts.
+- **`episodic_search`** — `query` (+ optional `text`, `mode: vector|text|hybrid`, `after`, `before`, `limit`). `vector` (default) is semantic; `text` is lexical BM25; `hybrid` fuses both via RRF (opt-in — can surface lexical noise). Returns dated excerpts with session IDs, scores, and message anchors. Remote indexes are vector-only: the plugin exposes only `vector` there, and explicit remote `text`/`hybrid` requests fail before embedding with actionable guidance rather than silently falling back. Local text/hybrid behavior is unchanged.
+- **`episodic_read_window`** — `session_id`, `anchor_message_id` (+ optional `source_id`, required for remote indexes; `before`, `after`, each 0-20, default 3). Current-source hits use privacy-gated live messages. Foreign-source hits use labeled indexed exchanges around the anchor, with before/after counting chunks instead of messages and each chunk rendered at up to 600 UTF-8 bytes. Missing or stale anchors cannot expand; use `episodic_read_session` with the same session/source and `indexed: true` for available indexed excerpts.
+- **`episodic_read_session`** — `session_id` (+ optional `source_id`, required for remote indexes; `indexed`). Reads the full live transcript, or indexed excerpts when requested, deleted, or on another source. Current-source indexed reads still check the live privacy marker and withhold cached content if validation fails. Prefer `episodic_search` -> `episodic_read_window` -> `episodic_read_session`, stopping once enough context has been recovered.
 
 ## Excluding conversations
 
@@ -128,6 +130,9 @@ instruction-tag match — the intent is the same, but our matching is literal.
 |---|---|---|
 | `EPISODIC_SOURCE_DB` | `~/.local/share/opencode/opencode.db` | OpenCode session store |
 | `EPISODIC_INDEX_DB` | `~/.local/share/opencode-episodic-memory/index.db` | Index location |
+| `EPISODIC_INDEX_URL` | unset | Opt-in libSQL/Turso index URL; activates remote vector-only mode |
+| `EPISODIC_INDEX_AUTH_TOKEN` | unset | Required for remote network URLs; passed to `@libsql/client` |
+| `EPISODIC_SOURCE_ID` | unset | Required in remote mode; stable device/source identity |
 | `EPISODIC_EMBED_MODEL` | `Snowflake/snowflake-arctic-embed-m-v1.5` | Transformers.js embedding model |
 | `EPISODIC_EMBED_MODE` | `sidecar` | `sidecar` runs embeddings in Node; `inline` is an explicit escape hatch |
 | `EPISODIC_NODE_BINARY` | `node` | Node 20+ executable used by sidecar mode |
@@ -142,6 +147,48 @@ during native-addon teardown. It is never selected automatically if sidecar
 startup fails. Run `bun run src/cli.ts doctor` to diagnose the selected mode,
 Node version, and a real embedding.
 
+### Optional shared remote index
+
+Set all three variables on each device (use a distinct, stable source ID per
+device):
+
+```bash
+export EPISODIC_INDEX_URL='libsql://your-index.turso.io'
+export EPISODIC_INDEX_AUTH_TOKEN='...'
+export EPISODIC_SOURCE_ID='laptop'
+```
+
+This is an explicit privacy boundary: sync still reads OpenCode locally and
+generates embeddings locally, but it **uploads condensed chunk text, session
+metadata, anchors, and embedding vectors** to the configured database. Do not
+configure it unless that database is appropriate for this conversation data.
+Sessions containing `DO NOT INDEX THIS CHAT` upload neither content nor a
+metadata tombstone; an existing row for that source/session is removed.
+Absolute local `file:` libSQL URLs are supported without a token for hermetic
+testing; network
+URLs must use `https:`, `wss:`, or TLS-enabled `libsql:` and require a token
+supplied only through `EPISODIC_INDEX_AUTH_TOKEN` (not embedded in the URL).
+For `libsql:`, omit `tls` or use exactly one lowercase `tls=1` parameter.
+The remote schema is freshly created or validates/adopts a compatible existing
+schema and does not use FTS, so remote mode supports vector search only. `--text`,
+`--hybrid`, and plugin `text`/`hybrid` modes fail clearly in remote mode.
+Remote cosine search reads embedding candidates in bounded pages and hydrates
+only the final result set.
+
+Remote search includes the source ID in each hit. `source_id` is required for
+remote indexed reads. Another device's hit can be read through the bounded
+indexed foreign-source path in `episodic_read_window` when its anchor is
+present and current; otherwise use `episodic_read_session` with
+`indexed: true`. These are condensed indexed excerpts, not a live transcript;
+indexes remain stale until the source syncs and carry no live privacy or
+freshness guarantees across devices.
+
+Network failures are surfaced by the CLI and doctor; plugin background reindex
+logs failures and never silently falls back to a local index (which would split
+history). To return to local-only mode, unset `EPISODIC_INDEX_URL`,
+`EPISODIC_INDEX_AUTH_TOKEN`, and `EPISODIC_SOURCE_ID`; the existing local index
+is selected unchanged. Re-run `sync` if the local index needs rebuilding.
+
 ## Not yet implemented (deliberate)
 
 - LLM-generated per-session summaries embedded instead of raw exchange text

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-episodic-memory",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Semantic search over past OpenCode conversations — local embeddings (Transformers.js), SQLite index, native plugin tools. Inspired by obra/episodic-memory, rebuilt natively for OpenCode.",
   "type": "module",
   "license": "MIT",
@@ -39,6 +39,7 @@
     "prepublishOnly": "bun run typecheck && bun test && bun run verify:entrypoint"
   },
   "dependencies": {
+    "@libsql/client": "^0.18.0",
     "@huggingface/transformers": "^4.2.0",
     "@opencode-ai/plugin": "^1.18.4",
     "zod": "^4.4.3"

package/plugin/episodic-memory.ts

@@ -1,47 +1,59 @@
 // OpenCode plugin: episodic memory over past conversations.
-// - Native tools: episodic_search, episodic_read
+// - Native tools: episodic_search, episodic_read_window, episodic_read_session
 // - Incremental reindex on session.idle (fire-and-forget, debounced)
 import { type Plugin, tool } from "@opencode-ai/plugin";
-import { openSource, getSession, getTranscriptChecked } from "../src/reader";
-import { openIndex, search, textSearch, isIndexEmpty } from "../src/store";
+import { openSource, getSession, getTranscriptChecked, getTranscriptContext, transcriptHasMarker } from "../src/reader";
+import { canLiveRead, openConfiguredIndex, remoteIndexConfig, type IndexStore } from "../src/store";
 import { syncSession, syncAll, pruneOrphans } from "../src/indexer";
 import { embedQuery } from "../src/embed";
-import { parseDateArg, formatHits, renderTranscript } from "../src/format";
+import { parseDateArg, formatHits, renderTranscript, renderTranscriptContext, renderIndexedContext } from "../src/format";
 
 export const EpisodicMemory: Plugin = async ({ client }) => {
+  const remoteSearch = Boolean(process.env.EPISODIC_INDEX_URL);
   const log = (level: "info" | "warn" | "error", message: string) =>
     client.app
       .log({ body: { service: "episodic-memory", level, message } })
       .catch(() => {});
+  let configuredIndex: Promise<IndexStore> | undefined;
+  const getIndex = () => configuredIndex ??= openConfiguredIndex().catch((error) => {
+    configuredIndex = undefined;
+    throw error;
+  });
 
   // Debounce concurrent reindex runs for the same session.
   const inflight = new Map<string, Promise<void>>();
+  const pending = new Set<string>();
   function reindex(sessionId?: string) {
     const key = sessionId ?? "__all__";
-    if (inflight.has(key)) return inflight.get(key)!;
+    if (inflight.has(key)) {
+      pending.add(key);
+      return inflight.get(key)!;
+    }
     const p = (async () => {
-      try {
-        const source = openSource();
-        const index = openIndex();
-        if (sessionId) {
-          const s = getSession(source, sessionId);
-          if (s) await syncSession(source, index, s);
-          // Cheap (two small SELECTs + rare DELETEs), so prune on every idle:
-          // the syncAll path below effectively never fires (session.idle always
-          // carries a sessionID), and without this, deleted conversations would
-          // linger in the index — searchable and readable — for plugin-only users.
-          pruneOrphans(source, index);
-        } else {
-          await syncAll(source, index); // syncAll prunes source-deleted orphans
+      do {
+        pending.delete(key);
+        try {
+          const source = openSource();
+          const index = await getIndex();
+          if (sessionId) {
+            const s = getSession(source, sessionId);
+            if (s) await syncSession(source, index, s);
+            // Cheap (two small SELECTs + rare DELETEs), so prune on every idle:
+            // the syncAll path below effectively never fires (session.idle always
+            // carries a sessionID), and without this, deleted conversations would
+            // linger in the index — searchable and readable — for plugin-only users.
+            await pruneOrphans(source, index);
+          } else {
+            await syncAll(source, index); // syncAll prunes source-deleted orphans
+          }
+          await log("info", `reindexed ${key}`);
+        } catch (e) {
+          await log("warn", `reindex failed for ${key}: ${e}`);
         }
-        await log("info", `reindexed ${key}`);
-      } catch (e) {
-        await log("warn", `reindex failed for ${key}: ${e}`);
-      } finally {
-        inflight.delete(key);
-      }
+      } while (pending.has(key));
     })();
     inflight.set(key, p);
+    p.finally(() => inflight.delete(key));
     return p;
   }
 
@@ -56,17 +68,23 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
     tool: {
       episodic_search: tool({
         description:
-          "Semantic search over your PAST OpenCode conversations. Use when the user references prior work, past decisions, or previous sessions (e.g. 'how did we handle X', 'the conversation about Y', 'what did we decide about Z'). Returns dated excerpts with session IDs; follow up with episodic_read for the full conversation.",
+          "Semantic search over your PAST OpenCode conversations. Use when the user references prior work, past decisions, or previous sessions (e.g. 'how did we handle X', 'the conversation about Y', 'what did we decide about Z'). Returns dated excerpts, session IDs, and anchors. Prefer episodic_search -> episodic_read_window for bounded context -> episodic_read_session only when more context is needed." +
+          (remoteSearch ? " Remote index: vector search only, without text filtering. Preserve source_id when reading hits; foreign-source windows contain indexed excerpts, not live messages." : ""),
         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", "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"),
+          ...(!remoteSearch ? { text: tool.schema.string().optional().describe("Exact substring to require in results (ANDed with semantic ranking)") } : {}),
+          mode: tool.schema.enum(remoteSearch ? ["vector"] : ["vector", "text", "hybrid"]).optional().describe(remoteSearch
+            ? "'vector' (default): the only supported remote mode. Scores are cosine (~0.4-0.7)."
+            : "'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)"),
         },
         async execute(args) {
-          const index = openIndex();
+          if (remoteIndexConfig() && (args.mode === "text" || args.mode === "hybrid" || args.text !== undefined)) {
+            return 'Remote indexes support vector search only, without text filtering. Retry with mode: "vector" and omit text; include relevant terms in query. Use a local index for exact text filtering, BM25, or hybrid search. No search was run.';
+          }
+          const index = await getIndex();
           const after = parseDateArg(args.after);
           if (!after.ok) return after.error;
           const before = parseDateArg(args.before);
@@ -75,13 +93,13 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
             limit: Math.min(Math.max(args.limit ?? 10, 1), 50),
             after: after.ms,
             before: before.ms,
-            text: args.text,
+            text: typeof args.text === "string" ? args.text : undefined,
           };
-          const noHits = () => isIndexEmpty(index)
+          const noHits = async () => await index.isEmpty()
             ? "No matching past conversations found. The index is empty — run `bun run src/cli.ts sync` to index conversations."
             : "No matching past conversations found.";
           if (args.mode === "text") {
-            const hits = textSearch(index, args.query, opts);
+            const hits = await index.textSearch(args.query, opts);
             if (hits.length === 0) return noHits();
             return formatHits(hits, 400, "score");
           }
@@ -90,49 +108,96 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
             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.';
+            return index.remote
+              ? "Semantic search unavailable: the embedding backend failed. Remote indexes support vector search only; run `bun run src/cli.ts doctor` for details."
+              : 'Semantic search unavailable: the embedding backend failed. Use mode: "text" for embedding-free lexical search, or run `bun run src/cli.ts doctor` for details.';
           }
           const hits = args.mode === "hybrid"
-            ? search(index, vector, { ...opts, queryText: args.query, hybrid: true })
-            : search(index, vector, opts);
+            ? await index.search(vector, { ...opts, queryText: args.query, hybrid: true })
+            : await index.search(vector, opts);
           if (hits.length === 0) return noHits();
           // Hybrid hits carry RRF scores (~0.03), not cosine — label them "rrf".
           return formatHits(hits, 400, args.mode === "hybrid" ? "rrf" : "score");
         },
       }),
 
-      episodic_read: tool({
+      episodic_read_window: tool({
+        description:
+          "Read bounded context around an anchor from episodic_search. Preserve session_id, anchor_message_id, and source_id. Current-source hits use privacy-gated live messages; foreign-source hits use labeled indexed condensed exchanges that may be stale. Missing or stale anchors cannot provide a window; use episodic_read_session with source_id and indexed: true for indexed excerpts instead.",
+        args: {
+          session_id: tool.schema.string().describe("Session ID from episodic_search, e.g. ses_..."),
+          source_id: tool.schema.string().optional().describe("Source ID shown by remote episodic_search results; required for remote indexes"),
+          anchor_message_id: tool.schema.string().describe("Anchor message ID from episodic_search"),
+          before: tool.schema.number().optional().describe("Messages before the anchor, or indexed chunks for a foreign source, 0-20 (default 3)"),
+          after: tool.schema.number().optional().describe("Messages after the anchor, or indexed chunks for a foreign source, 0-20 (default 3)"),
+        },
+        async execute(args) {
+          const remote = remoteIndexConfig();
+          if (remote && !args.source_id) {
+            throw new Error("source_id is required for episodic_read_window with a remote index. Use the source from the search hit.");
+          }
+          if (args.source_id && !canLiveRead(remote, args.source_id)) {
+            const index = await getIndex();
+            const rows = await index.readIndexedWindow(args.session_id, args.anchor_message_id, args.before, args.after, args.source_id);
+            if (rows.length === 0) {
+              throw new Error('No indexed window found for this source, session, and anchor. The anchor may be stale; use episodic_read_session with the same session_id, source_id, and indexed: true for available indexed excerpts.');
+            }
+            return renderIndexedContext(args.session_id, args.source_id, args.anchor_message_id, rows);
+          }
+          const source = openSource();
+          const context = getTranscriptContext(source, args.session_id, args.anchor_message_id, args.before, args.after);
+          if (!context.ok) {
+            if (context.reason === "unknown_session") throw new Error(`No live conversation found for session ${args.session_id}.`);
+            if (context.reason === "excluded") throw new Error("Session is marked private (exclusion marker present); context withheld.");
+            if (context.reason === "invalid_anchor") throw new Error(`Anchor message ${args.anchor_message_id} is stale or invalid for session ${args.session_id}.`);
+            throw new Error("before and after must be non-negative integers no greater than 20.");
+          }
+          return renderTranscriptContext(context.session, context);
+        },
+      }),
+
+      episodic_read_session: tool({
         description:
-          "Read the full transcript of a past OpenCode conversation, given a session ID (from episodic_search results). Reconstructs from the live session store; falls back to indexed excerpts if the session was deleted.",
+          "Read the full transcript of a past OpenCode session, given a session ID (from episodic_search results). Use after episodic_read_window when the bounded window is insufficient. Reconstructs from the live session store; falls back to indexed excerpts if the session was deleted.",
         args: {
           session_id: tool.schema.string().describe("Session ID, e.g. ses_..."),
+          source_id: tool.schema.string().optional().describe("Source ID shown by remote episodic_search results"),
           indexed: tool.schema.boolean().optional().describe("Force reading from the index instead of the live session store"),
         },
         async execute(args) {
-          if (!args.indexed) {
+          const remote = remoteIndexConfig();
+          if (remote && args.source_id === undefined) {
+            throw new Error("source_id is required for episodic_read_session with a remote index.");
+          }
+          const foreign = !canLiveRead(remote, args.source_id);
+          if (!foreign) {
             try {
               const source = openSource();
-              const s = getSession(source, args.session_id);
-              if (s) {
-                // Privacy gate lives inside getTranscriptChecked (authoritative
-                // raw-blob scan before any read).
-                const checked = getTranscriptChecked(source, args.session_id);
-                if (checked.excluded) {
+              try {
+                // Explicit indexed reads must also respect a marker added since sync.
+                if (transcriptHasMarker(source, args.session_id)) {
                   return "Session is marked private (exclusion marker present); transcript withheld.";
                 }
-                return renderTranscript(s, checked.messages).slice(0, 50000);
+                if (!args.indexed) {
+                  const s = getSession(source, args.session_id);
+                  if (s) {
+                    const checked = getTranscriptChecked(source, args.session_id);
+                    if (checked.excluded) {
+                      return "Session is marked private (exclusion marker present); transcript withheld.";
+                    }
+                    return renderTranscript(s, checked.messages).slice(0, 50000);
+                  }
+                }
+              } finally {
+                source.close();
               }
             } 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
+              await log("warn", `episodic_read_session live-store read failed for ${args.session_id}: ${e}`);
+              return "Live-source validation failed; indexed content withheld because current privacy status could not be verified.";
             }
           }
-          const index = openIndex();
-          const rows = index
-            .prepare<{ text: string }, [string]>("SELECT text FROM chunks WHERE session_id = ? ORDER BY seq")
-            .all(args.session_id);
+          const index = await getIndex();
+          const rows = await index.readIndexed(args.session_id, args.source_id);
           if (rows.length === 0) return `No conversation found for session ${args.session_id}.`;
           return `(indexed excerpts — live session unavailable)\n\n${rows.map((r) => r.text).join("\n\n---\n\n")}`.slice(0, 50000);
         },

package/skills/remembering-conversations/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: remembering-conversations
-description: Recall past OpenCode conversations when the user references previous work, past decisions, or earlier sessions — "how did we handle X", "the conversation about Y", "what did we decide", "we tried this before", "last week we...". Use the episodic_search and episodic_read tools to search semantically and read full transcripts.
+description: Recall past OpenCode conversations when the user references previous work, past decisions, or earlier sessions — "how did we handle X", "the conversation about Y", "what did we decide", "we tried this before", "last week we...". Use episodic_search, then episodic_read_window for a bounded window, and episodic_read_session only when the full session is needed.
 ---
 
 # Remembering Conversations
 
 You have episodic memory: every past OpenCode session is indexed and searchable
-via two native tools.
+via three native tools.
 
 ## When to search
 
@@ -25,16 +25,27 @@ conversation — the index is for cross-session recall, not code search.
 
 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 lexical BM25 search: every query word must appear (token-based
+   - Narrow with `after`/`before` dates. Local indexes also support an exact `text`
+     substring (an error string, a flag name, a file path).
+   - On local indexes, use `mode: "text"` for lexical BM25 search: every query word must appear (token-based
      AND, BM25-ranked) — not phrase/adjacency or substring matching.
-2. Skim the returned excerpts (date, session title, score). Similarity scores are
-   NOT calibrated probabilities: ≥ ~0.55 is a strong match, 0.4–0.55 is likely
-   relevant, < ~0.35 is weak or merely adjacent — judge by the snippet, not the
-   number, and say when the corpus doesn't really contain the topic.
-3. `episodic_read` with the session ID for the full transcript when an excerpt
-   isn't enough.
+   - Remote indexes support only vector search, without `text` filtering. Include
+     relevant terms in `query`; do not retry unsupported text/hybrid modes.
+2. Skim the returned excerpts (date, session title, score, and anchor). Vector
+   similarity scores are NOT calibrated probabilities: ≥ ~0.55 is a strong
+   match, 0.4–0.55 is likely relevant, and < ~0.35 is weak or merely adjacent.
+   These thresholds apply only to vector results. For hybrid results, use the
+   snippet and the `rrf` label instead; RRF scores are on a different scale.
+   Say when the corpus doesn't really contain the topic.
+3. `episodic_read_window` with the result's session ID, anchor message ID, and
+   `source_id` (required for remote indexes) to inspect a small window first.
+   Current-source windows read privacy-gated live messages. Foreign-source windows
+   read labeled indexed exchanges: `before`/`after` count chunks, not messages,
+   and content may be stale until that source syncs. Missing or stale anchors
+   cannot expand. Stop on privacy denials rather than trying indexed reads.
+4. `episodic_read_session` with the session ID and the same `source_id` when the
+   window is insufficient or unavailable. Use `indexed: true` for indexed excerpts,
+   including legacy unanchored hits. Do not present these as a full live transcript.
 
 ## Answering
 

package/src/cli.ts

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