opencode-history-search-v2 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 marioschweiger
+Copyright (c) 2026 joeyism (original opencode-history-search, V1)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# opencode-history-search-v2
+
+OpenCode **V2** plugin that gives the AI model a `history_search` tool: search past
+conversation sessions by keyword, fuzzy term, multi-term AND, or file touch history.
+
+OpenCode V2 stores sessions in a local SQLite database. This plugin opens that
+database **read-only**, on demand, and runs deterministic searches over it. No
+indexing, no network, no data leaves the machine.
+
+Port of [joeyism/opencode-history-search](https://github.com/joeyism/opencode-history-search)
+(V1, for legacy OpenCode) to the V2 plugin SDK and the V2 storage schema.
+
+## Install
+
+In `opencode.json` (global or project):
+
+```json
+{
+  "plugins": ["opencode-history-search-v2@latest"]
+}
+```
+
+The plugin hot-reloads on config change; no restart needed.
+
+## What the model gets
+
+A single tool, `history_search`, e.g. the model can answer:
+
+- "What did we decide about the cache bug last week?" → keyword + date search
+- "Which sessions touched `src/auth.ts`?" → file trace
+- "Find the session about both the truck API and the vertex deploy" → multi-term AND
+- "Search every project on this machine for 'postgres migration'" → cross-project
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `query` | string | Keyword, regex (with `regex: true`), or fuzzy term. Required unless `filePath` or `terms` is set. |
+| `terms` | string[] | Multi-term AND: sessions containing **all** terms. 1 term falls back to `query`. |
+| `filePath` | string | Trace which sessions touched this file path. Other filters are ignored. |
+| `searchAllProjects` | boolean | Search all projects on the machine instead of only the current one. |
+| `mode` | `"keyword" \| "fuzzy"` | Exact keyword (default) or typo-tolerant fuzzy matching. |
+| `regex` | boolean | Treat `query` as a regular expression (keyword mode). |
+| `caseSensitive` | boolean | Case-sensitive matching (keyword mode, default false). |
+| `fuzzyThreshold` | number | 0.0–1.0, lower = stricter (fuzzy mode, default 0.4). |
+| `date` | string | `'today'`, `'yesterday'`, `'last N days/weeks/months'`, `'YYYY-MM-DD'`, `'YYYY-MM'`, or `'YYYY-MM-DD to YYYY-MM-DD'`. |
+| `limit` | number | Max results (default 50). Applied **after** date filtering, so `date` + `limit` returns the newest results within the range. |
+| `role` | `"user" \| "assistant"` | Restrict message matches to one role. Title matches are always included. Ignored with `filePath`. |
+
+## Project scoping
+
+By default searches are scoped to the current project:
+
+- **Git repositories** → the project id is the git root's first-commit hash
+  (the same id OpenCode V2 uses).
+- **Non-git directories** → the location id plus the legacy `"global"` bucket,
+  so sessions from pre-migration (V1) installs are still found. On a fresh
+  install with no legacy sessions the `global` bucket simply matches nothing.
+
+`searchAllProjects: true` removes the project filter entirely.
+
+## Where it reads
+
+OpenCode's data directory, resolved the same way the OpenCode binary does:
+
+| Platform | Data directory |
+| --- | --- |
+| any | `$XDG_DATA_HOME/opencode` (if set) |
+| Linux | `~/.local/share/opencode` |
+| macOS | `~/Library/Application Support/opencode` |
+| Windows | `%LOCALAPPDATA%\opencode` |
+
+Database file: `$OPENCODE_DB` (absolute path or name inside the data dir) if
+set, else `opencode.db`, else the newest `opencode-<channel>.db` (OpenCode
+names the DB per channel on versioned installs). Everything is opened
+`readonly`.
+
+If the database contains an unexpected schema the tool returns an actionable
+error instead of raw SQL failures; on a machine without any OpenCode history
+yet it returns a friendly "no history found" message.
+
+## Privacy
+
+- Local only. No telemetry, no network access.
+- Read-only access to the session database.
+- Nothing is indexed or copied; queries run on demand against SQLite.
+
+## Requirements
+
+- OpenCode **V2** (the plugin runs inside OpenCode's bundled Bun runtime;
+  `bun:sqlite` is used directly, so there are no native dependencies to build).
+- Linux, macOS, or Windows.
+
+## Development
+
+```sh
+bun install
+bun test          # unit + integration tests (temp on-disk V2-schema DB)
+bunx tsc --noEmit
+bun run smoke-test.ts
+```
+
+Integration tests seed a temporary `XDG_DATA_HOME` with a real V2-schema
+database, so they never touch your actual history.
+
+## Behavior notes vs V1
+
+- Date filtering is applied **before** `limit` (V1 applied `limit` first, so a
+  small `limit` combined with a date filter could return "no matches").
+- Reads the V2 `session_v2` / `session_message` tables (parts are inline in
+  the message `data` JSON). The frozen legacy `session`/`message`/`part`
+  tables are not read: `session_v2` already contains every legacy session id.
+
+## Attribution & license
+
+Ported from [joeyism/opencode-history-search](https://github.com/joeyism/opencode-history-search)
+(MIT). Tool description and search semantics carry over; the storage layer was
+rewritten for the V2 schema. Dual copyright, see [LICENSE](./LICENSE).

package/index.ts

@@ -0,0 +1,248 @@
+import path from "path";
+import fs from "fs";
+import { Plugin } from "@opencode/plugin";
+import { searchKeyword } from "./src/search/keyword";
+import { searchFuzzy } from "./src/search/fuzzy";
+import { parseDateFilter, filterByDate } from "./src/search/date-filter";
+import { traceFile } from "./src/search/file-trace";
+import { searchMultiterm } from "./src/search/multiterm-sql";
+import { dbExists, getDbPath } from "./src/storage-sqlite";
+import { jsonStorageExists } from "./src/storage-provider";
+import {
+  formatResults,
+  formatTraceResults,
+  formatMultitermResults,
+} from "./src/format";
+import type { ProjectFilter } from "./src/storage-sqlite";
+
+interface HistorySearchArgs {
+  query?: string;
+  terms?: string[];
+  filePath?: string;
+  searchAllProjects?: boolean;
+  mode?: "keyword" | "fuzzy";
+  regex?: boolean;
+  caseSensitive?: boolean;
+  fuzzyThreshold?: number;
+  date?: string;
+  limit?: number;
+  role?: "user" | "assistant";
+}
+
+/**
+ * Walk up from `dir` looking for a `.git` entry (directory or file).
+ * Mirrors how V2 derives project ids: git worktrees get the repo's root
+ * commit hash, non-git directories get their own project id.
+ */
+function hasGitRoot(dir: string): boolean {
+  let d = dir;
+  for (let i = 0; i < 40; i++) {
+    try {
+      if (fs.existsSync(path.join(d, ".git"))) return true;
+    } catch {
+      return false;
+    }
+    const parent = path.dirname(d);
+    if (parent === d) return false;
+    d = parent;
+  }
+  return false;
+}
+
+/**
+ * Cap for searches that must run unbounded before a date filter is applied.
+ * Bounding the scan keeps worst-case cost finite while guaranteeing the date
+ * filter sees enough candidates that `limit` + `date` cannot starve it.
+ */
+const PRE_FILTER_LIMIT = 10_000;
+
+/**
+ * Apply the user's limit AFTER date filtering, so date + limit returns the
+ * newest `limit` results within the date range.
+ */
+function applyLimit<T>(results: T[], limit?: number): T[] {
+  return limit && limit > 0 ? results.slice(0, limit) : results;
+}
+
+export default Plugin.define({
+  id: "opencode-history-search-v2",
+
+  async setup(ctx) {
+    const locationProjectID: string = ctx.location.project.id;
+    const inGit = hasGitRoot(ctx.location.directory);
+
+    // Non-git locations: V2-era sessions live under the location's own
+    // project id, but every pre-migration session (V1 era, and early V2
+    // before per-directory projects existed) lives under the legacy
+    // "global" project. Search both so "current project only" covers the
+    // full history, matching what the V1 plugin searched.
+    const resolveProject = (allProjects: boolean): ProjectFilter => {
+      if (allProjects) return null;
+      return inGit ? [locationProjectID] : [locationProjectID, "global"];
+    };
+
+    await ctx.tool.transform((editor) => {
+      editor.add({
+        name: "history_search",
+        description: `Search through past conversation histories. Use searchAllProjects=true to search ALL projects on this machine. Searches session titles, message content, tool invocations, and file paths.
+
+THREE SEARCH MODES:
+1. SINGLE-TERM (query): Pass query for one search term. Returns per-part matches. Use mode: "fuzzy" for typos, regex: true for patterns.
+2. MULTI-TERM AND (terms): Pass terms: ["term1", "term2", ...] to find sessions containing ALL terms anywhere in the session (across title, messages, tools, file paths). Returns one result per session with per-term excerpts. Use when the user remembers multiple concepts (e.g., "find sessions about truck, vertex, and gemini"). Requires 2+ terms.
+3. FILE TRACE (filePath): Pass filePath to find which sessions created or modified a specific file.
+
+Supports keyword search, regex patterns, fuzzy search, multi-term AND search, date filtering, and role filtering.`,
+
+        input: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description:
+                "Search query (keyword, regex pattern, or fuzzy search term). Required unless filePath or terms is provided.",
+            },
+            terms: {
+              type: "array",
+              items: { type: "string" },
+              description:
+                'Array of terms for multi-term AND search. Returns sessions containing ALL terms anywhere in the session (title, messages, tools, file paths). Use when the user wants sessions matching multiple concepts (e.g., ["truck", "vertex", "gemini"]). Requires 2+ terms for multi-term path; 1 term falls back to single-term query. Case-insensitive substring matching.',
+            },
+            filePath: {
+              type: "string",
+              description:
+                "File path to trace touch history (e.g., 'src/auth.ts'). If provided, query, mode, regex, caseSensitive, fuzzyThreshold, and role are ignored.",
+            },
+            searchAllProjects: {
+              type: "boolean",
+              description:
+                "Set to true to search ALL projects on this machine across all repositories, not just the current one. Default: false (current repo only). Use when user asks to search globally, across all projects, machine-wide, or everywhere.",
+            },
+            mode: {
+              type: "string",
+              enum: ["keyword", "fuzzy"],
+              description:
+                "Search mode: 'keyword' for exact matches, 'fuzzy' for typo-tolerant matching (default: keyword)",
+            },
+            regex: {
+              type: "boolean",
+              description:
+                "Treat query as regex pattern (keyword mode only, default: false)",
+            },
+            caseSensitive: {
+              type: "boolean",
+              description:
+                "Case-sensitive search (keyword mode only, default: false)",
+            },
+            fuzzyThreshold: {
+              type: "number",
+              description:
+                "Fuzzy match threshold 0.0-1.0 (fuzzy mode only, default: 0.4, lower = stricter)",
+            },
+            date: {
+              type: "string",
+              description:
+                "Filter by date: 'today', 'yesterday', 'last N days/weeks/months', 'YYYY-MM-DD', 'YYYY-MM', 'YYYY-MM-DD to YYYY-MM-DD'",
+            },
+            limit: {
+              type: "number",
+              description:
+                "Maximum number of results (default: 50). Applied after date filtering, so date + limit returns the newest results within the date range.",
+            },
+            role: {
+              type: "string",
+              enum: ["user", "assistant"],
+              description:
+                "Filter by message role: 'user' for your messages only, 'assistant' for AI responses only. Ignored if filePath is provided.",
+            },
+          },
+          additionalProperties: false,
+        },
+
+        options: { codemode: true },
+
+        execute: async (rawArgs: unknown) => {
+          const args: HistorySearchArgs = {
+            ...((rawArgs as HistorySearchArgs) ?? {}),
+          };
+
+          if (!args.query && !args.filePath && !args.terms) {
+            throw new Error(
+              "Either 'query', 'terms', or 'filePath' must be provided.",
+            );
+          }
+
+          // Fresh install / empty history: answer cleanly instead of
+          // opening a database that does not exist yet.
+          if (!dbExists() && !jsonStorageExists()) {
+            return {
+              content: `No OpenCode history found yet (no session database at ${getDbPath()} and no legacy JSON storage detected). Once OpenCode has recorded sessions in this data directory, they will be searchable here.`,
+            };
+          }
+
+          if (args.terms !== undefined) {
+            if (!Array.isArray(args.terms) || args.terms.length === 0) {
+              throw new Error(
+                "'terms' must be a non-empty array of strings.",
+              );
+            }
+            if (args.terms.length === 1) {
+              args.query = args.terms[0];
+            } else {
+              const project = resolveProject(!!args.searchAllProjects);
+              let matches = await searchMultiterm(project, args.terms, {
+                limit: args.date ? PRE_FILTER_LIMIT : args.limit,
+              });
+              if (args.date) {
+                matches = filterByDate(matches, parseDateFilter(args.date));
+                matches = applyLimit(matches, args.limit);
+              }
+              return { content: formatMultitermResults(matches) };
+            }
+          }
+
+          const project = resolveProject(!!args.searchAllProjects);
+
+          if (args.filePath) {
+            let matches = await traceFile(project, args.filePath, {
+              limit: args.date ? PRE_FILTER_LIMIT : args.limit,
+            });
+
+            if (args.date) {
+              matches = filterByDate(matches, parseDateFilter(args.date));
+              matches = applyLimit(matches, args.limit);
+            }
+
+            return { content: formatTraceResults(matches) };
+          }
+
+          if (!args.query) {
+            throw new Error(
+              "'query' is required when 'filePath' is not provided.",
+            );
+          }
+
+          let matches =
+            args.mode === "fuzzy"
+              ? await searchFuzzy(project, args.query, {
+                  threshold: args.fuzzyThreshold,
+                  limit: args.date ? PRE_FILTER_LIMIT : args.limit,
+                  role: args.role,
+                })
+              : await searchKeyword(project, args.query, {
+                  regex: args.regex,
+                  caseSensitive: args.caseSensitive,
+                  limit: args.date ? PRE_FILTER_LIMIT : args.limit,
+                  role: args.role,
+                });
+
+          if (args.date) {
+            matches = filterByDate(matches, parseDateFilter(args.date));
+            matches = applyLimit(matches, args.limit);
+          }
+
+          return { content: formatResults(matches) };
+        },
+      });
+    });
+  },
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "opencode-history-search-v2",
+  "version": "1.0.0",
+  "description": "OpenCode V2 plugin: search past conversation sessions by keyword, fuzzy term, multi-term AND, or file touch history. Local, read-only, no network.",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "history",
+    "search",
+    "sqlite",
+    "memory"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marioschweiger/opencode-history-search-v2.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marioschweiger/opencode-history-search-v2/issues"
+  },
+  "homepage": "https://github.com/marioschweiger/opencode-history-search-v2#readme",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode/plugin": "^2.0.0"
+  },
+  "devDependencies": {
+    "@opencode/plugin": "^2.0.21",
+    "bun-types": "^1.4.2",
+    "typescript": "^5.9.0"
+  },
+  "dependencies": {
+    "fuse.js": "^7.1.0"
+  }
+}

