claude_memory 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7835fd6219efb8e7b8942c0933abd529228b92fc003649abeb26415fae05881b
-  data.tar.gz: 8a466024f18ac23db38cc85cedc9e80512f9b8a7cf74cdbcd453626f12408afc
+  metadata.gz: d32c7aa8093eedade1783eefa7109c996aa134d01dea01b67794612c126cf068
+  data.tar.gz: 78fe0f2ff602c740b6ab727a0fde88d07fb235f38b1143b644b4e7498f07079f
 SHA512:
-  metadata.gz: 664a3477dd134ad7857cc7e292fea52833260986cb8d85f80d5ab5faba5c3821bab72e754960d5dadd3c203e03443b393e3b7687fbd4915f70970b3d98c9e3ec
-  data.tar.gz: 9924044b6fbe3d4a39a722e754a4dc94d3f73af7b0cb9b5177353f9de7461afbd5688f411fbe8d2dcccdd52153318b2ed279ed70984fc7f8b6b45544ad2036e5
+  metadata.gz: be68b153e9e25ef3b8e5ad71ba7fdd89e5ace40f0848125b480bf35c96ad8b0a73b1fd891e59faf5807bc99d8d637f0c6d647e2b1d6c86ad0654b9df69c1ab45
+  data.tar.gz: 92ee3e92e7967e03f642a5736a84f70563dd6e9f00fc3a7b24714b97294348e35645cdbfdd4b760bc5ee21301bb869bccbc686050cbc95e2bf7399c38508a32e

data/.claude/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- ClaudeMemory v0.3.0 -->
+<!-- ClaudeMemory v0.5.0 -->
 # Project Memory
 
 @.claude/rules/claude_memory.generated.md

data/.claude/output-styles/memory-aware.md

@@ -0,0 +1 @@
+../../output-styles/memory-aware.md

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

@@ -1,46 +1,21 @@
 <!-- 
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-01-29T18:59:01Z
+  Generated: 2026-02-04T16:37:00Z
 -->
 
 # Project Memory
 
 ## Current Decisions
 
-- Extralite chosen to fix database lock contention between MCP server and hooks
+- 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
 
-- frozen_string_literal: true in all Ruby files
-- RSpec uses documentation format
-- Default Rake task runs tests and linter
-- frozen_string_literal: true in all Ruby files
-- Default Rake task runs spec and standard
-- Standard Ruby linter configured for Ruby 3.2
-- Pre-commit hook runs standard:fix and stages changes
-- Pre-commit hook runs tests
-- Pre-commit hook runs quality review on Ruby files
-- Pre-commit hook runs standard:fix and stages changes
-- Pre-commit hook runs tests
-- Pre-commit hook runs quality review on Ruby files
-- frozen_string_literal: true
-- RSpec documentation format
-- Default Rake task runs tests and linter
-- frozen_string_literal: true in all Ruby files
-- RSpec uses documentation format
-- Default Rake task runs tests and linter
-- Pre-commit hook runs standard:fix and stages changes
-- Pre-commit hook runs tests
-- Pre-commit hook runs quality review on Ruby files
-- Pre-commit hook runs standard:fix and stages changes
-- Pre-commit hook runs tests
-- Pre-commit hook runs quality review on Ruby files
-- frozen_string_literal: true in all Ruby files
-- RSpec format documentation mode
-- Default Rake task runs spec and standard
-- frozen_string_literal: true in all Ruby files
-
-## Technical Constraints
-
-- **Uses database**: SQLite with Extralite adapter
+- 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.

data/.claude/settings.local.json

@@ -25,7 +25,10 @@
       "Bash(git log:*)",
       "Bash(find:*)",
       "Bash(wc:*)",
-      "mcp__plugin_claude-memory_memory__memory_architecture"
+      "mcp__plugin_claude-memory_memory__memory_architecture",
+      "mcp__plugin_claude-memory_memory__memory_recall_index",
+      "Bash(./bin/run-evals:*)",
+      "WebSearch"
     ]
   },
   "enableAllProjectMcpServers": true

data/.claude/skills/check-memory/DEPRECATED.md

@@ -0,0 +1,29 @@
+# Deprecated: /check-memory
+
+This skill is **no longer needed** and should not be used.
+
+## Why Deprecated?
+
+The `/check-memory` skill was created to force a "check memory before file exploration" workflow. However, this should be **automatic**, not manual.
+
+## What Replaced It?
+
+The enhanced `memory-aware` output style now handles this automatically by:
+- Explicitly instructing Claude to check memory FIRST before file reads
+- Providing clear workflow: memory.recall → then file exploration if needed
+- Making this behavior persistent across all conversations
+
+## If You Need Debugging
+
+Use `/debug-memory` instead to troubleshoot ClaudeMemory installation issues.
+
+## Migration
+
+If you were using `/check-memory`:
+- **Remove** any references to it
+- **Use** the `memory-aware` output style (automatically applied)
+- **Trust** that Claude will check memory first automatically
+
+## Archive Date
+
+Deprecated: 2026-01-29

