opencode-rag-plugin 1.18.0 → 1.18.1

package/ReadMe.md

@@ -41,13 +41,14 @@ opencode-rag query "authentication middleware"
 | **OpenCode plugin** | Auto-inject context, read-tool override, TUI settings, Ctrl+Enter to add RAG context, MCP registration on `init` |
 | **Incremental indexing** | File-hash manifest, background watcher, auto-rebuild on corruption |
 | **Privacy-first** | All processing stays local (when using Ollama) |
-| **CLI Tools** | `init`, `index`, `query`, `status`, `list`, `show`, `dump`, `clear`, `describe-image`, `ui`, `mcp`, `setup`, `eval:sessions`, `eval:analyze`, `eval:compare` |
+| **CLI Tools** | `init`, `index`, `query`, `status`, `list`, `show`, `dump`, `clear`, `describe-image`, `ui`, `mcp`, `setup`, `quirk`, `eval:sessions`, `eval:analyze`, `eval:compare` |
 | **Proxy-aware** | Corporate proxy support with raw-socket localhost bypass |
 | **OpenAI / Anthropic / Cohere** | Use alternate embedding providers with API key auto-resolution |
 | **Evaluation** | Session-level token tracking, RAG-on vs RAG-off comparison, tiktoken BPE counting |
 | **Documentation mode** | `/doc` slash command: agent adds JSDoc/TSDoc to undocumented files, progress tracked per subdirectory |
 | **Wiki mode** | `/wiki` slash command: agent maintains a persistent knowledge wiki at `.opencode/wiki/` (ingest, query, lint, seed) |
 | **Context optimization** | Post-retrieval dedup, per-file chunk limits, adjacent-merge to fit the context window |
+| **Quirk memory** | Persistent experiential memory — agents recall/persist gotchas, preferences, decisions across sessions (`add_quirk` / `recall_quirks`, `opencode-rag quirk`) |
 | **AGENTS.md directive** | `opencode-rag init` merges a tool-usage directive into `AGENTS.md` via sentinel markers |
 
 ## Web UI
