@bojackduy/opencode-telescope 0.1.22 → 0.1.23

package/README.md

@@ -1,8 +1,8 @@
 # opencode-telescope
 
-OpenCode TUI plugin for fuzzy-searching local conversation history, session transcripts, and past AI coding chats.
+OpenCode TUI plugin for fuzzy and semantic search across local conversation history, session transcripts, and past AI coding chats.
 
-Install the npm package `@bojackduy/opencode-telescope` to grep through OpenCode chat history, find old code snippets, and jump back to any session instantly.
+Install the npm package `@bojackduy/opencode-telescope` to grep OpenCode chat history, find old code snippets, search by meaning with local embeddings, and jump back to any session instantly.
 
 > Inspired by [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim) — a fuzzy finder for your conversation history.
 
@@ -18,6 +18,7 @@ Install the npm package `@bojackduy/opencode-telescope` to grep through OpenCode
 ## Use cases
 
 - **"I know I discussed this somewhere"** — grep all your sessions by keyword
+- **"What was that auth caching idea?"** — semantic search can find related chats even when the exact words differ
 - **"Find that code snippet"** — search for code you saw in a past LLM response
 - **"Revisit a decision"** — find the conversation where you chose approach X
 - **"Session journal"** — browse your entire conversation history like a timeline
@@ -25,6 +26,8 @@ Install the npm package `@bojackduy/opencode-telescope` to grep through OpenCode
 ## Features
 
 - **Fuzzy grep** — search across all session messages by text
+- **Semantic memory search** — optional local vector search with `llama-server` embeddings and `sqlite-vec`
+- **Hybrid ranking** — blends keyword/FTS matches with semantic vector results when vector search is ready
 - **Live preview** — preview the matched conversation result before opening
 - **Find & jump** — select any result and jump straight to that session
 - **Neovim Telescope-style UX** — familiar `<leader>f` keybind and `/telescope` command
@@ -59,6 +62,53 @@ Add the plugin to your `tui.json`:
 | Open             | Press `Enter` to jump to the selected session   |
 | Owner filter     | Press `o` to cycle `all` / `you` / `assistant`  |
 
+## Semantic Search
+
+Semantic search is optional. Keyword and fuzzy search work out of the box; when vector dependencies are available, Telescope builds a local sidecar vector index and uses hybrid ranking so meaning-based matches can appear even when the query does not share exact words with the original chat.
+
+The semantic path stays local-first:
+
+- OpenCode's SQLite database is opened read-only.
+- Derived keyword and vector indexes are stored in Telescope's sidecar database.
+- Embeddings are generated through your local `llama-server` endpoint.
+- If embeddings or `sqlite-vec` are unavailable, Telescope falls back to keyword search.
+
+Quick setup:
+
+```bash
+mkdir -p "$HOME/.local/share/opencode-telescope/models"
+
+huggingface-cli download \
+  nomic-ai/nomic-embed-text-v1.5-GGUF \
+  nomic-embed-text-v1.5.f16.gguf \
+  --local-dir "$HOME/.local/share/opencode-telescope/models" \
+  --local-dir-use-symlinks false
+
+llama-server \
+  -m "$HOME/.local/share/opencode-telescope/models/nomic-embed-text-v1.5.f16.gguf" \
+  --embedding \
+  --pooling mean \
+  -c 8192 \
+  -ub 8192 \
+  --host 127.0.0.1 \
+  --port 8081
+```
+
+Then launch OpenCode normally. Telescope uses `http://127.0.0.1:8081` by default and will rebuild the vector sidecar from your local session history.
+
+Useful environment variables:
+
+```bash
+OPENCODE_TELESCOPE_EMBED_BASE_URL=http://127.0.0.1:8081
+OPENCODE_TELESCOPE_EMBED_MODEL=nomic-embed-text-v1.5
+OPENCODE_TELESCOPE_HYBRID_ALPHA=0.45
+OPENCODE_TELESCOPE_DISABLE_VECTOR=1
+OPENCODE_TELESCOPE_SQLITE_LIB=/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib
+OPENCODE_TELESCOPE_SQLITE_VEC_EXT=/path/to/vec0
+```
+
+See the full tutorial in [`docs/semantic-search.md`](./docs/semantic-search.md).
+
 ## Configuration
 
 Telescope reads optional plugin-specific config from:
@@ -98,10 +148,10 @@ Key strings support simple names like `j`, `k`, `down`, `up`, `enter`, `return`,
 
 ## How it works
 
-Reads the OpenCode local SQLite session database in read-only mode, parses conversations into searchable text, and opens the selected session through the existing TUI route.
+Reads the OpenCode local SQLite session database in read-only mode, parses conversations into searchable text, builds a Telescope-owned sidecar index, and opens the selected session through the existing TUI route. Optional semantic search adds local embeddings and `sqlite-vec` vector retrieval on top of the same sidecar.
 
 ## Keywords
 
-OpenCode plugin, OpenCode TUI, fuzzy finder, conversation search, chat history search, AI coding session search, LLM history, local session search, Telescope-style picker.
+OpenCode plugin, OpenCode TUI, fuzzy finder, semantic search, vector search, embeddings, sqlite-vec, llama-server, conversation search, chat history search, AI coding session search, LLM history, local session search, Telescope-style picker.
 
 ![Demo animation](./assets/demo.gif)

package/docs/index.html

