@jmtrin/opencode-kevin 0.1.5 → 0.3.0

package/README.md

@@ -6,6 +6,7 @@ Kevin is an [OpenCode](https://opencode.ai) plugin that **observes** every agent
 
 - **Local-first**: SQLite + FTS5, no external services, no network calls.
 - **Global memory**: a single `~/.opencode-kevin/kevin.db` shared across all your projects (WAL mode → safe for concurrent sessions). No per-project folders.
+- **Knowledge + Causality (v0.3.0)**: causal failure→fix chains, `kevin_why` explanations, OKF export/import, a supersede model, and human-in-the-loop AGENTS.md suggestions.
 - **Standalone**: works without any other plugin. With the ecosystem, it learns more richly.
 
 ---
@@ -30,7 +31,7 @@ For a **single project**, put the same `plugin` array in `./opencode.json` or `.
 
 ### 2. Restart OpenCode
 
-Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, OpenCode resolves the npm spec, caches the plugin in `~/.cache/opencode/packages/@jmtrin/opencode-kevin/`, and exposes five tools: `kevin_save`, `kevin_query`, `kevin_recall`, `kevin_status`, `kevin_retrospective`.
+Config is loaded once at startup and is **not hot-reloaded** — quit and reopen OpenCode after editing. On start, OpenCode resolves the npm spec, caches the plugin in `~/.cache/opencode/packages/@jmtrin/opencode-kevin/`, and exposes nine tools: `kevin_save`, `kevin_query`, `kevin_get`, `kevin_recall`, `kevin_status`, `kevin_retrospective`, `kevin_why`, `kevin_export`, `kevin_import`.
 
 ### 3. Where data lives
 
@@ -89,32 +90,52 @@ Use `:memory:` for `dbPath` in tests.
          ▼
   ┌─────────────────┐
   │   OBSERVE        │  ToolCallObserver records every call
-  │  ToolCallObserver│  (tool, args redacted, success, duration, error_type)
+  │  ToolCallObserver│  (tool, args redacted, success, duration, error_type,
+  │                  │   id = callID) + stripPrivate + opt-in dedup (v0.2.0)
   └────────┬────────┘
-           │ on failure
-           ▼
-  ┌─────────────────┐
-  │   LEARN          │  Reflector generates a heuristic lesson
-  │   Reflector      │  redacts paths/secrets, throttled 1/min,
-  └────────┬────────┘  persists type:error memory
-           │
-           ▼
-  ┌─────────────────┐
-  │   SHARE          │  ContextInjector injects relevant lessons
-  │ ContextInjector  │  pre-prompt (1500 tokens) and on compacting (2000 tokens)
+           │ on failure             │ on success
+           ▼                        ▼
+  ┌─────────────────┐   ┌─────────────────────────┐
+  │   LEARN          │   │  CAUSAL CHAIN (v0.3.0)  │
+  │   Reflector      │   │  CausalChain.onSuccess   │
+  │  heuristic lesson │   │  links the fix to the   │
+  │  per-error-code  │   │  failure within 10 tool │
+  │  rule table      │   │  calls (error_fingerprint)
+  │  (v0.2.0 v2),    │   └───────────┬─────────────┘
+  │  per-fingerprint │               │
+  │  throttle BEFORE │               │ session.idle
+  │  LLM enrich      │               ▼
+  │  (opt-in v0.3.0),│   ┌─────────────────────────┐
+  │  stamps          │   │  CausalChain.onSessionIdle│
+  │  error_fingerprint│  │  promotes recurring errors│
+  └────────┬────────┘   │  → causal patterns (idempotent,
+           │             │   cumulative evidence)     │
+           ▼             └───────────┬───────────────┘
+  ┌─────────────────┐               │
+  │   SHARE          │◄──────────────┘
+  │ ContextInjector  │  injects relevant lessons pre-prompt
+  │                  │  (1500 tokens) + on compacting (2000)
+  │                  │  + <protect> + id: line (v0.2.0)
+  │                  │  + origin-aware rank (v0.2.0)
+  │                  │  + <kevin-suggestion> after negative
+  │                  │    feedback half (HITL, v0.3.0)
   └────────┬────────┘
            │ session.idle
            ▼
   ┌─────────────────┐
-  │  RETROSPECTIVE   │  Retrospective generates ~/.opencode-kevin/retrospectives/<session>.md
-  └─────────────────┘  with summary of failures and lessons
+  │  RETROSPECTIVE   │  generates ~/.opencode-kevin/retrospectives/<session>.md
+  │                  │  with origin labels, FP recap, metrics snapshot (v0.2.0)
+  │                  │  + boostPositiveReflectors (v0.2.0)
+  │                  │  + penalizeRecurringReflectors (v0.3.0)
+  │                  │  + PatternMiner.mine (opt-in, v0.2.0)
+  └─────────────────┘
 ```
 
 ---
 
 ## Tools
 
-Kevin exposes 5 tools callable by the agent:
+Kevin exposes 9 tools callable by the agent:
 
 ### `kevin_save`
 
@@ -125,20 +146,37 @@ kevin_save({ type: "decision", content: "We use vitest for tests", scope: "proje
 // → { "id": "0195a3b2-..." }
 ```
 
-`type`: `error` | `pattern` | `decision` | `context`. `scope`: `project` (persists) | `session` (TTL 24h).
+`type`: `error` | `pattern` | `decision` | `context` | `rule` | `solution` (v0.3.0). `scope`: `project` (persists) | `session` (TTL 24h).
+
+Saving a `decision` or `rule` with the same `fingerprint` as an existing active row supersedes the old one (v0.3.0 — `status='superseded'`, hidden from default queries).
 
 ### `kevin_query`
 
-Searches memories by text (FTS5 + bm25).
+Searches memories by text (FTS5 + bm25). Returns a **slim** payload by default (v0.2.0). Pass `full: true` for the v0.1.x full content body, or `evidence: true` (v0.3.0) to include `confidence`, `evidence_count`, `last_verified_at` in the slim payload.
 
 ```
 kevin_query({ query: "typecheck", type: "error", limit: 5 })
+// → [{ "id": "...", "type": "error", "scope": "project", "score": -0.87, "snippet": "When bash fails with typecheck:..." }, ...]
+
+kevin_query({ query: "typecheck", type: "error", limit: 5, full: true })
 // → [{ "id": "...", "type": "error", "content": "...", "scope": "project" }, ...]
 ```
 
+### `kevin_get`
+
+Fetches a **single full memory** by id (v0.2.0 — progressive disclosure). Use when `kevin_query` returns a slim snippet and you need the complete content.
+
+```
+kevin_get({ id: "0195a3b2-..." })
+// → { "id": "...", "type": "error", "content": "...", "scope": "project",
+//      "relevanceScore": 0.55, "origin": "reflector", "fingerprint": "cbf29ce484222325",
+//      "projectId": null, "metadata": null,
+//      "evidenceCount": 0, "lastVerifiedAt": null, "status": "active" }
+```
+
 ### `kevin_recall`
 
-Retrieves relevant memories (greedy fill by relevance). Without `query`, returns all memories in scope.
+Retrieves relevant memories (greedy fill by relevance). Without `query`, returns all memories in scope. Pass `includeSuperseded: true` to include superseded rows (v0.3.0).
 
 ```
 kevin_recall({ query: "auth", limit: 3 })
@@ -147,11 +185,16 @@ kevin_recall({ query: "auth", limit: 3 })
 
 ### `kevin_status`
 
-Global counts.
+Global counts and metrics. v0.2.0 adds `memories_reflector`, `memories_agent`, `memories_pattern` and a `metrics` object; v0.3.0 adds `memories_causal` and 3 more seeded counters (`patterns_causal`, `causal_links`, `memories_superseded`).
 
 ```
 kevin_status({})
-// → { "memories": 42, "tool_calls": 318, "retrospectives": 7 }
+// → { "memories": 42, "memories_reflector": 12, "memories_agent": 30, "memories_pattern": 0,
+//      "memories_causal": 1, "tool_calls": 318, "retrospectives": 7,
+//      "metrics": { "tokens_injected_pre_prompt": 51, "tokens_injected_compacting": 0,
+//                   "reflections_throttled": 3, "duplicate_suppressions": 2,
+//                   "tool_calls_deduped": 0, "patterns_mined": 0,
+//                   "patterns_causal": 1, "causal_links": 2, "memories_superseded": 0 } }
 ```
 
 ### `kevin_retrospective`
@@ -164,6 +207,26 @@ kevin_retrospective({ session_id: "sess-abc" })
 // or → { "message": "No failures in session sess-abc." }
 ```
 
+### `kevin_why` (v0.3.0)
+
+Explains *why* a failure keeps happening: looks up causal patterns for the query and builds a failure → fix trace from memories + tool_calls, including related TypeScript error-code rules.
+
+```
+kevin_why({ query: "TS2304 cannot find name" })
+// → { "summary": "TS2304 recurs because ... Confirmed by 2 fixes.",
+//      "confidence": 0.7, "evidence_count": 2, "last_verified": "2026-08-01 10:00:00",
+//      "trace": [ { "type": "error", "summary": "..." }, { "type": "fix", "tool": "bash" } ],
+//      "related_rules": [ { "code": "TS2304", "suggestion": "import or typo" } ] }
+```
+
+### `kevin_export` (v0.3.0)
+
+Exports knowledge for sharing: `decision`/`rule`/`pattern` memories (active only, no raw errors) as YAML-frontmatter blocks (`format: "okf"`) or markdown (`format: "markdown"`). Includes `id`, `type`, `confidence`, `evidence_count`, `last_verified_at`, `fingerprint`.
+
+### `kevin_import` (v0.3.0)
+
+Ingests an exported bundle. Each entry becomes a `context` memory with `origin='imported'`; a fingerprint collision with an existing `decision`/`rule` supersedes the old row. Returns `{ imported, superseded }`.
+
 ---
 
 ## Hooks
@@ -173,15 +236,15 @@ Kevin subscribes to 6 OpenCode hooks:
 | Hook | What Kevin does |
 |---|---|
 | `tool.execute.before` | Records tool call start (callID + redacted args) |
-| `tool.execute.after` | Records result; on failure → Reflector.invoke async (throttled) |
-| `experimental.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (1500 tokens) |
-| `experimental.session.compacting` | Re-injects lessons in `<kevin-memory>` after compacting (2000 tokens) |
+| `tool.execute.after` | Records result (id = callID); on failure → Reflector.invoke async (throttled); on success → CausalChain.onSuccess links the fix (v0.3.0) |
+| `experimental.chat.system.transform` | Injects relevant lessons in `<kevin-context>` (1500 tokens) + optional `<kevin-suggestion>` (v0.3.0) |
+| `experimental.session.compacting` | Re-injects lessons in `<kevin-memory>` after compacting (2000 tokens) + optional `<kevin-suggestion>` |
 | `event` (`session.created`) | Captures current `sessionID` |
-| `event` (`session.idle`) | Generates retrospective.md for the session |
+| `event` (`session.idle`) | Generates retrospective.md; boosts positive lessons (v0.2.0); penalizes recurring failures (v0.3.0); promotes causal patterns + mines patterns (opt-in); flushes metrics |
 
-**Redaction**: absolute paths (`C:\Users\...`, `/home/...`) → `<path>` and secrets (`API_KEY=`, `Bearer`, `token`) → `<redacted>` before persisting anything.
+**Redaction**: absolute paths (`C:\Users\...`, `/home/...`) → `<path>` and secrets (`API_KEY=`, `Bearer`, `token`) → `<redacted>` before persisting anything. v0.2.0 adds `<private>…</private>` block redaction: sweeps tool call args and output before persistence, replaces with `<private: redacted N chars>`.
 
-**Throttle**: Reflector generates at most 1 lesson per minute (configurable via `throttleMs`).
+**Throttle**: Reflector generates at most 1 lesson per minute per unique fingerprint (v0.2.0: per-fingerprint, not global). Configurable via `throttleMs`.
 
 **Truncation**: content > 4KB keeps the lesson searchable; only the additional context is truncated (`metadata.truncated = true`).
 
@@ -232,15 +295,27 @@ npm publish --access public
 plugin/
   index.ts              # Entry point: KevinPlugin
   Store.ts              # Wrapper SQLite (node:sqlite / bun:sqlite / better-sqlite3 fallback)
-  Migrate.ts            # Idempotent migrations
-  MemoryService.ts      # save/query/getRelevant (FTS5 + bm25)
-  ToolCallObserver.ts   # onBefore/onAfter + redact + inferErrorType
-  Reflector.ts          # Heuristic lessons + throttle + truncation
-  ContextInjector.ts    # deriveQuery + pre-prompt/compacting injection
-  Retrospective.ts      # Generates retrospective.md + table insert
+  Migrate.ts            # Idempotent migrations + post-apply hooks
+  MemoryService.ts      # save/query/getRelevant (FTS5 + bm25 + origin-aware rank + supersede)
+  ToolCallObserver.ts   # onBefore/onAfter + redact + inferErrorType + dedup (opt-in)
+  Reflector.ts          # Heuristic lessons + per-fingerprint throttle + lesson v2 + LLM enrich
+  CausalChain.ts        # v0.3.0 — links fixes to failures + promotes causal patterns
+  ContextInjector.ts    # deriveQuery + pre-prompt/compacting injection + <kevin-suggestion>
+  Retrospective.ts      # Generates retrospective.md + FP recap + metrics snapshot
+  fingerprint.ts        # FNV-1a 64-bit (in-house, no node:crypto)
+  metrics.ts            # In-memory counters + debounced flush to kevin_metrics
+  PatternMiner.ts       # Opt-in deterministic 2-gram/3-gram miner
+  kevin_why.ts          # v0.3.0 — kevin_why tool: failure→fix traces + related rules
+  okf-export.ts         # v0.3.0 — kevin_export: OKF/markdown export
+  okf-import.ts         # v0.3.0 — kevin_import: bundle parser + import
+  memory-format.ts      # escapeInjectedText, formatMemories, <protect> + id: line wrappers
+  redact.ts             # redactPaths + stripPrivate
+  uuid.ts               # UUIDv7
 migrations/
   001_initial.sql       # schema: memories, tool_calls, retrospectives
   002_indexes.sql       # FTS5 + indexes
+  003_v02_signal.sql    # v0.2.0 Signal Quality: fingerprint, origin, metrics, dedup indexes
+  004_v03_knowledge.sql # v0.3.0 Knowledge + Causality: evidence/status/supersede, error_fingerprint
 tests/{unit,integration,e2e}/
 scripts/
   copy-migrations.mjs   # build step: copies *.sql to dist/migrations

package/dist/migrations/003_v02_signal.sql

@@ -0,0 +1,58 @@
+-- ============================================================
+-- Kevin 0.2.0 — Migration 003: Signal Quality (additive)
+-- ============================================================
+-- Backward-compatible, additive only. All new columns are
+-- nullable or carry a NOT NULL DEFAULT so legacy rows keep
+-- working without a destructive rebuild. The partial UNIQUE
+-- index excludes NULL fingerprints so legacy error memories
+-- do not collide. The schema_version table (created by 001)
+-- guarantees this file runs at most once per DB.
+-- ============================================================
+
+-- 1. memories: Signal Quality columns.
+--    project_id — first-class scoping dimension (D2-11).
+--    fingerprint — stable hash of normalized error content, salted by project_id (D2-14).
+--    origin — distinguishes reflector-sourced vs agent-sourced memories (D2-06),
+--             with a CHECK enum and DEFAULT 'agent' so legacy rows backfill cleanly.
+ALTER TABLE memories ADD COLUMN project_id  TEXT;
+ALTER TABLE memories ADD COLUMN fingerprint TEXT;
+ALTER TABLE memories ADD COLUMN origin      TEXT NOT NULL DEFAULT 'agent'
+  CHECK(origin IN ('reflector', 'agent', 'pattern', 'retrospective'));
+
+-- 2. tool_calls: same scoping/fingerprint columns for dedup and PatternMiner.
+ALTER TABLE tool_calls ADD COLUMN project_id  TEXT;
+ALTER TABLE tool_calls ADD COLUMN fingerprint TEXT;
+
+-- 3. Partial UNIQUE: one reflector-sourced error memory per (project_id, fingerprint).
+--    NULL fingerprints are excluded (no dedup for non-error memories or legacy rows).
+CREATE UNIQUE INDEX IF NOT EXISTS uq_memories_error_fp
+  ON memories (project_id, fingerprint)
+  WHERE type = 'error' AND fingerprint IS NOT NULL AND origin = 'reflector';
+
+-- 4. kevin_metrics: seeded counters surfaced by kevin_status (D2-07 / K2-004).
+CREATE TABLE IF NOT EXISTS kevin_metrics (
+  key        TEXT PRIMARY KEY,
+  value      INTEGER NOT NULL DEFAULT 0,
+  updated_at TEXT    NOT NULL DEFAULT (datetime('now'))
+);
+
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+  ('tokens_injected_pre_prompt', 0),
+  ('tokens_injected_compacting',  0),
+  ('reflections_throttled',       0),
+  ('duplicate_suppressions',      0),
+  ('tool_calls_deduped',          0),
+  ('patterns_mined',              0);
+
+-- 5. kevin_settings: opt-in feature flags (PatternMiner off, tool_calls dedup off).
+CREATE TABLE IF NOT EXISTS kevin_settings (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+  ('patternminer_enabled',     '0'),
+  ('tool_calls_dedup_enabled', '0');
+
+-- 6. Seed version 003.
+INSERT OR IGNORE INTO schema_version (version) VALUES ('003');

package/dist/migrations/004_v03_knowledge.sql

@@ -0,0 +1,138 @@
+-- ============================================================
+-- Kevin 0.3.0 — Migration 004: Knowledge + Causality (additive)
+-- ============================================================
+-- Backward-compatible, additive only. All new columns are
+-- nullable or carry a NOT NULL DEFAULT so legacy rows keep
+-- working without a destructive rebuild.
+-- ============================================================
+
+-- 1. memories: evidence + lifecycle columns.
+--    evidence_count — how many times this fingerprint was confirmed as fixed.
+--    last_verified_at — timestamp of the most recent causal confirmation.
+--    status — lifecycle state; default 'active'. Superseded rows are hidden.
+ALTER TABLE memories ADD COLUMN evidence_count INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE memories ADD COLUMN last_verified_at TEXT;
+ALTER TABLE memories ADD COLUMN status TEXT NOT NULL DEFAULT 'active'
+  CHECK (status IN ('active', 'superseded', 'stale', 'archived'));
+
+-- 2. tool_calls: causal link + feedback-loop link columns.
+--    fix_for_fingerprint — set when this successful call resolved a prior failure
+--    with the given fingerprint. NULL for tool calls that were not fixes.
+--    error_fingerprint — set by Reflector (via onLinkError callback) when a call
+--    FAILS, to the stderr-based fingerprint the matching error memory uses.
+--    This fixes the v0.2.0/v0.3.0 feedback-loop fingerprint mismatch bug:
+--    tool_calls.fingerprint is hashed from "tool|args|success" by ToolCallObserver,
+--    while memories.fingerprint is hashed from stderr text by Reflector — they
+--    never agreed, so boost/penalize queries silently mismatched. The new column
+--    stores the SAME identity dimension the error memory uses.
+ALTER TABLE tool_calls ADD COLUMN fix_for_fingerprint TEXT;
+ALTER TABLE tool_calls ADD COLUMN error_fingerprint TEXT;
+
+-- 3. Index: causal linkage by fingerprint. Used by CausalChain.onSuccess
+--    and kevin_why to materialize traces.
+CREATE INDEX IF NOT EXISTS idx_tool_calls_fix_fp
+  ON tool_calls(fix_for_fingerprint)
+  WHERE fix_for_fingerprint IS NOT NULL;
+
+-- 3b. Index: feedback-loop linkage by error_fingerprint. Used by
+--     boostPositiveReflectors / penalizeRecurringReflectors to count
+--     recurrences by the same identity dimension the error memory uses.
+CREATE INDEX IF NOT EXISTS idx_tool_calls_error_fp
+  ON tool_calls(error_fingerprint)
+  WHERE error_fingerprint IS NOT NULL;
+
+-- 4. Index: memories by fingerprint for promotion + supersede queries.
+CREATE INDEX IF NOT EXISTS idx_memories_fp
+  ON memories(fingerprint)
+  WHERE fingerprint IS NOT NULL;
+
+-- 5. kevin_metrics: seed new v0.3 counters.
+INSERT OR IGNORE INTO kevin_metrics (key, value) VALUES
+  ('patterns_causal',     0),
+  ('causal_links',        0),
+  ('memories_superseded', 0);
+
+-- 6. kevin_settings: seed new opt-in flags.
+INSERT OR IGNORE INTO kevin_settings (key, value) VALUES
+  ('llm_reflection_enabled', '0'),
+  ('cross_project_enabled',  '0');
+
+-- 7. Seed version 004.
+INSERT OR IGNORE INTO schema_version (version) VALUES ('004');
+
+-- ============================================================
+-- 8. Rebuild memories table with expanded CHECK constraints.
+--    v0.3.0 introduces new types (rule, solution) and origins
+--    (causal, imported). SQLite cannot ALTER a CHECK constraint,
+--    so we rebuild via a temporary table. FTS5 external-content
+--    table references the content table by name, so we drop+recreate
+--    the FTS5 triggers after the rebuild.
+-- ============================================================
+
+-- Step 1: Create new table with correct constraints
+CREATE TABLE memories_v04 (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK(type IN ('error','pattern','decision','context','rule','solution')),
+  content TEXT NOT NULL,
+  scope TEXT NOT NULL DEFAULT 'project' CHECK(scope IN ('project','session')),
+  relevance_score REAL DEFAULT 0.5,
+  source_tool TEXT,
+  source_session TEXT,
+  metadata TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  expires_at TEXT,
+  project_id TEXT,
+  fingerprint TEXT,
+  origin TEXT NOT NULL DEFAULT 'agent'
+    CHECK(origin IN ('reflector','agent','pattern','retrospective','causal','imported')),
+  evidence_count INTEGER NOT NULL DEFAULT 0,
+  last_verified_at TEXT,
+  status TEXT NOT NULL DEFAULT 'active'
+    CHECK(status IN ('active','superseded','stale','archived'))
+);
+
+-- Step 2: Copy data preserving rowids (FTS5 content sync relies on rowid)
+INSERT INTO memories_v04
+  (rowid, id, type, content, scope, relevance_score, source_tool,
+   source_session, metadata, created_at, updated_at, expires_at,
+   project_id, fingerprint, origin, evidence_count, last_verified_at, status)
+  SELECT rowid, id, type, content, scope, relevance_score, source_tool,
+         source_session, metadata, created_at, updated_at, expires_at,
+         project_id, fingerprint, origin, evidence_count, last_verified_at, status
+  FROM memories;
+
+-- Step 3: Drop old table and FTS triggers
+DROP TRIGGER IF EXISTS memories_ai;
+DROP TRIGGER IF EXISTS memories_ad;
+DROP TRIGGER IF EXISTS memories_au;
+DROP TABLE memories;
+
+-- Step 4: Rename new table
+ALTER TABLE memories_v04 RENAME TO memories;
+
+-- Step 5: Recreate FTS triggers (memories_fts is content=external, survives DROP of content table)
+CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+  INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.rowid, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+  INSERT INTO memories_fts(memories_fts, rowid, content) VALUES ('delete', old.rowid, old.content);
+  INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
+END;
+
+-- Step 6: Recreate indexes
+CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
+CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope);
+CREATE INDEX IF NOT EXISTS idx_memories_relevance ON memories(relevance_score DESC);
+CREATE INDEX IF NOT EXISTS idx_memories_created ON memories(created_at);
+CREATE UNIQUE INDEX IF NOT EXISTS uq_memories_error_fp
+  ON memories(project_id, fingerprint)
+  WHERE type = 'error' AND fingerprint IS NOT NULL AND origin = 'reflector';
+CREATE INDEX IF NOT EXISTS idx_memories_fp
+  ON memories(fingerprint)
+  WHERE fingerprint IS NOT NULL;

package/dist/plugin/CausalChain.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryService } from "./MemoryService.js";
+import type { Store } from "./Store.js";
+import type { Metrics } from "./metrics.js";
+export declare class CausalChain {
+    private store;
+    private memoryService;
+    private metrics;
+    constructor(store: Store, memoryService: MemoryService, metrics: Metrics | null);
+    onSuccess(_tool: string, _args: Record<string, unknown>, _projectId: string | null, sessionId: string): void;
+    onSessionIdle(sessionId: string): number;
+}

package/dist/plugin/CausalChain.js

@@ -0,0 +1,109 @@
+/** K3-007 — a success only links to a failure within this many calls. */
+const MAX_LINK_DISTANCE = 10;
+export class CausalChain {
+    store;
+    memoryService;
+    metrics;
+    constructor(store, memoryService, metrics) {
+        this.store = store;
+        this.memoryService = memoryService;
+        this.metrics = metrics;
+    }
+    // K3-007: link a success to the failing fingerprint only when it
+    // occurred within MAX_LINK_DISTANCE tool calls of the failure (plan
+    // §K3-007 acceptance: "within 24h and within 10 tool calls").
+    // v0.3.0 fix (bug #3) — the old code linked the most recent session
+    // success to the most recent unlinked error memory regardless of
+    // distance, so an unrelated success (e.g. an `ls` run after a
+    // typecheck failure) was stamped as the fix for that error.
+    onSuccess(_tool, _args, _projectId, sessionId) {
+        const successRow = this.store
+            .prepare(`SELECT rowid FROM tool_calls
+				 WHERE session_id = ? AND success = 1
+				 ORDER BY rowid DESC LIMIT 1`)
+            .get(sessionId);
+        if (!successRow)
+            return;
+        const linkedFps = new Set(this.store
+            .prepare(`SELECT DISTINCT fix_for_fingerprint FROM tool_calls
+						 WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL`)
+            .all(sessionId).map((r) => r.fix_for_fingerprint));
+        // Most recent failing calls in this session, newest first. The
+        // failing call's `error_fingerprint` (stamped by Reflector via
+        // onLinkError) is the SAME identity dimension the error memory
+        // uses; `fingerprint` is the legacy tool|args|success hash and
+        // simply never matches a reflector error memory.
+        const failRows = this.store
+            .prepare(`SELECT rowid, COALESCE(error_fingerprint, fingerprint) AS fp
+				 FROM tool_calls
+				 WHERE session_id = ?
+				   AND success = 0
+				   AND (error_fingerprint IS NOT NULL OR fingerprint IS NOT NULL)
+				 ORDER BY rowid DESC LIMIT ?`)
+            .all(sessionId, MAX_LINK_DISTANCE);
+        for (const fail of failRows) {
+            if (!fail.fp || linkedFps.has(fail.fp))
+                continue;
+            const dist = successRow.rowid - fail.rowid;
+            if (dist <= 0 || dist > MAX_LINK_DISTANCE)
+                continue;
+            const mem = this.store
+                .prepare(`SELECT 1 FROM memories
+					 WHERE fingerprint = ? AND type = 'error'
+					   AND origin = 'reflector' AND status = 'active'
+					   AND created_at > datetime('now', '-24 hours')
+					 LIMIT 1`)
+                .get(fail.fp);
+            if (!mem)
+                continue;
+            this.store
+                .prepare("UPDATE tool_calls SET fix_for_fingerprint = ? WHERE rowid = ?")
+                .run(fail.fp, successRow.rowid);
+            this.metrics?.incr("causal_links", 1);
+            return;
+        }
+    }
+    onSessionIdle(sessionId) {
+        const linkedErrors = this.store
+            .prepare(`SELECT m.id, m.fingerprint,
+				        (SELECT COUNT(*)
+				         FROM tool_calls tc_all
+				         WHERE tc_all.fix_for_fingerprint = m.fingerprint) as evidence_count
+				 FROM memories m
+				 WHERE m.type = 'error'
+				   AND m.origin = 'reflector'
+				   AND m.fingerprint IN (
+				       SELECT DISTINCT fix_for_fingerprint
+				       FROM tool_calls
+				       WHERE session_id = ? AND fix_for_fingerprint IS NOT NULL
+				   )
+				   AND m.status = 'active'
+				 GROUP BY m.fingerprint
+				 HAVING (
+				     SELECT MAX(tc.rowid) FROM tool_calls tc
+				     WHERE tc.fix_for_fingerprint = m.fingerprint
+				 ) > COALESCE(
+				     (SELECT MAX(m2.rowid) FROM memories m2
+				      WHERE m2.fingerprint = m.fingerprint
+				        AND m2.type = 'pattern'
+				        AND m2.origin = 'causal'),
+				     0
+				 )`)
+            .all(sessionId);
+        let promoted = 0;
+        for (const err of linkedErrors) {
+            try {
+                const id = this.memoryService.promoteToPattern(err.id, err.evidence_count);
+                if (id) {
+                    promoted++;
+                    this.metrics?.incr("patterns_causal", 1);
+                }
+            }
+            catch {
+                // promoteToPattern may fail if the error memory was removed
+            }
+        }
+        return promoted;
+    }
+}
+//# sourceMappingURL=CausalChain.js.map

package/dist/plugin/CausalChain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CausalChain.js","sourceRoot":"","sources":["../../plugin/CausalChain.ts"],"names":[],"mappings":"AAIA,yEAAyE;AACzE,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAE7B,MAAM,OAAO,WAAW;IAEd;IACA;IACA;IAHT,YACS,KAAY,EACZ,aAA4B,EAC5B,OAAuB;QAFvB,UAAK,GAAL,KAAK,CAAO;QACZ,kBAAa,GAAb,aAAa,CAAe;QAC5B,YAAO,GAAP,OAAO,CAAgB;IAC7B,CAAC;IAEJ,iEAAiE;IACjE,oEAAoE;IACpE,8DAA8D;IAC9D,oEAAoE;IACpE,iEAAiE;IACjE,8DAA8D;IAC9D,4DAA4D;IAC5D,SAAS,CACR,KAAa,EACb,KAA8B,EAC9B,UAAyB,EACzB,SAAiB;QAEjB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK;aAC3B,OAAO,CACP;;iCAE6B,CAC7B;aACA,GAAG,CAAC,SAAS,CAAkC,CAAC;QAClD,IAAI,CAAC,UAAU;YAAE,OAAO;QAExB,MAAM,SAAS,GAAG,IAAI,GAAG,CAEvB,IAAI,CAAC,KAAK;aACR,OAAO,CACP;gEAC0D,CAC1D;aACA,GAAG,CAAC,SAAS,CACf,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CACnC,CAAC;QAEF,+DAA+D;QAC/D,+DAA+D;QAC/D,+DAA+D;QAC/D,+DAA+D;QAC/D,iDAAiD;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK;aACzB,OAAO,CACP;;;;;iCAK6B,CAC7B;aACA,GAAG,CAAC,SAAS,EAAE,iBAAiB,CAG/B,CAAC;QAEJ,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBAAE,SAAS;YACjD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;YAC3C,IAAI,IAAI,IAAI,CAAC,IAAI,IAAI,GAAG,iBAAiB;gBAAE,SAAS;YAEpD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK;iBACpB,OAAO,CACP;;;;cAIS,CACT;iBACA,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACf,IAAI,CAAC,GAAG;gBAAE,SAAS;YAEnB,IAAI,CAAC,KAAK;iBACR,OAAO,CACP,+DAA+D,CAC/D;iBACA,GAAG,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC;YACjC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC;YACtC,OAAO;QACR,CAAC;IACF,CAAC;IAED,aAAa,CAAC,SAAiB;QAC9B,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK;aAC7B,OAAO,CACP;;;;;;;;;;;;;;;;;;;;;;;OAuBG,CACH;aACA,GAAG,CAAC,SAAS,CAIZ,CAAC;QAEJ,IAAI,QAAQ,GAAG,CAAC,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAChC,IAAI,CAAC;gBACJ,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,gBAAgB,CAC7C,GAAG,CAAC,EAAE,EACN,GAAG,CAAC,cAAc,CAClB,CAAC;gBACF,IAAI,EAAE,EAAE,CAAC;oBACR,QAAQ,EAAE,CAAC;oBACX,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;gBAC1C,CAAC;YACF,CAAC;YAAC,MAAM,CAAC;gBACR,4DAA4D;YAC7D,CAAC;QACF,CAAC;QAED,OAAO,QAAQ,CAAC;IACjB,CAAC;CACD"}

package/dist/plugin/ContextInjector.d.ts

@@ -1,4 +1,5 @@
 import type { MemoryService } from "./MemoryService.js";
+import { type Metrics } from "./metrics.js";
 export interface ChatMessage {
     role: string;
     content: string;
@@ -19,7 +20,30 @@ export interface CompactingOutput {
 }
 export declare class ContextInjector {
     private memoryService;
-    constructor(memoryService: MemoryService);
+    private metrics;
+    private lastRecurrenceCount;
+    constructor(memoryService: MemoryService, metrics?: Metrics | null);
+    /**
+     * v0.3.0 (K3-020) — notify the injector that the negative feedback half
+     * fired N times in the last session.idle. The next system.transform or
+     * compacting hook will prepend a HITL suggestion block.
+     */
+    setRecurrences(count: number): void;
+    /**
+     * v0.3.0 (K3-020) — generate a HITL suggestion block when recurrences
+     * occurred. Returns the block or empty string. Resets the counter.
+     */
+    generateSuggestion(): string;
+    /**
+     * v0.2.0 (K2-024): origin-aware ranking at injection time is delegated
+     * to `MemoryService.getRelevant()` (K2-023, D2-13). The injector does
+     * NOT re-rank on its own — it consumes the already-ranked slice and
+     * applies the conditional-budget guard for opt-out (`protect: false`)
+     * callers. Plan §B6.5: "apply the same multiplier as
+     * MemoryService.recall so reflector lessons outrank agent-saved notes
+     * at injection time" — satisfied transitively via the getRelevant call.
+     */
+    private inject;
     deriveQuery(messages: ChatMessage[]): string;
     onSystemTransform(input: SystemTransformInput, output: SystemTransformOutput): void;
     onCompacting(input: CompactingInput, output: CompactingOutput): void;