claude_memory 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f05a4ccf0612b34b72ae1e2001278be3dd6dc569aa11a764589056f1117710cb
-  data.tar.gz: 252d4a50878ac81b9b5a1ee337f7524edd7a4562b305927891c69e6de13ec2f8
+  metadata.gz: 28dba99c7b0ed1cb18bdc6f8ff8c2a12e86f3b89be8cfbc2055f7d4dd82c8250
+  data.tar.gz: a40e938d1ceab94a386a3f676f6d56cbfa5914b8940ac8ca6165a551b5ff090d
 SHA512:
-  metadata.gz: 412f9099d2fa874c4136c23a01633bbf17bb5ede675d0c36a832e42af0900d80ec12409a82e65f45b8bad3b8d85c7e35d742195beee877db5b0092be6940367e
-  data.tar.gz: 200a79697ed133fbd15754845fbefd1f302fedd785487d4f5c4e56606e6cfabcbd3931e28d023561e1a5827b6242c09e3bbc10f2fa8cd9b624fdf6dd0b3f5767
+  metadata.gz: 6575064801648828b09cc17db9413d339c46767e27b9510e0b877c5e877c452ce142c9082459af5315dd4dbf516360ea73a3b23295603304454b171ba70798b1
+  data.tar.gz: d2841200827478e8e4dd2f6a3a2575541138ed3bf673e0f9d633d771363355bb95c2adf0c677a104022175769af04973543cce65f81223a736eba7c3630ca3d9

data/.claude/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- ClaudeMemory v0.5.1 -->
+<!-- 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

@@ -18,6 +18,11 @@
             "type": "command",
             "command": "claude-memory hook ingest",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook context",
+            "timeout": 5
           }
         ]
       }

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.1",
+  "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/CHANGELOG.md

@@ -4,6 +4,61 @@ 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

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

data/docs/improvements.md

@@ -1,104 +1,102 @@
 # Improvements to Consider
 
-*Updated: 2026-02-03 - Removed Docid Short Hash System, LLM Response Caching, Structured Logging (implemented)*
+*Updated: 2026-03-02 - Re-studied all 5 influencer repos + new KBS study. Added new items from episodic-memory, claude-mem, updated QMD/grepai/supermemory findings.*
 *Sources:*
-- *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system*
-- *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search*
-- *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search with vector embeddings*
-- *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory plugin*
-- *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (updated 2026-02-02)*
+- *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.2, studied 2026-03-02)*
+- *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15, studied 2026-03-02)*
+- *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search (v0.34.0, studied 2026-03-02)*
+- *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory (v2.0.0, studied 2026-03-02)*
+- *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (v1.1.0, studied 2026-03-02)*
+- *[MadBomber/kbs](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1, studied 2026-03-02)*
 
 This document contains only unimplemented improvements. Completed items are removed.
 
 ---
 
-## High Priority (QMD-Inspired)
+## High Priority
 
-### 1. Native Vector Storage (sqlite-vec) ⭐ CRITICAL
+### ~~1. Native Vector Storage (sqlite-vec)~~ ✅ Implemented 2026-03-04
 
-- **Value**: 10-100x faster KNN queries, enables larger fact databases
-- **QMD Proof**: Handles 10,000+ documents with sub-second vector queries
-- **Current Issue**: JSON embedding storage requires loading all facts, O(n) Ruby similarity calculation
-- **Solution**: sqlite-vec extension with native C KNN queries
-- **Implementation**:
-  - Schema migration v11: Create `facts_vec` virtual table using `vec0`
-  - Two-step query pattern (avoid JOINs - they hang with vec tables!)
-  - Update `Embeddings::Similarity` class
-  - Backfill existing embeddings
-- **Trade-off**: Adds native dependency (acceptable, well-maintained, cross-platform)
+Schema migration v12 with `facts_vec` virtual table (vec0, cosine distance). Two-step query pattern (KNN → batch hydration). VectorIndex class with native C KNN search, fallback to O(n) Ruby. Backfill via `claude-memory index --vec` and sweeper. Doctor check with coverage stats. Cross-platform: arm64-darwin, x86_64-darwin, x86_64-linux.
 
----
-
-## High Priority (Study-Inspired)
+### ~~2. Claude Code Plugin Distribution Format~~ ✅ Implemented 2026-03-04
 
-### 2. SessionStart Context Injection via Hook ⭐
+Plugin packaging with `plugin.json` referencing MCP server, hooks, skills, commands, and output styles. Wrapper scripts (`scripts/serve-mcp.sh`, `scripts/hook-runner.sh`) handle gem detection gracefully. Initializers detect plugin mode via `CLAUDE_PLUGIN_ROOT` and skip hooks/MCP/output-style config. Version sync Rake task keeps plugin metadata in sync with gem version.
 
-Source: claude-supermemory study
+---
 
-- **Value**: Guarantees Claude sees memory context immediately, supplements existing `.claude/rules/` publish
-- **Implementation**: Inject recalled facts into Claude's context at session start using `hookSpecificOutput.additionalContext`
-- **Evidence**: `context-hook.js:72-74` — uses hook response to inject `<supermemory-context>` XML
-- **Effort**: 1-2 days (hook handler, context formatter, settings)
+## Medium Priority
 
