opencode-rag-plugin 1.18.0 → 1.18.2

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,48 @@ 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 **automatically injected into the agent's context on every user message** when their relevance score exceeds the configured threshold. Injection uses two thresholds: the stricter `recallMinScore` (0.72) for the user message context, and the more permissive `autoInjectMinScore` (0.45) for the system prompt. This lets the agent avoid repeating mistakes and accumulate project knowledge across sessions without manual recall.
+
+**Enabled by default.** Turn it on/off in `opencode-rag.json`:
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "autoInject": true,
+    "minConfidence": 0.5,
+    "recallMinScore": 0.8,
+    "autoInjectMinScore": 0.6,
+    "autoInjectTopK": 2,
+    "autoInjectLatencyBudgetMs": 2000,
+    "decay": { "enabled": false, "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`, the plugin checks for relevant quirks on every user message using the combined agent-response + user-query as the search query. Quirks are only injected when their relevance score exceeds the threshold — `recallMinScore` (default 0.72) for the user message, `autoInjectMinScore` (default 0.45) for the system prompt. A latency budget (`autoInjectLatencyBudgetMs`, default 2000ms) prevents slow embedders from blocking message processing. To avoid polluting the context window, each quirk is injected **at most once per session** — once recalled, it is filtered out from all subsequent auto-injections. 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/query.js

@@ -74,7 +74,7 @@ export function registerQueryCommand(program) {
                         logCliInfo(logFilePath, "query", `  ${c.label("  Matched:")} ${c.lang(r.explanation.matchedTerms.join(", "))}`);
                     }
                 }
-                logCliInfo(logFilePath, "query", `  ${pc.dim(r.chunk.content.slice(0, 200).replace(/\n/g, "\n  "))}`);
+                logCliInfo(logFilePath, "query", `  ${pc.dim(r.chunk.content.replace(/\n/g, "\n  "))}`);
             }
             await cleanupContext(ctx);
         }

package/dist/cli/commands/quirk.js

@@ -51,7 +51,7 @@ export function registerQuirkCommand(program) {
                 const badge = q.quirkType ? `[${q.quirkType}] ` : "";
                 const tags = q.tags.length > 0 ? ` (${q.tags.join(", ")})` : "";
                 const date = q.lastObserved ? new Date(q.lastObserved).toLocaleDateString() : "";
-                logCliInfo(ctx.logFilePath, "quirk list", `  ${c.value(badge)}${c.file(q.content.slice(0, 120))}${c.dim(tags)} ${c.dim(date)}`);
+                logCliInfo(ctx.logFilePath, "quirk list", `  ${c.value(badge)}${c.file(q.content)}${c.dim(tags)} ${c.dim(date)}`);
             }
             await cleanupContext(ctx);
         }
