opencode-rag-plugin 1.17.3 → 1.18.1

package/ReadMe.md

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

package/dist/cli/commands/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.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.
@@ -165,6 +166,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 +177,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",
         "",
@@ -248,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`.
  *
@@ -272,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/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/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/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,34 @@ 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;
+    /** 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. */
+        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 +298,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

@@ -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" +
@@ -253,6 +253,21 @@ export const DEFAULT_CONFIG = {
         cooldownMs: 3_600_000,
         maxConsecutiveFailures: 3,
     },
+    memory: {
+        enabled: true,
+        autoInject: false,
+        minConfidence: 0.5,
+        recallMinScore: 0.72,
+        passiveCapture: false,
+        promptEnforcement: true,
+        sessionEndExtraction: true,
+        autoCaptureMaxPerTurn: 2,
+        autoCaptureDedupThreshold: 0.85,
+        decay: {
+            enabled: false,
+            halfLifeDays: 30,
+        },
+    },
     ui: {
         port: 3210,
         openBrowser: true,
@@ -279,7 +294,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 +345,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 +497,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. */
@@ -42,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 {
@@ -130,6 +147,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 {
@@ -163,13 +183,17 @@ 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 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/core/runtime-overrides.d.ts

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