data/.claude/skills/check-memory/SKILL.md

@@ -16,6 +16,16 @@ The user is asking about: $ARGUMENTS
 
 ## Step-by-Step Workflow
 
+### 0. Verify Memory Health
+
+Before querying, confirm the memory system is operational:
+
+```
+memory.check_setup
+```
+
+If status is not "healthy", inform the user and suggest running `claude-memory doctor` for details.
+
 ### 1. Query Memory (REQUIRED FIRST STEP)
 
 Run multiple memory queries to find existing knowledge:

data/.claude/skills/debug-memory

@@ -0,0 +1 @@
+../../skills/debug-memory

data/.claude/skills/improve/SKILL.md

@@ -11,7 +11,8 @@ Systematically implement feature improvements from `docs/improvements.md`, makin
 
 ## Process Overview
 
-1. **Read the improvements document** from `docs/improvements.md`
+1. **Check memory health** by calling `memory.check_setup` to verify the system is operational
+2. **Read the improvements document** from `docs/improvements.md`
 2. **Identify unimplemented features** from "Remaining Tasks" section
 3. **Prioritize by stated priority** (Medium → Low)
 4. **Assess feasibility** (skip if too complex or requires external services)
@@ -22,6 +23,16 @@ Systematically implement feature improvements from `docs/improvements.md`, makin
 
 ## Detailed Steps
 
