opencode-rag-plugin 1.17.2 → 1.18.0

package/dist/plugin.js

@@ -15,15 +15,17 @@ 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, } from "./opencode/tools.js";
+import { createFileSkeletonTool, createFindUsagesTool, createDescribeImageTool, createRecallQuirksTool, createAddQuirkTool, } 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";
 import { loadManifest } from "./core/manifest.js";
 import { createSessionLogger } from "./eval/session-logger.js";
 import { countTokens } from "./eval/token-counter.js";
-import { checkForUpdate, getCurrentVersion } from "./core/version-check.js";
+import { checkForUpdate, getCurrentVersion, installLatestUpdate } from "./core/version-check.js";
+import { loadAutoUpdateState, saveAutoUpdateState, shouldAttemptInstall } from "./core/auto-update-state.js";
 import { destroyAllPooledConnections } from "./embedder/http.js";
+import { listQuirks, lintQuirks, recallQuirks } from "./quirks/quirk-store.js";
 import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -41,6 +43,8 @@ const mcpServers = new Map();
 const pendingUpdateInfo = new Map();
 /** Workspace directories that have already been prompted about an update this session. */
 const notifiedUpdateDirs = new Set();
+/** Pending "restart needed" notice after a background auto-install. */
+const pendingRestartNotice = new Map();
 /** Guard flag to prevent re-entrant shutdown. */
 let shutdownRegistered = false;
 /** Close all active background indexers and MCP servers, then destroy idle sockets. */
@@ -61,6 +65,7 @@ async function shutdownPluginResources() {
     }
     configCache.clear();
     pendingUpdateInfo.clear();
+    pendingRestartNotice.clear();
     notifiedUpdateDirs.clear();
     destroyAllPooledConnections();
 }
@@ -589,6 +594,40 @@ export function createRagHooks(options) {
             error: err,
         });
     }
