opencode-rag-plugin 1.19.1 → 1.19.3

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/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/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/cli/commands/status.js

@@ -7,7 +7,7 @@
 import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
-import { c, resolveCliContext, cleanupContext, logCliError, logCliInfo, formatTimestamp } from "../format.js";
+import { c, resolveCliContext, logCliError, logCliInfo, formatTimestamp } from "../format.js";
 import { getIndexStatusSummary } from "../../indexer.js";
 import { getPackageMetadata } from "../helpers.js";
 import { checkForUpdate } from "../../core/version-check.js";
@@ -156,7 +156,9 @@ export function registerStatusCommand(program) {
                     }
                 }).catch(() => { });
             }
-            await cleanupContext(ctx);
+            // Force exit — avoid LanceDB close() hanging on Windows native bindings.
+            // Status is read-only so there's no state to lose.
+            process.exit(0);
         }
         catch (err) {
             const message = err.message || String(err);

package/dist/cli/index.d.ts

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * @fileoverview CLI entry point creating the Commander program, wiring all command modules, and handling auto-run detection.
  */

package/dist/cli/index.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 /**
  * @fileoverview CLI entry point creating the Commander program, wiring all command modules, and handling auto-run detection.
  */

package/dist/core/config.js

@@ -266,14 +266,14 @@ export const DEFAULT_CONFIG = {
     },
     memory: {
         enabled: true,
-        autoInject: false,
+        autoInject: true,
         minConfidence: 0.5,
-        recallMinScore: 0.72,
-        autoInjectMinScore: 0.6,
+        recallMinScore: 0.6,
+        autoInjectMinScore: 0.5,
         autoInjectLatencyBudgetMs: 2000,
         autoInjectTopK: 2,
         autoInjectMinTokenOverlap: 1,
-        passiveCapture: false,
+        passiveCapture: true,
         promptEnforcement: true,
         sessionEndExtraction: true,
         autoCaptureMaxPerTurn: 2,

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

@@ -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

@@ -20,7 +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";
+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"] },
@@ -620,4 +620,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.js

@@ -15,7 +15,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 +645,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,

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/vectorstore/lancedb.d.ts

@@ -10,6 +10,19 @@ export declare function l2Normalize(vec: number[]): number[];
  * @returns True if the error matches a known corruption pattern.
  */
 export declare function isCorruptionError(err: unknown): boolean;
+/**
+ * Check whether an error is a LanceDB transient transaction conflict
+ * (e.g. "Incompatible transaction: This Append transaction is incompatible
+ * with concurrent transaction Restore at version ...").
+ *
+ * These are recoverable by retrying after the conflicting transaction finishes.
+ * Cross-process writes are the primary source; in-process writes are serialized
+ * by the write lock.
+ *
+ * @param err - The error to inspect.
+ * @returns True if the error matches a transient transaction conflict.
+ */
+export declare function isTransientConflictError(err: unknown): boolean;
 /**
  * Atomically replace one LanceDB store directory with another.
  * Swaps the real directory with a temporary one that was built during a rebuild.
@@ -31,6 +44,23 @@ export declare class LanceDbStore implements VectorStore {
     private table;
     private tableInit;
     private writeLock;
+    /**
+     * Execute an async function under an exclusive write lock.
+     *
+     * All write operations (addChunks, deleteByFilePath, optimize, tryRepair) must
+     * go through this helper to prevent concurrent LanceDB transactions from
+     * conflicting (e.g. Append vs Restore, which produces the "Incompatible
+     * transaction" error).
+     *
+     * The lock is a Promise chain: each caller chains onto `this.writeLock` and
+     * sets it to a new promise that resolves only when its operation finishes
+     * (or throws).  This guarantees FIFO serialization without any busy-waiting
+     * or timers.
+     *
+     * @param fn - The async function to execute under the lock.
+     * @returns The result of `fn`.
+     */
+    private withWriteLock;
     /**
      * @param dbPath - Filesystem path to the LanceDB database directory.
      * @param vectorDimension - Dimension of the embedding vectors. Default: 384.
@@ -191,4 +221,10 @@ export declare class LanceDbStore implements VectorStore {
      */
     private withCorruptionRecovery;
     private tryRepair;
+    /**
+     * Drop the existing chunks table and let getTable() create a fresh one.
+     * All indexed data is lost — callers should detect the empty table and
+     * trigger a re-index if needed.
+     */
+    private tryRebuildTable;
 }

package/dist/vectorstore/lancedb.js

@@ -27,9 +27,32 @@ export function l2Normalize(vec) {
  */
 export function isCorruptionError(err) {
     if (err instanceof Error) {
-        return (err.message.includes("Not found") &&
+        return ((err.message.includes("Not found") &&
             err.message.includes(".lance") &&
-            err.message.includes("lance error"));
+            err.message.includes("lance error")) ||
+            // Database has an incompatible transaction (e.g. a Restore from a prior
+            // version that conflicts with new Appends).  This is a recoverable
+            // corruption — tryRepair() iterates prior versions to find a consistent one.
+            (err.message.includes("Incompatible transaction") &&
+                err.message.includes("version")));
+    }
+    return false;
+}
+/**
+ * Check whether an error is a LanceDB transient transaction conflict
+ * (e.g. "Incompatible transaction: This Append transaction is incompatible
+ * with concurrent transaction Restore at version ...").
+ *
+ * These are recoverable by retrying after the conflicting transaction finishes.
+ * Cross-process writes are the primary source; in-process writes are serialized
+ * by the write lock.
+ *
+ * @param err - The error to inspect.
+ * @returns True if the error matches a transient transaction conflict.
+ */
+export function isTransientConflictError(err) {
+    if (err instanceof Error) {
+        return err.message.includes("Incompatible transaction");
     }
     return false;
 }
@@ -76,6 +99,43 @@ export class LanceDbStore {
     table = null;
     tableInit = null;
     writeLock = Promise.resolve(void 0);
+    /**
+     * Execute an async function under an exclusive write lock.
+     *
+     * All write operations (addChunks, deleteByFilePath, optimize, tryRepair) must
+     * go through this helper to prevent concurrent LanceDB transactions from
+     * conflicting (e.g. Append vs Restore, which produces the "Incompatible
+     * transaction" error).
+     *
+     * The lock is a Promise chain: each caller chains onto `this.writeLock` and
+     * sets it to a new promise that resolves only when its operation finishes
+     * (or throws).  This guarantees FIFO serialization without any busy-waiting
+     * or timers.
+     *
+     * @param fn - The async function to execute under the lock.
+     * @returns The result of `fn`.
+     */
+    async withWriteLock(fn) {
+        const prev = this.writeLock;
+        let release = () => { };
+        this.writeLock = new Promise((resolve) => { release = resolve; });
+        await prev;
+        try {
+            return await fn();
+        }
+        catch (err) {
+            // Cross-process transient conflict (e.g. CLI vs plugin):
+            // wait briefly and retry once, still under the same lock hold.
+            if (isTransientConflictError(err)) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                return await fn();
+            }
+            throw err;
+        }
+        finally {
+            release();
+        }
+    }
     /**
      * @param dbPath - Filesystem path to the LanceDB database directory.
      * @param vectorDimension - Dimension of the embedding vectors. Default: 384.
@@ -242,21 +302,18 @@ export class LanceDbStore {
     async addChunks(chunks) {
         if (chunks.length === 0)
             return;
-        const done = this.writeLock.then(() => this.addChunksInternal(chunks));
-        this.writeLock = done.catch(() => { });
-        try {
-            await done;
-        }
-        catch (err) {
-            this.writeLock = Promise.resolve();
-            if (isCorruptionError(err) && await this.tryRepair()) {
-                const retry = this.addChunksInternal(chunks);
-                this.writeLock = retry.catch(() => { });
-                await retry;
-                return;
+        await this.withWriteLock(async () => {
+            try {
+                await this.addChunksInternal(chunks);
             }
-            throw err;
-        }
+            catch (err) {
+                if (isCorruptionError(err) && await this.tryRepair()) {
+                    await this.addChunksInternal(chunks);
+                    return;
+                }
+                throw err;
+            }
+        });
     }
     async addChunksInternal(chunks) {
         const table = await this.getTable();
@@ -343,7 +400,7 @@ export class LanceDbStore {
         }
         catch (err) {
             if (isCorruptionError(err)) {
-                const repaired = await this.tryRepair();
+                const repaired = await this.withWriteLock(() => this.tryRepair());
                 if (repaired) {
                     return this.searchInternal(embedding, topK, filter);
                 }
@@ -577,19 +634,21 @@ export class LanceDbStore {
      * Should be called at the end of a successful index pass.
      */
     async optimize() {
-        try {
-            const table = await this.getTable();
-            // Clean up versions older than 1 hour — not "right now" — so in-flight
-            // queries (e.g. Web UI search, background auto-index) can finish before
-            // their data files are reclaimed.  Using new Date() here caused data-file
-            // race conditions where a reader got "Not found: … .lance" because the
-            // GC deleted fragments that the current version still referenced.
-            const threshold = new Date(Date.now() - 60 * 60 * 1000);
-            await table.optimize({ cleanupOlderThan: threshold, deleteUnverified: false });
-        }
-        catch {
-            // Optimize is best-effort — must not break indexing.
-        }
+        await this.withWriteLock(async () => {
+            try {
+                const table = await this.getTable();
+                // Clean up versions older than 1 hour �?" not "right now" �?" so in-flight
+                // queries (e.g. Web UI search, background auto-index) can finish before
+                // their data files are reclaimed.  Using new Date() here caused data-file
+                // race conditions where a reader got "Not found: �?� .lance" because the
+                // GC deleted fragments that the current version still referenced.
+                const threshold = new Date(Date.now() - 60 * 60 * 1000);
+                await table.optimize({ cleanupOlderThan: threshold, deleteUnverified: false });
+            }
+            catch {
+                // Optimize is best-effort �?" must not break indexing.
+            }
+        });
     }
     /**
      * Return all unique file paths currently stored in the index.
@@ -727,16 +786,18 @@ export class LanceDbStore {
      * @param filePath - The file path whose chunks should be deleted.
      */
     async deleteByFilePath(filePath) {
-        try {
-            await this.deleteByFilePathInternal(filePath);
-        }
-        catch (err) {
-            if (isCorruptionError(err) && await this.tryRepair()) {
+        await this.withWriteLock(async () => {
+            try {
                 await this.deleteByFilePathInternal(filePath);
-                return;
             }
-            throw err;
-        }
+            catch (err) {
+                if (isCorruptionError(err) && await this.tryRepair()) {
+                    await this.deleteByFilePathInternal(filePath);
+                    return;
+                }
+                throw err;
+            }
+        });
     }
     async deleteByFilePathInternal(filePath) {
         const db = await this.getDb();
@@ -791,8 +852,13 @@ export class LanceDbStore {
             return await fn();
         }
         catch (err) {
-            if (isCorruptionError(err) && await this.tryRepair()) {
-                return fn();
+            if (isCorruptionError(err)) {
+                // Repair must be under writeLock to prevent Restore from conflicting
+                // with concurrent Append transactions (addChunks / deleteByFilePath).
+                const repaired = await this.withWriteLock(() => this.tryRepair());
+                if (repaired) {
+                    return fn();
+                }
             }
             throw err;
         }
@@ -823,7 +889,7 @@ export class LanceDbStore {
                 return false;
             }
             if (versions.length <= 1) {
-                return false;
+                return this.tryRebuildTable(db);
             }
             const sorted = [...versions].sort((a, b) => b.version - a.version);
             for (const ver of sorted.slice(1)) {
@@ -839,10 +905,29 @@ export class LanceDbStore {
                     continue;
                 }
             }
-            console.error("[lancedb] All version-restore attempts failed. " +
-                "Run 'opencode-rag index --force' to rebuild the index.");
+            // All version-restore attempts failed (likely corrupted version graph
+            // with incompatible Restore transactions).  Drop and recreate the table.
+            console.warn("[lancedb] Version restore failed. Dropping and recreating table to recover from corrupt version graph.");
+            return this.tryRebuildTable(db);
+        }
+        catch {
             return false;
         }
+    }
+    /**
+     * Drop the existing chunks table and let getTable() create a fresh one.
+     * All indexed data is lost — callers should detect the empty table and
+     * trigger a re-index if needed.
+     */
+    async tryRebuildTable(db) {
+        try {
+            await db.dropTable(TABLE_NAME).catch(() => { });
+            this.table = null;
+            // Re-create fresh via getTable → initTable
+            await this.getTable();
+            console.warn("[lancedb] Table recreated from scratch after corruption recovery.");
+            return true;
+        }
         catch {
             return false;
         }

package/dist/web/api.js

@@ -244,7 +244,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 } };
 }
 /**

package/package.json

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