opencode-rag-plugin 1.15.1 → 1.17.2

package/dist/content/reader.js

@@ -4,7 +4,8 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import pLimit from "p-limit";
-import { computeFileHash, normalizeFilePath } from "../core/manifest.js";
+import { computeFileHash, computeDescriptionConfigHash, normalizeFilePath } from "../core/manifest.js";
+import { DescriptionCache } from "../core/desc-cache.js";
 import { createImageVisionProvider, } from "../chunker/image.js";
 import * as pdfExtractor from "./pdf.js";
 import * as docxExtractor from "./docx.js";
@@ -84,8 +85,11 @@ async function dispatchExtraction(filePath, buffer, imageVisionProvider, imagePr
  * Scan the workspace directory for indexable files, reading content or dispatching
  * binary extraction (PDF, DOCX, DOC, Excel, images). Respects the file manifest
  * for incremental re-indexing by skipping unchanged files.
+ *
+ * @param descCache - Optional persistent description cache. When set, image
+ *   descriptions are cached and reused across sessions (survives aborted runs).
  */
-export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPaths) {
+export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPaths, injectedVisionProvider, descCache) {
     const extensions = new Set(config.indexing.includeExtensions);
     let imageVisionProvider = null;
     let imagePrompt;
@@ -95,7 +99,7 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
         for (const ext of imageExtractor.SUPPORTED_IMAGE_EXTENSIONS) {
             extensions.add(ext.toLowerCase());
         }
-        imageVisionProvider = createImageVisionProvider(imageCfg);
+        imageVisionProvider = injectedVisionProvider ?? createImageVisionProvider(imageCfg);
         imagePrompt = imageCfg.prompt;
         imageResizeMaxDimension = imageCfg.resizeMaxDimension;
     }
@@ -135,6 +139,10 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
     const scanConcurrency = Math.min(config.indexing.concurrency * 2, 16);
     const textLimit = pLimit(scanConcurrency);
     const imageLimit = pLimit(1);
