opencode-rag-plugin 1.19.2 → 1.19.4

package/ReadMe.md

@@ -153,12 +153,16 @@ OpenCodeRAG gives your agent **persistent, cross-session memory** of non-obvious
 |------|----------|
 | `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 |
+| `update_quirk(id, { content, type, tags })` | A recalled quirk is outdated or wrong — fix it instead of adding a duplicate |
+| `delete_quirk(id)` | A quirk is fixed, obsolete, or no longer applies — remove it |
 
 **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 update <id> --content "..." --type decision
+opencode-rag quirk rm <id>
 opencode-rag quirk lint            # flag low-confidence / stale / duplicate quirks
 opencode-rag quirk test "npm needs --legacy-peer-deps"
 # ✓ Quirk has been appended:
@@ -166,7 +170,7 @@ opencode-rag quirk test "npm needs --legacy-peer-deps"
 #   99% confidence
 ```
 
-When `memory.autoInject` is `true`, the plugin checks for relevant quirks on every user message using the combined agent-response + user-query as the search query. Quirks are only injected when their relevance score exceeds the threshold — `recallMinScore` (default 0.72) for the user message, `autoInjectMinScore` (default 0.45) for the system prompt. A latency budget (`autoInjectLatencyBudgetMs`, default 2000ms) prevents slow embedders from blocking message processing. To avoid polluting the context window, each quirk is injected **at most once per session** — once recalled, it is filtered out from all subsequent auto-injections. Every `add_quirk` is vetted by an immutable trust monitor that rejects destructive patterns (e.g. `rm -rf`, `force push`, `bypass security`). See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI Reference: `quirk`](doc/cli.md#quirk).
+When `memory.autoInject` is `true`, the plugin checks for relevant quirks on every user message using the combined agent-response + user-query as the search query. Quirks are only injected when their relevance score exceeds the threshold — `recallMinScore` (default 0.72) for the user message, `autoInjectMinScore` (default 0.45) for the system prompt. A latency budget (`autoInjectLatencyBudgetMs`, default 2000ms) prevents slow embedders from blocking message processing. To avoid polluting the context window, each quirk is injected **at most once per session** — once recalled, it is filtered out from all subsequent auto-injections. Every `add_quirk` and every content-changing `update_quirk` is vetted by an immutable trust monitor that rejects destructive patterns (e.g. `rm -rf`, `force push`, `bypass security`). Outdated or fixed quirks should be corrected with `update_quirk` / `delete_quirk` rather than left to contradict newer memory. See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI Reference: `quirk`](doc/cli.md#quirk).
 
 ## MCP Server (Optional)
 

package/dist/api.d.ts

@@ -4,7 +4,7 @@
  */
 import { type IndexRunStats } from "./indexer.js";
 import { type WorkspaceFile } from "./content/reader.js";
-import type { SearchResult } from "./core/interfaces.js";
+import { type SearchResult } from "./core/interfaces.js";
 /** Options controlling a semantic search query. */
 export interface SearchOptions {
     /** Working directory to resolve relative paths against. */

package/dist/api.js

@@ -7,6 +7,7 @@ import { retrieve } from "./retriever/retriever.js";
 import { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "./retriever/context-optimizer.js";
 import { runIndexPass } from "./indexer.js";
 import { scanWorkspaceFiles } from "./content/reader.js";
+import { CODE_SEARCH_FILTER } from "./core/interfaces.js";
 import { destroyAllPooledConnections } from "./embedder/http.js";
 /**
  * Format a list of search results into a human-readable markdown block.
@@ -55,6 +56,7 @@ export async function search(query, options = {}) {
             filter: {
                 pathPatterns: options.pathHints,
                 languages: options.languageHints,
+                kinds: CODE_SEARCH_FILTER.kinds,
             },
         });
         const optCfg = ctx.config.retrieval.contextOptimization ?? DEFAULT_CONTEXT_OPTIMIZATION;

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

@@ -168,6 +168,7 @@ export function generateSkillFile() {
         "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",
+        "8. A recalled quirk is outdated or wrong → `update_quirk(id, ...)` to fix it, or `delete_quirk(id)` if it no longer applies",
         "",
         "### When to use each tool",
         "",
@@ -179,6 +180,8 @@ export function generateSkillFile() {
         "| `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'` |",
+        "| `update_quirk` | A recalled quirk is outdated or wrong — fix its content, type, or tags | `id` from `recall_quirks` output + `content: \"...\"` |",
+        "| `delete_quirk` | A quirk is fixed, obsolete, or no longer applies | `id` from `recall_quirks` output |",
         "",
         "### Workflow",
         "",
@@ -203,6 +206,10 @@ export function generateSkillFile() {
         "- `get_file_skeleton`: `filePath` (req)",
         "- `find_usages`: `symbolName` (req), `pathHint?`, `topK?`",
         "- `describe_image`: `filePath` (req)",
+        "- `recall_quirks`: `query` (req), `topK?`, `quirkType?`, `tags?`",
+        "- `add_quirk`: `content` (req), `quirkType?`, `tags?`, `sourceRef?`",
+        "- `update_quirk`: `id` (req) + at least one of `content?`, `quirkType?`, `tags?`, `confidence?`, `sourceRef?`",
+        "- `delete_quirk`: `id` (req)",
         "",
         "### Tips",
         "",

package/dist/cli/commands/query.js

@@ -6,6 +6,7 @@
  */
 import path from "node:path";
 import pc from "picocolors";
+import { CODE_SEARCH_FILTER } from "../../core/interfaces.js";
 import { retrieve } from "../../retriever/retriever.js";
 import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, formatDuration } from "../format.js";
 import { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "../../retriever/context-optimizer.js";
@@ -54,6 +55,7 @@ export function registerQueryCommand(program) {
                 hybridEnabled: hybridCfg?.enabled,
                 queryPrefix: config.embedding.queryPrefix,
                 explain: options.explain ?? false,
+                filter: CODE_SEARCH_FILTER,
             });
             const optCfg = config.retrieval.contextOptimization ?? DEFAULT_CONTEXT_OPTIMIZATION;
             const results = optimizeContext(rawResults, { topK, config: optCfg });

package/dist/cli/commands/quirk.js

@@ -1,5 +1,5 @@
 import { resolveCliContext, cleanupContext, logCliInfo, logCliError, c } from "../format.js";
-import { addQuirk, listQuirks, lintQuirks, recallQuirks, removeQuirk } from "../../quirks/quirk-store.js";
+import { addQuirk, listQuirks, lintQuirks, recallQuirks, removeQuirk, updateQuirk } from "../../quirks/quirk-store.js";
 /**
  * Register the `quirk` command on the given Commander program.
  *
@@ -37,6 +37,40 @@ export function registerQuirkCommand(program) {
             process.exit(1);
         }
     });
+    quirkCmd
+        .command("update")
+        .description("Update a quirk by ID (content, type, tags, confidence, source ref)")
+        .argument("<id>", "quirk ID")
+        .option("--content <text>", "replacement quirk text")
+        .option("-t, --type <type>", "quirk type: gotcha, preference, decision, environment-constraint")
+        .option("--tag <tags...>", "replacement tags for filtering")
+        .option("--confidence <0-1>", "replacement confidence", parseFloat)
+        .option("--source-ref <path>", "source file path reference")
+        .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;
+            const tags = options.tag;
+            const quirk = await updateQuirk({ embedder, store, keywordIndex: keywordIndex, cfg: config, storePath: ctx.storePath }, id, {
+                content: options.content,
+                quirkType: options.type,
+                tags: tags ? (Array.isArray(tags) ? tags : [tags]) : undefined,
+                confidence: options.confidence,
+                sourceRef: options.sourceRef,
+            });
+            logCliInfo(ctx.logFilePath, "quirk update", `\n${c.success("Quirk updated:")}`);
+            logCliInfo(ctx.logFilePath, "quirk update", `  ${c.label("ID:")} ${quirk.id}`);
+            logCliInfo(ctx.logFilePath, "quirk update", `  ${c.label("Type:")} ${quirk.quirkType ?? "general"}`);
+            logCliInfo(ctx.logFilePath, "quirk update", `  ${c.label("Confidence:")} ${(quirk.confidence * 100).toFixed(0)}%`);
+            logCliInfo(ctx.logFilePath, "quirk update", `  ${c.label("Content:")} ${quirk.content}`);
+            await cleanupContext(ctx);
+        }
+        catch (err) {
+            logCliError(resolveLogPath(), "quirk update", `Failed to update quirk: ${err.message}`, err);
+            process.exit(1);
+        }
+    });
     quirkCmd
         .command("list")
         .description("List all quirks")

package/dist/content/reader.js

@@ -56,17 +56,17 @@ export async function walkFiles(dir, extensions, excludeDirs, excludeFiles, root
     return results;
 }
 async function dispatchExtraction(filePath, buffer, imageVisionProvider, imagePrompt, resizeMaxDimension) {
-    const lower = filePath.toLowerCase();
-    if (pdfExtractor.PDF_EXTENSIONS.has(lower)) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (pdfExtractor.PDF_EXTENSIONS.has(ext)) {
         return pdfExtractor.extract(filePath, buffer);
     }
-    if (docxExtractor.DOCX_EXTENSIONS.has(lower)) {
+    if (docxExtractor.DOCX_EXTENSIONS.has(ext)) {
         return docxExtractor.extract(filePath, buffer);
     }
-    if (docExtractor.DOC_EXTENSIONS.has(lower)) {
+    if (docExtractor.DOC_EXTENSIONS.has(ext)) {
         return docExtractor.extract(filePath, buffer);
     }
-    if (excelExtractor.EXCEL_EXTENSIONS.has(lower)) {
+    if (excelExtractor.EXCEL_EXTENSIONS.has(ext)) {
         return excelExtractor.extract(filePath, buffer);
     }
     if (imageVisionProvider && imageExtractor.isImageFile(filePath)) {
@@ -164,10 +164,11 @@ export async function scanWorkspaceFiles(cwd, config, logger, manifest, filterPa
             }
         }
         const isImage = imageVisionProvider !== null && imageExtractor.isImageFile(filePath);
-        const isBinary = pdfExtractor.PDF_EXTENSIONS.has(filePath.toLowerCase()) ||
-            docxExtractor.DOCX_EXTENSIONS.has(filePath.toLowerCase()) ||
-            docExtractor.DOC_EXTENSIONS.has(filePath.toLowerCase()) ||
-            excelExtractor.EXCEL_EXTENSIONS.has(filePath.toLowerCase()) ||
+        const ext = path.extname(filePath).toLowerCase();
+        const isBinary = pdfExtractor.PDF_EXTENSIONS.has(ext) ||
+            docxExtractor.DOCX_EXTENSIONS.has(ext) ||
+            docExtractor.DOC_EXTENSIONS.has(ext) ||
+            excelExtractor.EXCEL_EXTENSIONS.has(ext) ||
             isImage;
         logger?.info(`Reading: ${filePath}`);
         const buffer = isBinary ? await fs.readFile(filePath) : Buffer.alloc(0);

package/dist/core/interfaces.d.ts

@@ -201,6 +201,14 @@ export interface MetadataFilter {
     /** Synthetic kind filters (e.g. ["quirk"]). */
     kinds?: string[];
 }
+/**
+ * Filter for general code/document retrieval that excludes quirk memory
+ * chunks. Regular indexed chunks store `kind: ""`, quirk chunks `kind: "quirk"`.
+ * All code-search paths (search_semantic, hotkey injection, CLI query, web UI,
+ * read-tool context) must pass this so quirks never surface as code results —
+ * quirks are only reachable through recall_quirks / the quirk CLI.
+ */
+export declare const CODE_SEARCH_FILTER: MetadataFilter;
 /** Callback interface for reporting indexing progress to the UI or CLI. */
 export interface IndexProgress {
     /** Set the total number of files to be indexed. */

package/dist/core/interfaces.js

@@ -2,5 +2,12 @@
  * @fileoverview Core type definitions for the OpenCodeRAG pipeline: Chunk, SearchResult,
  * Chunker, EmbeddingProvider, VectorStore, KeywordIndex, and related interfaces.
  */
-export {};
+/**
+ * Filter for general code/document retrieval that excludes quirk memory
+ * chunks. Regular indexed chunks store `kind: ""`, quirk chunks `kind: "quirk"`.
+ * All code-search paths (search_semantic, hotkey injection, CLI query, web UI,
+ * read-tool context) must pass this so quirks never surface as code results —
+ * quirks are only reachable through recall_quirks / the quirk CLI.
+ */
+export const CODE_SEARCH_FILTER = { kinds: [""] };
 //# sourceMappingURL=interfaces.js.map

package/dist/mcp/handlers.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Handler implementations for all MCP tools: semantic search, file skeleton, symbol usage lookup, and image description.
  */
-import type { EmbeddingProvider, VectorStore, KeywordIndex, SearchResult } from "../core/interfaces.js";
+import { type EmbeddingProvider, type VectorStore, type KeywordIndex, type SearchResult } from "../core/interfaces.js";
 import type { RagConfig } from "../core/config.js";
 import { type ImageVisionProvider } from "../chunker/image.js";
 import { retrieve } from "../retriever/retriever.js";

package/dist/mcp/handlers.js

@@ -1,3 +1,7 @@
+/**
+ * @fileoverview Handler implementations for all MCP tools: semantic search, file skeleton, symbol usage lookup, and image description.
+ */
+import { CODE_SEARCH_FILTER } from "../core/interfaces.js";
 import { SUPPORTED_IMAGE_EXTENSIONS } from "../chunker/image.js";
 import { retrieve } from "../retriever/retriever.js";
 import { optimizeContext, DEFAULT_CONTEXT_OPTIMIZATION } from "../retriever/context-optimizer.js";
@@ -178,6 +182,7 @@ export async function handleSearchSemantic(params, embedder, store, cfg, keyword
         keywordWeight: cfg.retrieval.hybridSearch?.keywordWeight,
         hybridEnabled: cfg.retrieval.hybridSearch?.enabled,
         queryPrefix: cfg.embedding.queryPrefix,
+        filter: CODE_SEARCH_FILTER,
     };
     const rawResults = await retrieveFn_(query, embedder, store, retrieveOpts);
     if (rawResults.length === 0) {
@@ -256,7 +261,7 @@ export async function handleFindUsages(params, embedder, store, cfg, keywordInde
     const symbolName = params.symbolName.trim();
     const topK = params.topK ?? 30;
     const kwResults = keywordIndex
-        ? keywordIndex.search(symbolName, topK)
+        ? keywordIndex.search(symbolName, topK, CODE_SEARCH_FILTER)
         : [];
     const count = await store.count();
     const vsResults = count > 0
@@ -265,6 +270,7 @@ export async function handleFindUsages(params, embedder, store, cfg, keywordInde
             minScore: 0,
             keywordIndex: undefined,
             queryPrefix: cfg.embedding.queryPrefix,
+            filter: CODE_SEARCH_FILTER,
         })
         : [];
     const seen = new Set();

package/dist/opencode/create-read-tool.d.ts

@@ -2,7 +2,7 @@
  * @fileoverview Creates the RAG-backed read tool that returns full file contents with supplementary semantic context.
  */
 import { tool } from "@opencode-ai/plugin/tool";
-import type { EmbeddingProvider, KeywordIndex, VectorStore, SearchResult } from "../core/interfaces.js";
+import { type EmbeddingProvider, type KeywordIndex, type VectorStore, type SearchResult } from "../core/interfaces.js";
 import type { RagConfig } from "../core/config.js";
 export interface RagReadToolOptions {
     /** Workspace root directory. */

package/dist/opencode/create-read-tool.js

@@ -3,6 +3,7 @@
  */
 import fs from "node:fs/promises";
 import { tool } from "@opencode-ai/plugin/tool";
+import { CODE_SEARCH_FILTER } from "../core/interfaces.js";
 import { retrieve } from "../retriever/retriever.js";
 import { normalizeReadArgs, resolveWorkspacePath } from "./tool-args.js";
 import { buildReadQuery } from "./read-query.js";
@@ -63,7 +64,7 @@ export function createRagReadTool(options) {
                             }
                             else {
                                 const retrievalQuery = buildSessionQuery(messageText, resolvedPath, normalized);
-                                rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, hybridEnabled: config.retrieval.hybridSearch?.enabled, queryPrefix: config.embedding.queryPrefix });
+                                rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, hybridEnabled: config.retrieval.hybridSearch?.enabled, queryPrefix: config.embedding.queryPrefix, filter: CODE_SEARCH_FILTER });
                                 const maxSize = options.maxSessionCacheSize ?? 50;
                                 if (!sessionRetrievalCache.has(sessionID) && sessionRetrievalCache.size >= maxSize) {
                                     const oldest = sessionRetrievalCache.keys().next().value;
@@ -80,7 +81,7 @@ export function createRagReadTool(options) {
                                 startLine: normalized.startLine,
                                 endLine: normalized.endLine,
                             });
-                            rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, hybridEnabled: config.retrieval.hybridSearch?.enabled, queryPrefix: config.embedding.queryPrefix });
+                            rawResults = await retrieve(retrievalQuery, embedder, store, { topK: retrievalTopK, keywordIndex, hybridEnabled: config.retrieval.hybridSearch?.enabled, queryPrefix: config.embedding.queryPrefix, filter: CODE_SEARCH_FILTER });
                         }
                         // Collect related files from raw results (before filtering)
                         relatedFiles = collectRelatedFiles(rawResults, resolvedPath, readRelatedFilesMax);

