opencode-rag-plugin 1.17.2 → 1.18.0

package/ReadMe.md

@@ -125,14 +125,16 @@ 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.
 
-## MCP Server
+## 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, OpenCode, Cursor, etc.).
+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.).
 
 ```bash
 opencode-rag mcp
 ```
 
+> **Note:** The MCP server is **optional**. When running as an OpenCode plugin, the four tools are registered **in-process** and work without the MCP server. The `chat.message` hook for hotkey injection also runs in-process. The MCP server is only needed when an **external** MCP client connects to OpenCodeRAG. The plugin auto-starts the server only if `mcp.enabled` is `true` in your config (default: `false`).
+
 ### MCP Tools
 
 | Tool | Description |

package/dist/cli/commands/index.d.ts

@@ -15,3 +15,4 @@ export { registerSetupCommand } from "./setup.js";
 export { registerUpdateCommand } from "./update.js";
 export { registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand } from "./eval.js";
 export { registerDescribeImageCommand } from "./describe-image.js";
+export { registerQuirkCommand } from "./quirk.js";

package/dist/cli/commands/index.js

@@ -15,4 +15,5 @@ export { registerSetupCommand } from "./setup.js";
 export { registerUpdateCommand } from "./update.js";
 export { registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand } from "./eval.js";
 export { registerDescribeImageCommand } from "./describe-image.js";
+export { registerQuirkCommand } from "./quirk.js";
 //# sourceMappingURL=index.js.map

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

