opencode-episodic-memory 0.3.0 → 0.3.1

package/README.md

@@ -35,7 +35,7 @@ tends to match injected boilerplate on this corpus.
 ## Install
 
 ```bash
-opencode plugin opencode-episodic-memory@0.3.0 -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.3.0"]
+  "plugin": ["opencode-episodic-memory@0.3.1"]
 }
 ```
 
@@ -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.3.0/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.3.0 sync
+bunx opencode-episodic-memory@0.3.1 sync
 ```
 
 ## CLI
@@ -90,16 +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.3.0 sync [--force]          # index new/changed sessions
-bunx opencode-episodic-memory@0.3.0 search "query"          # semantic (vector) search
-bunx opencode-episodic-memory@0.3.0 search q --text "terms"  # lexical BM25 (all terms AND-matched, token-based)
-bunx opencode-episodic-memory@0.3.0 search q --hybrid       # fuse vector + BM25 (RRF; opt-in)
-bunx opencode-episodic-memory@0.3.0 search q --after 2026-07-01 --limit 5
-bunx opencode-episodic-memory@0.3.0 read <session-id>       # full transcript (live store)
-bunx opencode-episodic-memory@0.3.0 read <id> --indexed     # local indexed excerpts
+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.0 stats                   # index statistics
-bunx opencode-episodic-memory@0.3.0 doctor                  # diagnose setup
+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
@@ -107,9 +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, scores, and message anchors. Legacy results without an anchor require a normal sync before bounded window reads.
-- **`episodic_read_window`** — `session_id`, `anchor_message_id` (+ optional `source_id`, required in remote mode; `before`, `after`, each 0-20, default 3). Reads a bounded chronological window from the privacy-gated live source transcript. Deleted, private, stale, or legacy-anchored sessions cannot provide a window.
-- **`episodic_read_session`** — `session_id` (+ optional `source_id`, required in remote mode; `indexed`). Reads the full session transcript from the live store, falling back to indexed excerpts. Prefer `episodic_search` -> `episodic_read_window` -> `episodic_read_session`, stopping once enough context has been recovered.
+- **`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
 
@@ -175,9 +175,13 @@ schema and does not use FTS, so remote mode supports vector search only. `--text
 Remote cosine search reads embedding candidates in bounded pages and hydrates
 only the final result set.
 
-Remote search includes the source ID in each hit. Bounded live reads are only
-valid for the current source; another device's hits remain available as indexed
-excerpts through `episodic_read_session` with that hit's `source_id`.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-episodic-memory",
-  "version": "0.3.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",

package/plugin/episodic-memory.ts

@@ -2,13 +2,14 @@
 // - 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, getTranscriptContext } from "../src/reader";
+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, renderTranscriptContext } 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 } })
@@ -67,16 +68,22 @@ 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, session IDs, and anchors. Prefer episodic_search -> episodic_read_window for a bounded live window -> episodic_read_session only when the full session is needed.",
+          "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) {
+          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;
@@ -86,7 +93,7 @@ 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 = async () => await index.isEmpty()
             ? "No matching past conversations found. The index is empty — run `bun run src/cli.ts sync` to index conversations."
@@ -116,18 +123,26 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
 
       episodic_read_window: tool({
         description:
-          "Read a bounded live-source message window around an anchor from episodic_search. Use the returned session_id and anchor_message_id; this cannot read deleted sessions or indexed-only excerpts.",
+          "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, 0-20 (default 3)"),
-          after: tool.schema.number().optional().describe("Messages after the anchor, 0-20 (default 3)"),
+          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 (!canLiveRead(remote, args.source_id)) {
-            throw new Error("This indexed hit belongs to another source (or has no source_id). Its excerpt is searchable, but live windows are only available for the current source.");
+          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);
@@ -155,24 +170,30 @@ export const EpisodicMemory: Plugin = async ({ client }) => {
             throw new Error("source_id is required for episodic_read_session with a remote index.");
           }
           const foreign = !canLiveRead(remote, args.source_id);
-          if (!args.indexed && !foreign) {
+          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_session live-store read failed for ${args.session_id}: ${e}`);
-              // fall through to indexed copy
+              return "Live-source validation failed; indexed content withheld because current privacy status could not be verified.";
             }
           }
           const index = await getIndex();

package/skills/remembering-conversations/SKILL.md

@@ -25,21 +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.
+   - 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 and anchor message ID to
-   inspect a small chronological window first. It is live-source only: private,
-   deleted, stale, and legacy unanchored results cannot expand.
-4. `episodic_read_session` with the session ID only when that window isn't enough
-   and the full session transcript is needed.
+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/format.ts

@@ -2,7 +2,7 @@
 // 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";
+import type { IndexedWindowRow, SearchHit } from "./store";
 import { Buffer } from "node:buffer";
 
 const MAX_CONTEXT_BODY_BYTES = 600;
@@ -86,6 +86,20 @@ export function renderTranscriptContext(
   return lines.join("\n");
 }
 