+### Step 0: Verify Memory Health
+
+Before starting, confirm the memory system is operational:
+
+```
+memory.check_setup
+```
+
+If status is not "healthy", address any issues before proceeding.
+
 ### Step 1: Read and Parse Improvements Document
 
 ```bash

data/.claude/skills/memory-first-workflow

@@ -0,0 +1 @@
+../../skills/memory-first-workflow

data/.claude/skills/setup-memory

@@ -0,0 +1 @@
+../../skills/setup-memory

data/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
   "author": {
     "name": "Valentino Stoll"

data/.lefthook/map_specs.rb

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Map changed Ruby files to their corresponding spec files
+# Usage: .lefthook/map_specs.rb
+# Returns: Space-separated list of spec files to run
+
+changed_files = `git diff --cached --name-only --diff-filter=ACM`.split("\n")
+ruby_files = changed_files.select { |f| f.end_with?(".rb") && f.start_with?("lib/") }
+
+# Map lib/ files to their spec/ equivalents
+specs = ruby_files.map do |file|
+  # lib/claude_memory/foo/bar.rb → spec/claude_memory/foo/bar_spec.rb
+  file.sub("lib/", "spec/").sub(".rb", "_spec.rb")
+end.select { |spec| File.exist?(spec) }
+
+# Always run integration tests if core infrastructure changed
+critical_paths = [
+  "lib/claude_memory/store",
+  "lib/claude_memory/mcp",
+  "lib/claude_memory/hook"
+]
+
+if ruby_files.any? { |f| critical_paths.any? { |path| f.start_with?(path) } }
+  specs += Dir["spec/integration/*_spec.rb"] if Dir.exist?("spec/integration")
+end
+
+# Output unique spec files
+puts specs.uniq.join(" ")

data/CHANGELOG.md

@@ -4,16 +4,94 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-02-04
+
 ### Added
 
-### Changed
+**MCP Structured Content & Compact Mode**
+- Dual content (text summary) + structuredContent (JSON) for all MCP tools
+  - `TextSummary` module generates human-readable summaries alongside structured data
+  - Compact mode (`compact: true`) omits provenance receipts for ~60% smaller responses
+- MCP query guide prompt registered via `prompts/list` and `prompts/get` endpoints
+  - `QueryGuide` module provides tool selection guidance to Claude
+
+**Search & Retrieval Improvements**
+- Reciprocal Rank Fusion (RRF) replacing naive merge for hybrid search
+  - Better result ordering when combining FTS5 and semantic search results
+- Smart expansion detection to skip unnecessary vector search
+  - Reduces latency when FTS5 already provides strong matches
+- Enhanced snippet extraction for search results
+  - Better context windows around matched terms
+
+**Provenance & Traceability**
+- Line-range references in provenance for precise source linking
+  - Facts now track exact line ranges in source transcripts
+- Fact dependency graph visualization via BFS traversal
+  - Trace supersession and conflict chains between facts
+
+**User-Friendly Identifiers**
+- Docid short hash system for user-friendly fact references
+  - Short, memorable identifiers instead of raw integer IDs
+
+**Caching & Performance**
+- LLM response caching schema and store methods
+  - Cache layer for expensive extraction operations
+- Structured JSON logging with level filtering
+  - Configurable log levels (debug, info, warn, error)
+  - JSON format for machine-parseable log output
+
+**Ingestion & Content Processing**
+- Configurable tool capture filtering for ingestion
+  - Control which tool outputs are captured during transcript processing
+- ContentSanitizer now strips `system-reminder`, `local-command-caveat`, `command-message`,
+  `command-name`, and `command-args` tags in addition to privacy tags
+- Relative time formatting in MCP recall output
+  - Progressive format: just now → Xm ago → Xh ago → Xd ago → YYYY-MM-DD
 
-### Fixed
+**Developer Tools**
+- `--brief` flag for doctor command and health checks in skills
+  - Quick pass/fail output for automated workflows
 
-### Documentation
+### Fixed
+- Preserve SQLite PRAGMAs across connection reconnects
+  - WAL mode and other pragmas now survive reconnection cycles
+- Timestamp-only churn in publish output
+  - Publish no longer regenerates files when only the timestamp changed
 
 ### Internal
 
+**Code Quality Improvements**
+- Extract duplicates and decompose long methods across codebase
+- Extract ingester transaction body into focused methods
+- Decompose `resolve_fact` into intention-revealing methods
+- Extract `check_setup` and `detailed_stats` into focused helpers
+- Fix N+1 query patterns in `recall.rb`
+- Fix 6 quick wins from quality review (frozen strings, method sizes, naming)
+
+**Research & Studies**
+- QMD restudy (2026-02-02): adopt Claude Code plugin format, MCP structured content pattern,
+  MCP query guide prompt, inline status checks
+- claude-supermemory study: adopt SessionStart hook context injection, tool-specific observation
+  compression, and relative time formatting
+
+## [0.4.0] - 2026-02-02
+
+### Added
+
+**Semantic Search with FastEmbed**
+- Integrated [fastembed-rb](https://github.com/khasinski/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
+
 ## [0.3.0] - 2026-01-29
 
 ### Added
@@ -41,9 +119,9 @@ All notable changes to this project will be documented in this file.
 - Configuration class for centralized ENV access and testability
 
 **Search & Recall**
-- `index` command to generate TF-IDF embeddings for semantic search
+- `index` command to generate embeddings for semantic search
 - Index command resumability with checkpoints (recover from interruption)
-- Semantic search capabilities using TF-IDF embeddings
+- Semantic search capabilities with embedding-based vector search
 - Improved full-text search with empty query handling
 
 **Session Intelligence**

data/CLAUDE.md

@@ -11,6 +11,10 @@ ClaudeMemory is a Ruby gem that provides long-term, self-managed memory for Clau
 - Sequel (~> 5.0) for database access
 - Extralite (~> 2.14) for high-performance SQLite storage
 
+## Working with This Codebase
+
+**Check memory before exploring code.** Use `memory.recall`, `memory.decisions`, `memory.architecture`, or `memory.conventions` to find existing knowledge before reading files.
+
 ## Development Commands
 
 ### Setup
@@ -49,6 +53,40 @@ bundle exec rake release # Tag + push to RubyGems (requires credentials)
 bundle exec claude-memory <command>
 ```
 
