opencode-rag-plugin 1.17.3 → 1.18.1

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;

package/dist/opencode/system-guidance.js

@@ -0,0 +1,127 @@
+/**
+ * @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 const BEGIN_MARKER = "<!-- BEGIN opencode-rag -->";
+/** Sentinel marker that closes the managed section. */
+export 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 const MANDATORY_GUIDANCE_LINES = [
+    "MANDATORY: OpenCodeRAG tools MUST be used before any code task:",
+    "- `search_semantic(query)`: retrieve relevant code chunks. Call BEFORE planning, editing, or answering. Accepts `pathHints` and `languageHints`.",
+    "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
+    "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
+    "- `describe_image(filePath)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image.",
+    "- `recall_quirks(query)`: query experiential quirk memory (gotchas, preferences, decisions). Call when you hit an error or need to recall known pitfalls.",
+    "- `add_quirk(content)`: store a new experiential memory. Call when you discover a non-obvious fact, gotcha, or coding convention.",
+    "",
+    "Decision tree — ALWAYS follow this order:",
+    "1. User mentions code behavior/architecture → `search_semantic(query)`",
+    "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
+    "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
+    "4. User asks a code question → `search_semantic` to gather context before answering",
+    "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+    "6. You encounter an error or need to recall a known pitfall → `recall_quirks(query)`",
+    "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it for future sessions",
+    "",
+    "Proactive triggers — you MUST call these tools when:",
+    "- User asks about code behavior, architecture, or implementation details",
+    "- User asks to edit, refactor, or fix code — call `find_usages` first",
+    "- User references files or functions you haven't read yet",
+    "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
+    "- User refers to an image, screenshot, diagram, or visual asset",
+    "- Before answering ANY code-related question, retrieve context first",
+    "- Before reading ANY file, call `get_file_skeleton` to orient first",
+    "",
+    "Anti-patterns — NEVER do these:",
+    "- Reading full files without calling `get_file_skeleton` first (wastes tokens)",
+    "- Editing a function without calling `find_usages` first (breaks call sites)",
+    "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
+    "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
+    "- Treating image files as text — use `describe_image` instead of reading raw bytes",
+    "- Using `npx opencode-rag quirk` shell commands instead of the built-in `add_quirk` / `recall_quirks` tools (the tools are faster, already loaded in-process, and go through the trust monitor)",
+];
+/**
+ * The conditional quirk-capture enforcement lines. Only included when
+ * `memory.promptEnforcement` is true.
+ */
+export const QUIRK_ENFORCEMENT_LINES = [
+    "",
+    "MANDATORY quirk capture rules — you MUST call `add_quirk` when:",
+    "- A build, test, or type-check command fails and you resolve it",
+    "- You discover an undocumented library constraint, peer dep, or workaround",
+    "- You learn an environment-specific requirement (OS, tool version, etc.)",
+    "- You make a design decision that future sessions should remember",
+    "- You resolve a gotcha that cost more than one attempt",
+    "",
+    "Anti-pattern — NEVER finish a coding session without adding quirks for resolved errors.",
+];
+/**
+ * Build the flat guidance lines array for the runtime system-prompt injector.
+ * Returns a new array each call.
+ */
+export function buildSystemGuidanceLines(opts) {
+    const lines = [...MANDATORY_GUIDANCE_LINES];
+    if (opts.promptEnforcement) {
+        lines.push(...QUIRK_ENFORCEMENT_LINES);
+    }
+    return lines;
+}
+/**
+ * Build the markdown-formatted AGENTS.md directive section, wrapped in sentinel
+ * markers so `mergeAgentsMdContent` can replace it in place on re-runs.
+ */
+export function buildAgentsMdDirective(opts) {
+    const lines = [
+        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",
+        "- **Recall quirks** — `recall_quirks(query)` when you hit a known pitfall",
+        "- **Add quirks** — `add_quirk(content)` when you discover a non-obvious fact",
+        "",
+        "If no results, run `opencode-rag index`.",
+        "",
+        "### Decision tree — ALWAYS follow this order",
+        "1. User mentions code behavior/architecture → `search_semantic(query)`",
+        "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
+        "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
+        "4. User asks a code question → `search_semantic` to gather context before answering",
+        "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+        "6. You encounter an error or need to recall a known pitfall → `recall_quirks(query)`",
+        "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it for future sessions",
+        "",
+        "### Proactive triggers — you MUST call these tools when",
+        "- User asks about code behavior, architecture, or implementation details",
+        "- User asks to edit, refactor, or fix code — call `find_usages` first",
+        "- User references files or functions you haven't read yet",
+        "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
+        "- User refers to an image, screenshot, diagram, or visual asset",
+        "- Before answering ANY code-related question, retrieve context first",
+        "- Before reading ANY file, call `get_file_skeleton` to orient first",
+        "",
+        "### Anti-patterns — NEVER do these",
+        "- Reading full files without calling `get_file_skeleton` first (wastes tokens)",
+        "- Editing a function without calling `find_usages` first (breaks call sites)",
+        "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
+        "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
+        "- Treating image files as text — use `describe_image` instead of reading raw bytes",
+        "- Using `npx opencode-rag quirk` shell commands instead of the built-in `add_quirk` / `recall_quirks` tools (the tools are faster, already loaded in-process, and go through the trust monitor)",
+    ];
+    if (opts.promptEnforcement) {
+        lines.push("", "### MANDATORY quirk capture rules — you MUST call `add_quirk` when", "- A build, test, or type-check command fails and you resolve it", "- You discover an undocumented library constraint, peer dep, or workaround", "- You learn an environment-specific requirement (OS, tool version, etc.)", "- You make a design decision that future sessions should remember", "- You resolve a gotcha that cost more than one attempt", "- NEVER finish a coding session without adding quirks for resolved errors.");
+    }
+    lines.push(END_MARKER);
+    return lines.join("\n");
+}
+//# sourceMappingURL=system-guidance.js.map