@@ -125,6 +126,45 @@ The agent maintains all wiki pages during normal coding sessions (ingest on lear
 
 See [Plugin documentation](doc/plugin.md#6-wiki-mode--slash-command-wiki) for the full protocol.
 
+## Quirk Memory
+
+OpenCodeRAG gives your agent **persistent, cross-session memory** of non-obvious facts — gotchas, preferences, decisions, and environment constraints — that it can recall and extend over time. Quirks are embedded and stored in the same vector store as your code, then recalled via semantic search whenever they're relevant. This lets the agent avoid repeating mistakes and accumulate project knowledge across sessions.
+
+**Enabled by default.** Turn it on/off in `opencode-rag.json`:
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "autoInject": true,
+    "minConfidence": 0.5,
+    "recallMinScore": 0.3,
+    "decay": { "enabled": true, "halfLifeDays": 30 }
+  }
+}
+```
+
+**Agent tools:**
+
+| Tool | Use when |
+|------|----------|
+| `recall_quirks(query)` | You hit an error or need to remember a gotcha, preference, or decision from past sessions |
+| `add_quirk(content, { type, tags })` | You just discovered a non-obvious fact, workaround, or convention worth remembering |
+
+**CLI — manage quirks directly:**
+
+```bash
+opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
+opencode-rag quirk list
+opencode-rag quirk lint            # flag low-confidence / stale / duplicate quirks
+opencode-rag quirk test "npm needs --legacy-peer-deps"
+# ✓ Quirk has been appended:
+#   [gotcha] npm needs --legacy-peer-deps (installation)
+#   99% confidence
+```
+
+When `memory.autoInject` is `true`, relevant quirks are automatically injected into the prompt during retrieval (via the `chat.message` hook). Every `add_quirk` is vetted by an immutable trust monitor that rejects destructive patterns (e.g. `rm -rf`, `force push`, `bypass security`). See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI Reference: `quirk`](doc/cli.md#quirk).
+
 ## MCP Server (Optional)
 
 OpenCodeRAG ships a CLI-based [MCP (Model Context Protocol)](https://spec.modelcontextprotocol.io/) server that exposes semantic code tools to any MCP-compatible client (Claude Desktop, Cursor, etc.).

package/dist/cli/commands/init-helpers.d.ts

@@ -83,9 +83,13 @@ export declare function mergeGitignoreContent(existingContent?: string): string;
  * provided, the section alone is returned as a new file.
  *
  * @param existingContent - The current `AGENTS.md` content, or `undefined` if absent.
+ * @param opts - Optional settings. `promptEnforcement` controls whether the
+ *   quirk-capture enforcement rules are included (default `true`).
  * @returns The merged `AGENTS.md` content with a trailing newline.
  */
-export declare function mergeAgentsMdContent(existingContent?: string): string;
+export declare function mergeAgentsMdContent(existingContent?: string, opts?: {
+    promptEnforcement?: boolean;
+}): string;
 /**
  * Get the runtime directory path (`~/.opencode`).
  *

package/dist/cli/commands/init-helpers.js

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, rmSync, symlinkSync, } from "node:fs";
 import { execSync } from "node:child_process";
 import { DEFAULT_CONFIG } from "../../core/config.js";
 import { c } from "../format.js";
+import { BEGIN_MARKER, END_MARKER, buildAgentsMdDirective } from "../../opencode/system-guidance.js";
 import { getStringRecord, readJsonObject, writeJsonFile, } from "../helpers.js";
 /**
  * Build the workspace-local `.opencode/package.json` content.
@@ -252,21 +253,6 @@ export function mergeGitignoreContent(existingContent) {
     merged.push("# OpenCodeRAG workspace state", ...missing, "");
     return merged.join("\n");
 }
-const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
-const END_MARKER = "<!-- END opencode-rag -->";
-const AGENTS_MD_SECTION = [
-    BEGIN_MARKER,
-    "## Code Navigation",
-    "",
-    "ALWAYS use OpenCodeRAG tools before reading or editing:",
-    "- **Search first** — `search_semantic(query)` instead of grep/glob",
-    "- **Skeleton before read** — `get_file_skeleton(filePath)` then read specific lines",
-    "- **Usages before edit** — `find_usages(symbolName)` before modifying any symbol",
-    "- **Images via describe** — `describe_image(filePath)` — never read raw bytes",
-    "",
-    "If no results, run `opencode-rag index`.",
-    END_MARKER,
-].join("\n");
 /**
  * Merge the OpenCodeRAG directive section into an existing `AGENTS.md`.
  *
@@ -276,23 +262,26 @@ const AGENTS_MD_SECTION = [
  * provided, the section alone is returned as a new file.
  *
  * @param existingContent - The current `AGENTS.md` content, or `undefined` if absent.
+ * @param opts - Optional settings. `promptEnforcement` controls whether the
+ *   quirk-capture enforcement rules are included (default `true`).
  * @returns The merged `AGENTS.md` content with a trailing newline.
  */
-export function mergeAgentsMdContent(existingContent) {
+export function mergeAgentsMdContent(existingContent, opts) {
+    const section = buildAgentsMdDirective({ promptEnforcement: opts?.promptEnforcement ?? true });
     if (!existingContent) {
-        return `${AGENTS_MD_SECTION}\n`;
+        return `${section}\n`;
     }
     const beginIdx = existingContent.indexOf(BEGIN_MARKER);
     const endIdx = existingContent.indexOf(END_MARKER);
     if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
         const before = existingContent.slice(0, beginIdx);
         const after = existingContent.slice(endIdx + END_MARKER.length);
-        const merged = `${before}${AGENTS_MD_SECTION}${after}`;
+        const merged = `${before}${section}${after}`;
         return merged.endsWith("\n") ? merged : `${merged}\n`;
     }
     const trimmed = existingContent.trimEnd();
     const separator = trimmed.endsWith(BEGIN_MARKER) ? "" : "\n\n";
-    return `${trimmed}${separator}${AGENTS_MD_SECTION}\n`;
+    return `${trimmed}${separator}${section}\n`;
 }
 /**
  * Get the runtime directory path (`~/.opencode`).

package/dist/cli/commands/init.js

@@ -54,6 +54,11 @@ export function registerInitCommand(program) {
             else {
                 console.log(`  ${c.exists("Exists:")}   .opencode/`);
             }
+            // Wiki safety: warn if wiki exists but would be affected (currently init never touches it)
+            const wikiDir = path.join(opencodeDir, "wiki");
+            if (existsSync(wikiDir)) {
+                console.log(`  ${c.exists("Preserved:")} .opencode/wiki/ (never modified by init)`);
+            }
             if (!existsSync(pluginsDir)) {
                 mkdirSync(pluginsDir, { recursive: true });
                 console.log(`  ${c.created("Created:")}  .opencode/plugins/`);
@@ -144,7 +149,18 @@ export function registerInitCommand(program) {
             }
             const agentsMdPath = path.join(cwd, "AGENTS.md");
             const agentsMdExists = existsSync(agentsMdPath);
-            const nextAgentsMd = mergeAgentsMdContent(agentsMdExists ? readFileSync(agentsMdPath, "utf-8") : undefined);
+            // Read effective promptEnforcement from existing config (if present)
+            let promptEnforcement = true;
+            try {
+                if (existsSync(configPath)) {
+                    const existingCfg = loadConfig(configPath, false);
+                    promptEnforcement = existingCfg.memory?.promptEnforcement ?? true;
+                }
+            }
+            catch {
+                // Malformed or missing config — use default
+            }
+            const nextAgentsMd = mergeAgentsMdContent(agentsMdExists ? readFileSync(agentsMdPath, "utf-8") : undefined, { promptEnforcement });
             if (!agentsMdExists || options.force) {
                 writeFileSync(agentsMdPath, nextAgentsMd, "utf-8");
                 console.log(`  ${agentsMdExists ? c.updated("Updated:") : c.created("Created:")} AGENTS.md`);
@@ -170,16 +186,34 @@ export function registerInitCommand(program) {
                 console.log(`  ${c.exists("Exists:")}   .opencode/package.json`);
             }
             const configExists = existsSync(configPath);
-            if (!configExists || options.force) {
-                if (configExists && options.force) {
-                    copyFileSync(configPath, configPath + ".bak");
-                    console.log(`  ${c.dim("Backup:")}        ${configPath}.bak`);
-                }
+            if (!configExists) {
                 writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
-                console.log(`  ${configExists ? c.updated("Updated:") : c.created("Created:")} opencode-rag.json`);
+                console.log(`  ${c.created("Created:")} opencode-rag.json`);
             }
             else {
-                console.log(`  ${c.exists("Exists:")}   opencode-rag.json`);
+                // NEVER overwrite existing config without interactive confirmation
+                let overwrite = false;
+                if (process.stdin.isTTY) {
+                    const readline = await import("node:readline");
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                    const answer = await new Promise((resolve) => {
+                        rl.question(`  ${c.warn("opencode-rag.json already exists.")} Overwrite with default config? A backup will be saved. (y/N) `, resolve);
+                    });
+                    rl.close();
+                    overwrite = /^y(?:es)?$/i.test(answer.trim());
+                }
+                if (overwrite) {
+                    copyFileSync(configPath, `${configPath}.bak`);
+                    console.log(`  ${c.dim("Backup:")}        opencode-rag.json.bak`);
+                    writeFileSync(configPath, generateDefaultConfigJson(), "utf-8");
+                    console.log(`  ${c.updated("Updated:")}  opencode-rag.json`);
+                }
+                else {
+                    console.log(`  ${c.exists("Exists:")}   opencode-rag.json (preserved)`);
+                    if (!process.stdin.isTTY && options.force) {
+                        console.log(`  ${c.warn("Skipped overwrite:")} non-interactive shell. Edit opencode-rag.json manually or re-run in a TTY.`);
+                    }
+                }
             }
             // ── Provider health check + dependency install (parallel) ──
             const healthPromise = options.skipHealthCheck

package/dist/cli/commands/setup.js

@@ -12,16 +12,25 @@ function removeIfExists(targetPath) {
 }
 function checkOpenCodeRunning() {
     try {
-        const pids = execSync("pgrep -x opencode 2>/dev/null || (Get-Process -Name opencode -ErrorAction SilentlyContinue 2>nul | ForEach-Object { $_.Id })", {
-            encoding: "utf-8",
-            timeout: 3_000,
-        }).trim();
-        if (pids) {
+        if (process.platform === "win32") {
+            execSync('tasklist /FI "IMAGENAME eq opencode.exe" 2>nul | find /I "opencode.exe" >nul', {
+                timeout: 3_000,
+                stdio: "ignore",
+            });
             console.log(`\n  ${c.warn("OpenCode is currently running.")} Restart it to load the updated plugin.`);
         }
+        else {
+            const pids = execSync("pgrep -x opencode 2>/dev/null", {
+                encoding: "utf-8",
+                timeout: 3_000,
+            }).trim();
+            if (pids) {
+                console.log(`\n  ${c.warn("OpenCode is currently running.")} Restart it to load the updated plugin.`);
+            }
+        }
     }
     catch {
-        // pgrep/Get-Process aren't available or succeeded silently
+        // OpenCode not found or tools unavailable
     }
 }
 export function registerSetupCommand(program) {

package/dist/cli/commands/ui.js

@@ -32,7 +32,7 @@ export function registerUiCommand(program) {
             const port = parseInt(options.port ?? String(config.ui?.port ?? 3210), 10);
             const openBrowser = options.open !== false && (config.ui?.openBrowser ?? true);
             const { startWebUi } = await import("../../web/server.js");
-            const server = await startWebUi(storePath, port, cwd);
+            const server = await startWebUi(storePath, port, cwd, config.embedding.vectorDimension ?? 384, config);
             const url = `http://127.0.0.1:${server.port}`;
             logCliInfo(logFilePath, "ui", `\n${c.heading("OpenCodeRAG Web UI")}`);
             logCliInfo(logFilePath, "ui", `  ${c.label("URL:")} ${c.value(url)}`);