+### Evals
+```bash
+# Run automated evaluation suite (stub mode - fast, free)
+./bin/run-evals                # Run all evals with summary report
+
+# Run real eval validation (slow, costs ~$0.12)
+./bin/run-real-evals all       # Run all scenarios with real Claude
+./bin/run-real-evals convention_recall,tech_stack_recall  # Specific scenarios
+
+# Or run directly with RSpec
+bundle exec rspec spec/evals/  # Run all eval scenarios (stub mode)
+bundle exec rspec --tag eval   # Run only eval-tagged tests
+EVAL_MODE=real bundle exec rspec spec/evals/ --tag eval_real  # Real mode
+```
+
+The eval framework tests ClaudeMemory's effectiveness by comparing baseline (no memory) vs memory-enabled responses. See `spec/evals/README.md` for details, `spec/evals/REAL_MODE.md` for real Claude execution, and `spec/evals/CI_INTEGRATION.md` for GitHub Actions integration.
+
+### Benchmarks (DevMemBench)
+```bash
+# Run offline benchmarks - retrieval accuracy + truth maintenance ($0, ~8s)
+bundle exec rspec spec/benchmarks/ --tag benchmark --format documentation
+
+# Run all evals + benchmarks together
+./bin/run-evals --all
+
+# Run only benchmarks (skip evals)
+./bin/run-evals --benchmarks-only
+
+# End-to-end with real Claude (~$2-8)
+EVAL_MODE=real bundle exec rspec spec/benchmarks/e2e/ --tag eval_real
+```
+
+DevMemBench measures retrieval accuracy (Recall@k, MRR, nDCG@10) across 155 queries, truth maintenance correctness across 100 cases, and end-to-end Claude response quality across 31 scenarios. Semantic and hybrid retrieval use [fastembed-rb](https://github.com/khasinski/fastembed-rb) (BAAI/bge-small-en-v1.5, local ONNX, no API key). See `spec/benchmarks/README.md` for full details.
+
 ## Architecture
 
 ### Dual-Database System

data/README.md

@@ -206,6 +206,49 @@ The uninstall command removes:
 - 🏗️ [Architecture](docs/architecture.md) - Technical deep dive
 - 📝 [Changelog](CHANGELOG.md) - Release notes
 
+## Benchmarks
+
+ClaudeMemory includes **DevMemBench**, a developer-domain benchmark suite that measures retrieval quality and truth maintenance accuracy. All offline benchmarks run locally at zero cost.
+
+### Latest Results
+
+| Benchmark | Metric | Score |
+|-----------|--------|-------|
+| **Truth Maintenance** | Accuracy (100 cases) | **100%** |
+| **FTS5 Retrieval** | Recall@5 (40 easy queries) | **97.5%** |
+| **Semantic Retrieval** | Recall@5 (85 queries aggregate) | **78.6%** |
+| **Semantic Retrieval** | Recall@5 (40 medium queries) | **69.6%** |
+| **Hybrid Retrieval** | Recall@5 (100 queries aggregate) | **72.7%** |
+| **Hybrid Retrieval** | Recall@10 (20 hard queries) | **62.8%** |
+| **Scope Ranking** | Queries returning expected facts | **5/5** |
+
+Semantic and hybrid retrieval use [fastembed-rb](https://github.com/khasinski/fastembed-rb) with the BAAI/bge-small-en-v1.5 model (384-dim, runs locally, no API key needed).
+
+### What the benchmarks measure
+
+**Retrieval accuracy** -- Given a database of ~105 developer-domain facts across 5 simulated projects, how well does search find the right facts? Measured with standard IR metrics (Recall@k, MRR, nDCG@10) across 155 queries at varying difficulty levels (exact keyword match, semantic paraphrase, cross-category synthesis, abstention, temporal).
+
+**Truth maintenance** -- Given pairs of existing and incoming facts, does the resolver correctly determine the outcome? 100 FEVER-inspired cases test four outcomes: supersession (new stated fact replaces old), conflict (inferred fact contradicts stated), accumulation (multi-value predicates coexist), and corroboration (same fact adds provenance).
+
+**End-to-end with Claude** -- 31 scenarios across 5 LongMemEval ability categories (information extraction, multi-session reasoning, temporal reasoning, knowledge updates, abstention). Requires `EVAL_MODE=real` and costs ~$2-8 per run.
+
+### Running benchmarks
+
+```bash
+# Offline benchmarks ($0, ~8 seconds)
+bundle exec rspec spec/benchmarks/ --tag benchmark --format documentation
+
+# Full evals + benchmarks
+./bin/run-evals --all
+
+# End-to-end with real Claude (~$2-8)
+EVAL_MODE=real bundle exec rspec spec/benchmarks/e2e/ --tag eval_real
+```
+
+The benchmark dataset draws from real CLAUDE.md patterns and is designed specifically for ClaudeMemory's 6 predicates and 8 entity types. Open IR datasets (BEIR, FEVER, LongMemEval) informed the methodology but don't cover developer-domain knowledge.
+
+👉 **[Benchmark Details →](spec/benchmarks/README.md)**
+
 ## For Developers
 
 - **Language:** Ruby 3.2+

data/Rakefile

@@ -3,7 +3,20 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+# Parallel test execution for faster runs
+desc "Run specs in parallel"
+task :spec do
+  # Use parallel_rspec if available, fall back to regular rspec
+  if system("which parallel_rspec > /dev/null 2>&1")
+    sh "bundle exec parallel_rspec spec/"
+  else
+    puts "parallel_tests not installed, running sequentially"
+    sh "bundle exec rspec"
+  end
+end
+
+# Sequential test execution (for debugging)
+RSpec::Core::RakeTask.new(:spec_sequential)
 
 require "standard/rake"