claude_memory 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d32c7aa8093eedade1783eefa7109c996aa134d01dea01b67794612c126cf068
-  data.tar.gz: 78fe0f2ff602c740b6ab727a0fde88d07fb235f38b1143b644b4e7498f07079f
+  metadata.gz: 28dba99c7b0ed1cb18bdc6f8ff8c2a12e86f3b89be8cfbc2055f7d4dd82c8250
+  data.tar.gz: a40e938d1ceab94a386a3f676f6d56cbfa5914b8940ac8ca6165a551b5ff090d
 SHA512:
-  metadata.gz: be68b153e9e25ef3b8e5ad71ba7fdd89e5ace40f0848125b480bf35c96ad8b0a73b1fd891e59faf5807bc99d8d637f0c6d647e2b1d6c86ad0654b9df69c1ab45
-  data.tar.gz: 92ee3e92e7967e03f642a5736a84f70563dd6e9f00fc3a7b24714b97294348e35645cdbfdd4b760bc5ee21301bb869bccbc686050cbc95e2bf7399c38508a32e
+  metadata.gz: 6575064801648828b09cc17db9413d339c46767e27b9510e0b877c5e877c452ce142c9082459af5315dd4dbf516360ea73a3b23295603304454b171ba70798b1
+  data.tar.gz: d2841200827478e8e4dd2f6a3a2575541138ed3bf673e0f9d633d771363355bb95c2adf0c677a104022175769af04973543cce65f81223a736eba7c3630ca3d9

data/.claude/CLAUDE.md

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

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

@@ -1,7 +1,7 @@
 <!-- 
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-02-04T16:37:00Z
+  Generated: 2026-02-05T18:27:44Z
 -->
 
 # Project Memory

data/.claude/settings.json

@@ -5,7 +5,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "command": "claude-memory hook ingest",
             "timeout": 10
           }
         ]
@@ -16,8 +16,13 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "command": "claude-memory hook ingest",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook context",
+            "timeout": 5
           }
         ]
       }
@@ -27,12 +32,12 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "command": "claude-memory hook ingest",
             "timeout": 30
           },
           {
             "type": "command",
-            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "command": "claude-memory hook sweep",
             "timeout": 30
           }
         ]
@@ -43,12 +48,12 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "command": "claude-memory hook ingest",
             "timeout": 30
           },
           {
             "type": "command",
-            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "command": "claude-memory hook sweep",
             "timeout": 30
           }
         ]

data/.claude/settings.local.json

@@ -28,7 +28,15 @@
       "mcp__plugin_claude-memory_memory__memory_architecture",
       "mcp__plugin_claude-memory_memory__memory_recall_index",
       "Bash(./bin/run-evals:*)",
-      "WebSearch"
+      "WebSearch",
+      "mcp__memory__memory_check_setup",
+      "WebFetch(domain:docs.anthropic.com)",
+      "Bash(export PATH=\"$HOME/.bun/bin:/usr/bin:/bin:$PATH\")",
+      "Bash(qmd search:*)",
+      "Skill(study-repo)",
+      "WebFetch(domain:www.rubydoc.info)",
+      "Bash(git status:*)",
+      "WebFetch(domain:github.com)"
     ]
   },
   "enableAllProjectMcpServers": true

data/.claude-plugin/marketplace.json

@@ -1,13 +1,16 @@
 {
   "name": "claude-memory-marketplace",
   "owner": {
-    "name": "Valentino Stoll"
+    "name": "Valentino Stoll",
+    "email": "v@codenamev.com"
   },
   "plugins": [
     {
       "name": "claude-memory",
+      "version": "0.6.0",
       "source": "./",
-      "description": "Long-term self-managed memory for Claude Code"
+      "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
+      "repository": "https://github.com/codenamev/claude_memory"
     }
   ]
 }

data/.claude-plugin/plugin.json

@@ -1,10 +1,23 @@
 {
   "name": "claude-memory",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
   "author": {
-    "name": "Valentino Stoll"
+    "name": "Valentino Stoll",
+    "email": "v@codenamev.com"
   },
+  "homepage": "https://github.com/codenamev/claude_memory",
+  "repository": "https://github.com/codenamev/claude_memory",
   "license": "MIT",
-  "keywords": ["memory", "facts", "knowledge", "persistence"]
+  "keywords": ["memory", "facts", "knowledge", "persistence", "long-term-memory"],
+  "mcpServers": {
+    "memory": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/serve-mcp.sh",
+      "args": []
+    }
+  },
+  "hooks": "./hooks/hooks.json",
+  "skills": "./skills/",
+  "commands": "./commands/",
+  "outputStyles": "./output-styles/"
 }