@@ -165,6 +165,8 @@ export function generateSkillFile() {
         "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 a known pitfall → `recall_quirks(query)`",
+        "7. You discover a non-obvious fact or workaround → `add_quirk(content)` to persist it",
         "",
         "### When to use each tool",
         "",
@@ -174,6 +176,8 @@ export function generateSkillFile() {
         "| `get_file_skeleton` | You have a file path but need to orient before reading | `\"src/plugin.ts\"` |",
         "| `find_usages` | Before editing any function, class, or variable — check all call sites | `\"createRagHooks\"` |",
         "| `describe_image` | When the user refers to an image or asks \"what's in this screenshot/diagram?\" | `\"assets/login-screen.png\"` |",
+        "| `recall_quirks` | You hit an error or need to remember a gotcha, preference, or decision from past sessions | `\"lancedb type casting\"` |",
+        "| `add_quirk` | You just discovered a non-obvious fact, workaround, or convention worth remembering | `'\"npm needs --legacy-peer-deps\" --type gotcha --tag installation'` |",
         "",
         "### Workflow",
         "",

package/dist/cli/commands/quirk.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Quirk command — manage experiential agent memory (add, list, rm, lint).
+ */
+import type { Command } from "commander";
+/**
+ * Register the `quirk` command on the given Commander program.
+ *
+ * @param program - The Commander `Command` instance to register on.
+ */
+export declare function registerQuirkCommand(program: Command): void;

package/dist/cli/commands/quirk.js

@@ -0,0 +1,141 @@
+import { resolveCliContext, cleanupContext, logCliInfo, logCliError, c } from "../format.js";
+import { addQuirk, listQuirks, lintQuirks, recallQuirks, removeQuirk } from "../../quirks/quirk-store.js";
+/**
+ * Register the `quirk` command on the given Commander program.
+ *
+ * @param program - The Commander `Command` instance to register on.
+ */
+export function registerQuirkCommand(program) {
+    const quirkCmd = program
+        .command("quirk")
+        .description("Manage experiential quirk memory (gotchas, preferences, decisions, constraints)");
+    quirkCmd
+        .command("add")
+        .description("Add a new quirk")
+        .argument("<content>", "quirk text")
+        .option("-t, --type <type>", "quirk type: gotcha, preference, decision, environment-constraint")
+        .option("--tag <tags...>", "tags for filtering")
+        .option("--source-ref <path>", "source file path reference")
+        .action(async (content, options) => {
+        try {
+            const ctx = await resolveCliContext(options, resolveLogPath());
+            const { config, embedder, store, keywordIndex } = ctx;
+            const quirk = await addQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, {
+                content,
+                quirkType: options.type,
+                tags: options.tag ? (Array.isArray(options.tag) ? options.tag : [options.tag]) : undefined,
+                sourceRef: options.sourceRef,
+            });
+            logCliInfo(ctx.logFilePath, "quirk add", `\n${c.success("Quirk added:")}`);
+            logCliInfo(ctx.logFilePath, "quirk add", `  ${c.label("ID:")} ${quirk.id}`);
+            logCliInfo(ctx.logFilePath, "quirk add", `  ${c.label("Type:")} ${quirk.quirkType ?? "general"}`);
+            logCliInfo(ctx.logFilePath, "quirk add", `  ${c.label("Confidence:")} ${(quirk.confidence * 100).toFixed(0)}%`);
+            await cleanupContext(ctx);
+        }
+        catch (err) {
+            logCliError(resolveLogPath(), "quirk add", `Failed to add quirk: ${err.message}`, err);
+            process.exit(1);
+        }
+    });
+    quirkCmd
+        .command("list")
+        .description("List all quirks")
+        .option("-c, --config <path>", "path to config file")
+        .action(async (options) => {
+        try {
+            const ctx = await resolveCliContext(options, resolveLogPath());
+            const { config, embedder, store, keywordIndex } = ctx;
+            const quirks = await listQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath });
+            logCliInfo(ctx.logFilePath, "quirk list", `\n${c.num(quirks.length)} quirk(s):\n`);
+            for (const q of quirks) {
+                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)}`);
+            }
+            await cleanupContext(ctx);
+        }
+        catch (err) {
+            logCliError(resolveLogPath(), "quirk list", `Failed to list quirks: ${err.message}`, err);
+            process.exit(1);
+        }
+    });
+    quirkCmd
+        .command("rm")
+        .description("Remove a quirk by ID")
+        .argument("<id>", "quirk ID")
+        .option("-c, --config <path>", "path to config file")
+        .action(async (id, options) => {
+        try {
+            const ctx = await resolveCliContext(options, resolveLogPath());
+            const { config, embedder, store, keywordIndex } = ctx;
+            await removeQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, id);
+            logCliInfo(ctx.logFilePath, "quirk rm", `\n${c.success("Quirk removed:")} ${id}`);
+            await cleanupContext(ctx);
+        }
+        catch (err) {
+            logCliError(resolveLogPath(), "quirk rm", `Failed to remove quirk: ${err.message}`, err);
+            process.exit(1);
+        }
+    });
+    quirkCmd
+        .command("lint")
+        .description("Health-check quirks (low confidence, stale, duplicates)")
+        .option("-c, --config <path>", "path to config file")
+        .action(async (options) => {
+        try {
+            const ctx = await resolveCliContext(options, resolveLogPath());
+            const { config, embedder, store, keywordIndex } = ctx;
+            const issues = await lintQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath });
+            if (issues.length === 0) {
+                logCliInfo(ctx.logFilePath, "quirk lint", c.success("\nNo issues found. All quirks look healthy."));
+            }
+            else {
+                logCliInfo(ctx.logFilePath, "quirk lint", `\n${c.warn(`${issues.length} issue(s) found:`)}\n`);
+                for (const issue of issues) {
+                    logCliInfo(ctx.logFilePath, "quirk lint", `  • ${issue}`);
+                }
+            }
+            await cleanupContext(ctx);
+        }
+        catch (err) {
+            logCliError(resolveLogPath(), "quirk lint", `Failed to lint quirks: ${err.message}`, err);
+            process.exit(1);
+        }
+    });
+    quirkCmd
+        .command("test")
+        .description("Test whether a quirk with similar content already exists")
+        .argument("<content>", "quirk text to test")
+        .option("-c, --config <path>", "path to config file")
+        .action(async (content, options) => {
+        try {
+            const ctx = await resolveCliContext(options, resolveLogPath());
+            const { config, embedder, store, keywordIndex } = ctx;
+            const results = await recallQuirks({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, content, { topK: 5 });
+            if (results.length > 0) {
+                logCliInfo(ctx.logFilePath, "quirk test", c.success("\n✓ Quirk has been appended:\n"));
+                for (const r of results) {
+                    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.dim(confidence)}`);
+                    logCliInfo(ctx.logFilePath, "quirk test", "");
+                }
+            }
+            else {
+                logCliInfo(ctx.logFilePath, "quirk test", c.warn("\n✗ No matching quirk found — quirk has not been appended\n"));
+            }
+            await cleanupContext(ctx);
+        }
+        catch (err) {
+            logCliError(resolveLogPath(), "quirk test", `Failed to test quirk: ${err.message}`, err);
+            process.exit(1);
+        }
+    });
+}
+function resolveLogPath() {
+    return "./.opencode/opencode-rag.log";
+}
+//# sourceMappingURL=quirk.js.map

