opencode-session-recall 0.4.0 → 0.5.0

package/README.md

@@ -1,12 +1,14 @@
 # opencode-session-recall
 
-**Give your agent a memory that survives compaction — without building another memory system.**
+A plugin for [opencode](https://github.com/opencode-ai/opencode) that gives 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 is an open-source AI coding agent that runs in your terminal. It manages long conversations through compaction: summarizing older context to keep the active window focused. But compaction means the agent forgets — original tool outputs, earlier reasoning, the user's exact words.
 
-`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.
+This plugin adds five tools to the agent's toolkit that let it search and retrieve that lost context on demand, within the current session, across all sessions in the project, or across every project on the machine.
 
-No embeddings. No vector store. No data duplication. Just direct access to the context your agent already generated.
+**It doesn't create a separate memory store.** Most agent "memory" solutions add vector databases, embedding pipelines, or knowledge graphs — duplicating your data into yet another system. `opencode-session-recall` does none of that. opencode already stores every message, every tool output, every reasoning trace in its database, even after compaction prunes them from context. This plugin simply gives the agent access to what's already there.
+
+No embeddings. No vector store. No data duplication. No setup. Just install the plugin and the agent can remember.
 
 ## What this enables
 

package/dist/context.d.ts.map

@@ -1 +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;AAC1D,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAGpB,wBAAgB,OAAO,CACrB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,GACb,cAAc,CAuGhB"}
+{"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;AAC1D,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAGpB,wBAAgB,OAAO,CACrB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,GACb,cAAc,CA2GhB"}

package/dist/get.d.ts.map

@@ -1 +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"}
+{"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,CAkE1D"}

package/dist/messages.d.ts.map

@@ -1 +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;AAChE,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAYpB,wBAAgB,QAAQ,CACtB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,GACb,cAAc,CA0GhB"}
+{"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;AAChE,OAAO,EAIL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAYpB,wBAAgB,QAAQ,CACtB,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,MAAM,GACb,cAAc,CAgHhB"}

package/dist/opencode-session-recall.d.ts.map

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

package/dist/opencode-session-recall.js

@@ -40,11 +40,15 @@ function errmsg(e) {
 // src/sessions.ts
 function sessions(client, unscoped, global, limits) {
   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).`,
+    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).
+
+Search filters by session title only (case-insensitive substring match \u2014 use recall for content search). Sessions are returned newest-updated first. This is a cheap metadata-only call.
+
+Returns { ok, sessions: [{ id, title, directory, time, archived }], returned, scope }. All tools return JSON with ok: true on success or ok: false with error on failure.`,
     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(limits.maxSessionList).default(Math.min(20, limits.maxSessionList)).describe("Max sessions to return")
+      search: tool.schema.string().optional().describe("Case-insensitive substring match on session title"),
+      limit: tool.schema.number().min(1).max(limits.maxSessionList).default(Math.min(20, limits.maxSessionList)).describe("Max sessions to return (newest first)")
     },
     async execute(args, ctx) {
       ctx.metadata({
@@ -176,7 +180,7 @@ function snippet(text, query, width = 200) {
     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);
+  const 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;
@@ -310,23 +314,37 @@ function search(client, unscoped, global, limits) {
   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.
+Searches text content, tool inputs/outputs, and reasoning via case-insensitive substring matching. Returns matching snippets with session/message IDs you can pass to recall_get for full content, or recall_context if you need surrounding messages.
+
+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.
+
+Scope costs: "session" scans 1 session. "project" scans up to \`sessions\` sessions (default 10). "global" scans across all projects.
+
+Returns { ok, results: [{ sessionID, messageID, role, time, partID, partType, pruned, snippet, toolName? }], scanned, total, truncated }. Each result includes a pruned flag \u2014 if true, the content was compacted from your context window and recall_get will return the original full output. Check truncated to know if more matches exist beyond your results limit.
 
-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.`,
+This tool's own outputs are excluded from search results to prevent recursive noise, but remain visible via recall_get, recall_context, and recall_messages.`,
     args: {
-      query: tool2.schema.string().min(1).describe("Text to search for (case-insensitive)"),
+      query: tool2.schema.string().min(1).describe("Text to search for (case-insensitive substring match)"),
       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(limits.maxSessions).default(Math.min(10, limits.maxSessions)).describe("Max sessions to scan"),
-      results: tool2.schema.number().min(1).max(limits.maxResults).default(Math.min(10, limits.maxResults)).describe("Max results to return"),
-      title: tool2.schema.string().optional().describe("Filter sessions by title"),
+      sessions: tool2.schema.number().min(1).max(limits.maxSessions).default(Math.min(10, limits.maxSessions)).describe(
+        "Max sessions to scan (controls cost for project/global scope)"
+      ),
+      results: tool2.schema.number().min(1).max(limits.maxResults).default(Math.min(10, limits.maxResults)).describe(
+        "Max results to return. Check truncated in response for more."
+      ),
+      title: tool2.schema.string().optional().describe(
+        "Filter sessions by title before scanning (same as recall_sessions search)"
+      ),
       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(Math.max(limits.defaultWidth, 1e3)).default(limits.defaultWidth).describe("Snippet width in characters")
+      width: tool2.schema.number().min(50).max(Math.max(limits.defaultWidth, 1e3)).default(limits.defaultWidth).describe(
+        "Characters of context around each match in the returned snippet. Only a snippet is returned \u2014 use recall_get for full content."
+      )
     },
     async execute(args, ctx) {
       ctx.metadata({ title: `Searching ${args.scope} for "${args.query}"` });
@@ -464,10 +482,16 @@ import {
 } 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.`,
+    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.
+
+Returns { message: { id, role, time, model }, parts: [{ type, content, toolName, input, output, pruned, ... }], context: { sessionTitle, directory } }. Each part has a pruned flag indicating whether it was compacted.
+
+Use recall_context instead if you need surrounding messages for context, not just a single message. Use sessionID and messageID from recall search results.`,
     args: {
-      sessionID: tool3.schema.string().describe("Session containing the message"),
-      messageID: tool3.schema.string().describe("Message to retrieve")
+      sessionID: tool3.schema.string().describe(
+        "Session containing the message (from recall search results)"
+      ),
+      messageID: tool3.schema.string().describe("Message to retrieve (from recall search results)")
     },
     async execute(args, ctx) {
       ctx.metadata({
@@ -518,18 +542,22 @@ import {
 } from "@opencode-ai/plugin";
 function context(client, limits) {
   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.`,
+    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 chronological window of full messages (with all parts) centered on the target.
+
+Returns { ok, messages: [{ message, parts, center? }], context, hasMoreBefore, hasMoreAfter }. The center message is marked with center: true. Use hasMoreBefore/hasMoreAfter with asymmetric before/after params to expand in either direction. window=3 returns up to 3 before + target + 3 after = 7 messages. window=0 returns only the target.
+
+Use recall_get for a single message without neighbors. Use recall_messages for paginated browsing of an entire session.`,
     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(limits.maxWindow).default(Math.min(3, limits.maxWindow)).describe(
-        "Number of messages to include before AND after the target (symmetric). Overridden by before/after if set."
+        "Messages on each side of target (window=3 \u2192 up to 7 total). Overridden by before/after if set."
       ),
       before: tool4.schema.number().min(0).max(limits.maxWindow).optional().describe(
-        "Messages to include before the target (overrides window for the before side)"
+        "Messages before the target (overrides window for before side). Set before=0, after=5 to see only what followed."
       ),
       after: tool4.schema.number().min(0).max(limits.maxWindow).optional().describe(
-        "Messages to include after the target (overrides window for the after side)"
+        "Messages after the target (overrides window for after side)"
       )
     },
     async execute(args, ctx) {
@@ -607,7 +635,11 @@ function msgMatches(msg, query) {
 }
 function messages(client, limits) {
   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.`,
+    description: `Browse messages in a session chronologically with pagination. Unlike recall (which searches for specific text and returns snippets), this returns full messages with all parts in chronological order. Use it to replay a session when you don't have a specific search term, or when you need complete message content rather than search hits.
+
+Use reverse=true to start from the most recent messages (offset 0 = newest). Use offset to paginate through results. Good for finding the user's original requirements at the start of a session.
+
+Returns { messages: [{ message: { id, role, time }, parts: [...] }], pagination: { offset, returned, total, hasMore } }. The query and role params filter client-side after fetching, so they may return fewer results than limit. pagination.total reflects the count after filtering.`,
     args: {
       sessionID: tool5.schema.string().optional().describe(
         "Session to browse. Defaults to current session if not provided."
@@ -616,10 +648,12 @@ function messages(client, limits) {
         "Skip this many messages from the start (or end if reversed)"
       ),
       limit: tool5.schema.number().min(1).max(limits.maxMessages).default(Math.min(10, limits.maxMessages)).describe("Max messages to return"),
-      role: tool5.schema.enum(["user", "assistant", "all"]).default("all").describe("Filter by message role"),
+      role: tool5.schema.enum(["user", "assistant", "all"]).default("all").describe(
+        "Filter by message role (client-side, may return fewer than limit)"
+      ),
       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)"
+        "Case-insensitive substring filter on message content (client-side, may return fewer than limit)"
       )
     },
     async execute(args, ctx) {
@@ -727,6 +761,7 @@ var server = async (ctx, options) => {
       recall_messages: messages(client, limits)
     },
     ...primary && {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- opencode config type not exported
       config: async (c) => {
         c.experimental ??= {};
         const existing = c.experimental.primary_tools ?? [];

package/dist/search.d.ts.map

@@ -1 +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;AAC7B,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAqEpB,wBAAgB,MAAM,CACpB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GACb,cAAc,CA2MhB"}
+{"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;AAC7B,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAqEpB,wBAAgB,MAAM,CACpB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GACb,cAAc,CAyNhB"}

package/dist/sessions.d.ts.map

@@ -1 +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;AAC1D,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAEpB,wBAAgB,QAAQ,CACtB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GACb,cAAc,CA0GhB"}
+{"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;AAC1D,OAAO,EAKL,KAAK,MAAM,EACZ,MAAM,YAAY,CAAC;AAEpB,wBAAgB,QAAQ,CACtB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GACb,cAAc,CA8GhB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-session-recall",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "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/opencode-session-recall.js",
@@ -57,8 +57,11 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@opencode-ai/plugin": "^1.4.3",
+    "eslint": "^10.2.0",
     "tsup": "^8.5.1",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1"
   }
 }