package/src/format.ts

@@ -0,0 +1,97 @@
+import type { SearchMatch } from "./search/keyword";
+import type { FileTraceResult } from "./search/file-trace";
+import type { MultitermSearchMatch } from "./search/multiterm-sql";
+
+export function formatResults(matches: SearchMatch[]): string {
+  if (matches.length === 0) {
+    return "No matches found in conversation history.";
+  }
+
+  const lines: string[] = [
+    `Found ${matches.length} matches in conversation history:\n`,
+  ];
+
+  for (const match of matches) {
+    const date = new Date(match.timestamp).toISOString().split("T")[0];
+    const time = new Date(match.timestamp).toTimeString().split(" ")[0];
+
+    lines.push(`## ${match.sessionTitle}`);
+    lines.push(`- Session ID: ${match.sessionID}`);
+    lines.push(`- Project: ${match.projectDirectory}`);
+    lines.push(`- Date: ${date} ${time}`);
+    lines.push(`- Match Type: ${match.matchType}`);
+    lines.push(`- Excerpt: "${match.excerpt}"`);
+
+    if (match.context && match.context !== match.excerpt) {
+      lines.push(`- Context: ...${match.context}...`);
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export function formatTraceResults(matches: FileTraceResult[]): string {
+  if (matches.length === 0) {
+    return "No file trace matches found in conversation history.";
+  }
+
+  const lines: string[] = [
+    `Found ${matches.length} file trace matches in conversation history:\n`,
+  ];
+
+  for (const match of matches) {
+    const date = new Date(match.timestamp).toISOString().split("T")[0];
+    const time = new Date(match.timestamp).toTimeString().split(" ")[0];
+
+    lines.push(`## ${match.sessionTitle}`);
+    lines.push(`- Session ID: ${match.sessionID}`);
+    lines.push(`- Date: ${date} ${time}`);
+    lines.push(`- Status: ${match.firstTouch ? "First seen" : "Later touch"}`);
+    lines.push(`- File: ${match.filePath}`);
+    if (match.toolName) {
+      lines.push(`- Tool: ${match.toolName}`);
+    }
+
+    if (match.userPrompt) {
+      lines.push(`- Preceding User Prompt: "${match.userPrompt}"`);
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export function formatMultitermResults(matches: MultitermSearchMatch[]): string {
+  if (matches.length === 0) {
+    return "No sessions found in conversation history.";
+  }
+
+  const lines: string[] = [
+    `Found ${matches.length} sessions in conversation history:\n`,
+  ];
+
+  for (const match of matches) {
+    const date = new Date(match.timestamp).toISOString().split("T")[0];
+    const time = new Date(match.timestamp).toTimeString().split(" ")[0];
+
+    lines.push(`## ${match.sessionTitle}`);
+    lines.push(`- Session ID: ${match.sessionID}`);
+    lines.push(`- Project: ${match.projectDirectory}`);
+    lines.push(`- Date: ${date} ${time}`);
+
+    if (match.termHits.size > 0) {
+      const termList = Array.from(match.termHits.keys()).join(", ");
+      lines.push(`- Matched terms: ${termList}`);
+      for (const [term, hit] of match.termHits) {
+        lines.push(`  - ${term}: ${hit.excerpt}`);
+      }
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/paths.ts

@@ -0,0 +1,87 @@
+import path from "path";
+import os from "os";
+import fs from "fs";
+
+/**
+ * Cross-platform resolution of OpenCode's data directory and session
+ * database file. Mirrors the logic in the OpenCode binary itself:
+ *
+ *   data dir:  $XDG_DATA_HOME (any platform)
+ *              darwin:  ~/Library/Application Support
+ *              linux:   ~/.local/share
+ *              win32:   %LOCALAPPDATA%
+ *   then the "opencode" subdirectory.
+ *
+ *   db file:   $OPENCODE_DB (absolute path or file name, overrides)
+ *              else `opencode.db`
+ *              else the newest `opencode-<channel>.db` in the data dir
+ *              (OpenCode names the DB per channel on versioned installs)
+ *              else `opencode.db` (may not exist yet; callers handle it)
+ */
+
+export function getDataDir(
+  platform: string = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const xdg = env.XDG_DATA_HOME;
+  if (xdg) return path.join(xdg, "opencode");
+  switch (platform) {
+    case "darwin":
+      return path.join(
+        os.homedir(),
+        "Library",
+        "Application Support",
+        "opencode",
+      );
+    case "win32": {
+      const local =
+        env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+      return path.join(local, "opencode");
+    }
+    default:
+      return path.join(os.homedir(), ".local", "share", "opencode");
+  }
+}
+
+export function resolveDbFile(
+  dataDir: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const override = env.OPENCODE_DB;
+  if (override) {
+    return path.isAbsolute(override)
+      ? override
+      : path.join(dataDir, override);
+  }
+
+  const stable = path.join(dataDir, "opencode.db");
+  if (fs.existsSync(stable)) return stable;
+
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(dataDir);
+  } catch {
+    return stable;
+  }
+
+  let best: string | null = null;
+  let bestMtime = 0;
+  for (const name of entries) {
+    if (!/^opencode-[^/\\]+\.db$/.test(name)) continue;
+    const full = path.join(dataDir, name);
+    try {
+      const mtime = fs.statSync(full).mtimeMs;
+      if (mtime > bestMtime) {
+        bestMtime = mtime;
+        best = full;
+      }
+    } catch {
+      // unreadable entry, skip
+    }
+  }
+  return best ?? stable;
+}
+
+export function getDbPath(): string {
+  return resolveDbFile(getDataDir());
+}