claude_memory 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1483a3663c9c589abad58f80c71d772c592f13727d3fd1339418c2ba1a3db875
-  data.tar.gz: 34beebdf5e3cc8a70d383757ffaf7e21fde0724f963532e2d2548ec2e63ba329
+  metadata.gz: 9b42d582ddd17dd325f8048268c889d6c80c1ca9c229732da1a8d619279201af
+  data.tar.gz: 8853caacc212900483a4a3f9939e8261e18f53b886675f01b4c5a5b61a506d26
 SHA512:
-  metadata.gz: 514022df68751e4421942d914c003a1e104a5c2b5ab4a639619ca05bb4d6bafd722d87009dc898a5b578f1b7efdae50df68b5b8232e1cf42a8bb5e88a06e66c3
-  data.tar.gz: 68c5a36361d3048e4c92bba7127e7fa0bc9ff09f6de3779ae59f7799cd4152d63030386ea2b124a90b345063545028b0da0401c9144f284c7e34290b2d674ba7
+  metadata.gz: a65038105334c741d26c5e485da7565016ae670ed24f04d4c23b2bb00329d729ee3bfd91cf333ea36ad518937e40e4c95c4d0846bcb423984b0ec683fee59b5a
+  data.tar.gz: d94e2ce5fbd1ed496a0c56f094b7f1fbb01b9eb255c819a95b2ffe6ecf79ea9c1706408fd658b2bcaee19d440a87d45a1185a7e471cb05fc7c003d433d6e5808

data/.claude/rules/claude_memory.generated.md

@@ -1,21 +1,51 @@
-<!-- 
+<!--
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-02-05T18:27:44Z
+  Generated: 2026-04-15T17:38:20Z
 -->
 
 # Project Memory
 
 ## Current Decisions
 
+- MCP tool-call telemetry stores minimal columns (tool_name, duration_ms, result_count, scope, error_class) — deliberately no query_text or query_hash. YAGNI: hashes are write-only without the raw text, and raw text adds privacy concerns without clear value beyond existing shortcut tools (memory.decisions, memory.conventions).
 - From QMD 2026-02-02 restudy: adopt Claude Code plugin format, MCP structured content pattern, MCP query guide prompt, inline status checks. Carry forward sqlite-vec, RRF, docids, smart expansion from 2026-01-26. Reject custom fine-tuned models, LLM reranking, YAML collections.
 - From claude-supermemory study: adopt SessionStart hook context injection (hookSpecificOutput.additionalContext), tool-specific observation compression, and relative time formatting. Reject cloud storage dependency and no-test approach.
 
 ## Conventions
 