data/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "memory": {
+      "type": "stdio",
+      "command": "claude-memory",
+      "args": ["serve-mcp"]
+    }
+  }
+}

data/CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-03-06
+
+### Added
+
+**Native Vector Storage (sqlite-vec)**
+- Integrated [sqlite-vec](https://github.com/asg017/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
+  - `bin/setup-competitors` for installing competitor tools
+  - `bin/run-evals --comparative` for side-by-side benchmarks
+
+### Fixed
+
+- **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 which handles initialization and access atomically.
+- **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 to handle future partition tables.
+- **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.
+- Fork-based concurrency tests skipped on Ruby 4.0+ (Extralite incompatibility)
+- Real eval tests now run in tmpdir with fixture database
+
+### Internal
+- Refactored publish to avoid unnecessary rewrites from timestamp churn
+- Skip quality-review hook when running inside Claude Code session
+- Influence studies for claude-mem, episodic-memory, kbs repositories
+
+## [0.5.1] - 2026-02-04
+
+### 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
+  - SQLite's busy_timeout doesn't reliably detect lock release; app-level retry compensates
+
+- **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)
+
 ## [0.5.0] - 2026-02-04
 
 ### Added

data/CLAUDE.md

@@ -87,6 +87,16 @@ 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.
 
+### Comparative Benchmarks
+```bash
+bin/setup-competitors              # Install QMD + grepai + dependencies (~3GB)
+bin/setup-competitors --check      # Show what's installed
+bin/setup-competitors --qmd-only   # Only install QMD + Bun
+bin/setup-competitors --grepai-only # Only install grepai + Ollama
+bin/run-evals --comparative        # Run benchmarks with available tools
+bin/run-evals --comparative --setup-competitors  # Install + run in one step
+```
+
 ## Architecture
 
 ### Dual-Database System
@@ -160,7 +170,9 @@ Transcripts → Ingest → Index (FTS5)
 - **`Ingest`**: Transcript reading and delta-based ingestion (`ingest/`)
   - Tracks cursor position per session to avoid re-processing
 
-- **`Index`**: Full-text search using SQLite FTS5 (`index/`)
+- **`Index`**: Full-text search and vector indexing (`index/`)
+  - `LexicalFTS`: SQLite FTS5 full-text search
+  - `VectorIndex`: sqlite-vec native KNN search with vec0 virtual tables
   - Optimized with batch queries to eliminate N+1 issues
 
 - **`Distill`**: Fact extraction interface (`distill/`)
@@ -184,8 +196,8 @@ 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
-  - Tools: recall, explain, promote, status, conflicts, changes, sweep_now
+  - Exposes memory tools to Claude Code (21 tools total)
+  - Dual content/structuredContent responses with compact mode
 
 - **`Hook`**: Hook entrypoint handlers (`hook/`)
   - Reads stdin JSON from Claude Code hooks
@@ -274,7 +286,7 @@ Single-value predicates (like "uses_database") supersede old values. Multi-value
 
 - `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 (20 commands)
+- `lib/claude_memory/commands/`: Individual command classes (22 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
@@ -289,31 +301,33 @@ 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 (18 total):
+Available MCP tools (21 total):
 - **Query & Recall**: `memory.recall`, `memory.recall_index`, `memory.recall_details`, `memory.recall_semantic`, `memory.search_concepts`
-- **Provenance**: `memory.explain`
+- **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`
 - **Monitoring**: `memory.status`, `memory.stats`, `memory.changes`, `memory.conflicts`
 - **Maintenance**: `memory.sweep_now`
-- **Setup**: `memory.check_setup`
+- **Discovery**: `memory.check_setup`, `memory.list_projects`
 
 ## Hook Integration
 
 ClaudeMemory integrates with Claude Code via hooks in `.claude/settings.json`:
 
-- **Ingest hook**: Triggers on Stop/SessionStart/PreCompact events
+- **Ingest hook**: Triggers on Stop/SessionStart/PreCompact/SessionEnd events
   - Calls `claude-memory hook ingest` with stdin JSON
   - Reads transcript delta and updates both global and project databases
 
-- **Sweep hook**: Triggers on idle_prompt and safety events
-  - Runs time-bounded maintenance on both databases
+- **Context hook**: Triggers on SessionStart
+  - Calls `claude-memory hook context`
+  - Injects recent facts via `hookSpecificOutput.additionalContext`
 
