v0.9.0 — Predicate Design Overhaul, Reject/Restore, Telemetry

Highlights

Predicate vocabulary overhaul — curated from 13 → 8 predicates based on a multi-project survey of real memory databases. uses_framework reclassified as multi-value (fixing silent data loss in production). PredicatePolicy is now the single source of truth for vocabulary, snapshot sections, synonym canonicalization, and LLM guidance.

New commands: reject and restore — first-class tools for managing distiller quality. Mark hallucinated facts as wrong, or recover facts that were superseded by an obsolete classification.

MCP tool-call telemetry — every tool invocation is timed and recorded. claude-memory stats --tools shows call counts, latency percentiles, and error rates.

Proactive memory recall — MCP instructions now direct Claude to check conventions before code generation, architecture before explanations, and decisions before refactoring. A/B testing showed this produces 76-line accurate architecture explanations vs honest refusals without memory.

---

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 superseded by obsolete single-value predicate classifications (Jaccard-based token overlap heuristic)
• MCP tool-call telemetry: mcp_tool_calls table, claude-memory stats --tools [--since DAYS], 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)
• Novel predicate warnings at insert time
• NullDistiller emits uses_language facts for detected language entities
• Proactive memory recall guidance in MCP server instructions
• YARD documentation across 13 core source files (+473 lines)

Changed

• uses_framework reclassified as multi-value — real projects use multiple frameworks (Rails + Turbo + Tailwind). Prior single-value classification silently superseded valid facts. Run claude-memory restore --predicate uses_framework to recover
• PredicatePolicy is single source of truth for vocabulary, snapshot sections, synonym canonicalization, and LLM guidance
• Predicate vocabulary curated 13 → 8 based on multi-project usage data
• Registry::COMMANDS stores {class:, description:} with direct class references
• Plugin and gem descriptions rewritten to be outcome-focused

Fixed

• StatsCommand broken in production — used Sequel.sqlite (requires unlisted sqlite3 gem). Now uses extralite adapter
• Missing embeddings command in shell completion output

Upgrade Notes

Schema: v12 → v14 (automatic). Migration 013 adds mcp_tool_calls. Migration 014 canonicalizes stale predicate names in existing facts.

Action required for uses_framework recovery: If your project uses multiple frameworks, past sessions may have superseded valid facts:

claude-memory restore --predicate uses_framework --dry-run   # preview
claude-memory restore --predicate uses_framework              # restore

Pruned predicates still work: preference, workflow, dependency, testing_strategy, tool_usage, ci_platform fall through to default multi-value policy. Existing facts are unaffected.

---

Full Changelog: v0.8.0...v0.9.0

v0.8.0

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

v0.7.1

Added

Three-Level Sweep Escalation

• Maintenance class with light/standard/deep sweep levels for progressive database maintenance
• Exposed sweep escalation via memory.sweep_now MCP tool with configurable level
• Tool escalation workflow added to MCP QueryGuide documentation

Embedding Deduplication

• Content-addressed deduplication for embeddings using SHA256 hashing
• Deduplication before vector scoring in fallback path to prevent duplicate results

MCP Enhancements

• Structured error classification for MCP tools via ErrorClassifier module
• Dynamic knowledge summary in MCP server instructions via InstructionsBuilder

Fixed

• Plugin hook loading error: Removed explicit hooks reference from plugin.json manifest — Claude Code auto-loads hooks/hooks.json from the plugin root, so declaring it caused "Duplicate hooks file detected" errors on plugin install

Internal

