opencode-session-recall 0.2.1

package/README.md

@@ -0,0 +1,146 @@
+# opencode-session-recall
+
+**Give your agent a memory that survives compaction — without building another memory system.**
+
+Most agent "memory" solutions add a new subsystem: vector databases, embedding pipelines, separate knowledge stores. They duplicate your data into yet another place that needs to be maintained, synced, and debugged.
+
+`opencode-session-recall` takes a different approach: **your conversation history is already the richest source of context you have.** opencode stores every message, every tool output, every reasoning trace in its database — even after compaction prunes them from the agent's context window. This plugin simply gives the agent tools to search and retrieve what's already there.
+
+No embeddings. No vector store. No data duplication. Just direct access to the context your agent already generated.
+
+## What this enables
+
+**"We already solved this."** The agent searches its own history and finds the solution from 2 hours ago that got compacted away, instead of solving the same problem again.
+
+**"How did we do it in that other project?"** Cross-project search finds the JWT middleware implementation from the auth project, the Docker config from the deployment project, the test patterns from the API project.
+
+**"What did you originally ask for?"** After 50+ tool calls and 3 compactions, the agent can pull up the user's exact original requirements to make sure it's still on track.
+
+**"What was that error?"** The full stack trace from the tool output that got pruned is still there. The agent retrieves it instead of reproducing the error.
+
+**"Show me what happened."** Browse any session chronologically, play back the conversation, understand the narrative of how a problem was investigated and solved.
+
+## Install
+
+```jsonc
+{
+  "plugin": [
+    "opencode-session-recall",
+
+    // Enable cross-project search
+    ["opencode-session-recall", { "global": true }],
+  ],
+}
+```
+
+## Tools
+
+Five tools, designed around how agents actually navigate conversation history:
+
+### `recall` — Search
+
+The primary tool. Full-text search across text, tool outputs, tool inputs, reasoning, and subtask descriptions. Searches the current session by default, or widen to all project sessions or all sessions globally.
+
+```
+recall({ query: "authentication", scope: "project" })
+recall({ query: "error", after: <2 days ago>, type: "tool" })
+recall({ query: "JWT", sessionID: "ses_from_another_project" })
+```
+
+| Param            | Default     | Description                                   |
+| ---------------- | ----------- | --------------------------------------------- |
+| `query`          | required    | Text to search for (case-insensitive)         |
+| `scope`          | `"session"` | `"session"`, `"project"`, or `"global"`       |
+| `sessionID`      | —           | Target a specific session (overrides scope)   |
+| `type`           | `"all"`     | `"text"`, `"tool"`, `"reasoning"`, or `"all"` |
+| `role`           | `"all"`     | `"user"`, `"assistant"`, or `"all"`           |
+| `before`/`after` | —           | Timestamp filters (ms epoch)                  |
+| `width`          | `200`       | Snippet size (50-1000 chars)                  |
+| `sessions`       | `10`        | Max sessions to scan                          |
+| `results`        | `10`        | Max results to return                         |
+
+### `recall_get` — Retrieve
+
+Get the full content of a specific message, including all parts. Tool outputs are returned in their original form, even if they were pruned from context. Use after `recall` finds something interesting.
+
+```
+recall_get({ sessionID: "ses_abc", messageID: "msg_def" })
+```
+
+### `recall_context` — Expand
+
+Get a window of messages around a specific message. After `recall` finds a match, see what was asked before it and what happened after. Supports symmetric and asymmetric windows.
+
+```
+recall_context({ sessionID: "ses_abc", messageID: "msg_def", window: 3 })
+recall_context({ sessionID: "ses_abc", messageID: "msg_def", before: 1, after: 5 })
+```
+
+Returns `hasMoreBefore`/`hasMoreAfter` so the agent knows if it's at a boundary.
+
+### `recall_messages` — Browse
+
+Paginated message browsing. Walk through a session chronologically, read the beginning, check the most recent messages, or filter by role. Also supports content filtering to combine search and pagination.
+
+```
+recall_messages({ limit: 5, role: "user", reverse: true })
+recall_messages({ sessionID: "ses_abc", offset: 10, limit: 10 })
+recall_messages({ query: "npm", role: "user", reverse: true })
+```
+
+Defaults to the current session. Pagination metadata includes `total`, `hasMore`, and `offset`.
+
+### `recall_sessions` — Discover
+
+List sessions by title. The starting point for cross-session and cross-project work.
+
+```
+recall_sessions({ scope: "project", search: "auth" })
+recall_sessions({ scope: "global", search: "deployment" })
+```
+
+## Real-world workflow
+
+This is what it actually looks like when an agent uses these tools to answer "what have we been doing with our UniFi network?" across a 3-week, 600+ message session in a different project:
+
+```
+1. recall_sessions({ scope: "global", search: "unifi" })
+   → discovers the ubiopti project session
+
+2. recall_messages({ sessionID: "...", limit: 5, role: "user", reverse: true })
+   → reads the most recent user messages to understand current state
+
+3. recall({ query: "kickout threshold", sessionID: "...", width: 500 })
+   → finds the technical root cause analysis in tool outputs
+
+4. recall_context({ sessionID: "...", messageID: "...", window: 3 })
+   → expands around the Ubiquiti support chat to see the full interaction
+
+5. recall({ query: "iwpriv", sessionID: "...", after: <recent timestamp> })
+   → finds only recent mentions, not the whole session history
+```
+
+Five tool calls, complete narrative reconstructed across projects.
+
+## Options
+
+| Option    | Type      | Default | Description                                         |
+| --------- | --------- | ------- | --------------------------------------------------- |
+| `primary` | `boolean` | `true`  | Register tools as primary (available to all agents) |
+| `global`  | `boolean` | `false` | Enable cross-project search via `scope: "global"`   |
+
+## How it works
+
+This plugin doesn't create a separate memory store. It reads what opencode already has.
+
+When opencode compacts a session, it doesn't delete anything. Tool outputs get a `compacted` timestamp and are replaced with placeholder text in the LLM's context — but the original data stays in the database. Messages before a compaction boundary are skipped when building the LLM context — but they're still there. The plugin accesses all of this through the opencode SDK.
+
+- Uses the opencode SDK client (no direct database queries, no separate storage)
+- Zero setup — no embeddings to generate, no indexes to build, no data to sync
+- Sessions are scanned newest-first with bounded concurrency
+- Respects abort signals for long-running searches
+- Global scope is disabled by default
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+export declare function context(client: OpencodeClient): ToolDefinition;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI1D,wBAAgB,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAuG9D"}