@@ -0,0 +1,298 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>opencode-telescope - Fuzzy and Semantic Search for OpenCode Chat History</title>
+    <meta
+      name="description"
+      content="opencode-telescope is an OpenCode TUI plugin for fuzzy and semantic search across local conversation history, session transcripts, AI coding chats, and old code snippets."
+    />
+    <meta
+      name="keywords"
+      content="OpenCode, OpenCode plugin, OpenCode TUI, fuzzy search, semantic search, vector search, embeddings, sqlite-vec, conversation search, chat history search, AI coding session search, LLM history, telescope"
+    />
+    <link rel="canonical" href="https://bojackduy.github.io/opencode-telescope/" />
+    <meta property="og:title" content="opencode-telescope" />
+    <meta
+      property="og:description"
+      content="Fuzzy and semantic search for local OpenCode conversations, session transcripts, and past AI coding chats from the TUI."
+    />
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content="https://bojackduy.github.io/opencode-telescope/" />
+    <meta
+      property="og:image"
+      content="https://raw.githubusercontent.com/bojackduy/opencode-telescope/main/assets/demo.png"
+    />
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta
+      name="twitter:image"
+      content="https://raw.githubusercontent.com/bojackduy/opencode-telescope/main/assets/demo.png"
+    />
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #090b10;
+        --panel: #111722;
+        --text: #eaf0ff;
+        --muted: #a8b3cf;
+        --accent: #8bd5ff;
+        --accent-2: #c6a0ff;
+        --border: #283247;
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      body {
+        margin: 0;
+        background:
+          radial-gradient(circle at top left, rgba(139, 213, 255, 0.18), transparent 30rem),
+          radial-gradient(circle at bottom right, rgba(198, 160, 255, 0.14), transparent 28rem),
+          var(--bg);
+        color: var(--text);
+        font-family:
+          ui-sans-serif,
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          "Segoe UI",
+          sans-serif;
+        line-height: 1.6;
+      }
+
+      main {
+        width: min(72rem, calc(100% - 2rem));
+        margin: 0 auto;
+        padding: 4rem 0;
+      }
+
+      .hero {
+        display: grid;
+        grid-template-columns: minmax(0, 1.2fr) minmax(18rem, 0.8fr);
+        gap: 2rem;
+        align-items: center;
+      }
+
+      .eyebrow {
+        color: var(--accent);
+        font-weight: 700;
+        letter-spacing: 0.12em;
+        text-transform: uppercase;
+      }
+
+      h1 {
+        margin: 0.5rem 0 1rem;
+        font-size: clamp(2.6rem, 8vw, 5.8rem);
+        line-height: 0.92;
+        letter-spacing: -0.07em;
+      }
+
+      h2 {
+        margin-top: 0;
+        font-size: 1.35rem;
+      }
+
+      p {
+        color: var(--muted);
+        font-size: 1.08rem;
+      }
+
+      a {
+        color: var(--accent);
+      }
+
+      .actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 0.75rem;
+        margin-top: 1.5rem;
+      }
+
+      .button {
+        border: 1px solid var(--border);
+        border-radius: 999px;
+        color: var(--text);
+        display: inline-flex;
+        font-weight: 700;
+        padding: 0.8rem 1rem;
+        text-decoration: none;
+      }
+
+      .button.primary {
+        background: linear-gradient(135deg, var(--accent), var(--accent-2));
+        color: #07101a;
+      }
+
+      .card,
+      pre {
+        background: rgba(17, 23, 34, 0.86);
+        border: 1px solid var(--border);
+        border-radius: 1.25rem;
+        box-shadow: 0 1.5rem 4rem rgba(0, 0, 0, 0.28);
+      }
+
+      .card {
+        padding: 1.25rem;
+      }
+
+      .demo-card {
+        padding: 0.8rem;
+      }
+
+      .demo-card img {
+        border: 1px solid var(--border);
+        border-radius: 0.9rem;
+        display: block;
+        height: auto;
+        width: 100%;
+      }
+
+      .caption {
+        color: var(--muted);
+        font-size: 0.92rem;
+        margin: 0.8rem 0 0.2rem;
+      }
+
+      pre {
+        color: #d9e7ff;
+        overflow-x: auto;
+        padding: 1rem;
+      }
+
+      code {
+        font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      }
+
+      .grid {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+        gap: 1rem;
+        margin-top: 2rem;
+      }
+
+      .links {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 1rem;
+        margin-top: 2rem;
+      }
+
+      .showcase {
+        display: grid;
+        grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+        gap: 1rem;
+        margin-top: 2rem;
+      }
+
+      @media (max-width: 760px) {
+        main {
+          padding: 2.5rem 0;
+        }
+
+        .hero,
+        .grid,
+        .showcase {
+          grid-template-columns: 1fr;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <section class="hero">
+        <div>
+          <div class="eyebrow">OpenCode TUI plugin</div>
+          <h1>Find the chat where it happened.</h1>
+          <p>
+            <strong>opencode-telescope</strong> adds a Telescope-style fuzzy finder
+            to OpenCode so you can search local conversation history by keyword
+            or meaning, recover old code snippets, and jump back to the exact chat.
+          </p>
+          <div class="actions">
+            <a class="button primary" href="https://www.npmjs.com/package/@bojackduy/opencode-telescope">Install from npm</a>
+            <a class="button" href="https://github.com/bojackduy/opencode-telescope">View on GitHub</a>
+          </div>
+        </div>
+        <div class="card">
+          <h2>Package</h2>
+          <pre><code>@bojackduy/opencode-telescope</code></pre>
+          <p>
+            Search OpenCode sessions by keyword or semantic similarity, preview
+            matches, and jump back into the exact conversation without leaving the TUI.
+          </p>
+        </div>
+      </section>
+
+      <section class="showcase" aria-label="Demo screenshots">
+        <div class="card demo-card">
+          <img
+            src="https://raw.githubusercontent.com/bojackduy/opencode-telescope/main/assets/demo.png"
+            alt="opencode-telescope fuzzy search UI preview inside the OpenCode terminal"
+            loading="lazy"
+          />
+          <p class="caption">Search across OpenCode sessions with a Telescope-style result list and preview pane.</p>
+        </div>
+        <div class="card demo-card">
+          <img
+            src="https://raw.githubusercontent.com/bojackduy/opencode-telescope/main/assets/demo.gif"
+            alt="Animated opencode-telescope demo showing chat history search and session navigation"
+            loading="lazy"
+          />
+          <p class="caption">Filter conversation history, inspect matches, and jump back to the exact chat.</p>
+        </div>
+      </section>
+
+      <section class="grid" aria-label="Features">
+        <div class="card">
+          <h2>Fuzzy + semantic</h2>
+          <p>Grep exact words or use local embeddings to find conversations by meaning.</p>
+        </div>
+        <div class="card">
+          <h2>Hybrid ranking</h2>
+          <p>Blend SQLite FTS matches with vector results from a local sidecar index.</p>
+        </div>
+        <div class="card">
+          <h2>Local first</h2>
+          <p>Reads OpenCode's SQLite database in read-only mode and uses your local embedding server.</p>
+        </div>
+      </section>
+
+      <section style="margin-top: 2rem">
+        <h2>Semantic memory search</h2>
+        <p>
+          Run a local <code>llama-server</code> embedding endpoint and Telescope can build a
+          <code>sqlite-vec</code> sidecar index for meaning-based recall. If vector dependencies
+          are missing, keyword search keeps working.
+        </p>
+        <pre><code>OPENCODE_TELESCOPE_EMBED_BASE_URL=http://127.0.0.1:8081
+OPENCODE_TELESCOPE_EMBED_MODEL=nomic-embed-text-v1.5
+OPENCODE_TELESCOPE_HYBRID_ALPHA=0.45</code></pre>
+        <p>
+          <a href="https://github.com/bojackduy/opencode-telescope/blob/main/docs/semantic-search.md">Read the semantic search setup guide</a>
+        </p>
+      </section>
+
+      <section style="margin-top: 2rem">
+        <h2>Install</h2>
+        <pre><code>{
+  "plugin": ["@bojackduy/opencode-telescope"]
+}</code></pre>
+        <p>
+          Open search with <code>&lt;leader&gt;f</code> or <code>/telescope</code>, type
+          to filter conversation text or describe the idea you remember, then press
+          <code>Enter</code> to jump to the selected OpenCode session.
+        </p>
+      </section>
+
+      <nav class="links" aria-label="Project links">
+        <a href="https://github.com/bojackduy/opencode-telescope">GitHub repository</a>
+        <a href="https://www.npmjs.com/package/@bojackduy/opencode-telescope">npm package</a>
+        <a href="https://github.com/bojackduy/opencode-telescope/blob/main/docs/semantic-search.md">Semantic search guide</a>
+        <a href="https://github.com/bojackduy/opencode-telescope/issues">Issues</a>
+        <a href="https://bojackduy.github.io/opencode-telescope/sitemap.xml">Sitemap</a>
+      </nav>
+    </main>
+  </body>
+</html>

package/docs/semantic-search.md

@@ -0,0 +1,92 @@
+# Semantic Search Setup
+
+opencode-telescope can search OpenCode chat history by meaning, not only by exact keywords. The default keyword/fuzzy search still works without extra setup. Semantic search turns on automatically when the local vector dependencies are ready.
+
+## What It Adds
+
+- Hybrid search across keyword FTS results and vector semantic matches.
+- Vector-only results when a query is related by meaning but not exact wording.
+- Local embeddings through a `llama-server` endpoint.
+- A Telescope-owned sidecar index so OpenCode's source database stays read-only.
+
+## Requirements
+
+- `@bojackduy/opencode-telescope` installed in OpenCode.
+- A local `llama-server` with an embedding model.
+- `sqlite-vec`, provided by the package dependency or by `OPENCODE_TELESCOPE_SQLITE_VEC_EXT`.
+- On macOS, an extension-capable SQLite library. Telescope tries Homebrew SQLite automatically, or you can set `OPENCODE_TELESCOPE_SQLITE_LIB`.
+
+## Recommended Model
+
+Use `nomic-ai/nomic-embed-text-v1.5-GGUF` for local embedding search.
+
+```bash
+mkdir -p "$HOME/.local/share/opencode-telescope/models"
+
+huggingface-cli download \
+  nomic-ai/nomic-embed-text-v1.5-GGUF \
+  nomic-embed-text-v1.5.f16.gguf \
+  --local-dir "$HOME/.local/share/opencode-telescope/models" \
+  --local-dir-use-symlinks false
+```
+
+## Start The Embedding Server
+
+```bash
+llama-server \
+  -m "$HOME/.local/share/opencode-telescope/models/nomic-embed-text-v1.5.f16.gguf" \
+  --embedding \
+  --pooling mean \
+  -c 8192 \
+  -ub 8192 \
+  --host 127.0.0.1 \
+  --port 8081
+```
+
+Smoke test the server:
+
+```bash
+curl http://127.0.0.1:8081/health
+
+curl http://127.0.0.1:8081/v1/embeddings \
+  -H "Content-Type: application/json" \
+  -d '{"input":"search_query: find the auth caching discussion","model":"nomic-embed-text-v1.5","encoding_format":"float"}'
+```
+
+## Configure Telescope
+
+Telescope defaults to `http://127.0.0.1:8081`, so most local setups only need the server running before opening OpenCode.
+
+Optional environment variables:
+
+```bash
+OPENCODE_TELESCOPE_EMBED_BASE_URL=http://127.0.0.1:8081
+OPENCODE_TELESCOPE_EMBED_MODEL=nomic-embed-text-v1.5
+OPENCODE_TELESCOPE_HYBRID_ALPHA=0.45
+OPENCODE_TELESCOPE_DISABLE_VECTOR=1
+OPENCODE_TELESCOPE_SQLITE_LIB=/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib
+OPENCODE_TELESCOPE_SQLITE_VEC_EXT=/path/to/vec0
+```
+
+`OPENCODE_TELESCOPE_HYBRID_ALPHA` controls the blend between keyword and vector ranking. `0` favors keyword search; `1` favors semantic vector search. The default is `0.45`.
+
+Use `OPENCODE_TELESCOPE_DISABLE_VECTOR=1` to force keyword-only search.
+
+## How It Works
+
+1. Telescope reads OpenCode's SQLite session database in read-only mode.
+2. It extracts searchable conversation documents into a sidecar index.
+3. Keyword search uses local SQLite FTS.
+4. Semantic search embeds documents with `search_document: ` and queries with `search_query: ` prefixes.
+5. Vector rows are stored with `sqlite-vec` in the sidecar database.
+6. Results are merged and ranked with hybrid keyword/vector scoring.
+
+If the embedding server or vector extension is unavailable, Telescope keeps keyword search working and marks vector search unavailable internally.
+
+## Troubleshooting
+
+- If semantic results do not appear, confirm `curl http://127.0.0.1:8081/health` returns success.
+- On macOS, install Homebrew SQLite if extension loading fails: `brew install sqlite`.
+- Set `OPENCODE_TELESCOPE_SQLITE_LIB` if SQLite is installed somewhere other than Homebrew's default path.
+- Set `OPENCODE_TELESCOPE_SQLITE_VEC_EXT` only when you need to load a specific `vec0` extension file.
+- Set `OPENCODE_TELESCOPE_DISABLE_VECTOR=1` when you want fast keyword-only search or are debugging local embedding setup.

package/package.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@bojackduy/opencode-telescope",
-  "version": "0.1.22",
-  "description": "OpenCode TUI plugin for fuzzy-searching local conversation history, session transcripts, and past AI coding chats",
+  "version": "0.1.23",
+  "description": "OpenCode TUI plugin for fuzzy and semantic search across local conversation history, session transcripts, and AI coding chats",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -22,6 +22,10 @@
     "session",
     "conversation",
     "conversation-search",
+    "semantic-search",
+    "vector-search",
+    "embeddings",
+    "sqlite-vec",
     "history",
     "ai-chat-history",
     "llm-history",
@@ -43,6 +47,8 @@
   },
   "files": [
     "assets",
+    "docs/index.html",
+    "docs/semantic-search.md",
     "README.md",
     "LICENSE",
     "tui.tsx",
@@ -60,6 +66,9 @@
       "import": "./tui.tsx"
     }
   },