-- **Publish hook**: Optional, on SessionEnd/PreCompact
-  - Publishes curated snapshot to `.claude/rules/`
+- **Sweep hook**: Triggers on PreCompact/SessionEnd events
+  - Runs time-bounded maintenance on both databases
+  - Cleans up vec0 entries for superseded/expired facts
 
-Hook commands read JSON payloads from stdin for robustness.
+Hook commands read JSON payloads from stdin for robustness. Supports `--async` flag for non-blocking execution.
 
 ## Code Style
 

data/README.md

@@ -95,12 +95,16 @@ Claude: "Based on my memory, you're using Rails with PostgreSQL..."
 ## Key Features
 
 - **Dual Scope**: Project-specific + global user preferences
+- **Hybrid Search**: FTS5 full-text + semantic vector search with Reciprocal Rank Fusion
+- **Native Vector Storage**: [sqlite-vec](https://github.com/asg017/sqlite-vec) for fast KNN search with local embeddings ([fastembed-rb](https://github.com/khasinski/fastembed-rb), no API key)
+- **Session Context**: Automatic context injection at session start with recent facts
 - **Privacy First**: `<private>` tags exclude sensitive data
 - **Progressive Disclosure**: Lightweight queries before full details
 - **Semantic Shortcuts**: Quick access to decisions, conventions, architecture
 - **Truth Maintenance**: Automatic conflict resolution
 - **Claude-Powered**: Uses Claude's intelligence to extract facts (no API key needed)
 - **Token Efficient**: 10x reduction in memory queries with progressive disclosure
+- **Database Maintenance**: Compact, export, and backup commands
 
 ## Privacy Control
 
@@ -169,10 +173,10 @@ claude-memory doctor
 This checks:
 - Database existence and integrity
 - Schema version compatibility
+- sqlite-vec availability and index coverage
 - Hooks configuration
 - Snapshot status
 - Stuck operations
-- Orphaned hooks (hooks without MCP configuration)
 
 ### Uninstalling
 
@@ -253,7 +257,7 @@ The benchmark dataset draws from real CLAUDE.md patterns and is designed specifi
 
 - **Language:** Ruby 3.2+
 - **Storage:** SQLite3 (no external services)
-- **Testing:** 985 examples, 100% core coverage
+- **Testing:** 1316 examples, 100% core coverage
 - **Code Style:** Standard Ruby
 
 ```bash

data/Rakefile

@@ -20,4 +20,26 @@ RSpec::Core::RakeTask.new(:spec_sequential)
 
 require "standard/rake"
 
+namespace :plugin do
+  desc "Sync ClaudeMemory::VERSION into .claude-plugin/plugin.json and marketplace.json"
+  task :sync_version do
+    require_relative "lib/claude_memory/version"
+    version = ClaudeMemory::VERSION
+
+    %w[.claude-plugin/plugin.json .claude-plugin/marketplace.json].each do |path|
+      next unless File.exist?(path)
+
+      content = File.read(path)
+      updated = content.gsub(/"version"\s*:\s*"[^"]*"/, "\"version\": \"#{version}\"")
+
+      if content != updated
+        File.write(path, updated)
+        puts "Updated #{path} to version #{version}"
+      else
+        puts "#{path} already at version #{version}"
+      end
+    end
+  end
+end
+
 task default: %i[spec standard]

data/db/migrations/011_add_tool_call_summaries.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Migration v11: Add compressed_summary to tool_calls
+# Stores human-readable summaries of tool observations
+# e.g., "Edited auth.rb: 'def login' → 'def async_login'"
+Sequel.migration do
+  up do
+    alter_table(:tool_calls) do
+      add_column :compressed_summary, String, text: true
+    end
+  end
+
+  down do
+    alter_table(:tool_calls) do
+      drop_column :compressed_summary
+    end
+  end
+end

data/db/migrations/012_add_vec_indexing_support.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Migration v12: Add vec_indexed_at tracking column to facts
+# Tracks which facts have been populated in the facts_vec virtual table.
+# The facts_vec virtual table itself is created lazily at runtime
+# because the sqlite-vec extension must be loaded before CREATE VIRTUAL TABLE.
+Sequel.migration do
+  up do
+    alter_table(:facts) do
+      add_column :vec_indexed_at, String, text: true
+    end
+  end
+
+  down do
+    alter_table(:facts) do
+      drop_column :vec_indexed_at
+    end
+  end
+end