-### 3. Tool-Specific Observation Compression ⭐
+### 3. Incremental Indexing with File Watching
 
-Source: claude-supermemory study
+Source: grepai study (reinforced 2026-03-02)
 
-- **Value**: ~70% token reduction vs raw tool I/O in provenance descriptions
-- **Implementation**: Compact per-tool summarization for provenance (e.g., `Edited auth.js: "login()" → "async login()"`)
-- **Evidence**: `compress.js:13-75` — 10 tool handlers with human-readable output
-- **Effort**: 4-6 hours (class + tests + ingest integration)
+- **Value**: Eliminates manual `claude-memory ingest` calls
+- **Implementation**: Add `Listen` gem, watch `.claude/projects/*/transcripts/*.jsonl`, debounce 500ms, trigger IngestCommand automatically
+- **Evidence**: `watcher/watcher.go:30-59` — fsnotify with debouncing (300ms default), gitignore respect, event deduplication
+- **Effort**: 2-3 days
+- **Trade-off**: Background process ~10MB memory overhead
 
-### 4. Claude Code Plugin Distribution Format ⭐
+### 4. Document Chunking for Long Transcripts
 
-Source: QMD study
+Source: QMD study (updated 2026-03-02)
 
-- **Value**: 10x easier installation (one command vs multi-step gem + MCP + hook config)
-- **Implementation**: Package ClaudeMemory as marketplace plugin for single-command installation
-- **Evidence**: `.claude-plugin/marketplace.json` — complete plugin spec with MCP server bundling and skill definitions
+- **Value**: Better embeddings for long content (>3000 chars)
+- **Implementation**: 900 tokens/chunk, 15% overlap, markdown-aware break points
+- **Evidence**: QMD v1.1.0 `store.ts:53-219` — scored break point patterns (h1=100 → newline=1), code fence detection, squared distance decay
+- **Consideration**: Only if users report issues with long transcripts
 - **Effort**: 2-3 days
 
+### ~~5. Background Processing for Hooks~~ ✅ Implemented 2026-03-02
+
+`--async` flag on hook ingest/sweep/publish subcommands. Fork+detach for non-blocking execution, fallback to sync when fork unavailable.
+
 ---
 
-## Medium Priority
+## Low Priority / Defer
 
-### 5. Incremental Indexing with File Watching
+### 5. Signal-Based Ingestion Filtering
 
-Source: grepai study
+Source: claude-supermemory study (2026-03-02)
 
-- **Value**: Eliminates manual `claude-memory ingest` calls
-- **Implementation**: Add `Listen` gem, watch `.claude/projects/*/transcripts/*.jsonl`, debounce 500ms, trigger IngestCommand automatically
-- **Evidence**: `watcher/watcher.go:44` — `fsnotify` with debouncing (300ms default), gitignore respect
-- **Effort**: 2-3 days
-- **Trade-off**: Background process ~10MB memory overhead
+- **Value**: Reduce noise by prioritizing transcript sections with signal keywords
+- **Evidence**: supermemory `settings.json:signalKeywords` — keyword-triggered capture with context window
+- **Implementation**: During ingest, weight transcript sections containing signal keywords ("decided", "convention", "always", "never", "prefer") higher
+- **Effort**: 1-2 days
+- **Trade-off**: May miss important but subtly-expressed facts. Our distiller already extracts structured facts, which inherently filters noise.
+- **Recommendation**: DEFER — Distiller handles this naturally
 
-### 6. Background Processing for Hooks
+### 6. HTTP MCP Transport
 
-Source: episodic-memory study
+Source: QMD study (2026-03-02)
 
-- **Value**: Non-blocking hooks for better UX
-- **Implementation**: `--async` flag on hook commands, fork and detach
-- **Trade-off**: Background process management complexity, potential race conditions
+- **Value**: Shared server, models stay loaded, faster subsequent queries
+- **Evidence**: QMD `mcp.ts:119-137` — WebStandardStreamableHTTPServerTransport with daemon mode
+- **Implementation**: Add HTTP transport option alongside stdio
+- **Effort**: 2-3 days
+- **Trade-off**: Process management complexity
+- **Recommendation**: DEFER — Only if MCP startup latency becomes an issue
 
-### 7. Document Chunking for Long Transcripts
+### ~~7. MCP Discovery Tools~~ ✅ Implemented 2026-03-02
 
-Source: QMD study
+Added `memory.list_projects` MCP tool. Shows global DB, current project, and discovers other projects from promoted facts/global fact paths with stats.
 
-- **Value**: Better embeddings for long content (>3000 chars)
-- **Implementation**: 800 tokens, 15% overlap, semantic boundary detection
-- **Consideration**: Only if users report issues with long transcripts
+### ~~8. Database Compact Command~~ ✅ Implemented 2026-03-02
 