+- Never use Sequel.sqlite for DB reads; this gem only depends on extralite. Use Sequel.connect("extralite://#{db_path}") or SQLiteStore.new. Sequel.sqlite requires the ungem'd sqlite3 adapter and fails at runtime.
+- Two distinct tool_calls tables exist: tool_calls (v3) for transcript-observed Claude Code tool usage, and mcp_tool_calls (v13) for MCP server telemetry. Disjoint purposes, never join.
+- MCP tool-call telemetry is recorded via MCP::Telemetry wrapping Server#handle_tools_call. Writes to mcp_tool_calls table in the project DB. Swallows DB errors so telemetry never breaks a real tool response. Viewable via 'claude-memory stats --tools [--since DAYS]'.
+- mcp_tool_calls retention is 90 days, enforced by Sweep::Maintenance#prune_old_mcp_tool_calls wired into Sweeper#run!. Configurable via mcp_tool_call_retention_days in Maintenance DEFAULT_CONFIG.
+- CLAUDE_CONFIG_DIR env var overrides the default ~/.claude location for Configuration#global_db_path. Access via Configuration#claude_config_dir. Additive, backwards compatible.
+- Registry::COMMANDS stores {class:, description:} entries as the single source of truth for command name, class reference, and shell-completion description. Class constants stored directly (no const_get). Registry.descriptions feeds CompletionCommand; adding a new command requires updating only this hash.
+- Prefer do...end over braces when a block has repeated argument names, multiple expressions, or non-trivial body. Single-expression simple blocks can still use braces.
+- EXPECTED_HOOKS constant must stay in sync with events in HooksConfigurator#build_hooks_config. Adding a new hook event without updating EXPECTED_HOOKS causes false doctor warnings.
+- Tests using --db for hook context only set the project DB path. StoreManager still connects to the real global DB. Must stub Configuration to return a temp global path for isolation.
+- Version must be updated in three places: lib/claude_memory/version.rb, .claude-plugin/plugin.json, .claude-plugin/marketplace.json. Runtime code uses ClaudeMemory::VERSION dynamically.
+- Use module inclusion (not class extraction) to break up god objects — preserves public API so zero tests need modification
+- Configuration class has instance methods only — use Configuration.new.global_db_path, not Configuration.global_db_path. Stub with instance_double + allow(Configuration).to receive(:new).and_return(config)
+- OperationTracker.reset_stuck_operations only resets operations older than 24 hours (STALE_THRESHOLD_SECONDS). Tests must backdate started_at to trigger resets.
+- SCHEMA_VERSION constant lives in Store::SchemaManager module but is accessible as SQLiteStore::SCHEMA_VERSION via Ruby include-based constant lookup
 - MCP tools return dual content (text summary) + structuredContent (JSON) via TextSummary module and Server#handle_tools_call. Compact mode (compact: true) omits receipts for ~60% smaller responses.
 - ContentSanitizer strips system-reminder, local-command-caveat, command-message, command-name, command-args tags in addition to private/no-memory/secret/claude-memory-context.
 - Core::RelativeTime module provides progressive time formatting: just now → Xm ago → Xh ago → Xd ago → YYYY-MM-DD. Used in ResponseFormatter for *_ago fields.
 - MCP server registers memory_guide prompt via prompts/list and prompts/get endpoints. QueryGuide module holds prompt content.
 - Claude Code plugin with marketplace.json, skill definitions, MCP server bundling. 5,700+ stars, by Tobi Lütke. Custom fine-tuned query expansion (Qwen3-1.7B, SFT+GRPO). Dual content/structuredContent MCP pattern.
 - Cloud-backed Claude Code plugin (~1,195 LOC JavaScript) using Supermemory API for persistent memory across sessions. Uses hooks for SessionStart context injection and Stop transcript capture. No local database.
+
+## Technical Constraints
+
+- **Uses database**: sqlite
+
+## Additional Knowledge
+
+### Architecture
+
+- MCP::Tools: Thin 104-line dispatcher that includes 6 handler modules in mcp/handlers/: QueryHandlers, ShortcutHandlers, ContextHandlers, ManagementHandlers, StatsHandlers, SetupHandlers
+- Recall: 94-line facade delegating to @engine (DualEngine or LegacyEngine), both include shared QueryCore module with all store-level query logic
+- SQLiteStore: 386-line CRUD class that includes RetryHandler (retry/connection logic) and SchemaManager (migrations/version sync) modules
+- Embeddings: Pluggable providers via Embeddings.resolve(name, env:). Three providers: tfidf (default), fastembed, api. Duck-typed contract: name, dimensions, generate(text). ENV: CLAUDE_MEMORY_EMBEDDING_PROVIDER
+- Embeddings::DimensionCheck: Pure value object — DimensionCheck.call(store, provider) returns Data.define Result with :fresh/:match/:mismatch status. No side effects; caller decides how to handle mismatch.
+

data/.claude/settings.json

@@ -5,17 +5,21 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 5
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 5,
+            "statusMessage": "Saving memory..."
           }
         ]
-      },
+      }
+    ],
+    "StopFailure": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 5
+            "timeout": 5,
+            "statusMessage": "Saving memory..."
           }
         ]
       }
@@ -26,87 +30,56 @@
           {
             "type": "command",
             "command": "claude-memory hook context",
-            "timeout": 5
+            "timeout": 5,
+            "statusMessage": "Loading memory..."
           }
         ]
       }
     ],
     "PreCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 30
-          },
-          {
-            "type": "command",
-            "command": "claude-memory hook sweep",
-            "timeout": 30
-          }
-        ]
-      },
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }
     ],
     "SessionEnd": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 30
