claude_memory 0.7.1 → 0.9.0

data/.claude-plugin/commands/memory-recall.md

@@ -0,0 +1,67 @@
+# Memory Recall Agent
+
+Search long-term memory for facts, decisions, conventions, and architectural knowledge. Chains multiple memory tools to build comprehensive answers while saving main-agent context.
+
+## Usage
+
+Provide a natural language query describing what you want to recall:
+
+```
+/memory-recall database migration strategy
+/memory-recall authentication decisions
+/memory-recall testing conventions
+```
+
+## Workflow
+
+1. **Fast lookup** — Start with `memory.recall` for keyword matches
+2. **Semantic search** — If recall returns few results, try `memory.recall_semantic` for conceptual matches
+3. **Shortcuts** — For known categories, use `memory.decisions`, `memory.conventions`, or `memory.architecture`
+4. **Deep dive** — For specific facts, use `memory.explain` to get provenance and `memory.fact_graph` to see relationships
+5. **Synthesize** — Combine findings into a concise, structured answer
+
+## Instructions
+
+You are a memory recall specialist. Given a query, search ClaudeMemory using the available MCP tools and return a synthesized answer.
+
+### Step 1: Initial Search
+
+Run `memory.recall` with the user's query. If the query mentions decisions, conventions, or architecture, also run the appropriate shortcut tool in parallel.
+
+### Step 2: Expand if Needed
+
+If Step 1 returns fewer than 3 results:
+- Try `memory.recall_semantic` with a rephrased version of the query
+- Try `memory.search_concepts` with 2-3 key concepts extracted from the query
+
+### Step 3: Enrich Key Facts
+
+For the top 2-3 most relevant facts:
+- Run `memory.explain` to get provenance (where the fact came from)
+- If relationships matter, run `memory.fact_graph` to see connected facts
+
+### Step 4: Synthesize
+
+Return a structured response:
+
+```
+## Memory Recall Results
+
+### Key Facts
+- [Fact 1 with provenance]
+- [Fact 2 with provenance]
+
+### Context
+[How these facts relate to the query]
+
+### Confidence
+[High/Medium/Low based on number and freshness of supporting facts]
+```
+
+### Guidelines
+
+- Prefer `memory.recall` (fast, token-efficient) before escalating to semantic search
+- Use `compact: true` on all tool calls to minimize token usage
+- Do NOT fabricate facts — only report what memory tools return
+- If no relevant facts found, say so clearly rather than guessing
+- Include fact IDs so the main agent can reference them

data/.claude-plugin/marketplace.json

@@ -7,9 +7,9 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.7.1",
+      "version": "0.9.0",
       "source": "./",
-      "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
+      "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
       "repository": "https://github.com/codenamev/claude_memory"
     }
   ]