package/dist/extract.d.ts

@@ -0,0 +1,12 @@
+import type { Part, Message } from "@opencode-ai/sdk/v2";
+import type { PartOutput, MessageItem } from "./types.js";
+export declare function matches(text: string, query: string): boolean;
+export declare function searchable(part: Part): string[];
+export declare function snippet(text: string, query: string, width?: number): string;
+export declare function pruned(part: Part): boolean;
+export declare function format(part: Part): PartOutput;
+export declare function formatMsg(msg: {
+    info: Message;
+    parts: Array<Part>;
+}): MessageItem;
+//# sourceMappingURL=extract.d.ts.map

package/dist/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../src/extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,IAAI,EAEJ,OAAO,EAGR,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAW1D,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAE5D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CA2B/C;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,SAAM,GAAG,MAAM,CAexE;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAI1C;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,UAAU,CA0D7C;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;CACpB,GAAG,WAAW,CAgBd"}

package/dist/get.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+export declare function get(client: OpencodeClient): ToolDefinition;
+//# sourceMappingURL=get.d.ts.map

package/dist/get.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get.d.ts","sourceRoot":"","sources":["../src/get.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAK1D,wBAAgB,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA0D1D"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from "@opencode-ai/plugin";
+declare const _default: {
+    id: string;
+    server: Plugin;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;;;;;AAkFlD,wBAGE"}

package/dist/index.js

@@ -0,0 +1,726 @@
+// src/index.ts
+import { createOpencodeClient } from "@opencode-ai/sdk/v2";
+
+// src/sessions.ts
+import {
+  tool
+} from "@opencode-ai/plugin";
+
+// src/types.ts
+function errmsg(e) {
+  if (e instanceof Error) return e.message;
+  if (typeof e === "string") return e;
+  if (e && typeof e === "object" && "data" in e) {
+    const data = e.data;
+    if (data?.message) return data.message;
+  }
+  try {
+    return JSON.stringify(e);
+  } catch {
+    return String(e);
+  }
+}
+
+// src/sessions.ts
+function sessions(client, unscoped, global) {
+  return tool({
+    description: `List sessions from the opencode database. Use this FIRST to discover which sessions exist, then search their content with recall. Returns session titles, directories, and timestamps. For cross-project discovery, use scope "global" (requires plugin option global: true).`,
+    args: {
+      scope: tool.schema.enum(["project", "global"]).default("project").describe("project = current project, global = all projects"),
+      search: tool.schema.string().optional().describe("Filter by session title"),
+      limit: tool.schema.number().min(1).max(100).default(20).describe("Max sessions to return")
+    },
+    async execute(args, ctx) {
+      ctx.metadata({
+        title: args.search ? `Listing ${args.scope} sessions matching "${args.search}"` : `Listing ${args.scope} sessions`
+      });
+      if (args.scope === "global" && !global) {
+        const err = {
+          ok: false,
+          error: "Global scope disabled. Enable via plugin option: global: true"
+        };
+        return JSON.stringify(err);
+      }
+      try {
+        const items = [];
+        if (args.scope === "global") {
+          const result = await unscoped.experimental.session.list({
+            search: args.search,
+            limit: args.limit
+          });
+          if (result.error) {
+            const err = {
+              ok: false,
+              error: `Failed to list sessions: ${errmsg(result.error)}`
+            };
+            return JSON.stringify(err);
+          }
+          if (result.data) {
+            for (const s of result.data) {
+              items.push({
+                id: s.id,
+                title: s.title,
+                directory: s.directory,
+                project: s.project ? { name: s.project.name, worktree: s.project.worktree } : void 0,
+                time: { created: s.time.created, updated: s.time.updated },
+                archived: s.time.archived != null
+              });
+            }
+          }
+        } else {
+          const result = await client.session.list({
+            search: args.search,
+            limit: args.limit
+          });
+          if (result.error) {
+            const err = {
+              ok: false,
+              error: `Failed to list sessions: ${errmsg(result.error)}`
+            };
+            return JSON.stringify(err);
+          }
+          if (result.data) {
+            for (const s of result.data) {
+              items.push({
+                id: s.id,
+                title: s.title,
+                directory: s.directory,
+                time: { created: s.time.created, updated: s.time.updated },
+                archived: s.time.archived != null
+              });
+            }
+          }
+        }
+        ctx.metadata({
+          title: `Found ${items.length} ${args.scope} sessions${args.search ? ` matching "${args.search}"` : ""}`
+        });
+        const out = {
+          ok: true,
+          sessions: items,
+          returned: items.length,
+          scope: args.scope
+        };
+        return JSON.stringify(out);
+      } catch (e) {
+        const err = { ok: false, error: errmsg(e) };
+        return JSON.stringify(err);
+      }
+    }
+  });
+}
+
+// src/search.ts
+import {
+  tool as tool2
+} from "@opencode-ai/plugin";
+
+// src/extract.ts
+var INPUT_SEARCH_LIMIT = 1e4;
+function input(val) {
+  const raw = JSON.stringify(val);
+  return raw.length > INPUT_SEARCH_LIMIT ? raw.slice(0, INPUT_SEARCH_LIMIT) : raw;
+}
+function matches(text, query) {
+  return text.toLowerCase().includes(query.toLowerCase());
+}
+function searchable(part) {
+  switch (part.type) {
+    case "text":
+    case "reasoning":
+      return part.text ? [part.text] : [];
+    case "tool": {
+      const result = [];
+      const state = part.state;
+      if (state.status === "completed") {
+        if (state.output) result.push(state.output);
+        if (state.title) result.push(state.title);
+        if (state.input) result.push(input(state.input));
+      }
+      if (state.status === "error") {
+        if (state.error) result.push(state.error);
+        if (state.input) result.push(input(state.input));
+      }
+      if (state.status === "running" || state.status === "pending") {
+        if (state.input) result.push(input(state.input));
+      }
+      return result;
+    }
+    case "subtask":
+      return [part.description, part.prompt];
+    default:
+      return [];
+  }
+}
+function snippet(text, query, width = 200) {
+  const lower = text.toLowerCase();
+  const idx = lower.indexOf(query.toLowerCase());
+  if (idx === -1)
+    return text.slice(0, width) + (text.length > width ? "..." : "");
+  const half = Math.floor(width / 2);
+  let start = Math.max(0, idx - half);
+  let end = Math.min(text.length, start + width);
+  if (end - start < width && start > 0) start = Math.max(0, end - width);
+  let result = text.slice(start, end);
+  if (start > 0) result = "..." + result;
+  if (end < text.length) result = result + "...";
+  return result;
+}
+function pruned(part) {
+  if (part.type !== "tool") return false;
+  if (part.state.status !== "completed") return false;
+  return part.state.time.compacted != null;
+}
+function format(part) {
+  const base = { id: part.id, type: part.type, pruned: pruned(part) };
+  switch (part.type) {
+    case "text":
+    case "reasoning":
+      return { ...base, content: part.text };
+    case "tool": {
+      const state = part.state;
+      if (state.status === "completed")
+        return {
+          ...base,
+          toolName: part.tool,
+          title: state.title,
+          input: state.input,
+          output: state.output
+        };
+      if (state.status === "error")
+        return {
+          ...base,
+          toolName: part.tool,
+          input: state.input,
+          error: state.error
+        };
+      return {
+        ...base,
+        toolName: part.tool,
+        input: state.input
+      };
+    }
+    case "subtask":
+      return { ...base, content: `[subtask] ${part.description}` };
+    case "compaction":
+      return {
+        ...base,
+        content: `[compaction boundary${part.auto ? " (auto)" : ""}]`
+      };
+    case "file":
+      return { ...base, content: `[file] ${part.filename ?? part.url}` };
+    case "snapshot":
+      return { ...base, content: `[snapshot] ${part.snapshot}` };
+    case "patch":
+      return { ...base, content: `[patch] ${part.files.join(", ")}` };
+    case "agent":
+      return { ...base, content: `[agent] ${part.name}` };
+    case "retry":
+      return {
+        ...base,
+        content: `[retry] attempt ${part.attempt}`,
+        error: part.error.data.message
+      };
+    case "step-start":
+      return { ...base, content: "[step-start]" };
+    case "step-finish":
+      return { ...base, content: `[step-finish] ${part.reason}` };
+    default:
+      return { ...base, content: `[${part.type}]` };
+  }
+}
+function formatMsg(msg) {
+  const info = msg.info;
+  let model;
+  if (info.role === "assistant") model = info.modelID;
+  else model = info.model.modelID;
+  return {
+    message: {
+      id: info.id,
+      role: info.role,
+      time: info.time.created,
+      agent: info.agent,
+      model
+    },
+    parts: msg.parts.map(format)
+  };
+}
+
+// src/search.ts
+var CONCURRENCY = 3;
+function meta(s) {
+  return { id: s.id, title: s.title, directory: s.directory };
+}
+function scan(messages2, session, query, type, role, limit, before, after, width) {
+  const results = [];
+  let total = 0;
+  for (const msg of messages2) {
+    if (results.length >= limit) break;
+    const ts = msg.info.time.created;
+    if (before != null && ts >= before) continue;
+    if (after != null && ts <= after) continue;
+    if (role !== "all" && msg.info.role !== role) continue;
+    for (const part of msg.parts) {
+      if (results.length >= limit) break;
+      if (type !== "all" && part.type !== type) continue;
+      const texts = searchable(part);
+      let matched = false;
+      for (const text of texts) {
+        if (!matches(text, query)) continue;
+        total++;
+        if (matched) continue;
+        matched = true;
+        if (results.length < limit) {
+          results.push({
+            sessionID: session.id,
+            sessionTitle: session.title,
+            directory: session.directory,
+            messageID: msg.info.id,
+            role: msg.info.role,
+            time: msg.info.time.created,
+            partID: part.id,
+            partType: part.type,
+            pruned: pruned(part),
+            snippet: snippet(text, query, width),
+            toolName: part.type === "tool" ? part.tool : void 0
+          });
+        }
+      }
+    }
+  }
+  return { results, total };
+}
+function search(client, unscoped, global) {
+  return tool2({
+    description: `Search your conversation history in the opencode database. Use this to recover context lost to compaction \u2014 original tool outputs, earlier messages, reasoning, and user instructions that were pruned from your context window.
+
+Searches text content, tool inputs/outputs, and reasoning. Returns matching snippets with session/message IDs you can pass to recall_get for full content.
+
+Start with scope "session" (fastest). Widen to "project" if not found. Use sessionID param to target a specific session found via recall_sessions. Use role "user" to find original requirements.`,
+    args: {
+      query: tool2.schema.string().min(1).describe("Text to search for (case-insensitive)"),
+      scope: tool2.schema.enum(["session", "project", "global"]).default("session").describe(
+        "session = current, project = all project sessions, global = all"
+      ),
+      sessionID: tool2.schema.string().optional().describe("Search a specific session (overrides scope)"),
+      type: tool2.schema.enum(["text", "tool", "reasoning", "all"]).default("all").describe("Filter by part type"),
+      role: tool2.schema.enum(["user", "assistant", "all"]).default("all").describe("Filter by message role"),
+      sessions: tool2.schema.number().min(1).max(50).default(10).describe("Max sessions to scan"),
+      results: tool2.schema.number().min(1).max(50).default(10).describe("Max results to return"),
+      title: tool2.schema.string().optional().describe("Filter sessions by title"),
+      before: tool2.schema.number().optional().describe("Only match messages before this timestamp (ms epoch)"),
+      after: tool2.schema.number().optional().describe("Only match messages after this timestamp (ms epoch)"),
+      width: tool2.schema.number().min(50).max(1e3).default(200).describe("Snippet width in characters")
+    },
+    async execute(args, ctx) {
+      ctx.metadata({ title: `Searching ${args.scope} for "${args.query}"` });
+      if (args.scope === "global" && !args.sessionID && !global) {
+        const err = {
+          ok: false,
+          error: "Global scope disabled. Enable via plugin option: global: true"
+        };
+        return JSON.stringify(err);
+      }
+      try {
+        let targets = [];
+        if (args.sessionID) {
+          let title = "";
+          let directory = "";
+          try {
+            const sess = await client.session.get({
+              sessionID: args.sessionID
+            });
+            if (sess.data) {
+              title = sess.data.title;
+              directory = sess.data.directory;
+            }
+          } catch {
+          }
+          targets = [{ id: args.sessionID, title, directory }];
+        } else if (args.scope === "session") {
+          let title = "";
+          let directory = "";
+          try {
+            const sess = await client.session.get({ sessionID: ctx.sessionID });
+            if (sess.data) {
+              title = sess.data.title;
+              directory = sess.data.directory;
+            }
+          } catch {
+          }
+          targets = [{ id: ctx.sessionID, title, directory }];
+        } else if (args.scope === "project") {
+          const resp = await client.session.list({
+            search: args.title,
+            limit: args.sessions
+          });
+          if (resp.error) {
+            const err = {
+              ok: false,
+              error: `Failed to list sessions: ${errmsg(resp.error)}`
+            };
+            return JSON.stringify(err);
+          }
+          if (resp.data) targets = resp.data.map(meta);
+        } else {
+          const resp = await unscoped.experimental.session.list({
+            search: args.title,
+            limit: args.sessions
+          });
+          if (resp.error) {
+            const err = {
+              ok: false,
+              error: `Failed to list sessions: ${errmsg(resp.error)}`
+            };
+            return JSON.stringify(err);
+          }
+          if (resp.data) targets = resp.data.map(meta);
+        }
+        const collected = [];
+        let scanned = 0;
+        let total = 0;
+        let early = false;
+        for (let i = 0; i < targets.length; i += CONCURRENCY) {
+          if (ctx.abort.aborted) {
+            early = true;
+            break;
+          }
+          if (collected.length >= args.results) {
+            early = true;
+            break;
+          }
+          const remaining = args.results - collected.length;
+          const batch = targets.slice(i, i + CONCURRENCY);
+          const loaded = await Promise.all(
+            batch.map(async (t) => {
+              try {
+                const resp = await client.session.messages({ sessionID: t.id });
+                return { session: t, messages: resp.data ?? [] };
+              } catch {
+                return { session: t, messages: [] };
+              }
+            })
+          );
+          for (const { session: sess, messages: msgs } of loaded) {
+            if (collected.length >= args.results) {
+              early = true;
+              break;
+            }
+            const result = scan(
+              msgs,
+              sess,
+              args.query,
+              args.type,
+              args.role,
+              remaining,
+              args.before,
+              args.after,
+              args.width
+            );
+            collected.push(...result.results);
+            total += result.total;
+          }
+          scanned += batch.length;
+        }
+        const final = collected.slice(0, args.results);
+        ctx.metadata({
+          title: `Found ${final.length} result${final.length !== 1 ? "s" : ""} for "${args.query}" (${scanned} session${scanned !== 1 ? "s" : ""} searched)`
+        });
+        const out = {
+          ok: true,
+          results: final,
+          scanned,
+          total,
+          truncated: early || total > final.length
+        };
+        return JSON.stringify(out);
+      } catch (e) {
+        const err = { ok: false, error: errmsg(e) };
+        return JSON.stringify(err);
+      }
+    }
+  });
+}
+
+// src/get.ts
+import {
+  tool as tool3
+} from "@opencode-ai/plugin";
+function get(client) {
+  return tool3({
+    description: `Retrieve the full content of a specific message from any session, including all parts (text, tool outputs, reasoning, etc). Use after recall to get the complete content of a search result. For tool parts, returns the original output even if it was pruned from your context window. Large outputs may be truncated by the opencode runtime.`,
+    args: {
+      sessionID: tool3.schema.string().describe("Session containing the message"),
+      messageID: tool3.schema.string().describe("Message to retrieve")
+    },
+    async execute(args, ctx) {
+      ctx.metadata({
+        title: `Retrieving message ${args.messageID.slice(0, 20)}...`
+      });
+      try {
+        const result = await client.session.message({
+          sessionID: args.sessionID,
+          messageID: args.messageID
+        });
+        if (!result.data) {
+          const msg = result.error ? errmsg(result.error) : `Message not found: ${args.messageID}`;
+          const err = { ok: false, error: msg };
+          return JSON.stringify(err);
+        }
+        const item = formatMsg(result.data);
+        let title;
+        let directory;
+        try {
+          const sess = await client.session.get({ sessionID: args.sessionID });
+          if (sess.data) {
+            title = sess.data.title;
+            directory = sess.data.directory;
+          }
+        } catch {
+        }
+        ctx.metadata({
+          title: `${item.message.role} message (${item.parts.length} part${item.parts.length !== 1 ? "s" : ""})${title ? ` from "${title}"` : ""}`
+        });
+        const out = {
+          ok: true,
+          message: item.message,
+          parts: item.parts,
+          context: { sessionTitle: title, directory }
+        };
+        return JSON.stringify(out);
+      } catch (e) {
+        const err = { ok: false, error: errmsg(e) };
+        return JSON.stringify(err);
+      }
+    }
+  });
+}
+
+// src/context.ts
+import {
+  tool as tool4
+} from "@opencode-ai/plugin";
+function context(client) {
+  return tool4({
+    description: `Get messages surrounding a specific message in a session. Use after recall finds a match and you need conversation context \u2014 what was asked before, what came after. Returns a window of messages centered on the target.`,
+    args: {
+      sessionID: tool4.schema.string().describe("Session containing the message"),
+      messageID: tool4.schema.string().describe("Center message to get context around"),
+      window: tool4.schema.number().min(0).max(10).default(3).describe(
+        "Number of messages to include before AND after the target (symmetric). Overridden by before/after if set."
+      ),
+      before: tool4.schema.number().min(0).max(10).optional().describe(
+        "Messages to include before the target (overrides window for the before side)"
+      ),
+      after: tool4.schema.number().min(0).max(10).optional().describe(
+        "Messages to include after the target (overrides window for the after side)"
+      )
+    },
+    async execute(args, ctx) {
+      ctx.metadata({ title: "Getting context around message..." });
+      const nb = args.before ?? args.window;
+      const na = args.after ?? args.window;
+      try {
+        const resp = await client.session.messages({
+          sessionID: args.sessionID
+        });
+        if (resp.error) {
+          const err = { ok: false, error: errmsg(resp.error) };
+          return JSON.stringify(err);
+        }
+        if (!resp.data) {
+          const err = { ok: false, error: "No messages returned" };
+          return JSON.stringify(err);
+        }
+        const msgs = resp.data;
+        const idx = msgs.findIndex((m) => m.info.id === args.messageID);
+        if (idx === -1) {
+          const err = {
+            ok: false,
+            error: `Message not found: ${args.messageID}`
+          };
+          return JSON.stringify(err);
+        }
+        const start = Math.max(0, idx - nb);
+        const end = Math.min(msgs.length, idx + na + 1);
+        const slice = msgs.slice(start, end);
+        const items = slice.map((m) => {
+          const item = formatMsg(m);
+          return { ...item, center: m.info.id === args.messageID };
+        });
+        let title;
+        let directory;
+        try {
+          const sess = await client.session.get({ sessionID: args.sessionID });
+          if (sess.data) {
+            title = sess.data.title;
+            directory = sess.data.directory;
+          }
+        } catch {
+        }
+        ctx.metadata({
+          title: `Context: ${items.length} messages around target${title ? ` from "${title}"` : ""}`
+        });
+        const out = {
+          ok: true,
+          messages: items,
+          context: { sessionTitle: title, directory },
+          hasMoreBefore: start > 0,
+          hasMoreAfter: end < msgs.length
+        };
+        return JSON.stringify(out);
+      } catch (e) {
+        const err = { ok: false, error: errmsg(e) };
+        return JSON.stringify(err);
+      }
+    }
+  });
+}
+
+// src/messages.ts
+import {
+  tool as tool5
+} from "@opencode-ai/plugin";
+function msgMatches(msg, query) {
+  for (const part of msg.parts) {
+    for (const text of searchable(part)) {
+      if (matches(text, query)) return true;
+    }
+  }
+  return false;
+}
+function messages(client) {
+  return tool5({
+    description: `Browse messages in a session chronologically with pagination. Use to play back conversation history, see what happened in order, or find the user's original requirements. Use reverse=true to start from the most recent messages (offset 0 = newest). Use offset to paginate through results.`,
+    args: {
+      sessionID: tool5.schema.string().optional().describe(
+        "Session to browse. Defaults to current session if not provided."
+      ),
+      offset: tool5.schema.number().min(0).default(0).describe(
+        "Skip this many messages from the start (or end if reversed)"
+      ),
+      limit: tool5.schema.number().min(1).max(50).default(10).describe("Max messages to return"),
+      role: tool5.schema.enum(["user", "assistant", "all"]).default("all").describe("Filter by message role"),
+      reverse: tool5.schema.boolean().default(false).describe("If true, start from most recent messages"),
+      query: tool5.schema.string().min(1).optional().describe(
+        "Only include messages containing this text (searches all parts)"
+      )
+    },
+    async execute(args, ctx) {
+      const sid = args.sessionID ?? ctx.sessionID;
+      if (!sid) {
+        const err = {
+          ok: false,
+          error: "No sessionID provided and no current session available"
+        };
+        return JSON.stringify(err);
+      }
+      ctx.metadata({ title: "Browsing messages..." });
+      try {
+        const resp = await client.session.messages({ sessionID: sid });
+        if (resp.error) {
+          const err = { ok: false, error: errmsg(resp.error) };
+          return JSON.stringify(err);
+        }
+        if (!resp.data) {
+          const err = { ok: false, error: "No messages returned" };
+          return JSON.stringify(err);
+        }
+        let filtered = resp.data;
+        if (args.role !== "all")
+          filtered = filtered.filter((m) => m.info.role === args.role);
+        if (args.query)
+          filtered = filtered.filter((m) => msgMatches(m, args.query));
+        const ordered = args.reverse ? [...filtered].reverse() : filtered;
+        const slice = ordered.slice(args.offset, args.offset + args.limit);
+        const items = slice.map(formatMsg);
+        let title;
+        let directory;
+        try {
+          const sess = await client.session.get({ sessionID: sid });
+          if (sess.data) {
+            title = sess.data.title;
+            directory = sess.data.directory;
+          }
+        } catch {
+        }
+        ctx.metadata({
+          title: `Showing ${items.length} of ${filtered.length} messages (offset ${args.offset})${title ? ` from "${title}"` : ""}`
+        });
+        const out = {
+          ok: true,
+          messages: items,
+          context: { sessionTitle: title, directory },
+          pagination: {
+            offset: args.offset,
+            returned: items.length,
+            total: filtered.length,
+            hasMore: args.offset + args.limit < filtered.length
+          }
+        };
+        return JSON.stringify(out);
+      } catch (e) {
+        const err = { ok: false, error: errmsg(e) };
+        return JSON.stringify(err);
+      }
+    }
+  });
+}
+
+// src/index.ts
+var TOOLS = [
+  "recall",
+  "recall_get",
+  "recall_sessions",
+  "recall_context",
+  "recall_messages"
+];
+var server = async (ctx, options) => {
+  const opts = options ?? {};
+  const primary = opts.primary !== false;
+  const global = opts.global === true;
+  const inner = ctx.client._client;
+  if (!inner?.getConfig)
+    throw new Error(
+      "opencode-session-recall: SDK internals changed \u2014 cannot extract fetch transport"
+    );
+  const cfg = inner.getConfig();
+  if (!cfg.fetch)
+    throw new Error("opencode-session-recall: SDK client has no custom fetch");
+  const { "x-opencode-directory": _, ...rest } = cfg.headers ?? {};
+  const client = createOpencodeClient({
+    baseUrl: cfg.baseUrl,
+    fetch: cfg.fetch,
+    headers: cfg.headers,
+    directory: ctx.directory
+  });
+  const unscoped = createOpencodeClient({
+    baseUrl: cfg.baseUrl,
+    fetch: cfg.fetch,
+    headers: rest
+  });
+  return {
+    tool: {
+      recall_sessions: sessions(client, unscoped, global),
+      recall: search(client, unscoped, global),
+      recall_get: get(client),
+      recall_context: context(client),
+      recall_messages: messages(client)
+    },
+    ...primary && {
+      config: async (c) => {
+        c.experimental ??= {};
+        const existing = c.experimental.primary_tools ?? [];
+        const deduped = new Set(existing);
+        for (const t of TOOLS) deduped.add(t);
+        c.experimental.primary_tools = [...deduped];
+      }
+    }
+  };
+};
+var index_default = {
+  id: "opencode-session-recall",
+  server
+};
+export {
+  index_default as default
+};

package/dist/messages.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+export declare function messages(client: OpencodeClient): ToolDefinition;
+//# sourceMappingURL=messages.d.ts.map

package/dist/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../src/messages.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAQ,MAAM,qBAAqB,CAAC;AAahE,wBAAgB,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA0G/D"}

package/dist/search.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+export declare function search(client: OpencodeClient, unscoped: OpencodeClient, global: boolean): ToolDefinition;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EACV,cAAc,EAIf,MAAM,qBAAqB,CAAC;AA6E7B,wBAAgB,MAAM,CACpB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,GACd,cAAc,CA2MhB"}

package/dist/sessions.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin";
+import type { OpencodeClient } from "@opencode-ai/sdk/v2";
+export declare function sessions(client: OpencodeClient, unscoped: OpencodeClient, global: boolean): ToolDefinition;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D,wBAAgB,QAAQ,CACtB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,GACd,cAAc,CA0GhB"}

package/dist/types.d.ts

@@ -0,0 +1,107 @@
+export type SearchResult = {
+    sessionID: string;
+    sessionTitle: string;
+    directory: string;
+    messageID: string;
+    role: "user" | "assistant";
+    time: number;
+    partID: string;
+    partType: string;
+    pruned: boolean;
+    snippet: string;
+    toolName?: string;
+};
+export type SearchOutput = {
+    ok: true;
+    results: SearchResult[];
+    scanned: number;
+    total: number;
+    truncated: boolean;
+};
+export type MessageOutput = {
+    ok: true;
+    message: {
+        id: string;
+        role: "user" | "assistant";
+        time: number;
+        agent?: string;
+        model?: string;
+    };
+    parts: PartOutput[];
+    context: {
+        sessionTitle?: string;
+        directory?: string;
+    };
+};
+export type PartOutput = {
+    id: string;
+    type: string;
+    pruned: boolean;
+    content?: string;
+    toolName?: string;
+    title?: string;
+    input?: unknown;
+    output?: string;
+    error?: string;
+};
+export type MessageItem = {
+    message: {
+        id: string;
+        role: "user" | "assistant";
+        time: number;
+        agent?: string;
+        model?: string;
+    };
+    parts: PartOutput[];
+    center?: boolean;
+};
+export type ContextOutput = {
+    ok: true;
+    messages: MessageItem[];
+    context: {
+        sessionTitle?: string;
+        directory?: string;
+    };
+    hasMoreBefore: boolean;
+    hasMoreAfter: boolean;
+};
+export type MessagesOutput = {
+    ok: true;
+    messages: MessageItem[];
+    context: {
+        sessionTitle?: string;
+        directory?: string;
+    };
+    pagination: {
+        offset: number;
+        returned: number;
+        total: number;
+        hasMore: boolean;
+    };
+};
+export type SessionItem = {
+    id: string;
+    title: string;
+    directory: string;
+    project?: {
+        name?: string;
+        worktree: string;
+    };
+    time: {
+        created: number;
+        updated: number;
+    };
+    archived: boolean;
+};
+export type SessionsOutput = {
+    ok: true;
+    sessions: SessionItem[];
+    returned: number;
+    scope: string;
+};
+export type ErrorOutput = {
+    ok: false;
+    error: string;
+};
+export declare function errmsg(e: unknown): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "opencode-session-recall",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Agent memory without a memory system — search and retrieve opencode conversation history that was lost to compaction, across sessions and projects",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "opencode plugin dev",
+    "typecheck": "tsc --noEmit",
+    "compile": "tsup src/index.ts --format esm && tsc --emitDeclarationOnly --outDir dist",
+    "prepublishOnly": "npm run typecheck && npm run compile"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "recall",
+    "history",
+    "compaction",
+    "context",
+    "search",
+    "memory"
+  ],
+  "author": "maelos",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.2.0"
+  },
+  "dependencies": {
+    "@opencode-ai/sdk": "^1.3.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.4.3",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2"
+  }
+}