opencode-session-recall 0.7.0 → 0.8.0

package/README.md

@@ -1,26 +1,77 @@
 # opencode-session-recall
 
-A plugin for [opencode](https://github.com/opencode-ai/opencode) that gives your agent a memory that survives compaction — without building another memory system.
+**Every conversation your agent has ever had — across every session, every project — is already in the database. It's just not looking.**
 
-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](https://github.com/opencode-ai/opencode) stores the full conversation history from every session your agent has ever run — messages, tool calls, tool outputs, reasoning traces. All of it. Not just the current session. Not just the current project. Every project on the machine. Even after compaction shrinks what the model can see, the original content stays in the database — just no longer visible to the agent.
 
-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.
+This plugin gives the agent five tools to search and retrieve all of it on demand.
 
-**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 new database.**
+**No embeddings.**
+**No summarization.**
+**No duplication.**
+**No overhead.**
 
-No embeddings. No vector store. No data duplication. No setup. Just install the plugin and the agent can remember.
+Just install the plugin. The agent gains access to its entire history.
 
-## What this enables
+## The problem is absurd when you think about it
 
-**"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.
+Your agent solves a tricky build error. Twenty minutes later, compaction runs. An hour later, the same error shows up. The agent starts from zero — debugging something it already figured out, while the answer sits in the database it's connected to.
 
-**"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.
+You built rate-limiting middleware in your API project last week. Now you need it in another project. The agent has no idea it ever existed — while the original implementation, the requirements discussion, the edge cases you worked through, all of it is sitting in the same database, in a session from a different 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.
+You're 200 tool calls and 3 compactions deep. The agent has drifted from your original request. Your exact words are gone from context. But they're not gone — they're in the database. The agent just can't see them.
 
-**"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.
+The data already exists. This plugin removes the blindfold.
 
-**"Show me what happened."** Browse any session chronologically, play back the conversation, understand the narrative of how a problem was investigated and solved.
+## What it looks like
+
+**"We already fixed this."**
+
+```
+recall({ query: "ECONNREFUSED retry", scope: "session" })
+```
+
+Agent finds its own solution from 2 hours ago. Doesn't re-derive it.
+
+**"It was in that other project."**
+
+```
+recall_sessions({ scope: "global", search: "rate limit" })
+recall_get({ sessionID: "...", messageID: "..." })
+```
+
+Finds the implementation from your API project. Reuses it instead of reinventing it.
+
+**"What did I originally ask for?"**
+
+```
+recall_messages({ limit: 5, role: "user" })
+```
+
+Pulls up exact original requirements after 3 compactions. Checks its own work against what you actually said.
+
+**"What was that error?"**
+
+```
+recall({ query: "TypeError", type: "tool", scope: "session" })
+```
+
+Gets the full stack trace from a tool output that got pruned. Doesn't re-run the failing command.
+
+**"Why did we decide on that approach?"**
+
+```
+recall({ query: "chose postgres over", scope: "project", type: "reasoning" })
+```
+
+Recovers the reasoning behind an architectural decision from three sessions ago. Context that no summary captures.
+
+## Recall is not memory
+
+This is not a memory system. Memory is selective and curated. Recall is raw history retrieval — verbatim, exhaustive, on demand.
+
+If you use a persistent memory system alongside this plugin, recall gives it source material. The agent searches history, finds something useful, and stores it deliberately. Discovery first, then permanent memory.
 
 ## Install
 
@@ -28,16 +79,19 @@ No embeddings. No vector store. No data duplication. No setup. Just install the
 opencode plugin opencode-session-recall
 ```
 
-Or add it to your `opencode.json` manually:
+Or add it to your `opencode.json`:
 
 ```jsonc
 {
-  "plugin": [
-    "opencode-session-recall",
+  "plugin": ["opencode-session-recall"],
+}
+```
+
+To disable cross-project search:
 
-    // Disable cross-project search if needed
-    ["opencode-session-recall", { "global": false }],
-  ],
+```jsonc
+{
+  "plugin": [["opencode-session-recall", { "global": false }]],
 }
 ```
 
@@ -47,25 +101,25 @@ 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.
+The primary tool. Full-text search across messages, tool outputs, tool inputs, reasoning, and subtask descriptions. Searches globally by default, or narrow to the current project or session.
 
 ```
 recall({ query: "authentication", scope: "project" })
-recall({ query: "error", after: <2 days ago>, type: "tool" })
+recall({ query: "error", type: "tool", scope: "session" })
 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                         |
+| Param            | Default    | Description                                   |
+| ---------------- | ---------- | --------------------------------------------- |
+| `query`          | required   | Text to search for (case-insensitive)         |
+| `scope`          | `"global"` | `"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
 
@@ -107,29 +161,6 @@ 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                                         |
@@ -139,13 +170,13 @@ Five tool calls, complete narrative reconstructed across projects.
 
 ## 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.
 
-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.
+This plugin reads all of it through the OpenCode SDK:
 
-- Uses the opencode SDK client (no direct database queries, no separate storage)
+- 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
+- Sessions scanned newest-first with bounded concurrency
 - Respects abort signals for long-running searches
 - Cross-project search enabled by default (disable with `global: false`)
 

package/dist/candidates.d.ts

@@ -0,0 +1,54 @@
+import type { Part } from "@opencode-ai/sdk/v2";
+export type SessionMeta = {
+    id: string;
+    title: string;
+    directory: string;
+};
+export type MsgInfo = {
+    id: string;
+    role: "user" | "assistant";
+    time: {
+        created: number;
+    };
+};
+export type Candidate = {
+    sessionID: string;
+    sessionTitle: string;
+    directory: string;
+    messageID: string;
+    role: "user" | "assistant";
+    time: number;
+    partID: string;
+    partType: string;
+    isPruned: boolean;
+    toolName?: string;
+    rawText: string;
+    tokens: string[];
+    primaryText?: string;
+    secondaryText?: string;
+    titleText?: string;
+    hintText?: string;
+};
+export type CandidateBudgets = {
+    maxMessagesPerSession: number;
+    maxPartsPerSession: number;
+    maxCharsPerCandidate: number;
+    maxCharsTotal: number;
+    maxCandidatesPerSession: number;
+    maxCandidatesTotal: number;
+};
+export declare const DEFAULT_BUDGETS: CandidateBudgets;
+/** Build candidates from a single session's messages. Returns candidates and budget tracking info. */
+export declare function buildCandidates(messages: Array<{
+    info: MsgInfo;
+    parts: Part[];
+}>, session: SessionMeta, budgets: CandidateBudgets, type: string, role: string, before?: number, after?: number): {
+    candidates: Candidate[];
+    messagesProcessed: number;
+    partsProcessed: number;
+    charsUsed: number;
+    budgetHit: boolean;
+};
+/** Populate stage-2 normalized fields on a candidate (mutates in place). */
+export declare function populateNormalized(candidate: Candidate): void;
+//# sourceMappingURL=candidates.d.ts.map

package/dist/candidates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../src/candidates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAIhD,MAAM,MAAM,WAAW,GAAG;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IAEtB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAGhB,MAAM,EAAE,MAAM,EAAE,CAAC;IAGjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,uBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAkB,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,gBAO7B,CAAC;AAEF,sGAAsG;AACtG,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,IAAI,EAAE,CAAA;CAAE,CAAC,EACjD,OAAO,EAAE,WAAW,EACpB,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb;IACD,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;CACpB,CAkGA;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAU7D"}

package/dist/fuse.d.ts

@@ -0,0 +1,23 @@
+import type { Candidate } from "./candidates.js";
+import type { ParsedQuery } from "./query.js";
+/** Match modes supported by Fuse.js (excludes "literal" which bypasses Fuse) */
+type FuseMode = "smart" | "fuzzy";
+export type FuseHit = {
+    candidate: Candidate;
+    /** 0 = perfect match, 1 = worst (raw from Fuse.js) */
+    fuseScore: number;
+    /** Inverted: 1 = perfect match, 0 = worst (for our ranking) */
+    normalizedScore: number;
+};
+/** Fuse.js threshold for smart mode (conservative) */
+export declare const SMART_THRESHOLD = 0.3;
+/** Fuse.js threshold for fuzzy mode (looser) */
+export declare const FUZZY_THRESHOLD = 0.5;
+/**
+ * Run Fuse.js search over pre-normalized candidates.
+ * Candidates MUST have stage-2 fields populated (primaryText etc.) before calling.
+ * Returns ALL matches above threshold so callers can compute accurate totals.
+ */
+export declare function fuseSearch(candidates: Candidate[], query: ParsedQuery, mode: FuseMode): FuseHit[];
+export {};
+//# sourceMappingURL=fuse.d.ts.map

package/dist/fuse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuse.d.ts","sourceRoot":"","sources":["../src/fuse.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C,gFAAgF;AAChF,KAAK,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAElC,MAAM,MAAM,OAAO,GAAG;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,sDAAsD;IACtD,SAAS,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,gDAAgD;AAChD,eAAO,MAAM,eAAe,MAAM,CAAC;AAanC;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,SAAS,EAAE,EACvB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,QAAQ,GACb,OAAO,EAAE,CAwBX"}

package/dist/normalize.d.ts

@@ -0,0 +1,7 @@
+/** Split camelCase/PascalCase at lowercase→uppercase boundaries */
+export declare function splitCamelCase(text: string): string;
+/** Stage 1: extract lightweight tokens from raw text for prefiltering */
+export declare function tokenize(text: string): string[];
+/** Stage 2: produce a fully normalized string for Fuse.js weighted fields */
+export declare function normalize(text: string): string;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../src/normalize.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,yEAAyE;AACzE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAM/C;AAED,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9C"}

package/dist/opencode-session-recall.js

@@ -267,7 +267,481 @@ function formatMsg(msg) {
   };
 }
 
+// src/normalize.ts
+function splitCamelCase(text) {
+  return text.replace(/([a-z])([A-Z])/g, "$1 $2");
+}
+function tokenize(text) {
+  const separated = text.replace(/[_\-/.]/g, " ");
+  const camelSplit = splitCamelCase(separated);
+  const lowered = camelSplit.toLowerCase();
+  const tokens = lowered.split(/\s+/).filter((t) => t.length > 0);
+  return [...new Set(tokens)];
+}
+function normalize(text) {
+  const separated = text.replace(/[_\-/.]/g, " ");
+  const camelSplit = splitCamelCase(separated);
+  const lowered = camelSplit.toLowerCase();
+  return lowered.replace(/\s+/g, " ").trim();
+}
+
+// src/query.ts
+var QUOTED_PHRASE_RE = /"([^"]*)"/g;
+function parseQuery(query) {
+  const raw = query;
+  const lower = raw.toLowerCase();
+  const phrases = [];
+  let remaining = raw;
+  for (const match of raw.matchAll(QUOTED_PHRASE_RE)) {
+    const content = match[1]?.toLowerCase().trim();
+    if (content) {
+      phrases.push(content);
+    }
+  }
+  remaining = remaining.replace(QUOTED_PHRASE_RE, " ");
+  const phraseTokens = phrases.flatMap((p) => tokenize(p));
+  const remainingTokens = tokenize(remaining);
+  const tokens = [.../* @__PURE__ */ new Set([...phraseTokens, ...remainingTokens])];
+  return {
+    raw,
+    lower,
+    tokens,
+    phrases
+  };
+}
+
+// src/candidates.ts
+var DEFAULT_BUDGETS = {
+  maxMessagesPerSession: 1e3,
+  maxPartsPerSession: 5e3,
+  maxCharsPerCandidate: 2e4,
+  maxCharsTotal: 2e6,
+  maxCandidatesPerSession: 500,
+  maxCandidatesTotal: 3e3
+};
+function buildCandidates(messages2, session, budgets, type, role, before, after) {
+  const candidates = [];
+  let messagesProcessed = 0;
+  let partsProcessed = 0;
+  let charsUsed = 0;
+  let budgetHit = false;
+  for (let mi = messages2.length - 1; mi >= 0; mi--) {
+    if (messagesProcessed >= budgets.maxMessagesPerSession) {
+      budgetHit = true;
+      break;
+    }
+    const msg = messages2[mi];
+    const info = msg.info;
+    if (role !== "all" && info.role !== role) continue;
+    if (before != null && info.time.created >= before) continue;
+    if (after != null && info.time.created <= after) continue;
+    messagesProcessed++;
+    for (const part of msg.parts) {
+      if (partsProcessed >= budgets.maxPartsPerSession) {
+        budgetHit = true;
+        break;
+      }
+      if (type !== "all" && part.type !== type) {
+        continue;
+      }
+      partsProcessed++;
+      const texts = searchable(part);
+      if (texts.length === 0) continue;
+      let rawText = texts.join("\n\n");
+      if (rawText.length > budgets.maxCharsPerCandidate) {
+        rawText = rawText.slice(0, budgets.maxCharsPerCandidate);
+      }
+      if (charsUsed + rawText.length > budgets.maxCharsTotal) {
+        budgetHit = true;
+        break;
+      }
+      charsUsed += rawText.length;
+      const candidate = {
+        sessionID: session.id,
+        sessionTitle: session.title,
+        directory: session.directory,
+        messageID: info.id,
+        role: info.role,
+        time: info.time.created,
+        partID: part.id,
+        partType: part.type,
+        isPruned: pruned(part),
+        rawText,
+        tokens: tokenize(rawText)
+      };
+      if (part.type === "tool") {
+        candidate.toolName = part.tool;
+      }
+      candidates.push(candidate);
+      if (candidates.length >= budgets.maxCandidatesPerSession) {
+        budgetHit = true;
+        break;
+      }
+    }
+    if (partsProcessed >= budgets.maxPartsPerSession || charsUsed >= budgets.maxCharsTotal || candidates.length >= budgets.maxCandidatesPerSession) {
+      break;
+    }
+  }
+  return {
+    candidates,
+    messagesProcessed,
+    partsProcessed,
+    charsUsed,
+    budgetHit
+  };
+}
+function populateNormalized(candidate) {
+  candidate.primaryText = normalize(candidate.rawText);
+  candidate.secondaryText = candidate.directory ? normalize(candidate.directory) : "";
+  candidate.titleText = candidate.sessionTitle ? normalize(candidate.sessionTitle) : "";
+  candidate.hintText = candidate.toolName ? normalize(candidate.toolName) : "";
+}
+
+// src/prefilter.ts
+import { distance } from "fastest-levenshtein";
+function tokenMatches(qt, candidateTokens) {
+  for (const ct of candidateTokens) {
+    if (ct.includes(qt)) return "exact";
+  }
+  if (qt.length >= 4) {
+    for (const ct of candidateTokens) {
+      if (Math.abs(ct.length - qt.length) > 1) continue;
+      if (distance(qt, ct) <= 1) return "typo";
+    }
+  }
+  return "none";
+}
+function prefilterScore(candidate, query) {
+  const rawLower = candidate.rawText.toLowerCase();
+  let score = 0;
+  if (rawLower.includes(query.lower)) {
+    score += 100;
+  }
+  for (const phrase of query.phrases) {
+    if (rawLower.includes(phrase)) {
+      score += 30;
+    }
+  }
+  let allMatched = true;
+  for (const qt of query.tokens) {
+    const result = tokenMatches(qt, candidate.tokens);
+    if (result === "exact") {
+      score += 10;
+    } else if (result === "typo") {
+      score += 3;
+    } else {
+      allMatched = false;
+    }
+  }
+  if (query.tokens.length > 0 && allMatched) {
+    score += 20;
+  }
+  return score;
+}
+function prefilter(candidates, query) {
+  const results = [];
+  for (const candidate of candidates) {
+    const score = prefilterScore(candidate, query);
+    if (score > 0) {
+      results.push({ candidate, prefilterScore: score });
+    }
+  }
+  return results;
+}
+
+// src/fuse.ts
+import Fuse from "fuse.js";
+var SMART_THRESHOLD = 0.3;
+var FUZZY_THRESHOLD = 0.5;
+var KEYS = [
+  { name: "primaryText", weight: 0.65 },
+  { name: "secondaryText", weight: 0.2 },
+  { name: "titleText", weight: 0.1 },
+  { name: "hintText", weight: 0.05 }
+];
+function thresholdFor(mode) {
+  return mode === "smart" ? SMART_THRESHOLD : FUZZY_THRESHOLD;
+}
+function fuseSearch(candidates, query, mode) {
+  const fuse = new Fuse(candidates, {
+    includeScore: true,
+    ignoreLocation: true,
+    ignoreFieldNorm: true,
+    shouldSort: true,
+    includeMatches: false,
+    threshold: thresholdFor(mode),
+    keys: KEYS
+  });
+  const normalizedQuery = normalize(query.raw);
+  const results = fuse.search(normalizedQuery);
+  return results.map((result) => {
+    const fuseScore = result.score ?? 1;
+    return {
+      candidate: result.item,
+      fuseScore,
+      normalizedScore: 1 - fuseScore
+    };
+  });
+}
+
+// src/rank.ts
+import { distance as distance2 } from "fastest-levenshtein";
+var EXACT_PHRASE_BOOST = 0.15;
+var ALL_TOKENS_BOOST = 0.1;
+var REASONING_BOOST = 0.05;
+var ERROR_TEXT_BOOST = 0.05;
+var USER_ROLE_BOOST = 0.03;
+var RECENCY_BOOST_MAX = 0.05;
+var RECENCY_WINDOW_MS = 7 * 24 * 60 * 60 * 1e3;
+var WEAK_FUZZY_PENALTY = -0.1;
+var WEAK_FUZZY_THRESHOLD = 0.7;
+var POOR_COVERAGE_PENALTY = -0.08;
+var MAX_PREFILTER_SCORE = 150;
+var ERROR_PATTERNS = ["error", "failed", "exception"];
+function containsErrorPattern(text) {
+  const lower = text.toLowerCase();
+  return ERROR_PATTERNS.some((p) => lower.includes(p));
+}
+function clamp01(value) {
+  return Math.max(0, Math.min(1, value));
+}
+function recencyBoost(time) {
+  const ageMs = Date.now() - time;
+  const factor = Math.max(0, 1 - ageMs / RECENCY_WINDOW_MS);
+  return factor * RECENCY_BOOST_MAX;
+}
+function findMatchedTerms(queryTokens, candidateTokens) {
+  const matched = [];
+  for (const qt of queryTokens) {
+    const exactFound = candidateTokens.some((ct) => ct.includes(qt));
+    if (exactFound) {
+      matched.push(qt);
+      continue;
+    }
+    if (qt.length >= 4) {
+      const typoFound = candidateTokens.some(
+        (ct) => Math.abs(ct.length - qt.length) <= 1 && distance2(qt, ct) <= 1
+      );
+      if (typoFound) {
+        matched.push(qt);
+      }
+    }
+  }
+  return matched;
+}
+function sortResults(results) {
+  return results.sort((a, b) => {
+    const scoreDiff = b.score - a.score;
+    if (scoreDiff !== 0) return scoreDiff;
+    return b.candidate.time - a.candidate.time;
+  });
+}
+function rank(hits, query, explain) {
+  const results = [];
+  for (const hit of hits) {
+    const { candidate, normalizedScore } = hit;
+    let score = normalizedScore;
+    const reasons = [];
+    if (explain) {
+      reasons.push(`Fuse.js base score: ${normalizedScore.toFixed(2)}`);
+    }
+    const rawLower = candidate.rawText.toLowerCase();
+    let hasExactPhrase = false;
+    for (const phrase of query.phrases) {
+      if (rawLower.includes(phrase)) {
+        hasExactPhrase = true;
+        break;
+      }
+    }
+    if (hasExactPhrase) {
+      score += EXACT_PHRASE_BOOST;
+      if (explain) {
+        reasons.push(`Exact phrase match: +${EXACT_PHRASE_BOOST.toFixed(2)}`);
+      }
+    }
+    const matchedTerms = findMatchedTerms(query.tokens, candidate.tokens);
+    const allTokensMatched = query.tokens.length > 0 && matchedTerms.length === query.tokens.length;
+    if (allTokensMatched) {
+      score += ALL_TOKENS_BOOST;
+      if (explain) {
+        reasons.push(
+          `All query tokens matched: +${ALL_TOKENS_BOOST.toFixed(2)}`
+        );
+      }
+    }
+    if (candidate.partType === "reasoning") {
+      score += REASONING_BOOST;
+      if (explain) {
+        reasons.push(`Reasoning part boost: +${REASONING_BOOST.toFixed(2)}`);
+      }
+    }
+    if (candidate.partType === "tool" && containsErrorPattern(candidate.rawText)) {
+      score += ERROR_TEXT_BOOST;
+      if (explain) {
+        reasons.push(`Error text boost: +${ERROR_TEXT_BOOST.toFixed(2)}`);
+      }
+    }
+    if (candidate.role === "user") {
+      score += USER_ROLE_BOOST;
+      if (explain) {
+        reasons.push(`User text boost: +${USER_ROLE_BOOST.toFixed(2)}`);
+      }
+    }
+    const recency = recencyBoost(candidate.time);
+    if (recency > 0) {
+      score += recency;
+      if (explain) {
+        reasons.push(`Recency boost: +${recency.toFixed(2)}`);
+      }
+    }
+    if (matchedTerms.length === 1 && query.tokens.length === 1 && normalizedScore < WEAK_FUZZY_THRESHOLD) {
+      score += WEAK_FUZZY_PENALTY;
+      if (explain) {
+        reasons.push(
+          `Weak single-token fuzzy: ${WEAK_FUZZY_PENALTY.toFixed(2)}`
+        );
+      }
+    }
+    if (query.tokens.length > 1 && matchedTerms.length < query.tokens.length / 2) {
+      score += POOR_COVERAGE_PENALTY;
+      if (explain) {
+        reasons.push(
+          `Poor query coverage: ${POOR_COVERAGE_PENALTY.toFixed(2)}`
+        );
+      }
+    }
+    score = clamp01(score);
+    results.push({
+      candidate,
+      score,
+      matchedTerms,
+      matchReasons: explain ? reasons : []
+    });
+  }
+  return sortResults(results);
+}
+function rankDegraded(candidates, query, explain) {
+  const results = [];
+  for (const entry of candidates) {
+    const { candidate, prefilterScore: prefilterScore2 } = entry;
+    const reasons = [];
+    let score = Math.min(1, prefilterScore2 / MAX_PREFILTER_SCORE);
+    if (explain) {
+      reasons.push(
+        `Degraded mode: prefilter score ${prefilterScore2} \u2192 ${score.toFixed(2)}`
+      );
+    }
+    const recency = recencyBoost(candidate.time);
+    if (recency > 0) {
+      score += recency;
+      if (explain) {
+        reasons.push(`Recency boost: +${recency.toFixed(2)}`);
+      }
+    }
+    score = clamp01(score);
+    const matchedTerms = findMatchedTerms(query.tokens, candidate.tokens);
+    results.push({
+      candidate,
+      score,
+      matchedTerms,
+      matchReasons: explain ? reasons : []
+    });
+  }
+  return sortResults(results);
+}
+
+// src/snippet.ts
+function frame(text, start, end, fullLength) {
+  let result = text;
+  if (start > 0) result = "..." + result;
+  if (end < fullLength) result = result + "...";
+  return result;
+}
+function headSlice(rawText, width) {
+  if (rawText.length <= width) return rawText;
+  return rawText.slice(0, width) + "...";
+}
+function extractWindow(rawText, idealStart, width) {
+  const start = Math.max(0, Math.min(idealStart, rawText.length - width));
+  const end = Math.min(rawText.length, start + width);
+  return frame(rawText.slice(start, end), start, end, rawText.length);
+}
+function findAllPositions(haystack, needle) {
+  const positions = [];
+  const lowerHaystack = haystack.toLowerCase();
+  const lowerNeedle = needle.toLowerCase();
+  if (lowerNeedle.length === 0) return positions;
+  let idx = 0;
+  while (idx <= lowerHaystack.length - lowerNeedle.length) {
+    const found = lowerHaystack.indexOf(lowerNeedle, idx);
+    if (found === -1) break;
+    positions.push(found);
+    idx = found + 1;
+  }
+  return positions;
+}
+function smartSnippet(rawText, query, width = 200) {
+  if (rawText.length === 0) return "";
+  if (rawText.length <= width) return rawText;
+  const allPositions = [];
+  for (const token of query.tokens) {
+    const positions = findAllPositions(rawText, token);
+    for (const position of positions) {
+      allPositions.push({ token, position });
+    }
+  }
+  for (const phrase of query.phrases) {
+    const positions = findAllPositions(rawText, phrase);
+    for (const position of positions) {
+      allPositions.push({ token: phrase, position });
+    }
+  }
+  if (allPositions.length === 0) {
+    return headSlice(rawText, width);
+  }
+  allPositions.sort((a, b) => a.position - b.position);
+  let bestStart = allPositions[0].position;
+  let bestDistinct = 0;
+  let bestSpread = Infinity;
+  for (const { position: windowStart } of allPositions) {
+    const seen = /* @__PURE__ */ new Set();
+    let minPos = Infinity;
+    let maxPos = -Infinity;
+    for (const { token, position } of allPositions) {
+      if (position >= windowStart && position <= windowStart + width) {
+        seen.add(token);
+        minPos = Math.min(minPos, position);
+        maxPos = Math.max(maxPos, position);
+      }
+    }
+    const distinct = seen.size;
+    const spread = maxPos - minPos;
+    if (distinct > bestDistinct || distinct === bestDistinct && spread < bestSpread) {
+      bestDistinct = distinct;
+      bestSpread = spread;
+      bestStart = windowStart;
+    }
+  }
+  const tokensInWindow = [];
+  for (const { position } of allPositions) {
+    if (position >= bestStart && position <= bestStart + width) {
+      tokensInWindow.push(position);
+    }
+  }
+  if (tokensInWindow.length > 0) {
+    const minPos = tokensInWindow[0];
+    const maxPos = tokensInWindow[tokensInWindow.length - 1];
+    const midpoint = Math.floor((minPos + maxPos) / 2);
+    const idealStart = midpoint - Math.floor(width / 2);
+    return extractWindow(rawText, idealStart, width);
+  }
+  return extractWindow(rawText, bestStart, width);
+}
+
 // src/search.ts
+var PROMOTED_SCOPES = /* @__PURE__ */ new Set(["session"]);
+var TIME_BUDGET_MS = 2e3;
+var PREFUSE_BUDGET_MS = 1500;
 function meta(s) {
   return { id: s.id, title: s.title, directory: s.directory };
 }
@@ -310,6 +784,120 @@ function scan(messages2, session, query, type, role, limit, before, after, width
   }
   return { results, total };
 }
+function smartScan(allMessages, query, type, role, limit, explain, mode, before, after, width) {
+  const pq = parseQuery(query);
+  const startTime = performance.now();
+  const allCandidates = [];
+  let totalCharsUsed = 0;
+  let anyBudgetHit = false;
+  for (const { session, messages: messages2 } of allMessages) {
+    const { candidates, charsUsed, budgetHit } = buildCandidates(
+      messages2,
+      session,
+      {
+        ...DEFAULT_BUDGETS,
+        maxCharsTotal: DEFAULT_BUDGETS.maxCharsTotal - totalCharsUsed
+      },
+      type,
+      role,
+      before,
+      after
+    );
+    allCandidates.push(...candidates);
+    totalCharsUsed += charsUsed;
+    if (budgetHit) anyBudgetHit = true;
+    if (allCandidates.length >= DEFAULT_BUDGETS.maxCandidatesTotal) {
+      allCandidates.length = DEFAULT_BUDGETS.maxCandidatesTotal;
+      anyBudgetHit = true;
+      break;
+    }
+  }
+  let filtered = prefilter(allCandidates, pq);
+  if (filtered.length > DEFAULT_BUDGETS.maxCandidatesTotal) {
+    filtered.sort((a, b) => b.prefilterScore - a.prefilterScore);
+    filtered = filtered.slice(0, DEFAULT_BUDGETS.maxCandidatesTotal);
+    anyBudgetHit = true;
+  }
+  const prefuseTime = performance.now() - startTime;
+  if (prefuseTime > PREFUSE_BUDGET_MS) {
+    const ranked2 = rankDegraded(filtered, pq, explain);
+    const results2 = rankedToSearchResults(
+      ranked2.slice(0, limit),
+      mode,
+      explain,
+      pq,
+      width
+    );
+    return {
+      results: results2,
+      total: filtered.length,
+      degradeKind: "time",
+      matchMode: mode
+    };
+  }
+  for (const { candidate } of filtered) {
+    populateNormalized(candidate);
+  }
+  const fuseCandidates = filtered.map((f) => f.candidate);
+  const hits = fuseSearch(fuseCandidates, pq, mode);
+  const totalTime = performance.now() - startTime;
+  const ranked = rank(hits, pq, explain);
+  const fuseTotal = ranked.length;
+  if (totalTime > TIME_BUDGET_MS) {
+    const results2 = rankedToSearchResults(
+      ranked.slice(0, limit),
+      mode,
+      explain,
+      pq,
+      width
+    );
+    return {
+      results: results2,
+      total: fuseTotal,
+      degradeKind: "time",
+      matchMode: mode
+    };
+  }
+  const results = rankedToSearchResults(
+    ranked.slice(0, limit),
+    mode,
+    explain,
+    pq,
+    width
+  );
+  return {
+    results,
+    total: fuseTotal,
+    degradeKind: anyBudgetHit ? "budget" : "none",
+    matchMode: mode
+  };
+}
+function rankedToSearchResults(ranked, mode, explain, query, width) {
+  return ranked.map((r) => {
+    const c = r.candidate;
+    const snip = smartSnippet(c.rawText, query, width);
+    const result = {
+      sessionID: c.sessionID,
+      sessionTitle: c.sessionTitle,
+      directory: c.directory,
+      messageID: c.messageID,
+      role: c.role,
+      time: c.time,
+      partID: c.partID,
+      partType: c.partType,
+      pruned: c.isPruned,
+      snippet: snip,
+      toolName: c.toolName,
+      score: r.score,
+      matchMode: mode,
+      matchedTerms: r.matchedTerms
+    };
+    if (explain && r.matchReasons.length > 0) {
+      result.matchReasons = r.matchReasons;
+    }
+    return result;
+  });
+}
 function search(client, unscoped, global, limits) {
   return tool2({
     description: `Search your conversation history in the opencode database. This is the primary discovery tool \u2014 use it before recall_sessions, which only searches titles. Before debugging an issue or implementing a feature, check whether prior sessions already tackled it \u2014 the history shows whether an approach succeeded or was abandoned. If you have access to a memory system, add useful findings to memory so they're available directly next time without searching history.
@@ -322,12 +910,20 @@ Scope costs: all scopes scan up to \`sessions\` sessions (default 10). "session"
 
 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.
 
-This tool's own outputs are excluded from search results to prevent recursive noise; use recall_get or recall_context to retrieve any message directly.`,
+This tool's own outputs are excluded from search results to prevent recursive noise; use recall_get or recall_context to retrieve any message directly.
+
+Use match:"smart" for fuzzy search when exact wording is uncertain \u2014 it handles typos, separator differences (rate-limit vs rateLimit), and ranks results by relevance. Currently available for scope:"session" only.`,
     args: {
       query: tool2.schema.string().min(1).describe("Text to search for (case-insensitive substring match)"),
       scope: tool2.schema.enum(["session", "project", "global"]).default("global").describe(
         "global = all projects (default), project = current project, session = current only. Searching broadly is fast."
       ),
+      match: tool2.schema.enum(["literal", "smart", "fuzzy"]).default("literal").describe(
+        'Matching strategy: "literal" = exact substring (default), "smart" = fuzzy ranked search (session scope only), "fuzzy" = looser fuzzy search (session scope only)'
+      ),
+      explain: tool2.schema.boolean().default(false).describe(
+        "Return scoring metadata for debugging. Adds matchReasons to each result."
+      ),
       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"),
@@ -347,7 +943,20 @@ This tool's own outputs are excluded from search results to prevent recursive no
       )
     },
     async execute(args, ctx) {
-      ctx.metadata({ title: `Searching ${args.scope} for "${args.query}"` });
+      const matchMode = args.match;
+      ctx.metadata({
+        title: `Searching ${args.scope} for "${args.query}"${matchMode !== "literal" ? ` (${matchMode})` : ""}`
+      });
+      if (matchMode !== "literal") {
+        const effectiveScope = args.sessionID ? "session" : args.scope;
+        if (!PROMOTED_SCOPES.has(effectiveScope)) {
+          const err = {
+            ok: false,
+            error: `match:"${matchMode}" is not yet available for scope:"${effectiveScope}". Try scope:"session" or use match:"literal" for broader searches.`
+          };
+          return JSON.stringify(err);
+        }
+      }
       if (args.scope === "global" && !args.sessionID && !global) {
         const err = {
           ok: false,
@@ -410,36 +1019,43 @@ This tool's own outputs are excluded from search results to prevent recursive no
           }
           if (resp.data) targets = resp.data.map(meta);
         }
-        const collected = [];
+        const allLoaded = [];
         let scanned = 0;
-        let total = 0;
-        let early = false;
         for (let i = 0; i < targets.length; i += limits.concurrency) {
-          if (ctx.abort.aborted) {
-            early = true;
-            break;
-          }
-          if (collected.length >= args.results) {
-            early = true;
-            break;
-          }
-          const remaining = args.results - collected.length;
+          if (ctx.abort.aborted) break;
           const batch = targets.slice(i, i + limits.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 ?? [] };
+                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) {
+          allLoaded.push(...loaded);
+          scanned += batch.length;
+        }
+        if (ctx.abort.aborted) {
+          const err = { ok: false, error: "aborted" };
+          return JSON.stringify(err);
+        }
+        if (matchMode === "literal") {
+          const collected = [];
+          let total = 0;
+          let early = false;
+          for (const { session: sess, messages: msgs } of allLoaded) {
             if (collected.length >= args.results) {
               early = true;
               break;
             }
+            const remaining = args.results - collected.length;
             const result = scan(
               msgs,
               sess,
@@ -454,18 +1070,83 @@ This tool's own outputs are excluded from search results to prevent recursive no
             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 out2 = {
+            ok: true,
+            results: final,
+            scanned,
+            total,
+            truncated: early || total > final.length
+          };
+          return JSON.stringify(out2);
+        }
+        const smartResult = smartScan(
+          allLoaded,
+          args.query,
+          args.type,
+          args.role,
+          args.results,
+          args.explain,
+          matchMode,
+          args.before,
+          args.after,
+          args.width
+        );
+        if (smartResult.results.length === 0) {
+          const collected = [];
+          let total = 0;
+          let early = false;
+          for (const { session: sess, messages: msgs } of allLoaded) {
+            if (collected.length >= args.results) {
+              early = true;
+              break;
+            }
+            const remaining = args.results - collected.length;
+            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;
+          }
+          const final = collected.slice(0, args.results);
+          if (final.length > 0) {
+            ctx.metadata({
+              title: `Found ${final.length} result${final.length !== 1 ? "s" : ""} for "${args.query}" (literal fallback, ${scanned} session${scanned !== 1 ? "s" : ""})`
+            });
+            const out2 = {
+              ok: true,
+              results: final,
+              scanned,
+              total,
+              truncated: early || total > final.length,
+              matchMode: "literal",
+              degradeKind: "fallback"
+            };
+            return JSON.stringify(out2);
+          }
         }
-        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)`
+          title: `Found ${smartResult.results.length} result${smartResult.results.length !== 1 ? "s" : ""} for "${args.query}" (${matchMode}, ${scanned} session${scanned !== 1 ? "s" : ""})`
         });
         const out = {
           ok: true,
-          results: final,
+          results: smartResult.results,
           scanned,
-          total,
-          truncated: early || total > final.length
+          total: smartResult.total,
+          truncated: smartResult.total > smartResult.results.length,
+          matchMode: smartResult.matchMode,
+          degradeKind: smartResult.degradeKind
         };
         return JSON.stringify(out);
       } catch (e) {

package/dist/prefilter.d.ts

@@ -0,0 +1,23 @@
+import type { Candidate } from "./candidates.js";
+import type { ParsedQuery } from "./query.js";
+export type PrefilterResult = {
+    candidate: Candidate;
+    prefilterScore: number;
+};
+/**
+ * Score a candidate for degraded-mode ranking.
+ * Deliberately crude — just good enough for degraded output.
+ */
+export declare function prefilterScore(candidate: Candidate, query: ParsedQuery): number;
+/**
+ * Filter candidates that have at least some lexical relevance to the query.
+ * Returns candidates that pass, with prefilter scores attached.
+ *
+ * A candidate survives if ANY of these are true:
+ * 1. Exact raw substring match of the full query in rawText
+ * 2. Any quoted phrase found as substring in rawText (lowercased)
+ * 3. At least one query token found as exact substring in candidate tokens
+ * 4. At least one query token of length >= 4 has edit-distance <= 1 to any candidate token
+ */
+export declare function prefilter(candidates: Candidate[], query: ParsedQuery): PrefilterResult[];
+//# sourceMappingURL=prefilter.d.ts.map

package/dist/prefilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefilter.d.ts","sourceRoot":"","sources":["../src/prefilter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC;AAmBF;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,WAAW,GACjB,MAAM,CAmCR;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,SAAS,EAAE,EACvB,KAAK,EAAE,WAAW,GACjB,eAAe,EAAE,CAWnB"}

package/dist/query.d.ts

@@ -0,0 +1,12 @@
+export type ParsedQuery = {
+    /** Original query string */
+    raw: string;
+    /** Lowercased version of the raw query */
+    lower: string;
+    /** Individual normalized tokens (from tokenize()) */
+    tokens: string[];
+    /** Quoted phrases extracted from the query (lowercased, without quotes) */
+    phrases: string[];
+};
+export declare function parseQuery(query: string): ParsedQuery;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG;IACxB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAIF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CA4BrD"}

package/dist/rank.d.ts

@@ -0,0 +1,23 @@
+import type { FuseHit } from "./fuse.js";
+import type { Candidate } from "./candidates.js";
+import type { ParsedQuery } from "./query.js";
+export type RankedResult = {
+    candidate: Candidate;
+    score: number;
+    matchedTerms: string[];
+    matchReasons: string[];
+};
+/**
+ * Apply structural boosts/penalties and produce final ranked results.
+ * Results are sorted by score descending, then by time descending for ties.
+ */
+export declare function rank(hits: FuseHit[], query: ParsedQuery, explain: boolean): RankedResult[];
+/**
+ * Rank prefilter-scored candidates for degraded mode (no Fuse.js).
+ * Used when time budget is exceeded.
+ */
+export declare function rankDegraded(candidates: Array<{
+    candidate: Candidate;
+    prefilterScore: number;
+}>, query: ParsedQuery, explain: boolean): RankedResult[];
+//# sourceMappingURL=rank.d.ts.map

package/dist/rank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rank.d.ts","sourceRoot":"","sources":["../src/rank.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgD9C,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AA+CF;;;GAGG;AACH,wBAAgB,IAAI,CAClB,IAAI,EAAE,OAAO,EAAE,EACf,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,OAAO,GACf,YAAY,EAAE,CAoHhB;AAID;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,KAAK,CAAC;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAAC,EACnE,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE,OAAO,GACf,YAAY,EAAE,CAsChB"}

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,CAwNhB"}
+{"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,EAGZ,MAAM,YAAY,CAAC;AA0RpB,wBAAgB,MAAM,CACpB,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,MAAM,GACb,cAAc,CAmVhB"}

package/dist/snippet.d.ts

@@ -0,0 +1,8 @@
+import type { ParsedQuery } from "./query.js";
+/**
+ * Select the best snippet window from raw text based on query token density.
+ * For smart/fuzzy mode: finds the window with the most query token matches.
+ * Falls back to centering on the first token match if no dense window found.
+ */
+export declare function smartSnippet(rawText: string, query: ParsedQuery, width?: number): string;
+//# sourceMappingURL=snippet.d.ts.map

package/dist/snippet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snippet.d.ts","sourceRoot":"","sources":["../src/snippet.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA8D9C;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,WAAW,EAClB,KAAK,GAAE,MAAY,GAClB,MAAM,CA8ER"}

package/dist/types.d.ts

@@ -9,6 +9,8 @@ export type Limits = {
     defaultWidth: number;
 };
 export declare const DEFAULTS: Limits;
+export type MatchMode = "literal" | "smart" | "fuzzy";
+export type DegradeKind = "none" | "time" | "budget" | "fallback";
 export type SearchResult = {
     sessionID: string;
     sessionTitle: string;
@@ -21,6 +23,14 @@ export type SearchResult = {
     pruned: boolean;
     snippet: string;
     toolName?: string;
+    /** Present for smart/fuzzy results */
+    score?: number;
+    /** Present for smart/fuzzy results */
+    matchMode?: MatchMode;
+    /** Present for smart/fuzzy results */
+    matchedTerms?: string[];
+    /** Present when explain=true */
+    matchReasons?: string[];
 };
 export type SearchOutput = {
     ok: true;
@@ -28,6 +38,10 @@ export type SearchOutput = {
     scanned: number;
     total: number;
     truncated: boolean;
+    /** Which strategy produced the returned results */
+    matchMode?: MatchMode;
+    /** What happened during ranking */
+    degradeKind?: DegradeKind;
 };
 export type MessageOutput = {
     ok: true;

package/dist/types.d.ts.map

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

package/package.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-session-recall",
-  "version": "0.7.0",
+  "version": "0.8.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",
+  "description": "Everything your agent ever did is already in the database — this plugin lets it look",
   "main": "./dist/opencode-session-recall.js",
   "exports": {
     ".": {
@@ -54,6 +54,8 @@
   },
   "dependencies": {
     "@opencode-ai/sdk": "^1.3.2",
+    "fastest-levenshtein": "^1.0.16",
+    "fuse.js": "^7.3.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {