claude_memory 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28dba99c7b0ed1cb18bdc6f8ff8c2a12e86f3b89be8cfbc2055f7d4dd82c8250
-  data.tar.gz: a40e938d1ceab94a386a3f676f6d56cbfa5914b8940ac8ca6165a551b5ff090d
+  metadata.gz: bfbba4c01acb3ad07b9114c6781ee7b6dbb197007ff61c72d7fa8b2ec164643e
+  data.tar.gz: 41df94bae4dc18bd00321ebca1fc80145faa6b180bb3ec00ff3d72a8cf091041
 SHA512:
-  metadata.gz: 6575064801648828b09cc17db9413d339c46767e27b9510e0b877c5e877c452ce142c9082459af5315dd4dbf516360ea73a3b23295603304454b171ba70798b1
-  data.tar.gz: d2841200827478e8e4dd2f6a3a2575541138ed3bf673e0f9d633d771363355bb95c2adf0c677a104022175769af04973543cce65f81223a736eba7c3630ca3d9
+  metadata.gz: f9e8278553ef1ba3c6d490304c9118c519612d5c6cd61230e94dc0dccca40ef653118e7c364e35ba2e58b2fb66d6b7fea39455f12723df6ddf8a8a9d55bc4d71
+  data.tar.gz: db870500e372150fbb6133ce43396aa57c2338e9aa392939219c4e2435d8bcaaac0724f858f387c97c3c9187a7b1409268b7246d91ad6018324935089daa149e

data/.claude/CLAUDE.md

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

data/.claude/settings.local.json

@@ -36,7 +36,17 @@
       "Skill(study-repo)",
       "WebFetch(domain:www.rubydoc.info)",
       "Bash(git status:*)",
-      "WebFetch(domain:github.com)"
+      "WebFetch(domain:github.com)",
+      "mcp__memory__memory_stats",
+      "mcp__memory__memory_recall_index",
+      "Bash(mkdir -p /tmp/study-repos)",
+      "Read(//tmp/**)",
+      "Bash(ls:*)",
+      "Bash(sort -k2 -rn)",
+      "Bash(claude-memory recall:*)",
+      "Bash(claude-memory stats:*)",
+      "Bash(claude-memory search:*)",
+      "Bash(bundle exec:*)"
     ]
   },
   "enableAllProjectMcpServers": true

data/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.6.0",
+      "version": "0.7.0",
       "source": "./",
       "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,6 +1,6 @@
 {
   "name": "claude-memory",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
   "author": {
     "name": "Valentino Stoll",

data/.gitattributes

@@ -0,0 +1 @@
+.claude/memory.sqlite3* filter=lfs diff=lfs merge=lfs -text

data/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-03-12
+
+### 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 `Sequel::DatabaseError`, `Extralite::Error`, `IOError`)
+- 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 to pass `project_path`/`scope` as parameters instead of instance variables (better thread safety)
+- `SnippetExtractor` refactored to eliminate duplication between `extract` and `extract_with_lines`
+- `StoreManager.promote_fact` inlined `copy_provenance` for single-transaction safety
+- Influence study: QMD v2.0.1 SDK-first architecture analysis
+
 ## [0.6.0] - 2026-03-06
 
 ### Added

data/CLAUDE.md

@@ -133,7 +133,7 @@ Transcripts → Ingest → Index (FTS5)
   - Each command is a separate class (HelpCommand, DoctorCommand, etc.)
   - All commands inherit from BaseCommand
   - Dependency injection for I/O (stdout, stderr, stdin)
-  - 20 commands total, each focused on single responsibility
+  - 22 commands total, each focused on single responsibility
 
 - **`Configuration`**: Centralized ENV access (`configuration.rb`)
   - Single source of truth for paths and environment variables

data/README.md

@@ -257,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:** 1316 examples, 100% core coverage
+- **Testing:** 1435 examples, 100% core coverage
 - **Code Style:** Standard Ruby
 
 ```bash

data/docs/improvements.md

@@ -1,13 +1,13 @@
 # Improvements to Consider
 
-*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.*
+*Updated: 2026-03-10 - Re-studied QMD (v2.0.1, up from v1.1.5). New findings: SDK-first architecture, dedicated Maintenance class, dynamic MCP instructions enhancement, embedded skill distribution, REST API endpoint. Other 5 repos unchanged since 2026-03-09.*
 *Sources:*
-- *[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)*
+- *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.5, studied 2026-03-09)*
+- *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15, studied 2026-03-09)*
+- *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search (latest, studied 2026-03-09)*
+- *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory (v2.0.1, studied 2026-03-09)*
+- *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (v2.0.1, studied 2026-03-10)*
+- *[MadBomber/kbs](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1, studied 2026-03-09 — no changes)*
 
 This document contains only unimplemented improvements. Completed items are removed.
 
@@ -23,11 +23,137 @@ Schema migration v12 with `facts_vec` virtual table (vec0, cosine distance). Two
 
 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.
 
+### 3. Intent Parameter for Recall ⭐
+
+Source: QMD v1.1.5 study (2026-03-09)
+
+- **Value**: Disambiguate ambiguous queries (e.g., "database" with intent "migration" vs "performance")
+- **Implementation**: Add `intent` param to `Recall#query`, `DualQueryTemplate`, and MCP recall tools. Intent steers expansion/reranking but doesn't replace the query itself. Weight differently per stage (0.5x for chunk selection, 0.3x for snippets)
+- **Evidence**: QMD `store.ts:3103-3110` — disables BM25 shortcut when intent provided; `llm.ts:993-994` — expansion prompt includes intent; `store.ts:2383-2384` — intent prepended to rerank query
+- **Effort**: 2-3 days
+- **Recommendation**: ADOPT
+
+### ~~4. MCP Tool Annotations~~ ✅ Implemented 2026-03-09
+
+Added `readOnlyHint`, `idempotentHint`, `destructiveHint` annotations to all 21 MCP tools via shared constants (READ_ONLY, WRITE, WRITE_IDEMPOTENT). 17 query tools marked read-only, store_extraction/sweep_now as write, promote as write-idempotent.
+
+### 5. Retrieval Score Traces ⭐
+
+Source: QMD v1.1.5 study (2026-03-09)
+
+- **Value**: Transparency into why facts were retrieved — FTS score, vector similarity, RRF contribution, final blend
+- **Implementation**: Add optional `explain: true` param to recall tools, return score breakdown per result. Enhances `memory.explain` and `memory.recall_details`
+- **Evidence**: QMD `store.ts:2477-2540` — `--explain` flag with per-document RRF contribution traces
+- **Effort**: 2 days
+- **Recommendation**: ADOPT
+
+### ~~6. MCP Stdout Protection Audit~~ ✅ Implemented 2026-03-09
+
+ServeMcpCommand captures real stdout for MCP transport, redirects `$stdout` to `$stderr` during serve. Accidental puts/print from gems goes to stderr. Restore via ensure block.
+
+### ~~7. Worktree-Aware Git Root Detection~~ ✅ Implemented 2026-03-09
+
+Configuration#project_dir uses `git rev-parse --git-common-dir` to resolve main repo root across worktrees. `CLAUDE_MEMORY_ISOLATE_WORKTREES` env var opts into per-worktree isolation. Uses Open3.capture2 with graceful fallback to Dir.pwd.
+
+### 8. Search Agent Delegation Pattern ⭐
+
+Source: episodic-memory study (2026-03-09)
+
+- **Value**: Save 50-100x main-agent context by delegating memory search to a subagent that chains recall → explain → fact_graph
+- **Implementation**: Create `agents/memory-recall.md` subagent definition in plugin that chains our MCP tools and synthesizes results
+- **Evidence**: episodic-memory `agents/search-conversations.md:1-162` — subagent-delegated search pattern
+- **Effort**: 1-2 days
+- **Recommendation**: ADOPT
+
+### ~~9. Self-Excluding Agent Conversations~~ ✅ Implemented 2026-03-09
+
+Added `SELF_CONTEXT_MARKER` constant (`claude-memory-self`) to ClaudeMemory module. Added to ingester EXCLUSION_TAGS. Transcripts containing `<claude-memory-self>` are skipped entirely, preventing meta-conversation pollution.
+
+### 10. Dedicated Maintenance Class ⭐
+
+Source: QMD v2.0.1 study (2026-03-10)
+
+- **Value**: Clean separation of maintenance operations from main store with return counts. QMD's `Maintenance` class wraps 6 cleanup operations (vacuum, orphaned content/vectors, LLM cache, inactive docs, clear embeddings)
+- **Implementation**: Extract `Sweep` module operations into a `Maintenance` class. Methods: `vacuum`, `cleanup_orphaned_vectors`, `cleanup_expired_facts`, `cleanup_superseded_facts`, `compact`. Return affected counts for reporting
+- **Evidence**: QMD `src/maintenance.ts:1-54` — constructor takes internal store, each method returns affected count
+- **Effort**: 1 day
+- **Recommendation**: ADOPT
+
+### 11. Dynamic MCP Instructions Enhancement ⭐
+
+Source: QMD v2.0.1 study (2026-03-10)
+
+- **Value**: QMD v2.0 builds rich MCP server instructions with collection stats, document counts, capability gaps, search examples, and retrieval workflow tips. Our MCP server has a static query guide prompt but no dynamic instructions
+- **Implementation**: Add `build_instructions` to MCP server that generates dynamic instructions with: fact counts (global/project), active conflict count, recent decision count, convention count, database health, and usage tips
+- **Evidence**: QMD `src/mcp/server.ts:92-152` — `buildInstructions()` with collections, counts, gaps, examples, tips
+- **Effort**: 1 day
+- **Recommendation**: ADOPT
+
+### 12. Embedded Skill Distribution ⭐
+
+Source: QMD v2.0.1 study (2026-03-10)
+
+- **Value**: `qmd skill install` copies packaged skill files to `~/.claude/commands/` — zero-config setup. Skills are embedded as base64 in source code and extracted at install time
+- **Implementation**: Add `claude-memory install-skill` command that writes our memory recall agent to `~/.claude/commands/memory-recall.md`. Embed skill content in a Ruby constant. Pairs with Search Agent Delegation Pattern (#8)
+- **Evidence**: QMD `src/embedded-skills.ts:1-22` — base64-encoded SKILL.md + references; CLI `skill install` command
+- **Effort**: 1-2 days
+- **Recommendation**: ADOPT
+
+### 13. Structured Error Classification
+
+Source: claude-supermemory v2.0.1 study (2026-03-09)
+
+- **Value**: Clean error handling in MCP server and hooks — benign errors silent, retryable logged, fatal with clear messages
+- **Implementation**: Three-tier classification: benign (empty results, first use), retryable (rate limits, server errors), fatal (auth failures, schema corruption)
+- **Evidence**: supermemory `src/lib/error-helpers.js:1-72` — error classification with user-friendly messages
+- **Effort**: 1 day
+- **Recommendation**: ADOPT
+
+### 14. Entity Context Extraction Prompts
+
+Source: claude-supermemory v2.0.1 study (2026-03-09)
+
+- **Value**: Structured prompt templates for distiller defining what to extract (decisions, preferences, conventions) vs what to skip
+- **Implementation**: Apply when replacing NullDistiller. Rich prompt with concrete examples in table format, separate personal vs repo context
+- **Evidence**: supermemory `src/lib/supermemory-client.js:21-58` — extraction prompts with examples
+- **Effort**: 1-2 days (when building real distiller)
+- **Recommendation**: ADOPT — template for distiller replacement
+
 ---
 
 ## Medium Priority
 
-### 3. Incremental Indexing with File Watching
+### 15. Shell Completion for CLI
+
+Source: grepai study (2026-03-09)
+
+- **Value**: Tab completion for commands and flags in zsh/bash
+- **Implementation**: Generate completion scripts from OptionParser. Dynamic completions for project names
+- **Evidence**: grepai `cli/completion.go` — static + dynamic completions
+- **Effort**: 1-2 days
+- **Recommendation**: CONSIDER
+
+### 16. Content-Addressed Deduplication for Embeddings
+
+Source: grepai study (2026-03-09)
+
+- **Value**: Skip re-embedding unchanged content using existing `text_hash` in `content_items`
+- **Implementation**: Check `text_hash` before computing embeddings; reuse cached vectors for identical content
+- **Evidence**: grepai `store/store.go:105-109` — EmbeddingCache interface
+- **Effort**: 1 day
+- **Recommendation**: CONSIDER — quick win, infrastructure already exists
+
+### 17. Deduplication Before Vector Scoring
+
+Source: QMD v1.1.5 study (2026-03-09)
+
+- **Value**: Free performance win — deduplicate fact texts before computing cosine similarity, map scores back
+- **Implementation**: In `VectorIndex#search`, group facts by text, score unique texts only, fan out results
+- **Evidence**: QMD `llm.ts:1098-1109` — reranker deduplication (identical chunks scored once, fanned out)
+- **Effort**: 1 day
+- **Recommendation**: CONSIDER
+
+### 18. Incremental Indexing with File Watching
 
 Source: grepai study (reinforced 2026-03-02)
 
@@ -37,7 +163,7 @@ Source: grepai study (reinforced 2026-03-02)
 - **Effort**: 2-3 days
 - **Trade-off**: Background process ~10MB memory overhead
 
-### 4. Document Chunking for Long Transcripts
+### 19. Document Chunking for Long Transcripts
 
 Source: QMD study (updated 2026-03-02)
 
@@ -55,7 +181,18 @@ Source: QMD study (updated 2026-03-02)
 
 ## Low Priority / Defer
 
-### 5. Signal-Based Ingestion Filtering
+### 20. REST API Endpoint
+
+Source: QMD v2.0.1 study (2026-03-10)
+
+- **Value**: POST `/query` alongside MCP — enables search from curl, scripts, CI, and non-MCP clients without the full MCP protocol handshake
+- **Implementation**: Add optional HTTP server mode to `claude-memory serve-mcp --http` with POST `/recall` endpoint. Accept `{ query, scope, limit }`, return JSON facts
+- **Evidence**: QMD `src/mcp/server.ts:626-675` — `/query` and `/search` endpoints with structured JSON
+- **Effort**: 2 days
+- **Trade-off**: Requires WEBrick or similar Ruby HTTP server dependency
+- **Recommendation**: CONSIDER — Useful for CI/scripting, but MCP covers primary use case
+
+### 21. Signal-Based Ingestion Filtering
 
 Source: claude-supermemory study (2026-03-02)
 
@@ -66,7 +203,7 @@ Source: claude-supermemory study (2026-03-02)
 - **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. HTTP MCP Transport
+### 22. HTTP MCP Transport
 
 Source: QMD study (2026-03-02)
 
@@ -117,6 +254,13 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
 - **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
+- **Mode/Domain System** — claude-mem v10.5.5 adds JSON-based mode profiles for domain-specific observation types. Our SPO fact model already generalizes across domains; only pursue if users request domain-specific support
+- **Config Inheritance Pattern** — claude-mem's `parent--override` naming with deep merge. Not enough configuration variants to justify the complexity
+- **HMAC Request Signing** — supermemory's `validate.js` uses HMAC but hardcodes the secret in a minified bundle. Security through obscurity, and we have no cloud API to protect
+- **Codebase Indexing Command** — supermemory's `/index` actively explores codebases. Our hook-based passive capture is more appropriate; active indexing risks generating low-quality facts from code structure
+- **SDK-First Architecture Refactor** — QMD v2.0 refactored to SDK-first with `QMDStore` interface consumed by CLI and MCP. Our gem + MCP architecture is already well-structured; major refactor for marginal gain
+- **Write-Through YAML Config** — QMD v2.0 writes collection mutations to both SQLite and YAML. We don't use YAML config; dual-database is our config model
+- **Multi-Session HTTP Transport** — QMD v2.0 supports concurrent MCP sessions via session map. Our MCP server is lightweight enough for stdio; no model loading latency to amortize
 
 ---
 
@@ -139,20 +283,20 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
 ## References
 
 - [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)
+- [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.5)
+- [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search (latest)
+- [claude-supermemory GitHub](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed memory (v2.0.1)
+- [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine (v2.0.1)
 - [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
+- [docs/influence/qmd.md](influence/qmd.md) - Updated 2026-03-10
+- [docs/influence/episodic-memory.md](influence/episodic-memory.md) - Updated 2026-03-09
+- [docs/influence/claude-mem.md](influence/claude-mem.md) - Updated 2026-03-09
+- [docs/influence/grepai.md](influence/grepai.md) - Updated 2026-03-09
+- [docs/influence/claude-supermemory.md](influence/claude-supermemory.md) - Updated 2026-03-09
+- [docs/influence/kbs.md](influence/kbs.md) - Updated 2026-03-09 (no changes)
 
 ---
 
-*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.*
+*Last updated: 2026-03-10 - Re-studied QMD (v2.0.1). Added 3 new high-priority items: Dedicated Maintenance Class (#10), Dynamic MCP Instructions Enhancement (#11), Embedded Skill Distribution (#12). Added 1 medium-priority item: REST API Endpoint (#20). Previously: Implemented 4 features: MCP Tool Annotations (#4), MCP Stdout Protection (#6), Worktree-Aware Git Root (#7), Self-Excluding Conversations (#9). Re-studied all 6 influencer repos. Previous: Claude Code Plugin Distribution Format, sqlite-vec, Database Compact, Fact Export, Background Processing, MCP Discovery Tools.*