+  "dependencies": {
+    "sqlite-vec": "^0.1.9"
+  },
   "peerDependencies": {
     "@opencode-ai/plugin": "*",
     "@opentui/core": "*",

package/search.ts

@@ -1,8 +1,10 @@
 import { Database } from "bun:sqlite"
+import { createHash } from "node:crypto"
 import { existsSync, readdirSync, statSync } from "node:fs"
 import { homedir } from "node:os"
 import path from "node:path"
 import { debug } from "./ui/debug.ts"
+import { LlamaEmbeddingClient } from "./search/embedding.ts"
 
 export type SearchResult = {
   id: string
@@ -63,6 +65,46 @@ export type ToolState = {
   error?: string
 }
 
+export type SemanticConfig = {
+  embedBaseUrl: string
+  embedModel?: string
+  disableVector: boolean
+  sqliteLibPath?: string
+  sqliteVecExtension?: string
+  hybridAlpha: number
+  documentPrefix: string
+  queryPrefix: string
+}
+
+export type VectorState = "enabled" | "disabled" | "unavailable" | "stale"
+
+export const DEFAULT_EMBED_BASE_URL = "http://127.0.0.1:8081"
+export const DEFAULT_DOCUMENT_PREFIX = "search_document: "
+export const DEFAULT_QUERY_PREFIX = "search_query: "
+export const DEFAULT_HYBRID_ALPHA = 0.45
+
+export function parseSemanticConfig(env: Record<string, string | undefined> = process.env): SemanticConfig {
+  return {
+    embedBaseUrl: env.OPENCODE_TELESCOPE_EMBED_BASE_URL ?? DEFAULT_EMBED_BASE_URL,
+    embedModel: env.OPENCODE_TELESCOPE_EMBED_MODEL || undefined,
+    disableVector: env.OPENCODE_TELESCOPE_DISABLE_VECTOR === "1" || env.OPENCODE_TELESCOPE_DISABLE_VECTOR === "true",
+    sqliteLibPath: env.OPENCODE_TELESCOPE_SQLITE_LIB || undefined,
+    sqliteVecExtension: env.OPENCODE_TELESCOPE_SQLITE_VEC_EXT || undefined,
+    hybridAlpha: parseAlpha(env.OPENCODE_TELESCOPE_HYBRID_ALPHA),
+    documentPrefix: DEFAULT_DOCUMENT_PREFIX,
+    queryPrefix: DEFAULT_QUERY_PREFIX,
+  }
+}
+
+function parseAlpha(value: string | undefined) {
+  if (!value) return DEFAULT_HYBRID_ALPHA
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) return DEFAULT_HYBRID_ALPHA
+  if (parsed < 0) return 0
+  if (parsed > 1) return 1
+  return parsed
+}
+
 type Row = {
   id: string
   message_id: string
@@ -80,6 +122,23 @@ type IndexSourceRow = Omit<Row, "text"> & {
   data: string
 }
 
+export type DocumentRow = {
+  doc_id: string
+  part_id: string
+  message_id: string
+  session_id: string
+  session_title: string
+  directory: string
+  role: string
+  part_type: string
+  tool: string | null
+  time_created: number
+  chunk_index: number
+  text: string
+  source_hash: string
+  extractor_version: string
+}
+
 type ConversationRow = {
   id: string
   message_id: string
@@ -734,6 +793,7 @@ function ensureSearchIndex(source: Database, sourcePath: string, options?: { reb
   const indexPath = searchIndexPath(sourcePath)
   if (!_indexDb || _indexDbPath !== indexPath) {
     _indexDb?.close()
+    configureCustomSQLite()
     _indexDb = new Database(indexPath)
     _indexDbPath = indexPath
     migrateSearchIndex(_indexDb)
@@ -773,7 +833,8 @@ function scheduleBackgroundIndexRebuild(dbPath: string) {
   ;(timer as { unref?: () => void }).unref?.()
 }
 
-const SEARCH_INDEX_VERSION = "6"
+const SEARCH_INDEX_VERSION = "7"
+const DOCUMENT_EXTRACTOR_VERSION = "1"
 
 function searchIndexPath(sourcePath: string) {
   const parsed = path.parse(sourcePath)
@@ -786,6 +847,24 @@ function migrateSearchIndex(db: Database) {
       key TEXT PRIMARY KEY,
       value TEXT NOT NULL
     );
+    CREATE TABLE IF NOT EXISTS document(
+      rowid INTEGER PRIMARY KEY,
+      doc_id TEXT UNIQUE NOT NULL,
+      part_id TEXT NOT NULL,
+      message_id TEXT NOT NULL,
+      session_id TEXT NOT NULL,
+      session_title TEXT NOT NULL,
+      directory TEXT NOT NULL,
+      role TEXT NOT NULL,
+      part_type TEXT NOT NULL,
+      tool TEXT,
+      time_created INTEGER NOT NULL,
+      chunk_index INTEGER NOT NULL,
+      text TEXT NOT NULL,
+      source_hash TEXT NOT NULL,
+      extractor_version TEXT NOT NULL,
+      indexed_at INTEGER NOT NULL
+    );
     CREATE VIRTUAL TABLE IF NOT EXISTS document_fts USING fts5(
       id UNINDEXED,
       message_id UNINDEXED,
@@ -895,7 +974,13 @@ function rebuildSearchIndex(source: Database, index: Database, sourcePath: strin
       AND json_extract(m.data, '$.role') IN ('user', 'assistant')
     ORDER BY p.time_created DESC
   `).all()
-  const insert = index.query<Row, [string, string, string, string, string, string, SearchResult["partType"], string | null, number, string]>(`
+  const now = Date.now()
+  const config = parseSemanticConfig()
+  const insertDoc = index.query<unknown, [string, string, string, string, string, string, string, string, string | null, number, number, string, string, string, number]>(`
+    INSERT INTO document(doc_id, part_id, message_id, session_id, session_title, directory, role, part_type, tool, time_created, chunk_index, text, source_hash, extractor_version, indexed_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `)
+  const insertFts = index.query<Row, [string, string, string, string, string, string, SearchResult["partType"], string | null, number, string]>(`
     INSERT INTO document_fts(id, message_id, session_id, session_title, directory, role, part_type, tool, time_created, text)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `)
@@ -905,10 +990,30 @@ function rebuildSearchIndex(source: Database, index: Database, sourcePath: strin
   `)
   index.exec("BEGIN IMMEDIATE")
   try {
+    index.exec("DELETE FROM document")
     index.exec("DELETE FROM document_fts")
     index.exec("DELETE FROM document_index")
     for (const row of rows.flatMap(indexSourceRowToRows)) {
-      insert.run(
+      const docID = `telescope:${row.session_id}:${row.message_id}:${row.id}:0`
+      const sourceHash = hashPartData({ session_id: row.session_id, message_id: row.message_id, part_id: row.id })
+      insertDoc.run(
+        docID,
+        row.id,
+        row.message_id,
+        row.session_id,
+        row.session_title ?? "Untitled session",
+        row.directory,
+        row.role,
+        row.part_type ?? "text",
+        row.tool ?? null,
+        row.time_created,
+        0,
+        row.text,
+        sourceHash,
+        DOCUMENT_EXTRACTOR_VERSION,
+        now,
+      )
+      insertFts.run(
         row.id,
         row.message_id,
         row.session_id,
@@ -937,6 +1042,13 @@ function rebuildSearchIndex(source: Database, index: Database, sourcePath: strin
     setMeta(index, "source_data_version", String(state.dataVersion))
     setMeta(index, "source_mtime_ms", String(state.mtimeMs))
     setMeta(index, "index_version", SEARCH_INDEX_VERSION)
+    setMeta(index, "schema_version", "2")
+    setMeta(index, "extractor_version", DOCUMENT_EXTRACTOR_VERSION)
+    setMeta(index, "ranking_version", "1")
+    setMeta(index, "embedding_base_url", config.embedBaseUrl)
+    setMeta(index, "document_prefix", config.documentPrefix)
+    setMeta(index, "query_prefix", config.queryPrefix)
+    if (config.embedModel) setMeta(index, "embedding_model", config.embedModel)
     index.exec("COMMIT")
   } catch (err) {
     index.exec("ROLLBACK")
@@ -944,6 +1056,321 @@ function rebuildSearchIndex(source: Database, index: Database, sourcePath: strin
   } finally {
     debug.timeEnd("fts:rebuild")
   }
+
+  if (config.disableVector) {
+    setMeta(index, "vector_state", "disabled")
+  } else {
+    setupVectorTable(index, config, searchIndexPath(sourcePath))
+  }
+}
+
+function hashPartData(value: { session_id: string; message_id: string; part_id: string }) {
+  return createHash("sha256").update(`${value.session_id}:${value.message_id}:${value.part_id}`).digest("hex")
+}
+
+let customSQLiteConfigured = false
+
+function configureCustomSQLite() {
+  if (customSQLiteConfigured) return
+  const config = parseSemanticConfig()
+  if (config.disableVector) return
+  customSQLiteConfigured = true
+
+  const candidates = [
+    config.sqliteLibPath,
+    process.platform === "darwin" ? "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib" : undefined,
+    process.platform === "darwin" ? "/usr/local/opt/sqlite/lib/libsqlite3.dylib" : undefined,
+  ].filter((item): item is string => Boolean(item))
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      try {
+        Database.setCustomSQLite(candidate)
+        debug.log("custom-sqlite:set", { path: candidate })
+        return
+      } catch (err) {
+        debug.log("custom-sqlite:error", { path: candidate, error: err instanceof Error ? err.message : String(err) })
+      }
+    }
+  }
+}
+
+function importPackage(specifier: string) {
+  return new Function("specifier", "return import(specifier)")(specifier) as Promise<{ default?: { load?: (db: Database) => void } }>
+}
+
+async function loadVecExtension(db: Database): Promise<boolean> {
+  try {
+    const sqliteVec = await importPackage("sqlite-vec").catch(() => undefined)
+    if (sqliteVec?.default?.load) {
+      sqliteVec.default.load(db)
+      debug.log("vector:extension:loaded", { source: "npm" })
+      return true
+    }
+  } catch {
+    debug.log("vector:extension:npm-failed")
+  }
+
+  const config = parseSemanticConfig()
+  const explicitPath = config.sqliteVecExtension || process.env.OPENCODE_TELESCOPE_SQLITE_VEC_EXT
+  if (explicitPath && existsSync(explicitPath)) {
+    try {
+      db.loadExtension(explicitPath)
+      debug.log("vector:extension:loaded", { source: "path", path: explicitPath })
+      return true
+    } catch (err) {
+      debug.log("vector:extension:path-failed", { path: explicitPath, error: err instanceof Error ? err.message : String(err) })
+    }
+  }
+
+  return false
+}
+
+function setupVectorTable(index: Database, config: SemanticConfig, indexPath: string) {
+  setMeta(index, "vector_state", "stale")
+  rebuildVectorIndex(indexPath, config).catch((err: Error) => {
+    debug.log("vector:rebuild:error", err instanceof Error ? err.message : String(err))
+  })
+}
+
+async function rebuildVectorIndex(indexPath: string, config: SemanticConfig) {
+  configureCustomSQLite()
+  const db = new Database(indexPath)
+  try {
+    const loaded = await loadVecExtension(db)
+    if (!loaded) {
+      setMeta(db, "vector_state", "unavailable")
+      return
+    }
+
+    const client = new LlamaEmbeddingClient({
+      baseUrl: config.embedBaseUrl,
+      model: config.embedModel,
+      documentPrefix: config.documentPrefix,
+      queryPrefix: config.queryPrefix,
+    })
+    const healthy = await client.health()
+    if (!healthy) {
+      setMeta(db, "vector_state", "unavailable")
+      return
+    }
+
+    const docs = db.query<{ rowid: number; text: string }, []>("SELECT rowid, text FROM document ORDER BY rowid ASC").all()
+    if (!docs.length) {
+      setMeta(db, "vector_state", "enabled")
+      return
+    }
+
+    debug.log("vector:embed:start", { count: docs.length })
+    const embeddings = await client.embedDocuments(docs.map((d) => d.text))
+    const dims = embeddings[0]?.length
+    if (!dims) {
+      setMeta(db, "vector_state", "unavailable")
+      return
+    }
+
+    db.exec("DROP TABLE IF EXISTS document_vec")
+    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS document_vec USING vec0(embedding float[${dims}])`)
+    debug.log("vector:table:recreated", { dimensions: dims })
+
+    const insert = db.prepare<unknown, [number, Float32Array]>("INSERT INTO document_vec(rowid, embedding) VALUES (?, vec_f32(?))")
+    const transaction = db.transaction(() => {
+      for (const [i, doc] of docs.entries()) {
+        insert.run(doc.rowid, embeddings[i])
+      }
+    })
+    transaction()
+
+    setMeta(db, "vector_state", "enabled")
+    setMeta(db, "embedding_dimensions", String(dims))
+    if (config.embedModel) setMeta(db, "embedding_model", config.embedModel)
+    debug.log("vector:rebuild:done", { vectors: docs.length, dimensions: dims })
+  } catch (err) {
+    setMeta(db, "vector_state", "unavailable")
+    debug.log("vector:rebuild:error", err instanceof Error ? err.message : String(err))
+  } finally {
+    db.close()
+  }
+}
+
+export type ScoredRow = Row & {
+  score: number
+  keywordScore: number
+  vectorScore: number
+}
+
+function searchVector(index: Database, embedding: Float32Array, limit: number): Row[] {
+  const count = index.query<{ count: number }, []>("SELECT COUNT(*) as count FROM document_vec").get()?.count ?? 0
+  if (!count) return []
+  const k = Math.min(count, Math.max(limit * 4, 200))
+  return index.query<Row, [Float32Array, number]>(`
+    SELECT d.part_id AS id, d.message_id, d.session_id, d.session_title, d.directory, d.role,
+           d.part_type, d.tool, CAST(d.time_created AS INTEGER) AS time_created, d.text
+    FROM document_vec v
+    JOIN document d ON d.rowid = v.rowid
+    WHERE v.embedding MATCH vec_f32(?) AND k = ?
+    ORDER BY v.distance
+  `).all(embedding, k)
+}
+
+export function hybridBlend(keyword: Row[], vector: Row[], alpha: number): ScoredRow[] {
+  const merged = new Map<string, ScoredRow>()
+  const defaultScore = 1 / Math.max(keyword.length, 1)
+
+  for (const [i, row] of keyword.entries()) {
+    merged.set(row.id, {
+      ...row,
+      score: 0,
+      keywordScore: keyword.length > 1 ? 1 - i / (keyword.length - 1) : 1,
+      vectorScore: 0,
+    })
+  }
+
+  for (const [i, row] of vector.entries()) {
+    const existing = merged.get(row.id)
+    const vectorScore = vector.length > 1 ? 1 - i / (vector.length - 1) : 1
+    if (existing) {
+      existing.vectorScore = vectorScore
+    } else {
+      merged.set(row.id, {
+        ...row,
+        score: 0,
+        keywordScore: defaultScore,
+        vectorScore,
+      })
+    }
+  }
+
+  const keywordValues = [...merged.values()].map((r) => r.keywordScore)
+  const vectorValues = [...merged.values()].map((r) => r.vectorScore)
+  const kwMin = Math.min(...keywordValues)
+  const kwMax = Math.max(...keywordValues)
+  const vecMin = Math.min(...vectorValues)
+  const vecMax = Math.max(...vectorValues)
+
+  const normalized = [...merged.values()].map((r) => {
+    const kn = kwMax === kwMin ? 0.5 : (r.keywordScore - kwMin) / (kwMax - kwMin)
+    const vn = vecMax === vecMin ? 0.5 : (r.vectorScore - vecMin) / (vecMax - vecMin)
+    return {
+      ...r,
+      keywordScore: kn,
+      vectorScore: vn,
+      score: (1 - alpha) * kn + alpha * vn,
+    }
+  })
+
+  return normalized.sort((a, b) => b.score - a.score)
+}
+
+export type HybridSearchOptions = {
+  limit?: number
+  offset?: number
+  directory?: string
+  role?: SearchRole
+  dbPath?: string
+}
+
+export async function performSearch(query: string, options?: HybridSearchOptions): Promise<SearchResult[]> {
+  if (!query.trim()) return searchSessionMessages(query, options)
+  const config = parseSemanticConfig()
+  if (!config.disableVector) {
+    try {
+      return await semanticSearchSessionMessages(query, options)
+    } catch {
+      debug.log("query:hybrid:fallback", { message: "hybrid search failed, falling back to keyword" })
+    }
+  }
+  return searchSessionMessages(query, options)
+}
+
+export async function semanticSearchSessionMessages(query: string, options?: HybridSearchOptions): Promise<SearchResult[]> {
+  const term = query.trim()
+  if (!term) return []
+  if (options?.dbPath === ":memory:") return []
+  const dbPath = options?.dbPath ?? resolveDatabasePath()
+  const db = getDb(dbPath)
+  const limit = options?.limit ?? 80
+  const dir = options?.directory
+  const role = options?.role
+
+  const index = ensureSearchIndex(db, dbPath)
+  if (!index) return []
+
+  const keyword = indexedTextRows(db, dbPath, limit, term, dir, options?.offset, role) ?? []
+  const config = parseSemanticConfig()
+
+  let vector: Row[] = []
+  if (!config.disableVector) {
+    const vecState = getMeta(index, "vector_state")
+    if (vecState === "enabled") {
+      try {
+        const client = new LlamaEmbeddingClient({
+          baseUrl: config.embedBaseUrl,
+          model: config.embedModel,
+          documentPrefix: config.documentPrefix,
+          queryPrefix: config.queryPrefix,
+        })
+        const embedding = await client.embedQuery(term)
+        vector = searchVector(index, embedding, limit)
+        debug.log("query:vector:results", { count: vector.length })
+      } catch (err) {
+        debug.log("query:vector:error", err instanceof Error ? err.message : String(err))
+      }
+    }
+  }
+
+  const merged = keyword.length || vector.length
+    ? hybridBlend(keyword, vector, config.hybridAlpha)
+    : []
+
+  const results: SearchResult[] = []
+  const seen = new Set<string>()
+  for (const row of merged) {
+    const result = rowToSearchResult(row, term) ?? rowToVectorResult(row)
+    if (result) {
+      seen.add(row.id)
+      results.push(result)
+    }
+  }
+
+  for (const row of vector) {
+    if (!seen.has(row.id)) {
+      const result = rowToSearchResult(row, term) ?? rowToVectorResult(row)
+      if (result) results.push(result)
+    }
+  }
+
+  return results
+}
+
+export function rowToVectorResult(row: Row): SearchResult | undefined {
+  const text = row.text.trim()
+  if (!text) return
+  const excerpt = text.slice(0, 200)
+  return {
+    id: row.id,
+    messageID: row.message_id,
+    sessionID: row.session_id,
+    sessionTitle: row.session_title || "Untitled session",
+    directory: row.directory,
+    role: row.role,
+    partType: row.part_type ?? "text",
+    tool: row.tool ?? undefined,
+    timeCreated: row.time_created,
+    snippet: excerpt,
+    matchStart: -1,
+    matchEnd: -1,
+    before: "",
+    match: "",
+    after: excerpt,
+    excerpt,
+    previewBefore: text.slice(0, Math.min(text.length, 1400)),
+    previewMatch: "",
+    previewAfter: "",
+    previewMode: "markdown" as const,
+    previewHighlight: false,
+    text,
+  }
 }
 
 function ftsQuery(query: string) {

package/telescope.tsx

@@ -9,6 +9,8 @@ import {
   loadConversationAfter,
   loadConversationAround,
   loadConversationBefore,
+  parseSemanticConfig,
+  performSearch,
   recentSessionMessages,
   resolveDatabasePath,
   searchSessionMessages,
@@ -35,6 +37,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
   const [nextResultOffset, setNextResultOffset] = createSignal(0)
   const [busy, setBusy] = createSignal(false)
   const [error, setError] = createSignal("")
+  const [searchMode, setSearchMode] = createSignal<"keyword" | "hybrid">("keyword")
   const [mode, setMode] = createSignal<"normal" | "insert">("normal")
   const [loading, setLoading] = createSignal(true)
   const [hasMore, setHasMore] = createSignal(true)
@@ -196,18 +199,25 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     })
   })
 
-  const executeSearch = (q: string, role: SearchRole | undefined, db: string, dir: string) => {
+  const detectSearchMode = () => {
+    if (!query().trim()) return "keyword" as const
+    const config = parseSemanticConfig()
+    return config.disableVector ? "keyword" as const : "hybrid" as const
+  }
+
+  const executeSearch = async (q: string, role: SearchRole | undefined, db: string, dir: string) => {
     lastFiredQuery = q
     const limit = q ? Math.min(searchBatchSize(), 80) : recentBatchSize()
     setLoading(true)
     if (q) setBusy(true)
+    setSearchMode(detectSearchMode())
     debug.time("query:search")
     try {
       debug.log("bootstrap:search:start", { limit, directory: dir, role, query: q || "(all recent)" })
       const batch = q
-        ? searchSessionMessages(q, { limit, offset: 0, dbPath: db, directory: dir, role })
+        ? await performSearch(q, { limit, offset: 0, dbPath: db, directory: dir, role })
         : recentSessionMessages({ limit, offset: 0, dbPath: db, directory: dir, role })
-      debug.log("bootstrap:search:done", { rows: batch.length, limit })
+      debug.log("bootstrap:search:done", { rows: batch.length, limit, mode: searchMode() })
       solidBatch(() => {
         setResults(batch)
         setResultBaseOffset(0)
@@ -266,7 +276,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     })
   })
 
-  const loadMoreResults = (advance = false) => {
+  const loadMoreResults = async (advance = false) => {
     if (advance) advanceSelectionAfterLoad = true
     if (!hasMore()) {
       advanceSelectionAfterLoad = false
@@ -285,7 +295,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
     debug.time("query:load-more")
     try {
       const batch = q
-        ? searchSessionMessages(q, { limit, offset, dbPath: db, directory: dir, role })
+        ? await performSearch(q, { limit, offset, dbPath: db, directory: dir, role })
         : recentSessionMessages({ limit, offset, dbPath: db, directory: dir, role })
       const nextHasMore = batch.length >= limit
       const nextLoadedUntil = offset + batch.length
@@ -1248,7 +1258,7 @@ export const Telescope = (props: { api: TuiPluginApi; config: TelescopeConfig; o
                   }}
                   flexGrow={1}
                 />
-                <text fg={theme().textMuted}>{busy() ? `searching ${ownerLabel()}` : loading() ? `loading ${ownerLabel()}` : query().trim() ? (results().length > 0 ? `${ownerLabel()} ${selected() + 1}/${nextResultOffset()} hits` : `${ownerLabel()} 0 hits`) : (results().length > 0 ? `${ownerLabel()} ${selected() + 1}/${nextResultOffset()} recent` : `${ownerLabel()} 0 recent`)}</text>
+                <text fg={theme().textMuted}>{busy() ? `searching ${ownerLabel()}` : loading() ? `loading ${ownerLabel()}` : query().trim() ? (results().length > 0 ? `${ownerLabel()} ${selected() + 1}/${nextResultOffset()} hits` : `${ownerLabel()} 0 hits`) + (query().trim() ? ` [${searchMode()}]` : "") : (results().length > 0 ? `${ownerLabel()} ${selected() + 1}/${nextResultOffset()} recent` : `${ownerLabel()} 0 recent`)}</text>
               </box>
             </box>