opencode-rag-plugin 1.17.3 → 1.18.0

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/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. */
@@ -270,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

@@ -253,6 +253,16 @@ export const DEFAULT_CONFIG = {
         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,
         openBrowser: true,
@@ -279,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) {
@@ -330,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");
     }
@@ -477,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