@jmtrin/opencode-kevin 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jmtrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -26,15 +26,19 @@ injects exactly what matters back into the model's context, curates the best
 of it into files you control, and shares it across a team through one
 git-friendly file — deterministically, locally, with zero network calls.
 
-![version](https://img.shields.io/badge/version-1.0.0-blue)
+![version](https://img.shields.io/badge/version-1.1.0-blue)
 ![node](https://img.shields.io/badge/node-%E2%89%A522.5-green)
-![tests](https://img.shields.io/badge/tests-1374%20passing-brightgreen)
+![tests](https://img.shields.io/badge/tests-1380%20passing-brightgreen)
 ![deps](https://img.shields.io/badge/runtime%20deps-1-orange)
 ![network](https://img.shields.io/badge/network-zero-black)
 ![license](https://img.shields.io/badge/license-MIT-lightgrey)
 
 </div>
 
+<!-- uncomment when docs/demo.gif lands
+![demo](docs/demo.gif)
+-->
+
 > **AI agents are good at solving problems. Kevin makes sure they don't have to solve the same problem twice.**
 
 ---
@@ -44,9 +48,10 @@ git-friendly file — deterministically, locally, with zero network calls.
 - [Why Kevin](#-why-kevin)
 - [The Kevin loop](#-the-kevin-loop)
 - [Quick start](#-quick-start)
+- [What's new in 1.1.0](#-whats-new-in-110)
 - [What's new in 1.0.0](#-whats-new-in-100)
 - [How it works](#-how-it-works)
-- [The 25 tools](#-the-25-tools)
+- [The 26 tools](#-the-26-tools)
 - [The benchmark: proven, not promised](#-the-benchmark-proven-not-promised)
 - [Curation: from session noise to AGENTS.md](#-curation-from-session-noise-to-agentsmd)
 - [Team sharing: one file, zero servers](#-team-sharing-one-file-zero-servers)
@@ -136,7 +141,7 @@ npm install @jmtrin/opencode-kevin
 
 ### 2. Restart OpenCode
 
-On first boot Kevin migrates its database to schema version `011` and starts
+On first boot Kevin migrates its database to schema version `012` and starts
 observing. Nothing else is required.
 
 ### 3. Talk to it
@@ -163,6 +168,18 @@ kevin_doctor    → health report: hooks, deps, perf, verdict
 
 ---
 
+## 🆕 What's new in 1.1.0 — "Drift"
+
+> 1.1.0 protects what 1.0.0 proved: a published number without a regression gate is marketing.
+
+- 🛡️ **Continuous benchmark gate** — `npm run bench:regress` compares the last two `bench/results` against per-metric thresholds (`precision@k` >0.02, `recall` >0.05, `mrr` >0.05 on the `kevin` arm); CI fails when truth drifts.
+- 🗑️ **Lifecycle closure — `kevin_forget`** — dry-run default, `confirm:true` archives locally and publishes a tombstone through the single write path; second identical run is a `noop`.
+- ⏱️ **Millisecond timestamps** — new `_ms` columns with conservative backfill; `settle()` and `CausalChain` now decide sub-second causality.
+- 🧹 **Debt paid** — one `STOP_WORDS` source, one `readOriginCallId`, `ConflictDetector` via `mapRow`, one column-probe registry; every setting has an on-path test.
+- 📜 **Public hygiene** — `LICENSE` (MIT), `homepage` filled, `docs/DISTRIBUTION.md` checklist, `scripts/release-notes.mjs` for `gh release create`, and `<!-- demo -->` slot.
+
+---
+
 ## 🆕 What's new in 1.0.0
 
 > 1.0.0 is the **proven release**: the surface is frozen as data, the cost is
@@ -231,7 +248,7 @@ Kevin is an intentionally deterministic pipeline — no LLM in the core loop:
 
 ---
 
-## 🧰 The 25 tools
+## 🧰 The 26 tools
 
 <details open>
 <summary><b>🧠 Core memory</b></summary>
@@ -537,8 +554,8 @@ npm run replay        # replay recorded sessions deterministically
 Project layout:
 
 ```
-plugin/      51 modules — Store, MemoryService, Reflector, Perf, Contract, …
-migrations/  001 → 011 — additive, idempotent, forward-only forever
+plugin/      53 modules — Store, MemoryService, Reflector, Perf, Contract, columns, kevin_forget …
+migrations/  001 → 012 — additive, idempotent, forward-only forever
 scripts/     bench · gen-corpus · verify-pack · verify-install · …
 tests/       unit · integration · e2e · replay fixtures
 bench/       committed corpus + committed results

package/dist/migrations/001_initial.sql

@@ -1,92 +1,92 @@
--- ============================================================
--- Kevin 0.1.0 — Schema inicial
--- ============================================================
-
--- Tabla de versiones para migraciones
-CREATE TABLE IF NOT EXISTS schema_version (
-  version TEXT PRIMARY KEY,
-  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
-);
-
--- ============================================================
--- memories: lecciones aprendidas
--- ============================================================
-CREATE TABLE IF NOT EXISTS memories (
-  id TEXT PRIMARY KEY,
-  type TEXT NOT NULL CHECK(type IN ('error', 'pattern', 'decision', 'context')),
-  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
-);
-
-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);
-
--- FTS5: búsqueda full-text con remoción de diacríticos (mejor para español)
-CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
-  content,
-  content='memories',
-  tokenize='unicode61 remove_diacritics 1'
-);
-
--- Triggers para mantener FTS5 sincronizado (FTS5 external-content se indexa por rowid)
-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;
-
--- ============================================================
--- tool_calls: observación de tool calls del agente
--- ============================================================
-CREATE TABLE IF NOT EXISTS tool_calls (
-  id TEXT PRIMARY KEY,
-  session_id TEXT NOT NULL,
-  ts TEXT NOT NULL DEFAULT (datetime('now')),
-  tool TEXT NOT NULL,
-  args_summary TEXT,
-  success INTEGER NOT NULL CHECK(success IN (0,1)),
-  duration_ms INTEGER,
-  agent TEXT,
-  error_type TEXT,
-  metadata TEXT
-);
-
-CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id);
-CREATE INDEX IF NOT EXISTS idx_tool_calls_tool ON tool_calls(tool);
-CREATE INDEX IF NOT EXISTS idx_tool_calls_ts ON tool_calls(ts);
-CREATE INDEX IF NOT EXISTS idx_tool_calls_success ON tool_calls(success);
-
--- ============================================================
--- retrospectives: resúmenes de sesión
--- ============================================================
-CREATE TABLE IF NOT EXISTS retrospectives (
-  id TEXT PRIMARY KEY,
-  session_id TEXT NOT NULL,
-  ts TEXT NOT NULL DEFAULT (datetime('now')),
-  failure_count INTEGER DEFAULT 0,
-  success_count INTEGER DEFAULT 0,
-  lessons_count INTEGER DEFAULT 0,
-  file_path TEXT,
-  metadata TEXT
-);
-
--- ============================================================
--- Seed: versión inicial
--- ============================================================
+-- ============================================================
+-- Kevin 0.1.0 — Schema inicial
+-- ============================================================
+
+-- Tabla de versiones para migraciones
+CREATE TABLE IF NOT EXISTS schema_version (
+  version TEXT PRIMARY KEY,
+  applied_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+-- ============================================================
+-- memories: lecciones aprendidas
+-- ============================================================
+CREATE TABLE IF NOT EXISTS memories (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK(type IN ('error', 'pattern', 'decision', 'context')),
+  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
+);
+
+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);
+
+-- FTS5: búsqueda full-text con remoción de diacríticos (mejor para español)
+CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+  content,
+  content='memories',
+  tokenize='unicode61 remove_diacritics 1'
+);
+
+-- Triggers para mantener FTS5 sincronizado (FTS5 external-content se indexa por rowid)
+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;
+
+-- ============================================================
+-- tool_calls: observación de tool calls del agente
+-- ============================================================
+CREATE TABLE IF NOT EXISTS tool_calls (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  ts TEXT NOT NULL DEFAULT (datetime('now')),
+  tool TEXT NOT NULL,
+  args_summary TEXT,
+  success INTEGER NOT NULL CHECK(success IN (0,1)),
+  duration_ms INTEGER,
+  agent TEXT,
+  error_type TEXT,
+  metadata TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_tool_calls_session ON tool_calls(session_id);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_tool ON tool_calls(tool);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_ts ON tool_calls(ts);
+CREATE INDEX IF NOT EXISTS idx_tool_calls_success ON tool_calls(success);
+
+-- ============================================================
+-- retrospectives: resúmenes de sesión
+-- ============================================================
+CREATE TABLE IF NOT EXISTS retrospectives (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL,
+  ts TEXT NOT NULL DEFAULT (datetime('now')),
+  failure_count INTEGER DEFAULT 0,
+  success_count INTEGER DEFAULT 0,
+  lessons_count INTEGER DEFAULT 0,
+  file_path TEXT,
+  metadata TEXT
+);
+
+-- ============================================================
+-- Seed: versión inicial
+-- ============================================================
 INSERT OR IGNORE INTO schema_version (version) VALUES ('001');

package/dist/migrations/002_indexes.sql

@@ -1,14 +1,14 @@
--- ============================================================
--- Kevin 0.1.1 — Migration 002: indexes adicionales
--- ============================================================
-
--- F#29: uniqueness on retrospectives.session_id
--- Prevents duplicate retrospective rows under concurrent session.idle events.
-CREATE UNIQUE INDEX IF NOT EXISTS idx_retrospectives_session
-  ON retrospectives(session_id);
-
--- F#31: index on memories.expires_at
--- Every query/queryRelevant/loadAll filters WHERE (expires_at IS NULL OR expires_at > datetime('now')).
--- Without this index the filter is a linear scan on large tables.
-CREATE INDEX IF NOT EXISTS idx_memories_expires
+-- ============================================================
+-- Kevin 0.1.1 — Migration 002: indexes adicionales
+-- ============================================================
+
+-- F#29: uniqueness on retrospectives.session_id
+-- Prevents duplicate retrospective rows under concurrent session.idle events.
+CREATE UNIQUE INDEX IF NOT EXISTS idx_retrospectives_session
+  ON retrospectives(session_id);
+
+-- F#31: index on memories.expires_at
+-- Every query/queryRelevant/loadAll filters WHERE (expires_at IS NULL OR expires_at > datetime('now')).
+-- Without this index the filter is a linear scan on large tables.
+CREATE INDEX IF NOT EXISTS idx_memories_expires
   ON memories(expires_at);

package/dist/migrations/003_v02_signal.sql

@@ -1,58 +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.
+-- ============================================================
+-- 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');