package/dist/opencode/system-guidance.js

@@ -20,6 +20,8 @@ export const MANDATORY_GUIDANCE_LINES = [
     "- `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.",
+    "- `update_quirk(id, ...)`: fix an outdated or wrong quirk (content, type, tags, confidence, source ref). The ID is shown in `recall_quirks` output.",
+    "- `delete_quirk(id)`: delete a quirk that is fixed, obsolete, or no longer applies. The ID is shown in `recall_quirks` output.",
     "",
     "Decision tree — ALWAYS follow this order:",
     "1. User mentions code behavior/architecture → `search_semantic(query)`",
@@ -29,6 +31,7 @@ export const MANDATORY_GUIDANCE_LINES = [
     "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",
+    "8. A recalled quirk is outdated or wrong → `update_quirk(id, ...)` to fix it, or `delete_quirk(id)` if it no longer applies",
     "",
     "Proactive triggers — you MUST call these tools when:",
     "- User asks about code behavior, architecture, or implementation details",
@@ -45,7 +48,7 @@ export const MANDATORY_GUIDANCE_LINES = [
     "- 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)",
+    "- Using `npx opencode-rag quirk` shell commands instead of the built-in quirk tools (`add_quirk` / `recall_quirks` / `update_quirk` / `delete_quirk`) (the tools are faster, already loaded in-process, and go through the trust monitor)",
 ];
 /**
  * The conditional quirk-capture enforcement lines. Only included when
@@ -60,6 +63,9 @@ export const QUIRK_ENFORCEMENT_LINES = [
     "- You make a design decision that future sessions should remember",
     "- You resolve a gotcha that cost more than one attempt",
     "",
+    "MANDATORY quirk hygiene — you MUST call `update_quirk` or `delete_quirk` when:",
+    "- A stored quirk is outdated, wrong, or has been fixed — update it or delete it instead of adding a contradicting duplicate",
+    "",
     "Anti-pattern — NEVER finish a coding session without adding quirks for resolved errors.",
 ];
 /**
@@ -89,6 +95,7 @@ export function buildAgentsMdDirective(opts) {
         "- **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",
+        "- **Fix quirks** — `update_quirk(id, ...)` / `delete_quirk(id)` when a stored quirk is outdated or wrong",
         "",
         "If no results, run `opencode-rag index`.",
         "",
@@ -100,6 +107,7 @@ export function buildAgentsMdDirective(opts) {
         "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",
+        "8. A recalled quirk is outdated or wrong → `update_quirk(id, ...)` to fix it, or `delete_quirk(id)` if it no longer applies",
         "",
         "### Proactive triggers — you MUST call these tools when",
         "- User asks about code behavior, architecture, or implementation details",
@@ -116,10 +124,10 @@ export function buildAgentsMdDirective(opts) {
         "- 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)",
+        "- Using `npx opencode-rag quirk` shell commands instead of the built-in quirk tools (`add_quirk` / `recall_quirks` / `update_quirk` / `delete_quirk`) (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("", "### 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", "", "### MANDATORY quirk hygiene — you MUST call `update_quirk` or `delete_quirk` when", "- A stored quirk is outdated, wrong, or has been fixed — update it or delete it instead of adding a contradicting duplicate", "- NEVER finish a coding session without adding quirks for resolved errors.");
     }
     lines.push(END_MARKER);
     return lines.join("\n");

package/dist/opencode/tools.d.ts

@@ -2,7 +2,7 @@
  * @fileoverview Factory functions for OpenCode autonomous-agent tools (file skeleton, find usages, describe image).
  */
 import type { ToolDefinition } from "@opencode-ai/plugin";
-import type { EmbeddingProvider, VectorStore, KeywordIndex } from "../core/interfaces.js";
+import { type EmbeddingProvider, type VectorStore, type KeywordIndex } from "../core/interfaces.js";
 import type { RagConfig } from "../core/config.js";
 import { type ImageVisionProvider } from "../chunker/image.js";
 import { retrieve } from "../retriever/retriever.js";
@@ -105,3 +105,41 @@ export interface AddQuirkToolOptions {
  * @returns A tool definition suitable for OpenCode plugin registration.
  */
 export declare function createAddQuirkTool(options: AddQuirkToolOptions): ToolDefinition;
+/** Options for creating the `update_quirk` tool. */
+export interface UpdateQuirkToolOptions {
+    store: VectorStore;
+    embedder: EmbeddingProvider;
+    cfg: RagConfig;
+    keywordIndex: KeywordIndex;
+    storePath: string;
+}
+/**
+ * Create the `update_quirk` tool.
+ *
+ * Updates an existing quirk by ID — replaces content, type, tags, confidence,
+ * or source ref. When content changes, the quirk is re-embedded so recall
+ * matches the corrected text. The new content passes the trust monitor.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export declare function createUpdateQuirkTool(options: UpdateQuirkToolOptions): ToolDefinition;
+/** Options for creating the `delete_quirk` tool. */
+export interface DeleteQuirkToolOptions {
+    store: VectorStore;
+    embedder: EmbeddingProvider;
+    cfg: RagConfig;
+    keywordIndex: KeywordIndex;
+    storePath: string;
+}
+/**
+ * Create the `delete_quirk` tool.
+ *
+ * Removes a quirk by ID from the vector store, keyword index, and audit log.
+ * Use when a quirk is wrong, no longer applies, or has been superseded by an
+ * updated version.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export declare function createDeleteQuirkTool(options: DeleteQuirkToolOptions): ToolDefinition;

package/dist/opencode/tools.js

@@ -13,6 +13,7 @@
  * These complement the general-purpose search_semantic tool.
  */
 import { tool } from "@opencode-ai/plugin/tool";
+import { CODE_SEARCH_FILTER } from "../core/interfaces.js";
 import { SUPPORTED_IMAGE_EXTENSIONS, createImageVisionProvider, getMimeType } from "../chunker/image.js";
 import { resizeImage } from "../content/image.js";
 import { retrieve } from "../retriever/retriever.js";
@@ -20,7 +21,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";
+import { addQuirk, updateQuirk, removeQuirk, 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"] },
@@ -362,7 +363,7 @@ export function createFindUsagesTool(options) {
     async function searchViaKeywordIndex(symbol, topK) {
         if (!keywordIndex)
             return [];
-        return keywordIndex.search(symbol, topK);
+        return keywordIndex.search(symbol, topK, CODE_SEARCH_FILTER);
     }
     async function searchViaVectorStore(symbol, topK) {
         const count = await store.count();
@@ -373,6 +374,7 @@ export function createFindUsagesTool(options) {
             minScore: 0,
             keywordIndex: undefined,
             queryPrefix: cfg.embedding.queryPrefix,
+            filter: CODE_SEARCH_FILTER,
         });
     }
     function escapeRegex(s) {
@@ -620,4 +622,117 @@ export function createAddQuirkTool(options) {
         },
     });
 }
+/**
+ * Create the `update_quirk` tool.
+ *
+ * Updates an existing quirk by ID — replaces content, type, tags, confidence,
+ * or source ref. When content changes, the quirk is re-embedded so recall
+ * matches the corrected text. The new content passes the trust monitor.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export function createUpdateQuirkTool(options) {
+    const { store, embedder, cfg, keywordIndex, storePath } = options;
+    return tool({
+        description: "Update an existing experiential memory (quirk) by its ID — fix outdated " +
+            "content, change its type, tags, or source ref. Use when a quirk from a " +
+            "past session is outdated, wrong, or superseded. Find the ID via " +
+            "`recall_quirks` (it is listed in the recall output) or `quirk list` " +
+            "in the CLI.",
+        args: {
+            id: tool.schema.string().min(1, "Quirk ID is required."),
+            content: tool.schema.string().optional(),
+            quirkType: tool.schema.string().optional(),
+            tags: tool.schema.array(tool.schema.string().min(1)).max(10).optional(),
+            confidence: tool.schema.number().min(0).max(1).optional(),
+            sourceRef: tool.schema.string().optional(),
+        },
+        async execute(args) {
+            try {
+                const deps = { embedder, store, keywordIndex, cfg, storePath };
+                const fields = [
+                    args.content,
+                    args.quirkType,
+                    args.tags,
+                    args.confidence,
+                    args.sourceRef,
+                ];
+                if (fields.every((f) => f === undefined)) {
+                    return {
+                        title: "Quirk update",
+                        output: "Nothing to update — provide at least one of `content`, `quirkType`, `tags`, `confidence`, or `sourceRef`.",
+                        metadata: { tool: "update_quirk", quirkId: args.id, error: "no fields provided" },
+                    };
+                }
+                const quirk = await updateQuirk(deps, args.id, {
+                    content: args.content,
+                    quirkType: args.quirkType,
+                    tags: args.tags,
+                    confidence: args.confidence,
+                    sourceRef: args.sourceRef,
+                });
+                return {
+                    title: "Quirk updated",
+                    output: `**Quirk updated** (id: \`${quirk.id}\`)\n` +
+                        `\`${quirk.quirkType ?? "general"}\` | confidence=${(quirk.confidence * 100).toFixed(0)}% | tags=${(quirk.tags ?? []).join(", ") || "none"}\n` +
+                        quirk.content,
+                    metadata: {
+                        tool: "update_quirk",
+                        quirkId: quirk.id,
+                        quirkType: quirk.quirkType,
+                        confidence: quirk.confidence,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    title: "Quirk update",
+                    output: `Failed to update quirk: ${err instanceof Error ? err.message : String(err)}`,
+                    metadata: { tool: "update_quirk", error: String(err) },
+                };
+            }
+        },
+    });
+}
+/**
+ * Create the `delete_quirk` tool.
+ *
+ * Removes a quirk by ID from the vector store, keyword index, and audit log.
+ * Use when a quirk is wrong, no longer applies, or has been superseded by an
+ * updated version.
+ *
+ * @param options - Store, embedder, config, keyword index, store path.
+ * @returns A tool definition suitable for OpenCode plugin registration.
+ */
+export function createDeleteQuirkTool(options) {
+    const { store, embedder, cfg, keywordIndex, storePath } = options;
+    return tool({
+        description: "Delete an experiential memory (quirk) by its ID. Use when a quirk is " +
+            "wrong, outdated, or superseded — for example a gotcha that was fixed " +
+            "or a decision that was reversed. Find the ID via `recall_quirks` (it " +
+            "is listed in the recall output) or `quirk list` in the CLI.",
+        args: {
+            id: tool.schema.string().min(1, "Quirk ID is required."),
+        },
+        async execute(args) {
+            try {
+                const deps = { embedder, store, keywordIndex, cfg, storePath };
+                await removeQuirk(deps, args.id);
+                return {
+                    title: "Quirk deleted",
+                    output: `**Quirk deleted** (id: \`${args.id}\`). It will no longer be recalled or auto-injected.`,
+                    metadata: { tool: "delete_quirk", quirkId: args.id },
+                };
+            }
+            catch (err) {
+                return {
+                    title: "Quirk delete",
+                    output: `Failed to delete quirk: ${err instanceof Error ? err.message : String(err)}`,
+                    metadata: { tool: "delete_quirk", error: String(err) },
+                };
+            }
+        },
+    });
+}
 //# sourceMappingURL=tools.js.map

package/dist/plugin.d.ts

@@ -4,7 +4,7 @@
  * automatic context injection and documentation mode.
  */
 import type { Plugin, Hooks } from "@opencode-ai/plugin";
-import type { EmbeddingProvider, DescriptionProvider, KeywordIndex, VectorStore } from "./core/interfaces.js";
+import { type EmbeddingProvider, type DescriptionProvider, type KeywordIndex, type VectorStore } from "./core/interfaces.js";
 import { type RagConfig } from "./core/config.js";
 import { createEmbedder } from "./embedder/factory.js";
 import { retrieve } from "./retriever/retriever.js";

package/dist/plugin.js

@@ -4,6 +4,7 @@
  * automatic context injection and documentation mode.
  */
 import { tool } from "@opencode-ai/plugin/tool";
+import { CODE_SEARCH_FILTER } from "./core/interfaces.js";
 import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig, persistProbedDimension } from "./core/config.js";
 import { createEmbedder } from "./embedder/factory.js";
 import { createDescriptionProvider } from "./describer/factory.js";
@@ -15,7 +16,7 @@ import { appendDebugLog } from "./core/fileLogger.js";
 import { loadRuntimeOverrides, applyRuntimeOverrides } from "./core/runtime-overrides.js";
 import { createBackgroundIndexer } from "./watcher.js";
 import { createRagReadTool } from "./opencode/create-read-tool.js";
-import { createFileSkeletonTool, createFindUsagesTool, createDescribeImageTool, createRecallQuirksTool, createAddQuirkTool, } from "./opencode/tools.js";
+import { createFileSkeletonTool, createFindUsagesTool, createDescribeImageTool, createRecallQuirksTool, createAddQuirkTool, createUpdateQuirkTool, createDeleteQuirkTool, } from "./opencode/tools.js";
 import { resolveApiKey } from "./core/resolve-api-key.js";
 import { consumePendingRagInjection } from "./core/rag-injection-flag.js";
 import { loadDocProgress, markSubdirectoryDocumented } from "./core/doc-progress.js";
@@ -645,6 +646,40 @@ export function createRagHooks(options) {
             error: err,
         });
     }