package/dist/cli/index.js

@@ -14,7 +14,7 @@ import { realpathSync } from "node:fs";
 import { basename, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getPackageMetadata } from "./helpers.js";
-import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerDescribeImageCommand, } from "./commands/index.js";
+import { registerIndexCommand, registerQueryCommand, registerClearCommand, registerStatusCommand, registerListCommand, registerShowCommand, registerDumpCommand, registerInitCommand, registerUiCommand, registerMcpCommand, registerSetupCommand, registerUpdateCommand, registerEvalSessionsCommand, registerEvalAnalyzeCommand, registerEvalCompareCommand, registerDescribeImageCommand, registerQuirkCommand, } from "./commands/index.js";
 /**
  * The top-level Commander program instance that defines the `opencode-rag` CLI.
  *
@@ -44,6 +44,7 @@ registerEvalSessionsCommand(program);
 registerEvalAnalyzeCommand(program);
 registerEvalCompareCommand(program);
 registerInitCommand(program);
+registerQuirkCommand(program);
 // ── Auto-run detection ──────────────────────────────────────────
 /**
  * Determine whether the CLI should auto-run for the current module.

package/dist/core/auto-update-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Persisted state for the background auto-update mechanism.
+ * Tracks when an install was last attempted, for which version,
+ * and consecutive failure counts to implement cooldown and backoff.
+ */
+/** Persisted state of a background auto-update attempt. */
+export interface AutoUpdateState {
+    /** Epoch ms of the most recent attempt. */
+    lastAttemptAt: number;
+    /** The latestVersion we tried to install (or checked). */
+    lastAttemptedVersion: string;
+    /** Outcome of the last attempt. */
+    lastResult: "success" | "failure";
+    /** Consecutive failures so far (reset on success). */
+    consecutiveFailures: number;
+}
+/** Full path to the state file for a given store path. */
+export declare function statePath(storePath: string): string;
+/** Load persisted auto-update state, or return null if missing / corrupt. */
+export declare function loadAutoUpdateState(storePath: string): AutoUpdateState | null;
+/** Persist auto-update state to disk (best-effort, never throws). */
+export declare function saveAutoUpdateState(storePath: string, state: AutoUpdateState): void;
+/**
+ * Determine whether an auto-install attempt should proceed, based on
+ * the persisted state, the version we just discovered, and configured
+ * limits.
+ *
+ * @returns An object with `attempt: boolean` and `reason: string`.
+ */
+export declare function shouldAttemptInstall(state: AutoUpdateState | null, latestVersion: string, cooldownMs: number, maxConsecutiveFailures: number): {
+    attempt: boolean;
+    reason: string;
+};