data/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-memory",
-  "version": "0.7.1",
-  "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
+  "version": "0.9.0",
+  "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
   "author": {
     "name": "Valentino Stoll",
     "email": "v@codenamev.com"
@@ -9,7 +9,7 @@
   "homepage": "https://github.com/codenamev/claude_memory",
   "repository": "https://github.com/codenamev/claude_memory",
   "license": "MIT",
-  "keywords": ["memory", "facts", "knowledge", "persistence", "long-term-memory"],
+  "keywords": ["memory", "architecture", "conventions", "decisions", "recall", "preferences", "long-term-memory"],
   "mcpServers": {
     "memory": {
       "command": "${CLAUDE_PLUGIN_ROOT}/scripts/serve-mcp.sh",

data/.claude-plugin/scripts/hook-runner.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Generic hook delegate for claude-memory.
+# Used by the Claude Code plugin to run hook subcommands.
+# Usage: hook-runner.sh <subcommand> [args...]
+# Exit 0 on missing binary to avoid blocking Claude Code.
+
+set -uo pipefail
+
+if command -v claude-memory > /dev/null 2>&1; then
+  exec claude-memory hook "$@"
+else
+  echo "claude-memory gem not found. Install with: gem install claude_memory" >&2
+  exit 0
+fi

data/.claude-plugin/scripts/serve-mcp.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Wrapper script for claude-memory MCP server.
+# Used by the Claude Code plugin to launch the MCP server.
+# Falls back to a JSON-RPC error if the gem is not installed.
+
+set -euo pipefail
+
+if command -v claude-memory > /dev/null 2>&1; then
+  exec claude-memory serve-mcp
+else
+  # Return a JSON-RPC error so Claude Code surfaces it to the user
+  echo '{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"claude-memory gem not found. Install with: gem install claude_memory"}}'
+  exit 1
+fi

data/.ruby-version

@@ -1 +1 @@
-4.0.1
+4.0.2

data/CHANGELOG.md

@@ -4,6 +4,95 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-04-16
+
+### Added
+
+- `claude-memory reject <id_or_docid>` command + `memory.reject_fact` MCP tool — explicitly mark distiller hallucinations as wrong, closing associated conflicts
+- `claude-memory restore --predicate NAME` command — recover facts that were superseded by obsolete single-value predicate classifications (uses Jaccard-based token overlap to distinguish bug-caused supersession from real corrections)
+- MCP tool-call telemetry: `mcp_tool_calls` table records every tool invocation with timing, result counts, and error classification. `claude-memory stats --tools [--since DAYS]` for usage reporting. 90-day retention via Sweep
+- `CLAUDE_CONFIG_DIR` env var support for non-standard Claude Code config locations
+- Predicate synonym canonicalization at insert time (`has_convention` → `convention`, `primary_language` → `uses_language`). Prevents drift from fragmenting the knowledge graph
+- Novel predicate warnings at insert time — logged when the Resolver encounters a predicate not in PredicatePolicy
+- NullDistiller now emits `uses_language` facts for detected language entities
+- Proactive memory recall guidance in MCP instructions — Claude now checks conventions before code generation, architecture before explanations, decisions before refactoring
+- YARD documentation across 13 core source files (+473 lines)
+
+### Changed
+
+- **`uses_framework` reclassified as multi-value** — real projects use multiple frameworks (Rails + Turbo + Tailwind). The prior single-value classification silently superseded valid facts in production databases. Run `claude-memory restore --predicate uses_framework` to recover affected facts
+- `PredicatePolicy` is now the single source of truth for predicate vocabulary, snapshot section mapping, synonym canonicalization, and LLM guidance. `tool_definitions.rb`, `publish.rb`, and `distill-transcripts.md` all derive from the policy
+- Predicate vocabulary curated from 13 → 8 based on multi-project usage data. Removed predicates (`preference`, `workflow`, `dependency`, `testing_strategy`, `tool_usage`, `ci_platform`, `primary_language`) had zero facts across all surveyed databases. They still work via DEFAULT_POLICY but are no longer advertised to the LLM
+- `Registry::COMMANDS` stores `{class:, description:}` entries with direct class references instead of string class names
+- Plugin and gem descriptions rewritten from mechanism-focused to outcome-focused
+
+### Fixed
+
+- **`StatsCommand` broken in production** — used `Sequel.sqlite` which requires the unlisted `sqlite3` gem. Now uses the extralite adapter consistently
+- Missing `embeddings` command in shell completion output
+
+### Upgrade Notes
+
+**Schema**: v12 → v14 (two automatic migrations). Migration 013 adds `mcp_tool_calls` table. Migration 014 canonicalizes stale predicate names (`has_convention` → `convention`, `primary_language` → `uses_language`) in existing facts.
+
+**Action required for `uses_framework` recovery**: If your project uses multiple frameworks (Rails + Turbo + Tailwind, etc.), past sessions may have superseded valid facts. After upgrading, run:
+
+```bash
+claude-memory restore --predicate uses_framework --dry-run   # preview
+claude-memory restore --predicate uses_framework              # restore
+claude-memory restore --predicate uses_framework --scope global  # if needed for global DB
+```
+
+**Pruned predicates still work**: `preference`, `workflow`, `dependency`, `testing_strategy`, `tool_usage`, `ci_platform` fall through to the default multi-value policy. Existing facts with these predicates are unaffected. They'll appear as "novel" in `memory.stats` but function normally.
+
+## [0.8.0] - 2026-03-30
+
+### Added
+
+**Three-Layer Distillation Pipeline**
+- Automatic distillation via NullDistiller in ingest pipeline (Layer 1: regex-based, P95 < 5ms)
+- Context hook injection for LLM-based extraction at SessionStart (Layer 2: Claude Code as distiller, zero extra cost)
+- `/distill-transcripts` skill for manual deep extraction (Layer 3: on-demand, depth-aware prompts)
+- `memory.undistilled` and `memory.mark_distilled` MCP tools for distillation tracking
+- `Hook::DistillationRunner` extracted from Handler for context hook injection
+- `TaskCompleted` and `TeammateIdle` hook events for ingest triggers
+- Distillation metrics backfill on database initialization
+- Doctor check for undistilled content
+- Pending distillation count in `memory.status` output
+
+**Recall Enhancements**
+- Intent parameter for recall query disambiguation (#3)
+- Retrieval score traces for semantic search (#5)
+- Configurable embedding providers with dimension checking
+
+**Hook Enhancements**
+- `statusMessage` on all hooks for descriptive spinner text during hook execution
+- `StopFailure` hook to capture transcript data even on session errors (rate limits, server errors)
+- `Notification` hook with `idle_prompt` matcher for opportunistic sweep during idle
+
+**New Commands & Skills**
+- `install-skill` command and `memory-recall` agent (#8, #12)
+- Shell completion command for bash and zsh (#18)
+
+**Distillation Benchmark Results**
+- NullDistiller: Concept Recall 0.952, Fact Precision/Recall 1.000 (31 test cases)
+- Claude Code LLM: Concept Recall 0.902 (all 41 cases), 0.900 on semantic cases (vs 0.333 for regex)
+- Average 1.6 facts stored per case across LLM extraction
+- E2E distillation recall benchmark and extraction quality benchmarks
+- Concept-based matching for distiller-agnostic benchmark comparison
+
+### Fixed
+
+- `--allowedTools` added to `ClaudeCliRunner` for MCP tool permissions
+- Test isolation for context hook when global database has facts
+
+### Internal
+- Extracted `RetryHandler` and `SchemaManager` modules from `SQLiteStore`
+- Extracted `Recall` into engine strategy pattern with `DualEngine`, `LegacyEngine`, and shared `QueryCore`
+- Extracted `Tools` god object into 6 handler modules
+- Added 36 specs for 5 previously untested files
+- All 3 god objects eliminated, 0 files over 500 lines
+
 ## [0.7.1] - 2026-03-17
 
 ### Added
@@ -45,7 +134,7 @@ All notable changes to this project will be documented in this file.
 - Opt-out: set `CLAUDE_MEMORY_ISOLATE_WORKTREES=1` for per-worktree isolation
 
 **MCP Enhancements**
-- Tool annotations: `readOnlyHint`, `idempotentHint`, `destructiveHint` on all 21 tools
+- Tool annotations: `readOnlyHint`, `idempotentHint`, `destructiveHint` on all 23 tools
 - Stdout protection: MCP server redirects `$stdout` to `$stderr` to prevent protocol corruption from accidental `puts`/`print` calls
 - Self-excluding agent conversations via `SELF_CONTEXT_MARKER` to prevent meta-pollution
 

data/CLAUDE.md

@@ -15,6 +15,12 @@ ClaudeMemory is a Ruby gem that provides long-term, self-managed memory for Clau
 
 **Check memory before exploring code.** Use `memory.recall`, `memory.decisions`, `memory.architecture`, or `memory.conventions` to find existing knowledge before reading files.
 
+### Git Usage & Best Practices
+
+- Before each commit, apply the quality-review skill
+- Iteratively commit related changes with their tests
+
+
 ## Development Commands
 
 ### Setup
@@ -99,6 +105,18 @@ bin/run-evals --comparative        # Run benchmarks with available tools
 bin/run-evals --comparative --setup-competitors  # Install + run in one step
 ```
 
+### Distillation Extraction Accuracy
+
+NullDistiller (regex, Layer 1):
+  - Concept Recall: 0.952 (regex-detectable entities/facts)
+  - Fact Precision: 1.000, Fact Recall: 1.000 (on 31 test cases)
+  - Pipeline latency: P95 < 5ms (medium text)
+
+Claude Code (LLM, Layers 2+3):
+  - Concept Recall: 0.902 (all 41 cases)
+  - Concept Recall on semantic cases: 0.900 (vs NullDistiller's 0.333)
+  - Avg facts stored per case: 1.6
+
 ## Architecture
 
 ### Dual-Database System
@@ -123,6 +141,16 @@ Transcripts → Ingest → Index (FTS5)
              Publish → .claude/rules/claude_memory.generated.md
 ```
 
+### Three-Layer Distillation
+
+The distillation pipeline operates at three levels of depth:
+
+- **Layer 1: NullDistiller** (automatic, regex, free) — Runs in the ingest pipeline on every hook event. Extracts entities, facts, and scope hints using pattern matching. P95 latency < 5ms.
+- **Layer 2: Context Hook Injection** (automatic, LLM, zero extra cost) — At SessionStart, undistilled content is injected into the session via `hookSpecificOutput.additionalContext` with extraction instructions. Claude Code itself acts as the distiller, extracting structured facts at no additional API cost.
+- **Layer 3: `/distill-transcripts` Skill** (manual, on-demand) — Deep extraction triggered by the user. Processes undistilled content with depth-aware prompts (initial extraction, consolidation, contradiction resolution).
+
+New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipeline by tracking which content items have been deeply distilled.
+
 ### Module Structure
 
 #### Application Layer
@@ -135,7 +163,7 @@ Transcripts → Ingest → Index (FTS5)
   - Each command is a separate class (HelpCommand, DoctorCommand, etc.)
   - All commands inherit from BaseCommand
   - Dependency injection for I/O (stdout, stderr, stdin)
-  - 22 commands total, each focused on single responsibility
+  - 28 commands total, each focused on single responsibility
 
 - **`Configuration`**: Centralized ENV access (`configuration.rb`)
   - Single source of truth for paths and environment variables
@@ -144,7 +172,7 @@ Transcripts → Ingest → Index (FTS5)
 #### Core Domain Layer
 
 - **`Domain`**: Rich domain models with business logic (`domain/`)
-  - `Fact`: Facts with validation, status checking (active?, superseded?)
+  - `Fact`: Facts with validation, status checking (active?, superseded?, rejected?)
   - `Entity`: Entities with type checking (database?, framework?)
   - `Provenance`: Evidence with strength checking (stated?, inferred?)
   - `Conflict`: Conflicts with status tracking (open?, resolved?)
@@ -160,7 +188,7 @@ Transcripts → Ingest → Index (FTS5)
 - **`Store`**: SQLite database access via Sequel (`store/`)
   - `SQLiteStore`: Database operations
   - `StoreManager`: Dual-database connection manager
-  - Schema includes: content_items, entities, facts, provenance, fact_links, conflicts
+  - Schema includes: content_items, entities, facts, provenance, fact_links, conflicts, mcp_tool_calls
   - Transaction safety for multi-step operations
 
 - **`Infrastructure`**: I/O abstractions (`infrastructure/`)
@@ -183,7 +211,7 @@ Transcripts → Ingest → Index (FTS5)
 
 - **`Resolve`**: Truth maintenance and conflict resolution (`resolve/`)
   - Determines equivalence, supersession, or conflicts
-  - PredicatePolicy controls single-value vs multi-value predicates
+  - PredicatePolicy: single source of truth for predicate vocabulary, cardinality, section mapping, and synonym canonicalization
   - Transaction safety for atomic operations
 
 - **`Recall`**: Query interface for facts (`recall.rb`)
@@ -198,12 +226,14 @@ Transcripts → Ingest → Index (FTS5)
   - Modes: shared (repo), local (uncommitted), home (user directory)
 
 - **`MCP`**: Model Context Protocol server and tools (`mcp/`)
-  - Exposes memory tools to Claude Code (21 tools total)
+  - Exposes memory tools to Claude Code (24 tools total)
+  - `Telemetry`: Records tool invocations to `mcp_tool_calls` table for usage stats
   - Dual content/structuredContent responses with compact mode
 
 - **`Hook`**: Hook entrypoint handlers (`hook/`)
   - Reads stdin JSON from Claude Code hooks
   - Routes to ingest/sweep/publish commands
+  - `DistillationRunner`: Manages context hook injection with undistilled content for LLM extraction
 
 ### Database Schema
 
@@ -215,6 +245,7 @@ Key tables (defined in `sqlite_store.rb`):
 - `provenance`: Links facts to source content_items
 - `fact_links`: Supersession and conflict relationships
 - `conflicts`: Open contradictions
+- `mcp_tool_calls`: MCP server tool invocation telemetry (schema v13)
 
 Facts include:
 - `scope`: "global" or "project" (determines applicability)
@@ -267,28 +298,34 @@ end
 
 ### Adding a New MCP Tool
 
-1. Add tool definition to `MCP::Tools::TOOLS` hash
-2. Implement handler in `MCP::Server#handle_tool_call`
-3. Ensure tool queries appropriate database(s) via StoreManager
-4. Add tests in `spec/claude_memory/mcp/`
+1. Add tool definition to `ToolDefinitions.all` array in `lib/claude_memory/mcp/tool_definitions.rb`
+2. Add `when` clause in `Tools#call` dispatch in `lib/claude_memory/mcp/tools.rb`
+3. Implement handler method in the appropriate handler module in `mcp/handlers/`
+4. Ensure tool queries appropriate database(s) via StoreManager
+5. Add tests in `spec/claude_memory/mcp/`
 
 ### Modifying Database Schema
 
-1. Increment `SCHEMA_VERSION` in `sqlite_store.rb`
-2. Add migration method (e.g., `migrate_to_v3!`)
-3. Call migration in `run_migrations!`
+1. Increment `SCHEMA_VERSION` in `store/schema_manager.rb`
+2. Create a new Sequel migration file in `db/migrations/` (e.g., `013_add_mcp_tool_calls.rb`)
+3. Sequel::Migrator runs migrations automatically in `ensure_schema!`
 4. Test migration on existing database files
 5. Update documentation if schema changes affect external interfaces
 
-### Adding a New Predicate Policy
+### Adding a New Predicate
+
+Edit `PredicatePolicy::POLICIES` in `lib/claude_memory/resolve/predicate_policy.rb` — this is the single source of truth. Choose cardinality:
+
+- **single** (exclusive: true): Facts supersede or conflict (e.g., `uses_database` — one per project)
+- **multi** (exclusive: false): Facts accumulate (e.g., `convention`, `uses_framework`)
 
-Single-value predicates (like "uses_database") supersede old values. Multi-value predicates (like "depends_on") accumulate. Modify `PredicatePolicy.single?` to adjust behavior.
+Also update `SECTION_MAP` if the predicate should appear in a specific snapshot section (`:decisions`, `:conventions`, `:constraints`). The `ToolDefinitions` predicate list updates automatically via `PredicatePolicy.known_predicates`. Add entries to `SYNONYMS` if the distiller might emit variant names.
 
 ## Important Files
 
 - `lib/claude_memory.rb`: Main module, requires, database path helpers
 - `lib/claude_memory/cli.rb`: Thin command router (41 lines)
-- `lib/claude_memory/commands/`: Individual command classes (22 commands)
+- `lib/claude_memory/commands/`: Individual command classes (28 commands)
 - `lib/claude_memory/configuration.rb`: Centralized configuration and ENV access
 - `lib/claude_memory/domain/`: Domain models (Fact, Entity, Provenance, Conflict)
 - `lib/claude_memory/core/`: Value objects and null objects
@@ -303,12 +340,13 @@ Single-value predicates (like "uses_database") supersede old values. Multi-value
 
 The gem includes an MCP server (`claude-memory serve-mcp`) that exposes memory operations as tools. Configuration should be in `.mcp.json` at project root.
 
-Available MCP tools (21 total):
+Available MCP tools (24 total):
 - **Query & Recall**: `memory.recall`, `memory.recall_index`, `memory.recall_details`, `memory.recall_semantic`, `memory.search_concepts`
 - **Provenance**: `memory.explain`, `memory.fact_graph`
 - **Shortcuts**: `memory.decisions`, `memory.conventions`, `memory.architecture`
 - **Context**: `memory.facts_by_tool`, `memory.facts_by_context`
-- **Management**: `memory.promote`, `memory.store_extraction`
+- **Management**: `memory.promote`, `memory.reject_fact`, `memory.store_extraction`
+- **Distillation**: `memory.undistilled`, `memory.mark_distilled`
 - **Monitoring**: `memory.status`, `memory.stats`, `memory.changes`, `memory.conflicts`
 - **Maintenance**: `memory.sweep_now`
 - **Discovery**: `memory.check_setup`, `memory.list_projects`
@@ -317,7 +355,7 @@ Available MCP tools (21 total):
 
 ClaudeMemory integrates with Claude Code via hooks in `.claude/settings.json`:
 
-- **Ingest hook**: Triggers on Stop/SessionStart/PreCompact/SessionEnd events
+- **Ingest hook**: Triggers on Stop/SessionStart/PreCompact/SessionEnd/TaskCompleted/TeammateIdle events
   - Calls `claude-memory hook ingest` with stdin JSON
   - Reads transcript delta and updates both global and project databases
 

data/README.md

@@ -83,6 +83,41 @@ Claude: "Based on my memory, you're using Rails with PostgreSQL..."
 👉 **[See Getting Started Guide →](docs/GETTING_STARTED.md)**
 👉 **[View Example Conversations →](docs/EXAMPLES.md)**
 
+## Why It Matters — Real A/B Test Results
+
+We tested identical prompts with and without ClaudeMemory to measure the actual impact. Here's what we found:
+
+### Architecture Recall Without File Traversal
+
+> **Prompt:** "Explain the conflict detection and resolution system. Answer from knowledge only — do not read any files."
+
+| | Without Memory | With Memory |
+|---|---|---|
+| **Response** | 16 lines: "I don't know this codebase — let me read the files" | 76 lines: correct 4-role PredicatePolicy explanation, resolution pipeline, specific examples |
+| **Outcome** | Honest refusal — zero architectural understanding | Deep understanding without touching the filesystem |
+
+### Correct File Paths vs Hallucinated Guesses
+
+> **Prompt:** "I want to add a new predicate. Walk me through every file I need to update."
+
+| | Without Memory | With Memory |
+|---|---|---|
+| **Response** | 6 steps targeting 3 **non-existent files** (`predicate.rb`, `predicate_synonyms.rb`, `json_schema.rb`) | 8 steps, all targeting **real files** with correct paths |
+| **Outcome** | Plausible but wrong — would waste developer time | Actionable, correct, references actual commits |
+
+### Cross-Project Preferences
+
+> **Prompt:** "What are my standard development environment preferences across all my projects?"
+
+| | Without Memory | With Memory |
+|---|---|---|
+| **Response** | "I don't have stored knowledge of your preferences" | Lists 7 real preferences: iTerm2, tmux, VS Code, PostgreSQL, Redis, Docker |
+| **Outcome** | Blank slate every session | Personalized from day one |
+
+### When Memory Doesn't Help
+
+File-searchable questions ("what version is this?") and one-shot code generation without explicit recall don't benefit — `grep` is equally effective. Memory shines when the answer **isn't in any single file**: architecture spanning dozens of classes, conventions from past sessions, decisions with rationale, and user preferences.
+
 ## How It Works
 
 1. **You chat with Claude** - Tell it about your project

data/db/migrations/013_add_mcp_tool_calls.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Migration v13: Add mcp_tool_calls telemetry table
+# Records every MCP server tool invocation for usage stats and ROI tracking.
+# Distinct from `tool_calls` (v3), which stores Claude Code tool observations
+# extracted from transcripts.
+Sequel.migration do
+  up do
+    create_table?(:mcp_tool_calls) do
+      primary_key :id
+      String :tool_name, null: false
+      String :called_at, null: false
+      Integer :duration_ms, null: false
+      Integer :result_count
+      String :scope
+      String :error_class
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_mcp_tool_calls_name_time ON mcp_tool_calls(tool_name, called_at)"
+    run "CREATE INDEX IF NOT EXISTS idx_mcp_tool_calls_called_at ON mcp_tool_calls(called_at)"
+  end
+
+  down do
+    drop_table?(:mcp_tool_calls)
+  end
+end

data/db/migrations/014_canonicalize_predicates.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Migration v14: Canonicalize stale predicate names in existing facts.
+#
+# The predicate vocabulary was curated in 0.9.0 — synonym canonicalization
+# now runs at insert time (Resolver), but existing facts with stale
+# predicate names need a one-time rewrite so they appear in the correct
+# snapshot sections and query results.
+#
+# This migration applies PredicatePolicy::SYNONYMS to all active facts.
+# Reversible: the down migration is a no-op because we can't know the
+# original predicate name after rewriting.
+Sequel.migration do
+  up do
+    # Inline the synonym map so the migration is self-contained and
+    # doesn't break if PredicatePolicy::SYNONYMS changes later.
+    synonyms = {
+      "has_convention" => "convention",
+      "primary_language" => "uses_language"
+    }
+
+    synonyms.each do |from, to|
+      self[:facts].where(predicate: from).update(predicate: to)
+    end
+  end
+
+  down do
+    # No-op: can't reverse a predicate rename without storing the original.
+  end
+end