+    try {
+        const updateQuirkTool = createUpdateQuirkTool({
+            store,
+            embedder,
+            cfg: effectiveCfg,
+            keywordIndex: keywordIndex,
+            storePath: options.storePath,
+        });
+        tools["update_quirk"] = updateQuirkTool;
+    }
+    catch (err) {
+        appendDebugLog(options.logFilePath, {
+            scope: "plugin",
+            message: "Failed to register update_quirk tool",
+            error: err,
+        });
+    }
+    try {
+        const deleteQuirkTool = createDeleteQuirkTool({
+            store,
+            embedder,
+            cfg: effectiveCfg,
+            keywordIndex: keywordIndex,
+            storePath: options.storePath,
+        });
+        tools["delete_quirk"] = deleteQuirkTool;
+    }
+    catch (err) {
+        appendDebugLog(options.logFilePath, {
+            scope: "plugin",
+            message: "Failed to register delete_quirk tool",
+            error: err,
+        });
+    }
     if (readOverride) {
         const readTool = createRagReadTool({
             worktree: options.worktree,
@@ -1155,6 +1190,8 @@ export function createRagHooks(options) {
                         keywordIndex,
                         keywordWeight: hybridCfg?.keywordWeight,
                         queryPrefix: effectiveCfg.embedding.queryPrefix,
+                        // Never surface quirk chunks in hotkey file lists / chunk injections.
+                        filter: CODE_SEARCH_FILTER,
                     });
                     const retrievalTimeMs = Date.now() - retrievalStart;
                     if (results.length > 0) {

package/dist/quirks/quirk-store.d.ts

@@ -9,9 +9,22 @@ export interface QuirkStoreDeps {
     cfg: RagConfig;
     storePath: string;
 }
+/** Look up a single quirk by its ID, or `undefined` when not found. */
+export declare function getQuirk(deps: QuirkStoreDeps, id: string): Promise<Quirk | undefined>;
+/**
+ * Update an existing quirk by ID. Fields in `patch` override the stored values.
+ *
+ * When `content` changes, the new text must pass the trust monitor, the quirk
+ * is re-embedded, and the vector-store chunk + keyword index entry are replaced
+ * (same ID, new embedding). The audit log entry is rewritten in place.
+ *
+ * @throws If no quirk with the given ID exists, or the new content is rejected
+ * by the trust monitor.
+ */
+export declare function updateQuirk(deps: QuirkStoreDeps, id: string, patch: Partial<QuirkInput>): Promise<Quirk>;
 /** Add a new quirk to the vector store, keyword index, and audit log. */
 export declare function addQuirk(deps: QuirkStoreDeps, input: QuirkInput): Promise<Quirk>;
-/** Remove a quirk by its ID. */
+/** Remove a quirk by its ID. Throws if no quirk with the given ID exists. */
 export declare function removeQuirk(deps: QuirkStoreDeps, id: string): Promise<void>;
 /** List all quirks sorted by lastObserved descending. */
 export declare function listQuirks(deps: QuirkStoreDeps): Promise<Quirk[]>;

package/dist/quirks/quirk-store.js

@@ -38,6 +38,106 @@ function rewriteJsonl(filePath, quirks) {
 function nowISO() {
     return new Date().toISOString();
 }
+/** Look up a single quirk by its ID, or `undefined` when not found. */
+export async function getQuirk(deps, id) {
+    if (!isMemoryStore(deps.storePath)) {
+        const jp = jsonlPath(deps.storePath);
+        if (existsSync(jp)) {
+            const found = readJsonl(jp).find((q) => q.id === id);
+            if (found)
+                return found;
+        }
+        const chunks = await deps.store.getChunksByFilePath(QUIRK_FILE_PREFIX + id);
+        const c = chunks[0];
+        if (c) {
+            return {
+                id: c.id,
+                content: c.content,
+                quirkType: c.metadata.quirkType,
+                tags: c.metadata.tags ?? [],
+                confidence: c.metadata.confidence ?? 1,
+                lastObserved: c.metadata.lastObserved ?? "",
+                sourceRef: undefined,
+            };
+        }
+        return undefined;
+    }
+    return memQuirks.get(id);
+}
+/**
+ * Update an existing quirk by ID. Fields in `patch` override the stored values.
+ *
+ * When `content` changes, the new text must pass the trust monitor, the quirk
+ * is re-embedded, and the vector-store chunk + keyword index entry are replaced
+ * (same ID, new embedding). The audit log entry is rewritten in place.
+ *
+ * @throws If no quirk with the given ID exists, or the new content is rejected
+ * by the trust monitor.
+ */
+export async function updateQuirk(deps, id, patch) {
+    const existing = await getQuirk(deps, id);
+    if (!existing) {
+        throw new Error(`Quirk not found: ${id}`);
+    }
+    const content = patch.content ?? existing.content;
+    const quirkType = patch.quirkType ?? existing.quirkType;
+    const tags = patch.tags ?? existing.tags;
+    const confidence = patch.confidence ?? existing.confidence;
+    const sourceRef = patch.sourceRef ?? existing.sourceRef;
+    if (content !== existing.content) {
+        const allowed = isQuirkAllowed(content);
+        if (!allowed.ok) {
+            throw new Error(`Quirk rejected by trust monitor: ${allowed.reason}`);
+        }
+    }
+    const updated = {
+        id,
+        content,
+        quirkType,
+        tags,
+        confidence,
+        lastObserved: existing.lastObserved,
+        sourceRef,
+    };
+    const filePath = QUIRK_FILE_PREFIX + id;
+    await deps.store.deleteByFilePath(filePath);
+    deps.keywordIndex.removeByFilePath(filePath);
+    const prefix = deps.cfg.embedding.documentPrefix ?? "";
+    const chunkContent = prefix + content;
+    const embeddings = await deps.embedder.embed([chunkContent], "document");
+    const embedding = embeddings[0];
+    if (!embedding || embedding.length === 0) {
+        throw new Error("Embedding returned empty vector for quirk content");
+    }
+    const chunk = {
+        id,
+        content,
+        description: "",
+        embedding,
+        metadata: {
+            filePath,
+            startLine: 0,
+            endLine: 0,
+            language: "quirk",
+            kind: "quirk",
+            quirkType,
+            tags,
+            confidence,
+            lastObserved: updated.lastObserved,
+        },
+    };
+    await deps.store.addChunks([chunk]);
+    deps.keywordIndex.addChunks([chunk]);
+    if (!isMemoryStore(deps.storePath)) {
+        const jp = jsonlPath(deps.storePath);
+        const all = readJsonl(jp).map((q) => (q.id === id ? updated : q));
+        rewriteJsonl(jp, all);
+    }
+    else {
+        memQuirks.set(id, updated);
+    }
+    return updated;
+}
 /** Add a new quirk to the vector store, keyword index, and audit log. */
 export async function addQuirk(deps, input) {
     const allowed = isQuirkAllowed(input.content);
@@ -90,8 +190,12 @@ export async function addQuirk(deps, input) {
     }
     return quirk;
 }
-/** Remove a quirk by its ID. */
+/** Remove a quirk by its ID. Throws if no quirk with the given ID exists. */
 export async function removeQuirk(deps, id) {
+    const existing = await getQuirk(deps, id);
+    if (!existing) {
+        throw new Error(`Quirk not found: ${id}`);
+    }
     const filePath = QUIRK_FILE_PREFIX + id;
     await deps.store.deleteByFilePath(filePath);
     deps.keywordIndex.removeByFilePath(filePath);

package/dist/web/api.d.ts

@@ -5,7 +5,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { LanceDbStore } from "../vectorstore/lancedb.js";
 import { KeywordIndex } from "../retriever/keyword-index.js";
 import type { RagConfig } from "../core/config.js";
-import type { EmbeddingProvider } from "../core/interfaces.js";
+import { type EmbeddingProvider } from "../core/interfaces.js";
 /** Internal shape for a JSON API response: an HTTP status code and a serialisable body. */
 interface ApiResponse {
     status: number;

package/dist/web/api.js

@@ -5,6 +5,7 @@ import { listSessions, getSession, deleteSession, compareSessions, validateSessi
 import { analyzeTokenUsage, compareTokenAnalyses, projectTokenSavings } from "../eval/token-analysis.js";
 import { listQuirks, lintQuirks, removeQuirk } from "../quirks/quirk-store.js";
 import { retrieve } from "../retriever/retriever.js";
+import { CODE_SEARCH_FILTER } from "../core/interfaces.js";
 const FILE_MIME_TYPES = {
     ".png": "image/png",
     ".jpg": "image/jpeg",
@@ -244,7 +245,16 @@ async function handleQuirkLint(deps) {
 }
 /** Delete a single quirk by its ID from the store, index, and audit log. */
 async function handleQuirkDelete(deps, id) {
-    await removeQuirk(deps, id);
+    try {
+        await removeQuirk(deps, id);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (/Quirk not found/.test(message)) {
+            return { status: 404, body: { error: message } };
+        }
+        throw err;
+    }
     return { status: 200, body: { deleted: true, id } };
 }
 /**
@@ -288,7 +298,7 @@ async function handleSearch(keywordIndex, params) {
     if (!query.trim()) {
         return { status: 200, body: { results: [] } };
     }
-    const results = keywordIndex.search(query, topK);
+    const results = keywordIndex.search(query, topK, CODE_SEARCH_FILTER);
     return {
         status: 200,
         body: {
@@ -346,6 +356,7 @@ async function handleRetrieve(store, keywordIndex, getEmbedder, cfg, params) {
             filter: {
                 pathPatterns: pathFilter ? pathFilter.split(",").map((s) => s.trim()).filter(Boolean) : undefined,
                 languages: langFilter ? langFilter.split(",").map((s) => s.trim()).filter(Boolean) : undefined,
+                kinds: CODE_SEARCH_FILTER.kinds,
             },
         });
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-rag-plugin",
-  "version": "1.19.2",
+  "version": "1.19.4",
   "description": "OpenCode plugin for local-first RAG-based semantic code search",
   "type": "module",
   "main": "./dist/plugin-entry.js",