+export function renderIndexedContext(sessionId: string, sourceId: string, anchorMessageId: string, rows: IndexedWindowRow[]): string {
+  const lines = [
+    "# Indexed excerpts (not a live transcript)",
+    `source: ${truncateContext(sourceId, MAX_CONTEXT_FIELD_BYTES)}  session: ${truncateContext(sessionId, MAX_CONTEXT_FIELD_BYTES)}`,
+    "Window bounds count condensed exchange chunks, not messages. Content may be stale until the source syncs.",
+    "",
+  ];
+  for (const row of rows) {
+    lines.push(`## Chunk ${row.seq}${row.anchor_message_id === anchorMessageId ? " (anchor)" : ""}`);
+    lines.push(truncateContext(row.text, MAX_CONTEXT_BODY_BYTES), "");
+  }
+  return lines.join("\n");
+}
+
 function truncateContext(value: string, byteLimit: number): string {
   if (Buffer.byteLength(value, "utf8") <= byteLimit) return value;
   const suffix = "... [truncated]";

package/src/store.ts

@@ -442,9 +442,23 @@ export interface IndexStore {
   isEmpty(): Promise<boolean>;
   stats(): Promise<IndexStats>;
   readIndexed(sessionId: string, sourceId?: string): Promise<{ text: string }[]>;
+  readIndexedWindow(sessionId: string, anchorMessageId: string, before?: number, after?: number, sourceId?: string): Promise<IndexedWindowRow[]>;
   close(): void;
 }
 
+export interface IndexedWindowRow {
+  seq: number;
+  anchor_message_id: string | null;
+  text: string;
+}
+
+function indexedWindowBounds(before: number = 3, after: number = 3): { before: number; after: number } {
+  if (!Number.isInteger(before) || before < 0 || before > 20 || !Number.isInteger(after) || after < 0 || after > 20) {
+    throw new Error("before and after must be non-negative integers no greater than 20.");
+  }
+  return { before, after };
+}
+
 class LocalIndexStore implements IndexStore {
   readonly remote = false;
   constructor(private readonly db: Database) {}
@@ -479,6 +493,28 @@ class LocalIndexStore implements IndexStore {
   async readIndexed(sessionId: string) {
     return this.db.prepare<{ text: string }, [string]>("SELECT text FROM chunks WHERE session_id = ? ORDER BY seq").all(sessionId);
   }
+  async readIndexedWindow(sessionId: string, anchorMessageId: string, before?: number, after?: number) {
+    const bounds = indexedWindowBounds(before, after);
+    return this.db.prepare<IndexedWindowRow, [string, string, string, number, string, number]>(
+      `WITH anchor AS (
+        SELECT seq FROM chunks WHERE session_id = ? AND anchor_message_id = ? ORDER BY seq LIMIT 1
+      ), previous AS (
+        SELECT c.seq, c.anchor_message_id, substr(c.text, 1, 4000) AS text
+        FROM chunks c JOIN anchor a
+        WHERE c.session_id = ? AND c.seq < a.seq
+        ORDER BY c.seq DESC LIMIT ?
+      ), following AS (
+        SELECT c.seq, c.anchor_message_id, substr(c.text, 1, 4000) AS text
+        FROM chunks c JOIN anchor a
+        WHERE c.session_id = ? AND c.seq >= a.seq
+        ORDER BY c.seq ASC LIMIT ?
+      )
+      SELECT seq, anchor_message_id, text FROM previous
+      UNION ALL
+      SELECT seq, anchor_message_id, text FROM following
+      ORDER BY seq`
+    ).all(sessionId, anchorMessageId, sessionId, bounds.before, sessionId, bounds.after + 1);
+  }
   close() { this.db.close(); }
 }
 
@@ -763,6 +799,35 @@ class RemoteIndexStore implements IndexStore {
     const result = await this.client.execute({ sql: "SELECT text FROM episodic_chunks WHERE source_id = ? AND session_id = ? ORDER BY seq", args: [sourceId, sessionId] });
     return result.rows.map((row) => ({ text: rowString(row, "text") }));
   }
+  async readIndexedWindow(sessionId: string, anchorMessageId: string, before?: number, after?: number, sourceId?: string): Promise<IndexedWindowRow[]> {
+    if (!sourceId) throw new Error("sourceId is required for remote indexed windows.");
+    const bounds = indexedWindowBounds(before, after);
+    const result = await this.client.execute({
+      sql: `WITH anchor AS (
+        SELECT seq FROM episodic_chunks
+        WHERE source_id = ? AND session_id = ? AND anchor_message_id = ?
+        ORDER BY seq LIMIT 1
+      ), previous AS (
+        SELECT c.seq, c.anchor_message_id, substr(c.text, 1, 4000) AS text
+        FROM episodic_chunks c JOIN anchor a
+        WHERE c.source_id = ? AND c.session_id = ? AND c.seq < a.seq
+        ORDER BY c.seq DESC LIMIT ?
+      ), following AS (
+        SELECT c.seq, c.anchor_message_id, substr(c.text, 1, 4000) AS text
+        FROM episodic_chunks c JOIN anchor a
+        WHERE c.source_id = ? AND c.session_id = ? AND c.seq >= a.seq
+        ORDER BY c.seq ASC LIMIT ?
+      )
+      SELECT seq, anchor_message_id, text FROM previous
+      UNION ALL
+      SELECT seq, anchor_message_id, text FROM following
+      ORDER BY seq`,
+      args: [sourceId, sessionId, anchorMessageId, sourceId, sessionId, bounds.before, sourceId, sessionId, bounds.after + 1],
+    });
+    return result.rows.map((row) => ({
+      seq: rowNumber(row, "seq"), anchor_message_id: rowNullableString(row, "anchor_message_id"), text: rowString(row, "text"),
+    }));
+  }
   close() { this.client.close(); }
 }