+    // Compute a hash of the image description config — used to build cache keys.
+    const imageDescConfigHash = config.imageDescription?.enabled
+        ? computeDescriptionConfigHash(config) ?? ""
+        : "";
     let completed = 0;
     async function processFile(filePath) {
         const normalizedPath = normalizeFilePath(filePath);
@@ -168,11 +176,48 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
             excelExtractor.EXCEL_EXTENSIONS.has(filePath.toLowerCase()) ||
             isImage;
         logger?.info(`Reading: ${filePath}`);
+        const buffer = isBinary ? await fs.readFile(filePath) : Buffer.alloc(0);
+        // For images, check the persistent description cache before calling the vision provider
+        if (isImage && descCache && imageDescConfigHash) {
+            const imageBytesHash = computeFileHash(buffer.toString("base64"));
+            const cacheKey = DescriptionCache.imageKey(imageBytesHash, imageDescConfigHash);
+            const cachedDesc = descCache.get(cacheKey);
+            if (cachedDesc) {
+                logger?.info(`  Using cached image description: ${filePath}`);
+                const content = cachedDesc;
+                let fileMtime;
+                let fileSize;
+                try {
+                    const stat = await fs.stat(filePath);
+                    fileMtime = stat.mtimeMs;
+                    fileSize = stat.size;
+                }
+                catch { /* best-effort stat */ }
+                completed++;
+                return {
+                    filePath,
+                    normalizedPath,
+                    content,
+                    hash: computeFileHash(content),
+                    isEmpty: false,
+                    isTooSmall: false,
+                    extractionStatus: "ok",
+                    mtime: fileMtime,
+                    size: fileSize,
+                };
+            }
+        }
         if (isImage) {
             logger?.info(`  Describing image: ${filePath}`);
         }
-        const buffer = isBinary ? await fs.readFile(filePath) : Buffer.alloc(0);
         const result = await dispatchExtraction(filePath, buffer, imageVisionProvider, imagePrompt, imageResizeMaxDimension);
+        // Cache the image description for future runs
+        if (isImage && result.ok && descCache && imageDescConfigHash) {
+            const imageBytesHash = computeFileHash(buffer.toString("base64"));
+            const cacheKey = DescriptionCache.imageKey(imageBytesHash, imageDescConfigHash);
+            descCache.set(cacheKey, result.content);
+            await descCache.save();
+        }
         if (!result.ok) {
             logger?.warn(`  ${filePath} (extraction failed: ${result.error})`);
         }

package/dist/core/config.d.ts

@@ -114,6 +114,13 @@ export interface DocumentationModeConfig {
     /** System prompt for the documentation agent. */
     systemPrompt: string;
 }
+/** Configuration for the wiki mode that instructs the AI agent to maintain a persistent knowledge wiki. */
+export interface WikiModeConfig {
+    /** Whether wiki mode is enabled. */
+    enabled: boolean;
+    /** System prompt for the wiki maintainer agent. */
+    systemPrompt: string;
+}
 /** Configuration for the terminal UI (TUI) keybindings. */
 export interface TuiConfig {
     /** Keybinding to toggle the file list panel. */
@@ -128,7 +135,7 @@ export interface McpConfig {
 }
 /** Configuration for automatic self-updates. */
 export interface AutoUpdateConfig {
-    /** Whether auto-update checking is enabled. */
+    /** Whether update checking is enabled (defaults to true). */
     enabled: boolean;
 }
 /** Configuration for post-retrieval context window optimization (adjacent merge, similarity dedup, file diversity cap). */
@@ -164,6 +171,8 @@ export interface RagConfig {
         documentPrefix?: string;
         /** Prefix prepended to queries before embedding (e.g. "search_query:"). */
         queryPrefix?: string;
+        /** Cached embedding vector dimension. Probed once on first startup, then persisted to config. */
+        vectorDimension?: number;
     };
     /** Indexing pipeline controls: what to index, concurrency, batch sizes. */
     indexing: {
@@ -187,6 +196,12 @@ export interface RagConfig {
         ollamaMaxBatchSize?: number;
         /** Maximum concurrent description generation requests. */
         descriptionConcurrency?: number;
+        /**
+         * Maximum file size in bytes for SVG/XML files before chunking is skipped.
+         * Large SVGs can cause tree-sitter to hang. Set to 0 for no limit.
+         * @default 1_048_576 (1 MB)
+         */
+        maxSvgSizeBytes?: number;
     };
     /** Vector storage backend configuration. */
     vectorStore: {
@@ -227,6 +242,8 @@ export interface RagConfig {
         readNoResultsBehavior?: ReadNoResultsBehavior;
         /** Maximum related files shown when read results are empty. */
         readRelatedFilesMax?: number;
+        /** Whether to inject RAG tool guidance into system prompts (default true). */
+        injectSystemPrompt?: boolean;
     };
     /** Custom chunker module registrations. */
     chunkers?: ChunkerConfig[];
@@ -241,6 +258,8 @@ export interface RagConfig {
     imageDescription?: ImageDescriptionConfig;
     /** Automated documentation mode config. */
     documentationMode?: DocumentationModeConfig;
+    /** Wiki mode config that instructs the AI agent to maintain a persistent knowledge wiki. */
+    wikiMode?: WikiModeConfig;
     /** MCP server integration config. */
     mcp?: McpConfig;
     /** Auto-update checking config. */
@@ -293,3 +312,12 @@ export declare const CONFIG_FILE_CANDIDATES: string[];
 export declare function findConfigFile(directory: string): string | undefined;
 /** Load and parse a JSON config file, deep-merge with defaults, optionally validate. */
 export declare function loadConfig(filePath: string, validate?: boolean): RagConfig;
+/**
+ * Persist a probed embedding vector dimension into the config JSON file.
+ * Sets `embedding.vectorDimension` so subsequent startups skip the probe.
+ * This is a best-effort operation — failures are silently ignored.
+ *
+ * @param configPath - Absolute path to the config JSON file.
+ * @param dimension - The vector dimension to persist.
+ */
+export declare function persistProbedDimension(configPath: string, dimension: number): void;

package/dist/core/config.js

@@ -2,7 +2,7 @@
  * @fileoverview Configuration types and defaults for OpenCodeRAG. Defines RagConfig,
  * all sub-config interfaces, DEFAULT_CONFIG, validateConfig, and loadConfig.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { env } from "node:process";
 export const DEFAULT_CONFIG = {
@@ -10,7 +10,7 @@ export const DEFAULT_CONFIG = {
         provider: "ollama",
         baseUrl: "http://127.0.0.1:11434/api",
         model: "qwen3-embedding:0.6b",
-        timeoutMs: 30000,
+        timeoutMs: 120000,
     },
     indexing: {
         includeExtensions: [
@@ -104,8 +104,9 @@ export const DEFAULT_CONFIG = {
         concurrency: 8,
         embedBatchSize: 100,
         embedConcurrency: 6,
-        ollamaMaxBatchSize: 4000,
+        ollamaMaxBatchSize: 500,
         descriptionConcurrency: 4,
+        maxSvgSizeBytes: 1_048_576,
     },
     vectorStore: {
         path: "./.opencode/rag_db",
@@ -113,7 +114,7 @@ export const DEFAULT_CONFIG = {
     },
     retrieval: {
         topK: 20,
-        minScore: 0.5,
+        minScore: 0.35,
         hybridSearch: {
             enabled: true,
             keywordWeight: 0.4,
@@ -130,6 +131,7 @@ export const DEFAULT_CONFIG = {
         enabled: true,
         maxContextChunks: 10,
         readOverride: true,
+        injectSystemPrompt: true,
         autoIndex: {
             enabled: false,
             debounceMs: 2000,
@@ -143,7 +145,7 @@ export const DEFAULT_CONFIG = {
         model: "minicpm-v4.6:latest",
         baseUrl: "http://127.0.0.1:11434/api",
         timeoutMs: 60000,
-        prompt: "Describe this image 10-20 comma-separated keywords.",
+        prompt: "Describe this image in 1-2 sentences: what it shows, its purpose, and key visual elements.",
         think: false,
         numCtx: 2048,
         resizeMaxDimension: 1024,
@@ -156,7 +158,7 @@ export const DEFAULT_CONFIG = {
         think: false,
         numCtx: 4096,
         timeoutMs: 60000,
-        systemPrompt: "Describe this code in 10-20 comma-separated keywords.",
+        systemPrompt: "Describe this code in 2-3 sentences: purpose, key concepts, inputs/outputs, and dependencies. No code repetition.",
         batchConcurrency: 1,
         retryMax: 3,
         retryBaseDelayMs: 1000,
@@ -181,11 +183,72 @@ export const DEFAULT_CONFIG = {
             "## Output format\n\n" +
             "Return your changes as a list of file paths with the full new content of the comment block for each modified symbol. Do NOT output the entire file unless asked.",
     },
+    wikiMode: {
+        enabled: false,
+        systemPrompt: "You are a wiki maintainer for this codebase. You incrementally build and maintain " +
+            "a persistent knowledge wiki at `.opencode/wiki/` — a structured, interlinked collection " +
+            "of markdown files that synthesizes knowledge from the codebase, documentation, and your conversations.\n\n" +
+            "## Three layers\n\n" +
+            "- **Raw sources**: code, docs, READMEs (immutable — read with `search_semantic`, `get_file_skeleton`, `find_usages`, `read`)\n" +
+            "- **Wiki**: `.opencode/wiki/*.md` (you own this layer — create, update, and maintain ALL pages)\n" +
+            "- **Schema**: this prompt (the protocol you follow)\n\n" +
+            "## Wiki layout\n\n" +
+            "`.opencode/wiki/`\n" +
+            "- `index.md` — content catalog: every page listed with a link and one-line summary\n" +
+            "- `log.md` — append-only timeline: `## [date] op | title`\n" +
+            "- `entities/` — pages for modules, services, key classes, components\n" +
+            "- `concepts/` — pages for patterns, conventions, architectural decisions, gotchas\n" +
+            "- `sources/` — summaries of external sources (articles, specs, discussions)\n\n" +
+            "## Page frontmatter\n\n" +
+            "Every page should start with:\n" +
+            "```\n" +
+            "---\n" +
+            "title: <page title>\n" +
+            "tags: [relevant tags]\n" +
+            "sourceRefs: [file paths or URLs this page synthesizes]\n" +
+            "lastReviewed: <date>\n" +
+            "---\n" +
+            "```\n\n" +
+            "## Operations\n\n" +
+            "### Ingest (when you learn something new)\n" +
+            "1. Read the source (code, doc, external article)\n" +
+            "2. Extract key information — what it does, why it exists, how it connects to existing knowledge\n" +
+            "3. Create or update relevant entity/concept pages\n" +
+            "4. Add cross-references with `[[wiki/page-name]]` links between related pages\n" +
+            "5. Update `index.md` with any new pages\n" +
+            "6. Append to `log.md`: `## [date] ingest | page title`\n\n" +
+            "### Query (when the user asks a question)\n" +
+            "1. Read `index.md` first to find relevant wiki pages\n" +
+            "2. Read those pages with the `read` tool\n" +
+            "3. If the wiki is insufficient, use `search_semantic` for code-level retrieval\n" +
+            "4. Synthesize an answer citing wiki pages where possible\n" +
+            "5. If the answer produced valuable analysis, file it back as a new wiki page\n\n" +
+            "### Lint (periodically, or when `/wiki lint` is invoked)\n" +
+            "Check for:\n" +
+            "- Orphan pages with no inbound `[[links]]`\n" +
+            "- Stale pages whose `sourceRefs` files changed since `lastReviewed`\n" +
+            "- Contradictions between pages\n" +
+            "- Important concepts mentioned but lacking their own page\n" +
+            "Append findings to `log.md`.\n\n" +
+            "### Seed (when `/wiki seed` is invoked)\n" +
+            "Generate initial wiki from existing sources:\n" +
+            "1. Read README and top-level docs for project overview → create overview page\n" +
+            "2. Scan file structure with `get_file_skeleton` for major modules → create entity pages\n" +
+            "3. Identify common conventions from code patterns → create concept pages\n" +
+            "4. Create `index.md` listing all pages\n" +
+            "5. Create `log.md` with initial entry\n" +
+            "6. Keep pages focused — one concept per page, short prose\n\n" +
+            "## Principles\n\n" +
+            "- You write and maintain ALL wiki pages — never ask the user to do it\n" +
+            "- Good answers and analyses get filed back as new pages — explorations compound\n" +
+            "- One concept per page — short, focused, cross-referenced\n" +
+            "- The wiki is git-trackable in `.opencode/` — every edit is a diff",
+    },
     mcp: {
         enabled: true,
     },
     autoUpdate: {
-        enabled: false,
+        enabled: true,
     },
     ui: {
         port: 3210,
@@ -213,7 +276,7 @@ export function validateConfig(config) {
     const KNOWN_TOP_KEYS = new Set([
         "embedding", "indexing", "vectorStore", "retrieval",
         "openCode", "chunkers", "chunking", "description",
-        "imageDescription", "documentationMode", "mcp", "autoUpdate", "ui", "tui", "logging",
+        "imageDescription", "documentationMode", "wikiMode", "mcp", "autoUpdate", "ui", "tui", "logging",
     ]);
     const topKeys = new Set(Object.keys(config));
     for (const key of topKeys) {
@@ -331,6 +394,8 @@ export function loadConfig(filePath, validate = true) {
     let parsed;
     try {
         raw = readFileSync(filePath, "utf-8");
+        if (raw.charCodeAt(0) === 0xfeff)
+            raw = raw.slice(1);
         parsed = JSON.parse(raw);
     }
     catch (err) {
@@ -397,6 +462,10 @@ export function loadConfig(filePath, validate = true) {
             ...DEFAULT_CONFIG.documentationMode,
             ...(safeObj(parsed.documentationMode) ?? {}),
         },
+        wikiMode: {
+            ...DEFAULT_CONFIG.wikiMode,
+            ...(safeObj(parsed.wikiMode) ?? {}),
+        },
         mcp: {
             ...DEFAULT_CONFIG.mcp,
             ...(safeObj(parsed.mcp) ?? {}),
@@ -426,4 +495,32 @@ export function loadConfig(filePath, validate = true) {
     }
     return cfg;
 }
+/**
+ * Persist a probed embedding vector dimension into the config JSON file.
+ * Sets `embedding.vectorDimension` so subsequent startups skip the probe.
+ * This is a best-effort operation — failures are silently ignored.
+ *
+ * @param configPath - Absolute path to the config JSON file.
+ * @param dimension - The vector dimension to persist.
+ */
+export function persistProbedDimension(configPath, dimension) {
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf-8");
+    }
+    catch {
+        return;
+    }
+    try {
+        const obj = JSON.parse(raw);
+        const embedding = (obj.embedding ??= {});
+        if (embedding.vectorDimension === dimension)
+            return; // already set
+        embedding.vectorDimension = dimension;
+        writeFileSync(configPath, JSON.stringify(obj, null, 2), "utf-8");
+    }
+    catch {
+        // best-effort
+    }
+}
 //# sourceMappingURL=config.js.map

package/dist/core/desc-cache.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fileoverview Persistent description cache keyed by content hash + description config hash.
+ * Survives aborted index runs so that descriptions are not regenerated unnecessarily.
+ * Two namespaces: "code" (per-chunk descriptions) and "image" (per-file image descriptions).
+ */
+export declare class DescriptionCache {
+    private cache;
+    private cacheDir;
+    private dirty;
+    private savePromise;
+    private loadPromise;
+    constructor(cacheDir: string);
+    /** Load the cache from disk. */
+    load(): Promise<void>;
+    /** Get a cached description for the given key. */
+    get(key: string): string | undefined;
+    /** Set a cached description for the given key. */
+    set(key: string, description: string): void;
+    /** Set multiple entries at once. */
+    setMany(entries: Array<[string, string]>): void;
+    /** Check if a key exists in the cache. */
+    has(key: string): boolean;
+    /** Persist the cache to disk if dirty. Safe to call multiple times. */
+    save(): Promise<void>;
+    /** Build a cache key for a code chunk. */
+    static codeKey(content: string, descConfigHash: string): string;
+    /** Build a cache key for an image file. */
+    static imageKey(imageBytesHash: string, imageDescConfigHash: string): string;
+    /** Remove old entries to stay under the limit. */
+    private maybeEvict;
+}

package/dist/core/desc-cache.js

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Persistent description cache keyed by content hash + description config hash.
+ * Survives aborted index runs so that descriptions are not regenerated unnecessarily.
+ * Two namespaces: "code" (per-chunk descriptions) and "image" (per-file image descriptions).
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+const CACHE_VERSION = 1;
+const MAX_ENTRIES = 50_000;
+const MAX_AGE_DAYS = 30;
+export class DescriptionCache {
+    cache = { version: CACHE_VERSION, entries: {} };
+    cacheDir;
+    dirty = false;
+    savePromise = Promise.resolve();
+    loadPromise = null;
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir;
+    }
+    /** Load the cache from disk. */
+    async load() {
+        if (this.loadPromise)
+            return this.loadPromise;
+        this.loadPromise = (async () => {
+            const cachePath = path.join(this.cacheDir, ".desc-cache.json");
+            try {
+                const raw = await fs.readFile(cachePath, "utf-8");
+                const parsed = JSON.parse(raw);
+                if (parsed.version === CACHE_VERSION && parsed.entries) {
+                    this.cache = parsed;
+                    this.dirty = false;
+                }
+            }
+            catch {
+                // Cache file missing or corrupt — start fresh
+            }
+        })();
+        return this.loadPromise;
+    }
+    /** Get a cached description for the given key. */
+    get(key) {
+        return this.cache.entries[key]?.description;
+    }
+    /** Set a cached description for the given key. */
+    set(key, description) {
+        this.cache.entries[key] = {
+            description,
+            createdAt: Date.now(),
+        };
+        this.dirty = true;
+        this.maybeEvict();
+    }
+    /** Set multiple entries at once. */
+    setMany(entries) {
+        const now = Date.now();
+        for (const [key, description] of entries) {
+            this.cache.entries[key] = { description, createdAt: now };
+        }
+        this.dirty = true;
+        this.maybeEvict();
+    }
+    /** Check if a key exists in the cache. */
+    has(key) {
+        return key in this.cache.entries;
+    }
+    /** Persist the cache to disk if dirty. Safe to call multiple times. */
+    async save() {
+        if (!this.dirty)
+            return;
+        this.savePromise = this.savePromise.then(async () => {
+            const cachePath = path.join(this.cacheDir, ".desc-cache.json");
+            const tmpPath = cachePath + ".tmp";
+            try {
+                await fs.mkdir(this.cacheDir, { recursive: true });
+                await fs.writeFile(tmpPath, JSON.stringify(this.cache), "utf-8");
+                try {
+                    await fs.rename(tmpPath, cachePath);
+                }
+                catch {
+                    await fs.unlink(cachePath).catch(() => { });
+                    await fs.rename(tmpPath, cachePath);
+                }
+                this.dirty = false;
+            }
+            catch {
+                // Best-effort save
+            }
+        });
+        return this.savePromise;
+    }
+    /** Build a cache key for a code chunk. */
+    static codeKey(content, descConfigHash) {
+        const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 16);
+        return contentHash + "_" + descConfigHash.slice(0, 16);
+    }
+    /** Build a cache key for an image file. */
+    static imageKey(imageBytesHash, imageDescConfigHash) {
+        return imageBytesHash.slice(0, 16) + "_" + imageDescConfigHash.slice(0, 16);
+    }
+    /** Remove old entries to stay under the limit. */
+    maybeEvict() {
+        const keys = Object.keys(this.cache.entries);
+        if (keys.length <= MAX_ENTRIES)
+            return;
+        const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000;
+        const entries = this.cache.entries;
+        for (const key of keys) {
+            if (entries[key].createdAt < cutoff) {
+                delete entries[key];
+            }
+        }
+        // If still over limit, delete oldest
+        if (Object.keys(entries).length > MAX_ENTRIES) {
+            const sorted = Object.entries(entries)
+                .sort(([, a], [, b]) => a.createdAt - b.createdAt);
+            const toDelete = Object.keys(entries).length - MAX_ENTRIES;
+            for (let i = 0; i < toDelete; i++) {
+                delete entries[sorted[i][0]];
+            }
+        }
+    }
+}
+//# sourceMappingURL=desc-cache.js.map

package/dist/core/interfaces.d.ts

@@ -22,12 +22,26 @@ export interface DescriptionLogger {
     warn(message: string): void;
     debug(message: string): void;
 }
+/** Progress callback invoked after each chunk is described during batch generation. */
+export type ChunkProgressFn = (chunk: Chunk, completed: number, total: number) => void;
+/** Optional progress reporting for batch description generation. */
+export interface BatchDescriptionOptions {
+    /** Total number of chunks across the whole run (may exceed `chunks.length` when called per sub-batch). */
+    total?: number;
+    /** Called once per completed chunk with the chunk, the running completed count, and `total`. */
+    onProgress?: ChunkProgressFn;
+}
 /** Generates natural-language descriptions for code chunks using an LLM. */
 export interface DescriptionProvider {
     /** Generate a description for a single chunk. */
     generateDescription(chunk: Chunk): Promise<string>;
-    /** Generate descriptions for multiple chunks concurrently. Returns a Map of chunk ID to description. */
-    generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger): Promise<Map<string, string>>;
+    /**
+     * Generate descriptions for multiple chunks concurrently. Returns a Map of chunk ID to description.
+     * @param chunks - Chunks to describe.
+     * @param logger - Optional logger for diagnostic messages.
+     * @param opts - Optional progress reporting options.
+     */
+    generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
 }
 /** Explains how a search result score was computed, including vector and keyword contributions. */
 export interface SearchExplanation {
@@ -43,6 +57,10 @@ export interface SearchExplanation {
         rawKeywordScore: number;
         /** Weight applied to keyword score during fusion (0-1). */
         keywordWeight: number;
+        /** Rank (0-indexed) in the vector store results. */
+        vectorRank?: number;
+        /** Rank (0-indexed) in the keyword index results. */
+        keywordRank?: number;
     };
     /** Query terms that matched in the keyword index, if hybrid search was used. */
     matchedTerms?: string[];
@@ -86,12 +104,14 @@ export interface EmbeddingProvider {
 }
 /** In-memory TF-IDF inverted index for keyword-based search alongside vector search. */
 export interface KeywordIndex {
+    /** Release resources and free memory. */
+    close(): void;
     /** Index a set of chunks by tokenizing their content. */
     addChunks(chunks: Chunk[]): void;
     /** Remove all entries for a given file path from the index. */
     removeByFilePath(filePath: string): void;
     /** Search the index for the top-K matching chunks. */
-    search(query: string, topK: number): SearchResult[];
+    search(query: string, topK: number, filter?: MetadataFilter): SearchResult[];
     /** Get the terms from a query that matched a specific chunk. */
     getMatchedTerms(query: string, chunkId: string): string[];
     /** Clear all indexed data. */
@@ -101,20 +121,55 @@ export interface KeywordIndex {
     /** Persist the index to disk as JSON. */
     save(filePath?: string): Promise<void>;
 }
+/** A paginated chunk summary for dump/list operations. */
+export interface ChunkSummary {
+    id: string;
+    filePath: string;
+    language: string;
+    startLine: number;
+    endLine: number;
+    content: string;
+    description: string;
+}
+/** A file summary for list operations. */
+export interface FileSummary {
+    filePath: string;
+    language: string;
+    chunkCount: number;
+}
 /** Persistent vector storage and retrieval backend (LanceDB or in-memory). */
 export interface VectorStore {
     /** Store a batch of chunks with their embeddings. */
     addChunks(chunks: Chunk[]): Promise<void>;
     /** Search for the top-K nearest neighbor chunks by embedding similarity. */
     search(embedding: number[], topK: number): Promise<SearchResult[]>;
+    /** Search with optional metadata filtering. */
+    searchWithFilter(embedding: number[], topK: number, filter?: MetadataFilter): Promise<SearchResult[]>;
     /** Return the total number of stored chunks. */
     count(): Promise<number>;
     /** Remove all stored data. */
     clear(): Promise<void>;
     /** Delete all chunks associated with a specific file path. */
     deleteByFilePath(filePath: string): Promise<void>;
+    /** Return all unique file paths currently stored in the index. */
+    getFilePaths(): Promise<string[]>;
     /** Release any held resources and close the store. */
     close(): Promise<void>;
+    /** Retrieve a paginated list of chunks without embeddings. */
+    getChunks(offset: number, limit: number): Promise<ChunkSummary[]>;
+    /** List all distinct file paths with language and chunk count. */
+    listFiles(): Promise<FileSummary[]>;
+    /** Retrieve all chunks for a specific file path, sorted by start line. */
+    getChunksByFilePath(filePath: string): Promise<Chunk[]>;
+    /** Re-open the store, optionally pointing at a new database path. */
+    reopen?(newPath?: string): Promise<void>;
+}
+/** Filter criteria for narrowing search results by file path patterns or language. */
+export interface MetadataFilter {
+    /** Glob-style path patterns (e.g. "src/**", "lib/auth/*"). */
+    pathPatterns?: string[];
+    /** Language identifiers (e.g. ["typescript", "tsx"]). */
+    languages?: string[];
 }
 /** Callback interface for reporting indexing progress to the UI or CLI. */
 export interface IndexProgress {