-          },
-          {
-            "type": "command",
-            "command": "claude-memory hook sweep",
-            "timeout": 30
-          }
-        ]
-      },
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }
     ],
     "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 10
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
           }
         ]
       }
@@ -116,17 +89,22 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 15
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 15,
+            "statusMessage": "Saving memory..."
           }
         ]
-      },
+      }
+    ],
+    "Notification": [
       {
+        "matcher": "idle_prompt",
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 15
+            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 10,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }

data/.claude/settings.local.json

@@ -48,7 +48,9 @@
       "Bash(claude-memory search:*)",
       "Bash(bundle exec:*)",
       "Skill(improve)",
-      "Skill(improve:*)"
+      "Skill(improve:*)",
+      "WebFetch(domain:arxiv.org)",
+      "mcp__memory__memory_conflicts"
     ]
   },
   "enableAllProjectMcpServers": true,

data/.claude/skills/upgrade-dependencies/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: upgrade-dependencies
+description: "Upgrade all Ruby gem dependencies to their latest versions with release note review and codebase alignment checks. Use this skill whenever the user asks to update, upgrade, or bump dependencies, gems, or packages — even casually like 'update my gems' or 'are my deps up to date?'"
+agent: general-purpose
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write, Agent, WebFetch
+---
+
+# Dependency Upgrade Skill
+
+Systematically upgrade Ruby gem dependencies by researching latest versions, reviewing release notes for breaking changes, updating version constraints, verifying with tests, and confirming codebase alignment.
+
+The goal is a *thoughtful* upgrade — not blindly bumping versions, but understanding what changed and ensuring the codebase is compatible. This matters because a silent API change can introduce bugs that tests don't catch if the tests don't exercise the affected code path.
+
+## Process Overview
+
+1. **Discover** current dependencies and their constraints
+2. **Research** latest versions and release notes (in parallel)
+3. **Analyze** breaking changes and codebase impact
+4. **Upgrade** version constraints and install
+5. **Verify** with the full test suite
+6. **Report** a summary table with upgrade details
+
+## Step 1: Discover Current Dependencies
+
+Read the gemspec and Gemfile to build a complete dependency inventory.
+
+```
+Read *.gemspec        → runtime dependencies (add_dependency)
+Read Gemfile          → development dependencies (gem declarations)
+Run: bundle outdated  → current vs latest versions, which are constrained
+```
+
+Build a working list with these columns:
+- **Gem name**
+- **Source** (gemspec or Gemfile)
+- **Current constraint** (e.g., `~> 5.0`)
+- **Installed version** (from `bundle outdated` or `Gemfile.lock`)
+- **Latest version** (from `bundle outdated`)
+- **Constrained?** (is the version constraint preventing upgrade?)
+
+## Step 2: Research Release Notes
+
+For each gem that has a newer version available, research what changed. Launch these as parallel Agent subagents — one per gem — to avoid sequential delays.
+
+Each research agent should:
+
+1. Run `gem search <name> --exact --versions` to confirm the latest version
+2. Fetch the changelog or release notes from GitHub (check CHANGELOG.md, CHANGES, HISTORY.md, or GitHub Releases)
+3. Summarize changes between the installed version and latest version
+4. Flag any **breaking changes**, **deprecations**, or **API changes**
+5. Note if it's a **major version bump** (higher risk)
+
+For transitive dependencies (not directly declared but showing in `bundle outdated`), research is optional — focus on direct dependencies. Transitive deps are upgraded automatically when their parent gem allows it.
+
+### What to look for in release notes
+
+- **Removed methods or classes** the codebase might use
+- **Renamed options or changed defaults** that could silently alter behavior
+- **New required arguments** to methods we call
+- **Deprecated features** we rely on (working now, but will break later)
+- **Changed return types** or data structures
+- **Minimum Ruby version bumps** that could affect CI or deployment
+
+## Step 3: Analyze Codebase Impact
+
+For each gem with breaking changes or API modifications:
+
+1. **Grep the codebase** for usage of affected APIs
+2. **Check test coverage** — are the affected code paths tested?
+3. **Determine if changes are needed** before or after the upgrade
+
+Classify each upgrade:
+
+- **Safe** — no breaking changes, or breaking changes don't affect our usage
+- **Needs code changes** — our code uses a deprecated or removed API
+- **Held back** — a transitive dependency constraint prevents the upgrade (explain which parent gem and why)
+
+If code changes are needed, make them *before* bumping the version constraint so the upgrade commit is clean.
+
+## Step 4: Upgrade Dependencies
+
+### Gemspec dependencies (runtime)
+
+Update version constraints to target the latest version. Use `~>` with the appropriate precision:
+
+- For stable gems (1.0+): `~> X.Y` allows patch updates (e.g., `~> 5.102` allows 5.102.x)
+- For pre-1.0 gems: `~> 0.X, ">= 0.X.Y"` to pin a minimum while allowing patches
+- For gems where a specific fix matters: add `">= X.Y.Z"` as an additional constraint
+
+### Gemfile dependencies (development)
+
+Same approach. If a major version bump is available (e.g., lefthook 1.x → 2.x), check the migration guide before bumping.
+
+### Install
+
+```bash
+bundle update
+```
+
+If `bundle update` fails due to dependency conflicts, resolve them. Common strategies:
+- Relax an overly tight constraint
+- Update the conflicting parent gem first
+- Accept that a gem can't be upgraded yet and document why
+
+## Step 5: Verify with Tests
+
+Run the full test suite:
+
+```bash
+bundle exec rspec
+```
+
+Also run the linter to catch any style issues:
+
+```bash
+bundle exec rake standard
+```
+
+If tests fail:
+1. Read the failure carefully — is it caused by the upgrade or pre-existing?
+2. If caused by the upgrade, fix the code to work with the new version
+3. If unfixable, revert that specific gem's upgrade and note it in the report
+
+## Step 6: Present Summary
+
+Present a clear summary table of all changes:
+
+```markdown
+| Gem | Old Version | New Version | Old Constraint | New Constraint | Notes |
+|-----|------------|-------------|----------------|----------------|-------|
+| sequel | 5.100.0 | 5.102.0 | ~> 5.0 | ~> 5.102 | No breaking changes |
+| lefthook | 1.13.6 | 2.1.4 | ~> 1.6 | ~> 2.1 | Major version bump, reviewed migration guide |
+```
+
+Follow the table with:
+
+1. **Breaking changes found** — what changed and how the codebase was updated
+2. **Gems held back** — which gems couldn't be upgraded and why (e.g., "diff-lcs 2.0 held back by rspec's ~> 1.4 constraint")
+3. **Notable new features** — anything worth adopting from the new versions
+4. **Test results** — confirmation that all tests pass
+
+## Edge Cases
+
+### Gems with no GitHub repository
+Fall back to `gem info <name>` and the RubyGems page for release history. Note reduced confidence in the review.
+
+### Yanked versions
+If `bundle update` fails because a version was yanked, try the next most recent version.
+
+### Pre-release versions
+Do not upgrade to pre-release or alpha versions unless the user explicitly asks. Stick to stable releases.
+
+### Monorepo gems
+Some gems (like rails components) are versioned together. Upgrade them as a group.

data/.claude-plugin/marketplace.json

@@ -7,9 +7,9 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.8.0",
+      "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.8.0",
-  "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,47 @@ 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

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
@@ -157,7 +163,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
   - Each command is a separate class (HelpCommand, DoctorCommand, etc.)
   - All commands inherit from BaseCommand
   - Dependency injection for I/O (stdout, stderr, stdin)
-  - 23 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
@@ -166,7 +172,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
 #### 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?)
@@ -182,7 +188,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
 - **`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/`)
@@ -205,7 +211,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
 
 - **`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`)
@@ -220,7 +226,8 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
   - Modes: shared (repo), local (uncommitted), home (user directory)
 
 - **`MCP`**: Model Context Protocol server and tools (`mcp/`)
-  - Exposes memory tools to Claude Code (23 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/`)
@@ -238,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)
@@ -290,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 (23 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
@@ -326,12 +340,12 @@ 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 (23 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`