package/dist/core/config.d.ts

@@ -131,6 +131,16 @@ export interface MemoryConfig {
     minConfidence: number;
     /** Minimum query-relevance score (0-1) for a quirk to be recalled. */
     recallMinScore: number;
+    /** Automatically extract quirks from each completed agent turn. */
+    passiveCapture: boolean;
+    /** Upgrade the system-prompt nudge into a mandatory trigger. */
+    promptEnforcement: boolean;
+    /** Summarize the full session transcript into quirks at session end. */
+    sessionEndExtraction: boolean;
+    /** Max quirks to auto-capture per turn/session-end pass. */
+    autoCaptureMaxPerTurn: number;
+    /** Lexical similarity threshold (0-1) above which a candidate is considered a duplicate and skipped. */
+    autoCaptureDedupThreshold: number;
     /** Decay settings for aging quirks. */
     decay: {
         /** Whether confidence decays over time. */

package/dist/core/config.js

@@ -184,7 +184,7 @@ export const DEFAULT_CONFIG = {
             "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,
+        enabled: true,
         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" +
@@ -258,6 +258,11 @@ export const DEFAULT_CONFIG = {
         autoInject: false,
         minConfidence: 0.5,
         recallMinScore: 0.72,
+        passiveCapture: false,
+        promptEnforcement: true,
+        sessionEndExtraction: true,
+        autoCaptureMaxPerTurn: 2,
+        autoCaptureDedupThreshold: 0.85,
         decay: {
             enabled: false,
             halfLifeDays: 30,

package/dist/core/interfaces.d.ts

@@ -52,6 +52,13 @@ export interface DescriptionProvider {
      * @param opts - Optional progress reporting options.
      */
     generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
+    /**
+     * Generate free-form text from a system prompt and user message.
+     * Used by auto-capture to extract quirks from agent transcripts.
+     */
+    generateText(system: string, user: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<string>;
 }
 /** Explains how a search result score was computed, including vector and keyword contributions. */
 export interface SearchExplanation {
@@ -176,6 +183,8 @@ export interface VectorStore {
     getChunksByFilePath(filePath: string): Promise<Chunk[]>;
     /** Re-open the store, optionally pointing at a new database path. */
     reopen?(newPath?: string): Promise<void>;
+    /** Compact fragments and prune old versions to prevent version-manifest accumulation. */
+    optimize?(): Promise<void>;
 }
 /** Filter criteria for narrowing search results by file path, language, or kind. */
 export interface MetadataFilter {

package/dist/core/runtime-overrides.d.ts

@@ -42,6 +42,13 @@ export interface RuntimeOverrides {
         model?: string;
         provider?: string;
     };
+    memory?: {
+        passiveCapture?: boolean;
+        promptEnforcement?: boolean;
+        sessionEndExtraction?: boolean;
+        autoCaptureMaxPerTurn?: number;
+        autoCaptureDedupThreshold?: number;
+    };
     tui?: {
         fileListKeybinding?: string;
         chunksKeybinding?: string;

package/dist/core/runtime-overrides.js

@@ -122,6 +122,21 @@ export function applyRuntimeOverrides(cfg, overrides) {
             merged.imageDescription.model = overrides.imageDescription.model;
         }
     }
+    if (overrides.memory) {
+        if (!merged.memory)
+            merged.memory = { ...DEFAULT_CONFIG.memory };
+        const m = merged.memory;
+        if (overrides.memory.passiveCapture !== undefined)
+            m.passiveCapture = overrides.memory.passiveCapture;
+        if (overrides.memory.promptEnforcement !== undefined)
+            m.promptEnforcement = overrides.memory.promptEnforcement;
+        if (overrides.memory.sessionEndExtraction !== undefined)
+            m.sessionEndExtraction = overrides.memory.sessionEndExtraction;
+        if (overrides.memory.autoCaptureMaxPerTurn !== undefined)
+            m.autoCaptureMaxPerTurn = overrides.memory.autoCaptureMaxPerTurn;
+        if (overrides.memory.autoCaptureDedupThreshold !== undefined)
+            m.autoCaptureDedupThreshold = overrides.memory.autoCaptureDedupThreshold;
+    }
     if (overrides.tui) {
         merged.tui = {
             ...DEFAULT_CONFIG.tui,

package/dist/describer/anthropic.d.ts

@@ -18,6 +18,10 @@ export declare class AnthropicDescriptionProvider implements DescriptionProvider
     /** @inheritdoc */
     generateDescription(chunk: Chunk): Promise<string>;
     /** @inheritdoc */
+    generateText(system: string, user: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<string>;
+    /** @inheritdoc */
     generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
     /**
      * Sends a request to the Anthropic Messages API with retry and exponential backoff.

package/dist/describer/anthropic.js

@@ -25,6 +25,13 @@ export class AnthropicDescriptionProvider {
         return this.chatRequest(messages, this.config.timeoutMs ?? 60000);
     }
     /** @inheritdoc */
+    async generateText(system, user, opts) {
+        const messages = [
+            { role: "user", content: user },
+        ];
+        return this.chatRequest(messages, opts?.timeoutMs ?? this.config.timeoutMs ?? 60000, system);
+    }
+    /** @inheritdoc */
     async generateBatchDescriptions(chunks, logger, opts) {
         const log = logger ?? { info: (msg) => process.stderr.write(`${msg}\n`), warn: (msg) => process.stderr.write(`${msg}\n`), debug: (msg) => process.stderr.write(`${msg}\n`) };
         const concurrency = this.config.batchConcurrency ?? 3;
@@ -60,10 +67,10 @@ export class AnthropicDescriptionProvider {
      * @returns The trimmed response text from the model.
      * @throws When all retry attempts are exhausted or the response is empty.
      */
-    async chatRequest(messages, timeoutMs) {
+    async chatRequest(messages, timeoutMs, systemOverride) {
         const baseUrl = this.config.baseUrl.replace(/\/+$/, "");
         const apiKey = this.config.apiKey ?? "";
-        const systemPrompt = this.config.systemPrompt;
+        const systemPrompt = systemOverride ?? this.config.systemPrompt;
         const body = {
             model: this.config.model,
             max_tokens: 4096,

package/dist/describer/describer.d.ts

@@ -18,6 +18,10 @@ export declare class LlmDescriptionProvider implements DescriptionProvider {
     /** @inheritdoc */
     generateDescription(chunk: Chunk): Promise<string>;
     /** @inheritdoc */
+    generateText(system: string, user: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<string>;
+    /** @inheritdoc */
     generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
     /**
      * Sends a chat completion request to the LLM API with retry and exponential backoff.

package/dist/describer/describer.js

@@ -26,6 +26,14 @@ export class LlmDescriptionProvider {
         return this.chatRequest(messages, this.config.timeoutMs ?? 60000);
     }
     /** @inheritdoc */
+    async generateText(system, user, opts) {
+        const messages = [
+            { role: "system", content: system },
+            { role: "user", content: user },
+        ];
+        return this.chatRequest(messages, opts?.timeoutMs ?? this.config.timeoutMs ?? 60000);
+    }
+    /** @inheritdoc */
     async generateBatchDescriptions(chunks, logger, opts) {
         const log = logger ?? { info: (msg) => process.stderr.write(`${msg}\n`), warn: (msg) => process.stderr.write(`${msg}\n`), debug: (msg) => process.stderr.write(`${msg}\n`) };
         const concurrency = this.config.batchConcurrency ?? 3;

package/dist/describer/gemini.d.ts

@@ -12,6 +12,9 @@ export declare class GeminiDescriptionProvider implements DescriptionProvider {
     private readonly config;
     constructor(config: DescriptionConfig);
     generateDescription(chunk: Chunk): Promise<string>;
+    generateText(system: string, user: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<string>;
     generateBatchDescriptions(chunks: Chunk[], logger?: DescriptionLogger, opts?: BatchDescriptionOptions): Promise<Map<string, string>>;
     private chatRequest;
 }

package/dist/describer/gemini.js

@@ -21,6 +21,12 @@ export class GeminiDescriptionProvider {
         ];
         return this.chatRequest(contents, this.config.timeoutMs ?? 60000);
     }
+    async generateText(system, user, opts) {
+        const contents = [
+            { role: "user", parts: [{ text: user }] },
+        ];
+        return this.chatRequest(contents, opts?.timeoutMs ?? this.config.timeoutMs ?? 60000, system);
+    }
     async generateBatchDescriptions(chunks, logger, opts) {
         const log = logger ?? { info: (msg) => process.stderr.write(`${msg}\n`), warn: (msg) => process.stderr.write(`${msg}\n`), debug: (msg) => process.stderr.write(`${msg}\n`) };
         const concurrency = this.config.batchConcurrency ?? 3;
@@ -46,11 +52,11 @@ export class GeminiDescriptionProvider {
         log.debug(`[describer] Descriptions generated: ${result.size}/${total}`);
         return result;
     }
-    async chatRequest(contents, timeoutMs) {
+    async chatRequest(contents, timeoutMs, systemOverride) {
         const baseUrl = this.config.baseUrl.replace(/\/+$/, "");
         const apiKey = this.config.apiKey ?? "";
         const model = this.config.model;
-        const systemPrompt = this.config.systemPrompt;
+        const systemPrompt = systemOverride ?? this.config.systemPrompt;
         const allParts = [{ text: systemPrompt }];
         for (const c of contents) {
             allParts.push(...c.parts);

package/dist/indexer/pipeline.js

@@ -169,7 +169,10 @@ async function runIndexPassInner(options, logger) {
     const workspaceFiles = await scanWorkspaceFiles(options.cwd, options.config, logger, options.force ? undefined : manifest, filterPaths, options.imageVisionProvider, descCache);
     const scanSec = ((Date.now() - scanStart) / 1000).toFixed(1);
     logger.info(`Workspace scan complete: ${workspaceFiles.length} files in ${scanSec}s`);
+    logger.info(`Querying vector store for existing chunk count...`);
+    const storeCountStart = Date.now();
     const existingCount = await options.store.count();
+    logger.info(`Store has ${existingCount} existing chunks (${((Date.now() - storeCountStart) / 1000).toFixed(1)}s)`);
     // Detect data loss: if the store has far fewer chunks than the manifest expects,
     // treat it as a corrupt store (e.g. schema migration dropped the old table).
     if (!options.force && manifestStatus === "ok" && existingCount > 0) {
@@ -276,6 +279,11 @@ async function runIndexPassInner(options, logger) {
     logger.debug(`Processing ${workspaceFiles.length} files (${newCount} new, ${modifiedCount} modified, ${unchangedCount} unchanged)...`);
     const limit = pLimit(options.config.indexing.concurrency);
     const deferDescriptions = !!options.descriptionProvider;
+    const activeCount = workspaceFiles.filter((f) => !f.isEmpty && !f.isTooSmall && (!manifest.files[f.normalizedPath] || manifest.files[f.normalizedPath].hash !== f.hash)).length;
+    logger.info(`Chunking ${activeCount} file(s)...`);
+    let chunkedDone = 0;
+    const chunkProgressInterval = Math.max(1, Math.floor(activeCount / 20));
+    const chunkPhaseStart = Date.now();
     const prepared = await Promise.all(workspaceFiles.map((file) => limit(async () => {
         const fileLabel = path.relative(options.cwd, file.normalizedPath).replace(/\\/g, "/");
         const isActive = !file.isEmpty && !file.isTooSmall &&
@@ -284,11 +292,20 @@ async function runIndexPassInner(options, logger) {
             options.progress?.startFile(fileLabel);
         }
         const prep = await prepareFile(file, options.cwd, manifest.files[file.normalizedPath], options.config, options.keywordIndex, options.descriptionProvider, logger, deferDescriptions, descHash);
+        if (isActive) {
+            chunkedDone++;
+            if (chunkedDone % chunkProgressInterval === 0 || chunkedDone === activeCount) {
+                const pct = ((chunkedDone / activeCount) * 100).toFixed(1);
+                logger.info(`  Chunking: ${chunkedDone}/${activeCount} files (${pct}%)`);
+            }
+        }
         if (prep.earlyResult && isActive) {
             options.progress?.finishFile(fileLabel);
         }
         return prep;
     })));
+    const chunkPhaseSec = ((Date.now() - chunkPhaseStart) / 1000).toFixed(1);
+    logger.info(`Chunking complete: ${activeCount} files in ${chunkPhaseSec}s`);
     const aborted = () => options.abortSignal?.aborted ?? false;
     // Shared progress logger: "stage <file> (chunk i/n) — X/total remaining (P%)".
     const logChunkProgress = (stage, fileLabel, index, count, completed, total) => {
@@ -302,6 +319,7 @@ async function runIndexPassInner(options, logger) {
             const allChunks = [];
             const oversizedChunks = [];
             const maxContentChars = options.config.description?.maxContentChars;
+            logger.info(`Description phase: ${deferredPreps.length} files with chunks to describe`);
             for (const prep of deferredPreps) {
                 for (const chunk of prep.chunks) {
                     if (chunk.metadata.contentType !== "image") {
@@ -469,6 +487,8 @@ async function runIndexPassInner(options, logger) {
             for (const prep of deferredPreps) {
                 prep.textToEmbed = buildTextsToEmbed(prep.chunks, prep.relPath, prep.metaHeader ?? "", prep.docPrefix ?? "", prep.isImageFile ?? false);
             }
+            const totalDescribedChunks = deferredPreps.reduce((s, p) => s + (p.chunks?.length ?? 0), 0);
+            logger.info(`Description phase complete: ${totalDescribedChunks} chunks across ${deferredPreps.length} files`);
         }
     }
     // Cross-file embedding batch: collect all texts into a single queue,
@@ -530,12 +550,15 @@ async function runIndexPassInner(options, logger) {
     let embeddedDone = 0;
     const allTexts = embedQueue.map(item => item.text);
     let allEmbeddings = [];
+    const embedPhaseStart = Date.now();
     if (allTexts.length > 0) {
+        logger.info(`Embedding phase: ${allTexts.length} texts in batches of ${batchSize}...`);
         try {
             allEmbeddings = await embedBatch(options.embedder, allTexts, batchSize, "document", defaultConcurrency, (completed, total) => {
                 embeddedDone = completed;
                 logChunkProgress("Embedding", "", completed, total, embeddedDone, totalEmbedChunks);
             });
+            logger.info(`Embedding complete: ${allTexts.length} texts in ${((Date.now() - embedPhaseStart) / 1000).toFixed(1)}s`);
         }
         catch (err) {
             logger.warn(`  Global embedding failed: ${err.message}`);
@@ -564,6 +587,8 @@ async function runIndexPassInner(options, logger) {
     }
     // ── Phase 3: Store + manifest update per file (parallel) ──────────────
     const filesToStore = prepared.filter((p) => !earlyWorkerResults.has(prepared.indexOf(p)) && p.chunks && (p.textToEmbed?.length ?? 0) > 0).length;
+    const storePhaseStart = Date.now();
+    logger.info(`Store phase: storing ${filesToStore} file(s) into vector database...`);
     let storedFiles = 0;
     const storeLimit = pLimit(options.config.indexing.concurrency);
     const storeResults = await Promise.all(prepared.map((prep, fi) => storeLimit(async () => {
@@ -648,6 +673,8 @@ async function runIndexPassInner(options, logger) {
             entry.size = size;
         }
     }
+    const storePhaseSec = ((Date.now() - storePhaseStart) / 1000).toFixed(1);
+    logger.info(`Store phase complete: ${storedFiles} files stored in ${storePhaseSec}s (${stats.totalChunks} total chunks)`);
     aggregateStats(stats, finalResults);
     // Update timestamps; advance lastGitCommit ONLY on a complete pass
     manifest.lastIndexedAt = Date.now();
@@ -696,6 +723,19 @@ async function runIndexPassInner(options, logger) {
     // a successful swap this points to the new data; after an abort it's the old).
     await saveManifest(options.storePath, manifest);
     await options.keywordIndex?.save(options.storePath);
+    // Compact fragments and prune old version manifests so countRows() can't
+    // hang on accumulated versions from many add/delete cycles.
+    if (!aborted()) {
+        logger.info("Optimizing vector store (compacting fragments, pruning old versions)...");
+        const optimizeStart = Date.now();
+        try {
+            await effectiveStore.optimize?.();
+            logger.info(`Vector store optimized in ${((Date.now() - optimizeStart) / 1000).toFixed(1)}s`);
+        }
+        catch (err) {
+            logger.warn(`Vector store optimization failed: ${err.message}`);
+        }
+    }
     // Persist description cache
     await descCache.save();
     // Count from the store — after a successful swap, the original handle has

package/dist/opencode/system-guidance.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Single source of truth for the mandatory OpenCodeRAG tool-usage guidance
+ * that is injected into both the runtime system prompt (via plugin.ts) and the AGENTS.md
+ * directive (via init-helpers.ts).
+ */
+/** Sentinel marker that opens the managed section. */
+export declare const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
+/** Sentinel marker that closes the managed section. */
+export declare const END_MARKER = "<!-- END opencode-rag -->";
+/**
+ * The always-on mandatory guidance lines — tool list, decision tree,
+ * proactive triggers, and anti-patterns. Used verbatim by the runtime
+ * system prompt injector.
+ */
+export declare const MANDATORY_GUIDANCE_LINES: readonly string[];
+/**
+ * The conditional quirk-capture enforcement lines. Only included when
+ * `memory.promptEnforcement` is true.
+ */
+export declare const QUIRK_ENFORCEMENT_LINES: readonly string[];
+/**
+ * Build the flat guidance lines array for the runtime system-prompt injector.
+ * Returns a new array each call.
+ */
+export declare function buildSystemGuidanceLines(opts: {
+    promptEnforcement: boolean;
+}): string[];
+/**
+ * Build the markdown-formatted AGENTS.md directive section, wrapped in sentinel
+ * markers so `mergeAgentsMdContent` can replace it in place on re-runs.
+ */
+export declare function buildAgentsMdDirective(opts: {
+    promptEnforcement: boolean;
+}): string;