• Influence study: lossless-claw v0.3.0 DAG-based lossless context management
• Marked 7 improvements as implemented (#10, #11, #14, #15, #16, #19, #20)

v0.7.0

ClaudeMemory v0.7.0

Added

FTS5 Contentless Mode

• FTS5 tables now created with content='' for ~40% smaller databases
• Auto-detection: both legacy and contentless formats work seamlessly
• compact command rebuilds FTS index to contentless format
• stats command reports FTS format and optimization hints

Worktree-Aware Project Paths

• Project database now resolves to main repository root across git worktrees
• Prevents duplicate project databases when using git worktree
• Opt-out: set CLAUDE_MEMORY_ISOLATE_WORKTREES=1 for per-worktree isolation

MCP Enhancements

• Tool annotations: readOnlyHint, idempotentHint, destructiveHint on all 21 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

New Commands

• git-lfs command for setting up git-lfs tracking of project memory databases

Fixed

• Narrowed rescue clauses in discover_other_projects (was bare rescue, now catches specific exceptions)
• FTS entries now cleaned up when content is pruned by sweeper (prevents orphaned index entries)
• FTS index rebuilt during compact for consistent state after upgrades
• Real evals CI: install gem and use correct release API

Internal

• Resolver refactored for better thread safety (parameters instead of instance variables)
• SnippetExtractor DRY refactoring
• StoreManager.promote_fact single-transaction safety
• Influence study: QMD v2.0.1 SDK-first architecture analysis

22 CLI commands · 21 MCP tools · 1,435 tests

v0.6.0

What's New

Native Vector Storage (sqlite-vec)

• Integrated sqlite-vec for native KNN vector search
  • VectorIndex class with vec0 virtual table for cosine similarity search
  • Dual-write: embeddings stored in both JSON column and vec0 index
  • claude-memory index --vec flag for backfilling existing embeddings into vec0
  • Fast path in Recall uses sqlite-vec KNN when available, falls back to JSON + Ruby
  • Sweeper cleans up vec0 entries for superseded/expired facts
  • Doctor and MCP status/stats report vec0 availability and coverage
  • Cross-platform support with platform-specific gem installation

Database Maintenance

• compact command for database maintenance (VACUUM + integrity check)
• export command for fact backup and migration to JSON

Hook Enhancements

• SessionStart context injection via hookSpecificOutput.additionalContext
  • Injects recent facts and project context at session start
• Tool-specific observation compression for reduced token usage
• --async flag for non-blocking hook execution
• Hook error classification for graceful degradation
• Conversation exclusion markers for session-level opt-out

MCP Discovery

• memory.list_projects MCP tool for discovering all project databases

Developer Experience

• Dynamic MCP server instructions with progressive disclosure documentation
• Comparative benchmark suite with QMD and grepai adapters

Bug Fixes

• Recall returned no results: DualQueryTemplate accessed stores before initializing them, causing all recall queries to silently return empty results. Refactored to use existing store_for_scope method.
• Doctor crashed on sqlite-vec tables: SchemaValidator iterated all tables including vec0 virtual tables, which require the sqlite-vec extension. Now skips facts_vec* tables using prefix match.
• Forward-migrated databases: Older gem versions now gracefully handle databases migrated by newer versions instead of crashing.
• Hybrid retrieval ordering: Preserved BM25 scores and RRF ordering in hybrid search results instead of re-sorting by source/time.

Stats

• 21 MCP tools, 22 CLI commands
• 1316 test examples, 0 failures
• Full changelog: CHANGELOG.md

v0.5.1

What's Changed

Fixed

• Database Lock Errors: Fixed "database is locked" and "database is busy" errors when multiple Claude Code hooks run concurrently

  • Added application-level retry with exponential backoff (5 retries, 0.1s base delay)
  • Reduced SQLite busy_timeout from 30s to 1s for faster failure detection
  • Added with_retry and transaction_with_retry methods for concurrent access handling

• MCP Server Auto-Registration: Added .mcp.json at plugin root so MCP server is automatically registered when plugin is installed (previously only worked in dev directory)

Full Changelog: v0.5.0...v0.5.1

v0.5.0

What's New in v0.5.0

MCP Structured Content & Compact Mode

• All MCP tools now return dual content (text summary) + structuredContent (JSON)
• Compact mode (compact: true) omits provenance receipts for ~60% smaller responses
• MCP query guide prompt for tool selection guidance

Search & Retrieval Improvements

• Reciprocal Rank Fusion (RRF) replaces naive merge for hybrid search — better result ordering
• Smart expansion detection skips unnecessary vector search when FTS5 already provides strong matches
• Enhanced snippet extraction with better context windows

Provenance & Traceability

• Line-range references in provenance for precise source linking
• Fact dependency graph visualization via BFS traversal

User-Friendly Identifiers

• Docid short hash system — memorable identifiers instead of raw integer IDs

Caching & Performance

• LLM response caching schema and store methods
• Structured JSON logging with configurable level filtering

Ingestion & Content Processing

• Configurable tool capture filtering for ingestion
• ContentSanitizer now strips system-reminder, local-command-caveat, and other Claude Code internal tags
• Relative time formatting in recall output (just now → Xm ago → Xh ago → Xd ago)

Developer Tools

• --brief flag for doctor command for automated workflows

Bug Fixes

• Preserve SQLite PRAGMAs across connection reconnects
• Fix timestamp-only churn in publish output

Internal

• Significant code quality improvements: method decomposition, N+1 query fixes, duplicate extraction
• Research studies: QMD restudy (plugin format, structured MCP) and claude-supermemory study (context injection)

Full Changelog: https://github.com/codenamev/claude_memory/blob/main/CHANGELOG.md#050---2026-02-04

v0.4.0 - Semantic Search with FastEmbed

Added

Semantic Search with FastEmbed

• Integrated fastembed-rb for high-quality local embeddings
  • Uses BAAI/bge-small-en-v1.5 model (384-dim, ~67MB ONNX, runs locally)
  • No API key required -- model downloaded once to ~/.cache/fastembed/
  • Asymmetric query/passage encoding for better retrieval accuracy
• FastembedAdapter class implementing the existing Generator interface for drop-in replacement
• Benchmark retrieval scores jumped significantly with real embeddings:
  • Semantic easy: Recall@5 = 0.900, medium: 0.696
  • Hybrid aggregate: Recall@5 = 0.727 (was 0.266 with TF-IDF fallback)

Documentation

• Updated benchmark results throughout README, spec/benchmarks/README, and architecture docs
• Replaced TF-IDF embedding references with FastEmbed in architecture documentation

v0.3.0 - Database Performance, Semantic Search & Quality Improvements

v0.3.0 - 2026-01-29

Added

Setup & Initialization

• Version markers in CLAUDE.md files for upgrade detection
  • HTML comment format: <!-- ClaudeMemory vX.Y.Z -->
  • Enables version comparison and upgrade workflows
• memory.check_setup MCP tool for initialization detection
  • Returns status: healthy, needs_upgrade, partially_initialized, not_initialized
  • Checks databases, CLAUDE.md, version, and hooks configuration
  • Provides actionable recommendations
• /setup-memory skill for installation guidance
  • Comprehensive troubleshooting documentation
  • Step-by-step setup instructions
  • Links to diagnostic tools

Database & Infrastructure

• Schema version 6 with new tables:
  • operation_progress - Track long-running operation state (index generation, migrations)
  • schema_health - Record schema validation results and migration history
• WAL (Write-Ahead Logging) mode for better concurrency and crash recovery
• Incremental sync with source_mtime tracking to avoid re-processing unchanged files
• Atomic migrations with per-migration transactions for safety
• Configuration class for centralized ENV access and testability

Search & Recall

• index command to generate TF-IDF embeddings for semantic search
• Index command resumability with checkpoints (recover from interruption)
• Semantic search capabilities using TF-IDF embeddings
• Improved full-text search with empty query handling

Session Intelligence

• Session metadata extraction:
  • Git branch tracking (git_branch)
  • Working directory context (cwd)
  • Claude version tracking (claude_version)
  • Tool usage patterns (tool_calls)
• Session-aware fact extraction for better provenance

Developer Tools

• Enhanced doctor command with:
  • Schema validation and integrity checks
  • Migration history verification
  • Recovery suggestions for corrupted databases
• stats command for database statistics
• Recovery command for stuck long-running operations
• Transaction wrapper for ingestion atomicity

Quality Improvements

• Quality review workflow with Ruby expert perspectives:
  • /review-for-quality skill for comprehensive codebase review
  • Expert analysis from Sandi Metz, Jeremy Evans, Kent Beck, Avdi Grimm, Gary Bernhardt
  • Automated quality documentation generation
• Infrastructure abstractions (FileSystem, InMemoryFileSystem) for testability
• Domain model enhancements with immutable, self-validating objects

Repository Analysis

• /study-repo skill for deep analysis of external repositories
  • Systematic exploration through 6 phases (context, architecture, patterns, quality, comparison, adoption)
  • Generates comprehensive influence documents in docs/influence/
  • Updates docs/improvements.md with prioritized recommendations
  • Focus mode support for targeted analysis (testing, MCP, database, CLI, performance)
  • Integration with /improve workflow

Error Handling

• Graceful error messages when databases are missing or not accessible
• Structured error responses with recommendations
• Directs users to memory.check_setup for diagnosis

Changed

• IMPORTANT: Switched from sqlite3 to extralite as required dependency
  • Extralite provides better concurrency and performance
  • Fixes database lock contention between MCP server and hooks
  • Extralite (~> 2.14) is now the only SQLite adapter
• Ingestion now tracks file modification time to skip unchanged content
• Migration process now uses per-migration transactions for atomicity
• Doctor command now includes schema validation and recovery guidance
• Index operations can resume from checkpoints after interruption
• MCP tool descriptions now emphasize memory-first workflow
• Tool descriptions are more directive ("Check FIRST", "Use BEFORE")
• Init command now adds version markers to generated CLAUDE.md files

Fixed

• Critical: Database lock contention between MCP server and hooks
  • Switched to extralite adapter for better concurrent access
  • Improved busy timeout handling
• Database busy error handling for both SQLite adapters
• Concurrent access test for extralite adapter
• Public keyword placement in SQLiteStore (Ruby style conformance)
• Transaction safety for multi-step database operations

Documentation

• Complete getting started guide (GETTING_STARTED.md)
• Enhanced plugin documentation with setup workflows
• Comprehensive examples for all features
• Architecture documentation updates
• Updated all documentation to reflect current codebase metrics
  • 20 commands (was documented as 16)
  • 18 MCP tools (was documented as 7-8)
  • 985 test examples (was documented as 583/426)
• Auto-initialization and upgrade design document (docs/auto_init_design.md)
• Multi-phase upgrade strategy documentation

Internal

• Consolidated ENV access via Configuration class
• Registered new infrastructure modules in main loader
• Improved test coverage for new features
• Major code quality improvements with component extraction:
  • Core::FactQueryBuilder - Query construction logic from Recall
  • Core::SetupStatusAnalyzer - Setup status analysis from MCP Tools
  • MCP::ToolDefinitions - Tool definitions separated from server logic
  • MCP::ResponseFormatter - Response formatting with multiple query types
  • Core::TextBuilder - Text building utilities
  • Core::ResultSorter - Result sorting logic
  • Core::EmbeddingCandidateBuilder - Embedding candidate construction
  • Core::FactCollector - Fact collection logic
  • Core::ResultBuilder - Result building logic
• Init command test suite (19 examples)
• Setup detection test suite (25 examples)
• Error handling test suite (4 examples)
• Comprehensive test coverage (53 new tests)

v0.2.0 - Privacy, Performance & Claude Integration

v0.2.0 - 2026-01-22

Added

Privacy & Security

• Privacy tag system: <private>, <no-memory>, <secret> tags strip sensitive content from ingestion
• ContentSanitizer module with comprehensive sanitization logic
• ReDoS protection: Maximum 100 tags per ingestion to prevent regex attacks
• 100% test coverage for ContentSanitizer (security-critical module)

Token Economics & Performance

• Progressive disclosure pattern with two-phase queries:
  • memory.recall_index - Lightweight index with previews (~50 tokens per fact)
  • memory.recall_details - Full details on demand with provenance
• TokenEstimator module for accurate query result sizing
• 10x token reduction for initial memory searches
• N+1 query elimination in Recall class (reduced from 2N+1 to 3 queries via batch loading)
• IndexQuery object for cleaner full-text search logic
• QueryOptions parameter object for consistent option handling

Semantic Shortcuts

• memory.decisions - Quick access to architectural decisions and accepted proposals
• memory.conventions - Global coding conventions and style preferences
• memory.architecture - Framework choices and architectural patterns
• Shortcuts query builder with centralized predicate configuration
• Pre-configured queries eliminate manual search construction

Claude Code Plugin

• Full plugin structure for seamless Claude Code integration
• .claude-plugin/plugin.json manifest with marketplace metadata
• hooks/hooks.json with prompt hooks for Claude-powered extraction
• skills/memory/SKILL.md for /memory command

Claude-Powered Fact Extraction

• memory.store_extraction MCP tool for structured fact storage
• Accepts JSON with entities, facts, and decisions
• Prompt hooks trigger extraction on session stop
• No API key required - uses Claude Code's own session
• Full schema validation with truth maintenance

Developer Experience

• Exit code strategy for hooks with semantic constants
• Comprehensive hook tests covering all event types (13 test cases)
• PrivacyTag value object for type-safe tag handling
• Empty query handling for FTS5 search

Testing & Quality

• 157 new test examples (grew from 426 to 583 total)
• 100% coverage for TokenEstimator (accuracy-critical)
• Comprehensive privacy tag tests including ReDoS protection
• Hook exit code verification tests

Changed

• CLI hook commands now return standardized exit codes instead of mixed returns
• Recall queries optimized with batch loading for provenance and entities
• Index searches use QueryOptions for consistent parameter handling

Documentation

• README restructured for clarity and quick onboarding
• New comprehensive examples documentation
• Simplified getting started experience