package/dist/opencode/tools.d.ts

@@ -67,3 +67,41 @@ export declare function createDescribeImageTool(options: DescribeImageToolOption
  * @returns A tool definition suitable for OpenCode plugin registration.
  */
 export declare function createFindUsagesTool(options: FindUsagesToolOptions): ToolDefinition;
+/** Options for creating the `recall_quirks` tool. */
+export interface RecallQuirksToolOptions {
+    store: VectorStore;
+    embedder: EmbeddingProvider;
+    cfg: RagConfig;
+    keywordIndex: KeywordIndex;
+    storePath: string;
+}
+/**
+ * Create the `recall_quirks` tool.
+ *
+ * Queries experiential quirk memory (gotchas, preferences, decisions,
+ * environment constraints) via hybrid vector-keyword search filtered to
+ * `kind === "quirk"`. Results are re-weighted by confidence.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export declare function createRecallQuirksTool(options: RecallQuirksToolOptions): ToolDefinition;
+/** Options for creating the `add_quirk` tool. */
+export interface AddQuirkToolOptions {
+    store: VectorStore;
+    embedder: EmbeddingProvider;
+    cfg: RagConfig;
+    keywordIndex: KeywordIndex;
+    storePath: string;
+}
+/**
+ * Create the `add_quirk` tool.
+ *
+ * Stores a new quirk into experiential memory. The quirk is embedded as a
+ * synthetic chunk (kind="quirk") in the vector store and indexed in the
+ * keyword index. An audit trail is written to quirks.jsonl.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export declare function createAddQuirkTool(options: AddQuirkToolOptions): ToolDefinition;

package/dist/opencode/tools.js

@@ -20,6 +20,7 @@ import { Parser } from "web-tree-sitter";
 import { initParser, loadLanguage, walkTree } from "../chunker/grammar.js";
 import { readFileSync } from "node:fs";
 import { resolveWorkspacePath } from "./tool-args.js";
+import { addQuirk, recallQuirks } from "../quirks/quirk-store.js";
 const SKELETON_CONFIGS = {
     ".ts": { grammarName: "typescript", nodeTypes: ["function_declaration", "method_definition", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration"] },
     ".tsx": { grammarName: "typescript", nodeTypes: ["function_declaration", "method_definition", "class_declaration", "interface_declaration", "type_alias_declaration", "enum_declaration", "arrow_function"] },
@@ -493,4 +494,130 @@ export function createFindUsagesTool(options) {
         },
     });
 }
+/**
+ * Create the `recall_quirks` tool.
+ *
+ * Queries experiential quirk memory (gotchas, preferences, decisions,
+ * environment constraints) via hybrid vector-keyword search filtered to
+ * `kind === "quirk"`. Results are re-weighted by confidence.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export function createRecallQuirksTool(options) {
+    const { store, embedder, cfg, keywordIndex, storePath } = options;
+    return tool({
+        description: "Query experiential quirk memory — gotchas, preferences, decisions, and " +
+            "environment constraints discovered during previous sessions. " +
+            "Leverage when you encounter an error, need to recall how something works, " +
+            "or want to avoid known pitfalls. Results are filtered by confidence and " +
+            "relevance.",
+        args: {
+            query: tool.schema.string().min(1, "A search query is required."),
+            topK: tool.schema.number().int().min(1).max(25).optional(),
+            quirkType: tool.schema.string().optional(),
+            tags: tool.schema.array(tool.schema.string().min(1)).max(10).optional(),
+        },
+        async execute(args) {
+            try {
+                const deps = { embedder, store, keywordIndex, cfg, storePath };
+                const results = await recallQuirks(deps, args.query, {
+                    topK: args.topK ?? 10,
+                    quirkType: args.quirkType,
+                    tags: args.tags,
+                });
+                if (results.length === 0) {
+                    return {
+                        title: "Quirk memory recall",
+                        output: "No quirks matched your query.",
+                        metadata: { tool: "recall_quirks", query: args.query, matches: 0 },
+                    };
+                }
+                const lines = [];
+                lines.push(`**${results.length} quirk(s) found:**\n`);
+                for (const r of results) {
+                    const m = r.chunk.metadata;
+                    const badge = m.quirkType ? `[\`${m.quirkType}\`] ` : "";
+                    const tags = m.tags && m.tags.length > 0 ? ` _(${m.tags.join(", ")})_` : "";
+                    const confidence = m.confidence != null
+                        ? ` confidence=${(m.confidence * 100).toFixed(0)}%`
+                        : "";
+                    const score = r.score.toFixed(3);
+                    lines.push(`- ${badge}${r.chunk.content}${tags}`, `  _score=${score}${confidence}_`);
+                }
+                return {
+                    title: `Quirk memory recall (${results.length})`,
+                    output: lines.join("\n"),
+                    metadata: {
+                        tool: "recall_quirks",
+                        query: args.query,
+                        matches: results.length,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    title: "Quirk memory recall",
+                    output: `Recall failed: ${err instanceof Error ? err.message : String(err)}`,
+                    metadata: { tool: "recall_quirks", error: String(err) },
+                };
+            }
+        },
+    });
+}
+/**
+ * Create the `add_quirk` tool.
+ *
+ * Stores a new quirk into experiential memory. The quirk is embedded as a
+ * synthetic chunk (kind="quirk") in the vector store and indexed in the
+ * keyword index. An audit trail is written to quirks.jsonl.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export function createAddQuirkTool(options) {
+    const { store, embedder, cfg, keywordIndex, storePath } = options;
+    return tool({
+        description: "Store a new experiential memory (quirk) — a gotcha, preference, decision, or " +
+            "environment constraint you discovered. The quirk is embedded and indexed so " +
+            "future sessions can recall it via `recall_quirks`. Use when you hit a " +
+            "non-obvious behavior, workaround, or coding convention.",
+        args: {
+            content: tool.schema.string().min(1, "Quirk content is required."),
+            quirkType: tool.schema
+                .string()
+                .optional(),
+            tags: tool.schema.array(tool.schema.string().min(1)).max(10).optional(),
+            sourceRef: tool.schema.string().optional(),
+        },
+        async execute(args) {
+            try {
+                const deps = { embedder, store, keywordIndex, cfg, storePath };
+                const quirk = await addQuirk(deps, {
+                    content: args.content,
+                    quirkType: args.quirkType,
+                    tags: args.tags,
+                    sourceRef: args.sourceRef,
+                });
+                return {
+                    title: "Quirk added",
+                    output: `**Quirk recorded** (id: \`${quirk.id}\`)\n\`${args.quirkType ?? "general"}\` | confidence=${(quirk.confidence * 100).toFixed(0)}% | tags=${(quirk.tags ?? []).join(", ") || "none"}`,
+                    metadata: {
+                        tool: "add_quirk",
+                        quirkId: quirk.id,
+                        quirkType: quirk.quirkType,
+                        confidence: quirk.confidence,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    title: "Quirk add",
+                    output: `Failed to add quirk: ${err instanceof Error ? err.message : String(err)}`,
+                    metadata: { tool: "add_quirk", error: String(err) },
+                };
+            }
+        },
+    });
+}
 //# sourceMappingURL=tools.js.map