@@ -119,7 +119,7 @@ export function registerQuirkCommand(program) {
                     const badge = r.chunk.metadata.quirkType ? `[${r.chunk.metadata.quirkType}] ` : "";
                     const tags = r.chunk.metadata.tags?.length ? ` (${r.chunk.metadata.tags.join(", ")})` : "";
                     const confidence = r.chunk.metadata.confidence ? `${(r.chunk.metadata.confidence * 100).toFixed(0)}% confidence` : "";
-                    logCliInfo(ctx.logFilePath, "quirk test", `  ${c.value(badge)}${c.file(r.chunk.content.slice(0, 120))}${c.dim(tags)}`);
+                    logCliInfo(ctx.logFilePath, "quirk test", `  ${c.value(badge)}${c.file(r.chunk.content)}${c.dim(tags)}`);
                     logCliInfo(ctx.logFilePath, "quirk test", `  ${c.dim(confidence)}`);
                     logCliInfo(ctx.logFilePath, "quirk test", "");
                 }

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,22 @@ export interface MemoryConfig {
     minConfidence: number;
     /** Minimum query-relevance score (0-1) for a quirk to be recalled. */
     recallMinScore: number;
+    /** Minimum relevance score for auto-injected quirks (lower than recallMinScore for manual calls). */
+    autoInjectMinScore: number;
+    /** Maximum latency budget (ms) for auto-inject quirk recall. If exceeded, injection is skipped. */
+    autoInjectLatencyBudgetMs: number;
+    /** Max quirks to auto-inject per turn (default 2). */
+    autoInjectTopK: 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,14 @@ export const DEFAULT_CONFIG = {
         autoInject: false,
         minConfidence: 0.5,
         recallMinScore: 0.72,
+        autoInjectMinScore: 0.6,
+        autoInjectLatencyBudgetMs: 2000,
+        autoInjectTopK: 2,
+        passiveCapture: false,
+        promptEnforcement: true,
+        sessionEndExtraction: true,
+        autoCaptureMaxPerTurn: 2,
+        autoCaptureDedupThreshold: 0.85,
         decay: {
             enabled: false,
             halfLifeDays: 30,
@@ -345,6 +353,19 @@ export function validateConfig(config) {
         if (r < 0 || r > 1)
             warnings.push("memory.recallMinScore must be between 0 and 1");
     }
+    if (config.memory?.autoInjectMinScore != null) {
+        const r = config.memory.autoInjectMinScore;
+        if (r < 0 || r > 1)
+            warnings.push("memory.autoInjectMinScore must be between 0 and 1");
+    }
+    if (config.memory?.autoInjectLatencyBudgetMs != null) {
+        const r = config.memory.autoInjectLatencyBudgetMs;
+        if (r < 0)
+            warnings.push("memory.autoInjectLatencyBudgetMs must be >= 0");
+    }
+    if (config.memory?.autoInjectTopK != null && config.memory.autoInjectTopK < 1) {
+        warnings.push("memory.autoInjectTopK must be >= 1");
+    }
     if (config.openCode.maxContextChunks <= 0) {
         warnings.push("openCode.maxContextChunks must be > 0");
     }

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,16 @@ export interface RuntimeOverrides {
         model?: string;
         provider?: string;
     };
+    memory?: {
+        passiveCapture?: boolean;
+        promptEnforcement?: boolean;
+        sessionEndExtraction?: boolean;
+        autoCaptureMaxPerTurn?: number;
+        autoCaptureDedupThreshold?: number;
+        autoInjectMinScore?: number;
+        autoInjectLatencyBudgetMs?: number;
+        autoInjectTopK?: number;
+    };
     tui?: {
         fileListKeybinding?: string;
         chunksKeybinding?: string;
@@ -50,6 +60,6 @@ export interface RuntimeOverrides {
 /** Load runtime overrides from the store directory. Returns empty object if none exist. */
 export declare function loadRuntimeOverrides(storePath: string): RuntimeOverrides;
 /** Save a single runtime override value at a dotted path. Creates intermediate objects as needed. */
-export declare function saveRuntimeOverride(storePath: string, path: string[], value: boolean | number | string): void;
+export declare function saveRuntimeOverride(storePath: string, path: string[], value: boolean | number | string | Record<string, unknown>): void;
 /** Deep-merge runtime overrides into a config object. Returns a new object without mutating the original. */
 export declare function applyRuntimeOverrides(cfg: RagConfig, overrides: RuntimeOverrides): RagConfig;

package/dist/core/runtime-overrides.js

@@ -122,6 +122,27 @@ 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.memory.autoInjectMinScore !== undefined)
+            m.autoInjectMinScore = overrides.memory.autoInjectMinScore;
+        if (overrides.memory.autoInjectLatencyBudgetMs !== undefined)
+            m.autoInjectLatencyBudgetMs = overrides.memory.autoInjectLatencyBudgetMs;
+        if (overrides.memory.autoInjectTopK !== undefined)
+            m.autoInjectTopK = overrides.memory.autoInjectTopK;
+    }
     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);