package/dist/core/auto-update-state.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Persisted state for the background auto-update mechanism.
+ * Tracks when an install was last attempted, for which version,
+ * and consecutive failure counts to implement cooldown and backoff.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+/** Name of the state file written to the store path. */
+const STATE_FILE_NAME = ".auto-update-state.json";
+/** Full path to the state file for a given store path. */
+export function statePath(storePath) {
+    return path.join(storePath, STATE_FILE_NAME);
+}
+/** Load persisted auto-update state, or return null if missing / corrupt. */
+export function loadAutoUpdateState(storePath) {
+    try {
+        const p = statePath(storePath);
+        if (!existsSync(p))
+            return null;
+        const raw = readFileSync(p, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.lastAttemptAt !== "number" ||
+            typeof parsed.lastAttemptedVersion !== "string" ||
+            (parsed.lastResult !== "success" && parsed.lastResult !== "failure") ||
+            typeof parsed.consecutiveFailures !== "number") {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist auto-update state to disk (best-effort, never throws). */
+export function saveAutoUpdateState(storePath, state) {
+    try {
+        writeFileSync(statePath(storePath), JSON.stringify(state, null, 2), "utf-8");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/**
+ * Determine whether an auto-install attempt should proceed, based on
+ * the persisted state, the version we just discovered, and configured
+ * limits.
+ *
+ * @returns An object with `attempt: boolean` and `reason: string`.
+ */
+export function shouldAttemptInstall(state, latestVersion, cooldownMs, maxConsecutiveFailures) {
+    if (!state) {
+        return { attempt: true, reason: "first run" };
+    }
+    const elapsed = Date.now() - state.lastAttemptAt;
+    if (state.lastAttemptedVersion === latestVersion && elapsed < cooldownMs) {
+        return {
+            attempt: false,
+            reason: `version ${latestVersion} already attempted ${Math.round(elapsed / 1000)}s ago (cooldown ${Math.round(cooldownMs / 1000)}s)`,
+        };
+    }
+    if (state.lastResult === "failure" && state.consecutiveFailures >= maxConsecutiveFailures && elapsed < cooldownMs) {
+        return {
+            attempt: false,
+            reason: `${state.consecutiveFailures} consecutive failures within cooldown window`,
+        };
+    }
+    return { attempt: true, reason: "proceeding" };
+}
+//# sourceMappingURL=auto-update-state.js.map

package/dist/core/config.d.ts

@@ -121,6 +121,24 @@ export interface WikiModeConfig {
     /** System prompt for the wiki maintainer agent. */
     systemPrompt: string;
 }
+/** Configuration for the quirk/experiential memory system. */
+export interface MemoryConfig {
+    /** Whether quirk memory is enabled. */
+    enabled: boolean;
+    /** Whether relevant quirks should be auto-injected into the prompt during retrieval. */
+    autoInject: boolean;
+    /** Minimum confidence (0-1) for a quirk to be returned. */
+    minConfidence: number;
+    /** Minimum query-relevance score (0-1) for a quirk to be recalled. */
+    recallMinScore: number;
+    /** Decay settings for aging quirks. */
+    decay: {
+        /** Whether confidence decays over time. */
+        enabled: boolean;
+        /** Number of days after which confidence halves. */
+        halfLifeDays: number;
+    };
+}
 /** Configuration for the terminal UI (TUI) keybindings. */
 export interface TuiConfig {
     /** Keybinding to toggle the file list panel. */
@@ -128,15 +146,21 @@ export interface TuiConfig {
     /** Keybinding to toggle the chunk viewer panel. */
     chunksKeybinding: string;
 }
-/** Configuration for MCP (Model Context Protocol) server integration. */
+/** Configuration for the standalone MCP (Model Context Protocol) server. */
 export interface McpConfig {
-    /** Whether the MCP server is enabled. */
+    /** Whether to auto-start the MCP server on plugin load. Default false — agent tools run in-process regardless. Set true only when an external MCP client needs to connect via `opencode-rag mcp`. */
     enabled: boolean;
 }
 /** Configuration for automatic self-updates. */
 export interface AutoUpdateConfig {
     /** Whether update checking is enabled (defaults to true). */
     enabled: boolean;
+    /** When true, automatically install a newer release on startup (default false). */
+    autoInstall?: boolean;
+    /** Cooldown window (ms) before re-attempting the same version (default 3 600 000 = 1h). */
+    cooldownMs?: number;
+    /** Back off after this many consecutive failures (default 3). */
+    maxConsecutiveFailures?: number;
 }
 /** Configuration for post-retrieval context window optimization (adjacent merge, similarity dedup, file diversity cap). */
 export interface ContextOptimizationConfig {
@@ -264,6 +288,8 @@ export interface RagConfig {
     mcp?: McpConfig;
     /** Auto-update checking config. */
     autoUpdate?: AutoUpdateConfig;
+    /** Quirk memory config for experiential agent memory. */
+    memory?: MemoryConfig;
     /** Web dashboard UI config. */
     ui?: UiConfig;
     /** Terminal UI keybinding config. */

package/dist/core/config.js

@@ -245,10 +245,23 @@ export const DEFAULT_CONFIG = {
             "- The wiki is git-trackable in `.opencode/` — every edit is a diff",
     },
     mcp: {
-        enabled: true,
+        enabled: false,
     },
     autoUpdate: {
         enabled: true,
+        autoInstall: false,
+        cooldownMs: 3_600_000,
+        maxConsecutiveFailures: 3,
+    },
+    memory: {
+        enabled: true,
+        autoInject: false,
+        minConfidence: 0.5,
+        recallMinScore: 0.72,
+        decay: {
+            enabled: false,
+            halfLifeDays: 30,
+        },
     },
     ui: {
         port: 3210,
@@ -276,7 +289,7 @@ export function validateConfig(config) {
     const KNOWN_TOP_KEYS = new Set([
         "embedding", "indexing", "vectorStore", "retrieval",
         "openCode", "chunkers", "chunking", "description",
-        "imageDescription", "documentationMode", "wikiMode", "mcp", "autoUpdate", "ui", "tui", "logging",
+        "imageDescription", "documentationMode", "wikiMode", "mcp", "autoUpdate", "memory", "ui", "tui", "logging",
     ]);
     const topKeys = new Set(Object.keys(config));
     for (const key of topKeys) {
@@ -327,6 +340,11 @@ export function validateConfig(config) {
             warnings.push("retrieval.hybridSearch.keywordWeight must be between 0 and 1");
         }
     }
+    if (config.memory?.recallMinScore != null) {
+        const r = config.memory.recallMinScore;
+        if (r < 0 || r > 1)
+            warnings.push("memory.recallMinScore must be between 0 and 1");
+    }
     if (config.openCode.maxContextChunks <= 0) {
         warnings.push("openCode.maxContextChunks must be > 0");
     }
@@ -474,6 +492,10 @@ export function loadConfig(filePath, validate = true) {
             ...DEFAULT_CONFIG.autoUpdate,
             ...(safeObj(parsed.autoUpdate) ?? {}),
         },
+        memory: {
+            ...DEFAULT_CONFIG.memory,
+            ...(safeObj(parsed.memory) ?? {}),
+        },
         ui: {
             ...DEFAULT_CONFIG.ui,
             ...(safeObj(parsed.ui) ?? {}),

package/dist/core/interfaces.d.ts

@@ -14,6 +14,16 @@ export interface Chunk {
         endLine: number;
         language: string;
         contentType?: string;
+        /** Synthetic chunk kind — e.g. "quirk" for experiential memory entries. */
+        kind?: string;
+        /** Quirk sub-type when kind === "quirk": gotcha, preference, decision, environment-constraint. */
+        quirkType?: string;
+        /** Arbitrary tags for filtering/queries. */
+        tags?: string[];
+        /** Confidence score 0-1 (quirk memory). */
+        confidence?: number;
+        /** ISO timestamp of last confirmation (quirk memory). */
+        lastObserved?: string;
     };
 }
 /** Logger interface for description generation progress messages. */
@@ -130,6 +140,9 @@ export interface ChunkSummary {
     endLine: number;
     content: string;
     description: string;
+    kind: string;
+    quirkType: string;
+    tags: string;
 }
 /** A file summary for list operations. */
 export interface FileSummary {
@@ -164,12 +177,14 @@ export interface VectorStore {
     /** Re-open the store, optionally pointing at a new database path. */
     reopen?(newPath?: string): Promise<void>;
 }
-/** Filter criteria for narrowing search results by file path patterns or language. */
+/** Filter criteria for narrowing search results by file path, language, or kind. */
 export interface MetadataFilter {
     /** Glob-style path patterns (e.g. "src/**", "lib/auth/*"). */
     pathPatterns?: string[];
     /** Language identifiers (e.g. ["typescript", "tsx"]). */
     languages?: string[];
+    /** Synthetic kind filters (e.g. ["quirk"]). */
+    kinds?: string[];
 }
 /** Callback interface for reporting indexing progress to the UI or CLI. */
 export interface IndexProgress {

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