----
+Added `claude-memory compact` command. Runs SQLite VACUUM with optional integrity check (`--check`). Supports `--scope` for global/project/all. Reports size before/after with savings.
+
+### ~~9. Fact Export Command~~ ✅ Implemented 2026-03-02
+
+Added `claude-memory export` command. Dumps facts with entities and provenance to JSON. Supports `--scope`, `--status` (active/all), `--output` (file), `--pretty`. Includes version metadata for import compatibility.
 
 ---
 
 ## Features to Avoid
 
-- **Chroma Vector Database** — We use fastembed-rb with local ONNX model instead
+- **Chroma Vector Database** — We use fastembed-rb with local ONNX model. sqlite-vec is the better upgrade path (claude-mem uses Chroma, but QMD/episodic-memory prove sqlite-vec is simpler and sufficient)
 - **Claude Agent SDK for Distillation** — Direct API calls via `anthropic-rb` gem
-- **Worker Service Background Process** — Keep stdio-based MCP server
+- **Worker Service Background Process** — Keep stdio-based MCP server. claude-mem's worker architecture adds significant complexity and failure modes.
 - **Web Viewer UI** — CLI output is sufficient. Add if users request it
-- **Configuration-Driven Context** — Default config is sufficient. Add if users request it
 - **Neural Embeddings (EmbeddingGemma)** — Superseded by FastEmbed (BAAI/bge-small-en-v1.5)
 - **Cross-Encoder Reranking (Qwen3-Reranker-0.6B)** — Over-engineering for fact retrieval
 - **Query Expansion (LLM, Qwen3-1.7B)** — No LLM in recall path, too heavy
@@ -106,6 +104,19 @@ Source: QMD study
 - **YAML Collection System** — Our dual-database approach is cleaner
 - **Content-Addressable Storage** — Facts deduplicated by signature, not content hash
 - **Virtual Path System** — Dual-database provides clear namespace
+- **Cloud Storage Dependency** — Local-first is superior (supermemory's weakness)
+- **Tree-Sitter AST Code Navigation** — Out of scope for memory/fact retrieval (claude-mem's Smart Explore)
+- **RPG Semantic Code Graph** — Wrong domain; code structure graph vs fact knowledge graph (grepai)
+- **AGPL Licensing** — Too restrictive for developer tools (claude-mem)
+- **Multiple AI Providers (Gemini/OpenRouter)** — Over-engineering; anthropic-rb is sufficient
+- **Bubble Tea TUI** — CLI output is sufficient (grepai)
+- **Query Document Format (lex/vec/hyde)** — Over-engineering for fact retrieval (QMD)
+- **Team Memory via Cloud Sync** — Our dual-database handles scope well; cloud sync adds complexity (supermemory)
+- **Raw Conversation Storage** — We distill into structured facts (episodic-memory stores raw exchanges)
+- **KBS as Dependency (RETE inference engine)** — KBS (MadBomber/kbs) provides RETE inference, but solves a fundamentally different problem (forward-chaining rules vs knowledge recall). Architectural mismatch, schema incompatibility (JSON blobs vs normalized triples), performance regression (raw sqlite3 vs Sequel+Extralite), low adoption (2 stars, sole maintainer). See `docs/influence/kbs.md`.
+- **KBS Redis Backend** — Redis store adds operational complexity; SQLite + Extralite is fast enough for our use case
+- **KBS Message Queue** — Hook ordering already handles coordination; message queue adds unnecessary complexity
+- **KBS Declarative Rule DSL** — Expressive but wrong paradigm for knowledge recall; our query/search approach is more appropriate
 
 ---
 
@@ -127,12 +138,21 @@ Source: QMD study
 
 ## References
 
-- [episodic-memory GitHub](https://github.com/obra/episodic-memory) - Semantic conversation search
-- [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system
-- [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search
-- [claude-supermemory GitHub](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed memory
-- [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine
+- [episodic-memory GitHub](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15)
+- [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.2)
+- [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search (v0.34.0)
+- [claude-supermemory GitHub](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed memory (v2.0.0)
+- [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine (v1.1.0)
+- [KBS GitHub](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1)
+
+Influence documents:
+- [docs/influence/qmd.md](influence/qmd.md) - Updated 2026-03-02
+- [docs/influence/episodic-memory.md](influence/episodic-memory.md) - New 2026-03-02
+- [docs/influence/claude-mem.md](influence/claude-mem.md) - New 2026-03-02
+- [docs/influence/grepai.md](influence/grepai.md) - Updated 2026-03-02
+- [docs/influence/claude-supermemory.md](influence/claude-supermemory.md) - Updated 2026-03-02
+- [docs/influence/kbs.md](influence/kbs.md) - New 2026-03-02
 
 ---
 
-*Last updated: 2026-02-03 - Removed Docid, LLM Cache, Structured Logging (implemented). Renumbered items.*
+*Last updated: 2026-03-04 - Marked Claude Code Plugin Distribution Format as implemented. Previous: sqlite-vec (Native Vector Storage), Database Compact Command, Fact Export Command, Background Processing for Hooks (--async), MCP Discovery Tools (memory.list_projects), Hook Error Classification, Dynamic MCP Server Instructions, Progressive Disclosure Documentation, Conversation Exclusion Markers.*