+    try {
+        const recallQuirksTool = createRecallQuirksTool({
+            store,
+            embedder,
+            cfg: effectiveCfg,
+            keywordIndex: keywordIndex,
+            storePath: options.storePath,
+        });
+        tools["recall_quirks"] = recallQuirksTool;
+    }
+    catch (err) {
+        appendDebugLog(options.logFilePath, {
+            scope: "plugin",
+            message: "Failed to register recall_quirks tool",
+            error: err,
+        });
+    }
+    try {
+        const addQuirkTool = createAddQuirkTool({
+            store,
+            embedder,
+            cfg: effectiveCfg,
+            keywordIndex: keywordIndex,
+            storePath: options.storePath,
+        });
+        tools["add_quirk"] = addQuirkTool;
+    }
+    catch (err) {
+        appendDebugLog(options.logFilePath, {
+            scope: "plugin",
+            message: "Failed to register add_quirk tool",
+            error: err,
+        });
+    }
     if (readOverride) {
         const readTool = createRagReadTool({
             worktree: options.worktree,
@@ -662,6 +701,8 @@ export function createRagHooks(options) {
                     "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
                     "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
                     "- `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.",
                     "",
                     "Decision tree — ALWAYS follow this order:",
                     "1. User mentions code behavior/architecture → `search_semantic(query)`",
@@ -669,6 +710,8 @@ export function createRagHooks(options) {
                     "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
                     "4. User asks a code question → `search_semantic` to gather context before answering",
                     "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+                    "6. You encounter an error or need 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",
                     "",
                     "Proactive triggers — you MUST call these tools when:",
                     "- User asks about code behavior, architecture, or implementation details",
@@ -699,6 +742,16 @@ export function createRagHooks(options) {
                     `they would like you to install it. If they agree, run \`opencode-rag update\` via the bash tool, then tell ` +
                     `them to restart OpenCode to load the new version. Do not mention this notice again.`);
             }
+            // Inject a one-time "restart needed" notice after a background auto-install.
+            // Fires only once per workspace per session, mirroring the notify-only pattern above.
+            const restartInfo = pendingRestartNotice.get(options.worktree);
+            if (restartInfo && !notifiedUpdateDirs.has(options.worktree + ":restart")) {
+                notifiedUpdateDirs.add(options.worktree + ":restart");
+                pendingRestartNotice.delete(options.worktree);
+                output.system.unshift(`OpenCodeRAG was automatically updated from v${restartInfo.fromVersion} to v${restartInfo.toVersion} ` +
+                    `in the background. At the very start of your next response, tell the user the update was installed ` +
+                    `and ask them to restart OpenCode to load the new version. Do not mention this notice again.`);
+            }
             // Inject documentation mode system prompt if enabled
             const docMode = getEffectiveCfg().documentationMode;
             if (docMode?.enabled && docMode.systemPrompt) {
@@ -868,6 +921,67 @@ export function createRagHooks(options) {
                     }
                     return;
                 }
+                // Handle /quirk slash command
+                if (text.startsWith("/quirk")) {
+                    const memoryCfg = getEffectiveCfg().memory;
+                    if (!memoryCfg?.enabled) {
+                        const parts = output?.parts ?? output?.message?.parts;
+                        if (Array.isArray(parts) && parts.length > 0) {
+                            const first = parts[0];
+                            if (typeof first.text === "string") {
+                                parts[0] = { ...first, text: "Quirk memory is not enabled. Set `memory.enabled` to `true` in opencode-rag.json." };
+                            }
+                        }
+                        return;
+                    }
+                    const arg = text.slice(6).trim().toLowerCase();
+                    const lines = [];
+                    if (arg === "lint") {
+                        const deps = { embedder, store, keywordIndex: keywordIndex, cfg: getEffectiveCfg(), storePath: options.storePath };
+                        const issues = await lintQuirks(deps);
+                        lines.push("## Quirk Lint", "");
+                        if (issues.length === 0) {
+                            lines.push("No issues found. All quirks look healthy.");
+                        }
+                        else {
+                            lines.push(`Found ${issues.length} issue(s):\n`);
+                            for (const issue of issues) {
+                                lines.push(`- ${issue}`);
+                            }
+                            lines.push("", "Fix the issues and consider updating or removing the flagged quirks.");
+                        }
+                    }
+                    else if (arg.startsWith("add ")) {
+                        lines.push("## Add Quirk", "", "Use the `add_quirk` tool to store a new experiential memory entry. Example:", "", '`content`: "npm install needs --legacy-peer-deps due to LanceDB peer dep conflicts"', '`quirkType`: "gotcha"', "`tags`: [\"npm\", \"lancedb\", \"installation\"]");
+                    }
+                    else {
+                        // Status / list
+                        const deps = { embedder, store, keywordIndex: keywordIndex, cfg: getEffectiveCfg(), storePath: options.storePath };
+                        const quirks = await listQuirks(deps);
+                        lines.push("## Quirk Memory", "");
+                        if (quirks.length === 0) {
+                            lines.push("No quirks stored yet.");
+                        }
+                        else {
+                            lines.push(`${quirks.length} quirk(s) stored:\n`);
+                            for (const q of quirks) {
+                                const badge = q.quirkType ? `[\`${q.quirkType}\`] ` : "";
+                                const tags = q.tags.length > 0 ? ` _(${q.tags.join(", ")})_` : "";
+                                lines.push(`- ${badge}${q.content.slice(0, 100)}${tags}  `);
+                            }
+                            lines.push("", "Commands:", "- `/quirk` — show this status", "- `/quirk lint` — health-check quirks", "- `/quirk add <text>` — instructions to use the add_quirk tool");
+                        }
+                    }
+                    const quirkMsg = lines.join("\n");
+                    const parts = output?.parts ?? output?.message?.parts;
+                    if (Array.isArray(parts) && parts.length > 0) {
+                        const first = parts[0];
+                        if (typeof first.text === "string") {
+                            parts[0] = { ...first, text: quirkMsg };
+                        }
+                    }
+                    return;
+                }
                 // Handle hotkey-triggered RAG injection (Ctrl+Enter / Ctrl+Alt+Enter)
                 const pendingInjection = consumePendingRagInjection(options.storePath);
                 if (pendingInjection) {
@@ -924,6 +1038,40 @@ export function createRagHooks(options) {
                                 });
                             }
                         }
+                        // Auto-inject quirks when memory.autoInject is enabled
+                        const memoryCfg = effectiveCfg.memory;
+                        if (memoryCfg?.autoInject) {
+                            try {
+                                const quirkDeps = { embedder, store, keywordIndex: keywordIndex, cfg: effectiveCfg, storePath: options.storePath };
+                                const quirkResults = await recallQuirks(quirkDeps, searchQuery, { topK: 3 });
+                                if (quirkResults.length > 0) {
+                                    const quirkLines = ["", "---", "⚠ **Quirk memory**", ""];
+                                    for (const qr of quirkResults) {
+                                        const m = qr.chunk.metadata;
+                                        const badge = m.quirkType ? `[\`${m.quirkType}\`] ` : "";
+                                        quirkLines.push(`- ${badge}${qr.chunk.content.slice(0, 200)}`);
+                                    }
+                                    const quirkBlock = quirkLines.join("\n");
+                                    const parts = output?.parts ?? output?.message?.parts;
+                                    if (Array.isArray(parts) && parts.length > 0) {
+                                        const first = parts[0];
+                                        if (typeof first.text === "string") {
+                                            parts[0] = { ...first, text: first.text + "\n\n" + quirkBlock };
+                                        }
+                                        const msgParts = output?.message?.parts;
+                                        if (Array.isArray(msgParts) && msgParts !== parts) {
+                                            const mfirst = msgParts[0];
+                                            if (typeof mfirst.text === "string") {
+                                                msgParts[0] = { ...mfirst, text: mfirst.text + "\n\n" + quirkBlock };
+                                            }
+                                        }
+                                    }
+                                }
+                            }
+                            catch {
+                                // Non-critical — must never throw
+                            }
+                        }
                     }
                     appendDebugLog(options.logFilePath, {
                         scope: "chat.message",
@@ -1161,6 +1309,7 @@ export const ragPlugin = async (input, _options) => {
     // Clean up stale config cache and pending update info for this directory
     configCache.delete(input.directory);
     pendingUpdateInfo.delete(input.directory);
+    pendingRestartNotice.delete(input.directory);
     notifiedUpdateDirs.delete(input.directory);
     // Clean up idle HTTP sockets from previous provider connections
     destroyAllPooledConnections();
@@ -1253,8 +1402,11 @@ export const ragPlugin = async (input, _options) => {
             catch { /* ignore */ }
         }
     }
-    // Auto-start MCP server if enabled (skip in temp dirs / test environments)
-    const mcpCfg = effectiveCfg.mcp ?? { enabled: true };
+    // Auto-start standalone MCP server if enabled (default: off). Agent tools
+    // (search_semantic, get_file_skeleton, find_usages, describe_image) and the
+    // chat.message hook run in-process regardless. Enable only when an external
+    // MCP client connects to `opencode-rag mcp`.
+    const mcpCfg = effectiveCfg.mcp ?? { enabled: false };
     const isTempDir = path.resolve(input.directory).startsWith(tmpdir());
     if (mcpCfg.enabled && !isTempDir) {
         const mcpInstance = startMcpServerProcess(input.directory, logFilePath, logLevel);
@@ -1262,14 +1414,75 @@ export const ragPlugin = async (input, _options) => {
     }
     // Auto-update check (non-blocking, best-effort). On by default; can be
     // disabled via `autoUpdate.enabled: false` in opencode-rag.json. When a newer
-    // release is found it is stored and surfaced as a one-time install prompt via
-    // the system transform hook (see createRagHooks).
+    // release is found it is either surfaced as a one-time install prompt via
+    // the system transform hook (default) or automatically installed in the
+    // background when `autoUpdate.autoInstall: true` is configured.
     const autoUpdateCfg = effectiveCfg.autoUpdate;
     if (autoUpdateCfg?.enabled) {
         const currentVersion = getCurrentVersion();
         checkForUpdate(currentVersion)
             .then((info) => {
-            if (info.updateAvailable) {
+            if (!info.updateAvailable)
+                return;
+            if (autoUpdateCfg?.autoInstall) {
+                // Background auto-install branch (opt-in). Persist a cooldown file
+                // so we don't re-install on every plugin reload or after failures.
+                const cooldownMs = autoUpdateCfg.cooldownMs ?? 3_600_000;
+                const maxFailures = autoUpdateCfg.maxConsecutiveFailures ?? 3;
+                const state = loadAutoUpdateState(storePath);
+                const { attempt, reason } = shouldAttemptInstall(state, info.latestVersion, cooldownMs, maxFailures);
+                if (!attempt) {
+                    appendDebugLog(logFilePath, {
+                        scope: "updater",
+                        message: `Auto-install skipped: ${reason}`,
+                    }, logLevel);
+                    return;
+                }
+                saveAutoUpdateState(storePath, {
+                    lastAttemptAt: Date.now(),
+                    lastAttemptedVersion: info.latestVersion,
+                    lastResult: "failure",
+                    consecutiveFailures: 1,
+                });
+                installLatestUpdate({ verbose: false })
+                    .then((result) => {
+                    if (result.success && result.toVersion && result.toVersion !== currentVersion) {
+                        pendingRestartNotice.set(input.directory, {
+                            fromVersion: currentVersion,
+                            toVersion: result.toVersion,
+                        });
+                        saveAutoUpdateState(storePath, {
+                            lastAttemptAt: Date.now(),
+                            lastAttemptedVersion: info.latestVersion,
+                            lastResult: "success",
+                            consecutiveFailures: 0,
+                        });
+                        appendDebugLog(logFilePath, {
+                            scope: "updater",
+                            message: `Auto-installed v${currentVersion} → v${result.toVersion}`,
+                        }, logLevel);
+                    }
+                    else {
+                        saveAutoUpdateState(storePath, {
+                            lastAttemptAt: Date.now(),
+                            lastAttemptedVersion: info.latestVersion,
+                            lastResult: "success",
+                            consecutiveFailures: 0,
+                        });
+                    }
+                })
+                    .catch(() => {
+                    const existing = loadAutoUpdateState(storePath);
+                    saveAutoUpdateState(storePath, {
+                        lastAttemptAt: Date.now(),
+                        lastAttemptedVersion: info.latestVersion,
+                        lastResult: "failure",
+                        consecutiveFailures: (existing?.consecutiveFailures ?? 0) + 1,
+                    });
+                });
+            }
+            else {
+                // Notify-only: surface as a one-time agent prompt
                 pendingUpdateInfo.set(input.directory, info);
                 appendDebugLog(logFilePath, {
                     scope: "updater",

package/dist/quirks/monitor.d.ts

@@ -0,0 +1,5 @@
+/** Check whether quirk content is allowed within the immutable environment boundary. */
+export declare function isQuirkAllowed(content: string): {
+    ok: boolean;
+    reason?: string;
+};

package/dist/quirks/monitor.js

@@ -0,0 +1,23 @@
+/** Patterns that are never allowed in quirk memory — the immutable trust boundary. */
+const BLOCKED_PATTERNS = [
+    /\bskip\s+(?:\S+\s+)*?tests?\b/i,
+    /\bdisable\s+(lint|typecheck|strict)/i,
+    /\bignore\s+(all\s+)?errors/i,
+    /\brm\s+-rf\b/,
+    /\bforce\s+push\b/,
+    /\bgit\s+push\s+--force\b/,
+    /\bdelete\s+.+\.git/i,
+    /\btouch\s+(?:\.env|withheld)/i,
+    /\bbypass\s+(?:security|review|check)/i,
+];
+/** Check whether quirk content is allowed within the immutable environment boundary. */
+export function isQuirkAllowed(content) {
+    for (const pattern of BLOCKED_PATTERNS) {
+        const match = content.match(pattern);
+        if (match) {
+            return { ok: false, reason: `Content matches blocked pattern: "${match[0]}"` };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=monitor.js.map

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

@@ -0,0 +1,25 @@
+import type { EmbeddingProvider, VectorStore, KeywordIndex, SearchResult } from "../core/interfaces.js";
+import type { RagConfig } from "../core/config.js";
+import type { Quirk, QuirkInput } from "./types.js";
+/** Dependencies required by all quirk-store operations. */
+export interface QuirkStoreDeps {
+    embedder: EmbeddingProvider;
+    store: VectorStore;
+    keywordIndex: KeywordIndex;
+    cfg: RagConfig;
+    storePath: string;
+}
+/** 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. */
+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[]>;
+/** Recall quirks matching a query, with confidence re-weighting. */
+export declare function recallQuirks(deps: QuirkStoreDeps, query: string, options?: {
+    topK?: number;
+    quirkType?: string;
+    tags?: string[];
+}): Promise<SearchResult[]>;
+/** Lint quirks for low confidence, staleness, duplicates, and orphan source refs. */
+export declare function lintQuirks(deps: QuirkStoreDeps): Promise<string[]>;

package/dist/quirks/quirk-store.js

@@ -0,0 +1,217 @@
+import { appendFileSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { retrieve } from "../retriever/retriever.js";
+import { isQuirkAllowed } from "./monitor.js";
+const QUIRK_FILE_PREFIX = "quirk:";
+const QUIKK_JSONL = "quirks.jsonl";
+function jsonlPath(storePath) {
+    return path.join(storePath, QUIKK_JSONL);
+}
+function isMemoryStore(storePath) {
+    return storePath.startsWith("memory:");
+}
+/** In-memory backup for memory:// stores. */
+const memQuirks = new Map();
+function readJsonl(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const raw = readFileSync(filePath, "utf-8").trim();
+    if (!raw)
+        return [];
+    return raw.split("\n").map((l) => JSON.parse(l));
+}
+function appendJsonl(filePath, q) {
+    const dir = path.dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    appendFileSync(filePath, JSON.stringify(q) + "\n", "utf-8");
+}
+function rewriteJsonl(filePath, quirks) {
+    const dir = path.dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filePath, quirks.map((q) => JSON.stringify(q)).join("\n") + "\n", "utf-8");
+}
+function nowISO() {
+    return new Date().toISOString();
+}
+/** Add a new quirk to the vector store, keyword index, and audit log. */
+export async function addQuirk(deps, input) {
+    const allowed = isQuirkAllowed(input.content);
+    if (!allowed.ok) {
+        throw new Error(`Quirk rejected by trust monitor: ${allowed.reason}`);
+    }
+    const id = `quirk:${randomUUID()}`;
+    const lastObserved = nowISO();
+    const confidence = input.confidence ?? 1;
+    const quirk = {
+        id,
+        content: input.content,
+        quirkType: input.quirkType,
+        tags: input.tags ?? [],
+        confidence,
+        lastObserved,
+        sourceRef: input.sourceRef,
+    };
+    const prefix = deps.cfg.embedding.documentPrefix ?? "";
+    const chunkContent = prefix + input.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: input.content,
+        description: "",
+        embedding,
+        metadata: {
+            filePath: QUIRK_FILE_PREFIX + id,
+            startLine: 0,
+            endLine: 0,
+            language: "quirk",
+            kind: "quirk",
+            quirkType: input.quirkType,
+            tags: input.tags ?? [],
+            confidence,
+            lastObserved,
+        },
+    };
+    await deps.store.addChunks([chunk]);
+    deps.keywordIndex.addChunks([chunk]);
+    if (!isMemoryStore(deps.storePath)) {
+        appendJsonl(jsonlPath(deps.storePath), quirk);
+    }
+    else {
+        memQuirks.set(id, quirk);
+    }
+    return quirk;
+}
+/** Remove a quirk by its ID. */
+export async function removeQuirk(deps, id) {
+    const filePath = QUIRK_FILE_PREFIX + id;
+    await deps.store.deleteByFilePath(filePath);
+    deps.keywordIndex.removeByFilePath(filePath);
+    if (!isMemoryStore(deps.storePath)) {
+        const jp = jsonlPath(deps.storePath);
+        const all = readJsonl(jp).filter((q) => q.id !== id);
+        rewriteJsonl(jp, all);
+    }
+    else {
+        memQuirks.delete(id);
+    }
+}
+/** List all quirks sorted by lastObserved descending. */
+export async function listQuirks(deps) {
+    if (!isMemoryStore(deps.storePath)) {
+        const jp = jsonlPath(deps.storePath);
+        if (existsSync(jp)) {
+            const all = readJsonl(jp);
+            all.sort((a, b) => b.lastObserved.localeCompare(a.lastObserved));
+            return all;
+        }
+        // Fallback: scan the store
+        const filePaths = await deps.store.getFilePaths();
+        const quirkPaths = filePaths.filter((fp) => fp.startsWith(QUIRK_FILE_PREFIX));
+        const result = [];
+        for (const fp of quirkPaths) {
+            const chunks = await deps.store.getChunksByFilePath(fp);
+            for (const c of chunks) {
+                result.push({
+                    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,
+                });
+            }
+        }
+        result.sort((a, b) => b.lastObserved.localeCompare(a.lastObserved));
+        return result;
+    }
+    const all = [...memQuirks.values()];
+    all.sort((a, b) => b.lastObserved.localeCompare(a.lastObserved));
+    return all;
+}
+/** Recall quirks matching a query, with confidence re-weighting. */
+export async function recallQuirks(deps, query, options) {
+    const topK = options?.topK ?? 10;
+    const minConfidence = deps.cfg.memory?.minConfidence ?? 0.5;
+    const filter = { kinds: ["quirk"] };
+    if (options?.quirkType) {
+        filter.languages = [options.quirkType];
+    }
+    const recallMinScore = deps.cfg.memory?.recallMinScore ?? 0.72;
+    const raw = await retrieve(query, deps.embedder, deps.store, {
+        topK: topK * 3,
+        minScore: recallMinScore,
+        keywordIndex: deps.keywordIndex,
+        keywordWeight: deps.cfg.retrieval.hybridSearch?.keywordWeight,
+        hybridEnabled: false,
+        queryPrefix: deps.cfg.embedding.queryPrefix,
+        filter,
+    });
+    // Confidence re-weighting + type/tag filtering
+    const filtered = raw.filter((r) => {
+        const conf = r.chunk.metadata.confidence ?? 1;
+        if (conf < minConfidence)
+            return false;
+        if (options?.quirkType && r.chunk.metadata.quirkType !== options.quirkType)
+            return false;
+        if (options?.tags?.length) {
+            const chunkTags = r.chunk.metadata.tags ?? [];
+            if (!options.tags.some((t) => chunkTags.includes(t)))
+                return false;
+        }
+        return true;
+    });
+    // Re-weight score by confidence, re-sort
+    for (const r of filtered) {
+        const conf = r.chunk.metadata.confidence ?? 1;
+        r.score = r.score * Math.min(1, Math.max(0.01, conf));
+    }
+    filtered.sort((a, b) => b.score - a.score);
+    return filtered.slice(0, topK);
+}
+/** Lint quirks for low confidence, staleness, duplicates, and orphan source refs. */
+export async function lintQuirks(deps) {
+    const issues = [];
+    const quirks = await listQuirks(deps);
+    const cfg = deps.cfg.memory;
+    for (const q of quirks) {
+        if (q.confidence < (cfg?.minConfidence ?? 0.5)) {
+            issues.push(`Low confidence (${q.confidence}): "${q.content.slice(0, 60)}..." [${q.id}]`);
+        }
+        if (cfg?.decay?.enabled && q.lastObserved) {
+            const ageDays = (Date.now() - new Date(q.lastObserved).getTime()) / 86_400_000;
+            const halfLife = cfg.decay.halfLifeDays;
+            if (halfLife > 0 && ageDays > halfLife * 2) {
+                issues.push(`Stale (${Math.round(ageDays)}d old): "${q.content.slice(0, 60)}..." [${q.id}]`);
+            }
+        }
+    }
+    // Duplicate detection (lexically similar content)
+    for (let i = 0; i < quirks.length; i++) {
+        for (let j = i + 1; j < quirks.length; j++) {
+            const sim = lexicalSimilarity(quirks[i].content, quirks[j].content);
+            if (sim > 0.85) {
+                issues.push(`Near-duplicate (${(sim * 100).toFixed(0)}% similar): "${quirks[i].content.slice(0, 50)}..." ↔ "${quirks[j].content.slice(0, 50)}..."`);
+            }
+        }
+    }
+    return issues;
+}
+/** Simple Jaccard-based lexical similarity (word overlap). */
+function lexicalSimilarity(a, b) {
+    const wordsA = new Set(a.toLowerCase().split(/\W+/).filter(Boolean));
+    const wordsB = new Set(b.toLowerCase().split(/\W+/).filter(Boolean));
+    const intersection = new Set([...wordsA].filter((w) => wordsB.has(w)));
+    const union = new Set([...wordsA, ...wordsB]);
+    return union.size === 0 ? 0 : intersection.size / union.size;
+}
+//# sourceMappingURL=quirk-store.js.map

package/dist/quirks/types.d.ts

@@ -0,0 +1,20 @@
+/** Quirk sub-type labels. */
+export type QuirkType = "gotcha" | "preference" | "decision" | "environment-constraint";
+/** Input for adding a new quirk. */
+export interface QuirkInput {
+    content: string;
+    quirkType?: string;
+    tags?: string[];
+    confidence?: number;
+    sourceRef?: string;
+}
+/** A quirk entry stored in the vectordb and audit log. */
+export interface Quirk {
+    id: string;
+    content: string;
+    quirkType?: string;
+    tags: string[];
+    confidence: number;
+    lastObserved: string;
+    sourceRef?: string;
+}

package/dist/quirks/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/retriever/keyword-index.js

@@ -184,6 +184,9 @@ export class KeywordIndex {
                     startLine: chunk.metadata.startLine,
                     endLine: chunk.metadata.endLine,
                     language: chunk.metadata.language,
+                    kind: chunk.metadata.kind ?? "",
+                    quirkType: chunk.metadata.quirkType ?? "",
+                    tags: chunk.metadata.tags ? JSON.stringify(chunk.metadata.tags) : "",
                 },
             ])),
         };
@@ -215,6 +218,14 @@ export class KeywordIndex {
             index.invertedIndex.set(token, docMap);
         }
         for (const [id, data] of Object.entries(parsed.chunkMap)) {
+            let tags;
+            try {
+                if (data.tags)
+                    tags = JSON.parse(data.tags);
+            }
+            catch {
+                tags = undefined;
+            }
             index.chunkMap.set(id, {
                 id: data.id,
                 content: data.content,
@@ -224,6 +235,9 @@ export class KeywordIndex {
                     startLine: data.startLine,
                     endLine: data.endLine,
                     language: data.language,
+                    kind: data.kind || undefined,
+                    quirkType: data.quirkType || undefined,
+                    tags,
                 },
             });
         }
@@ -251,6 +265,8 @@ function matchesFilter(chunk, filter) {
         return true;
     if (filter.languages?.length && !filter.languages.includes(chunk.metadata.language))
         return false;
+    if (filter.kinds?.length && !filter.kinds.includes(chunk.metadata.kind ?? ""))
+        return false;
     if (filter.pathPatterns?.length) {
         return filter.pathPatterns.some((p) => globMatch(p, chunk.metadata.filePath));
     }