claude_memory 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfbba4c01acb3ad07b9114c6781ee7b6dbb197007ff61c72d7fa8b2ec164643e
-  data.tar.gz: 41df94bae4dc18bd00321ebca1fc80145faa6b180bb3ec00ff3d72a8cf091041
+  metadata.gz: 00a7e67707543e2a5266200eab3a276a5b70d25a41ebbc8a5eab8767c44952a8
+  data.tar.gz: 261f86e807d5638739a7462872ae9f5472451afd7aea5496c1cf785b54a76dc6
 SHA512:
-  metadata.gz: f9e8278553ef1ba3c6d490304c9118c519612d5c6cd61230e94dc0dccca40ef653118e7c364e35ba2e58b2fb66d6b7fea39455f12723df6ddf8a8a9d55bc4d71
-  data.tar.gz: db870500e372150fbb6133ce43396aa57c2338e9aa392939219c4e2435d8bcaaac0724f858f387c97c3c9187a7b1409268b7246d91ad6018324935089daa149e
+  metadata.gz: 79ffe3d19420ae16dd26e2083a45c3725be43fd955bf707e3a1e157e04d790821cd5d199b8c67ea713c354c82314a931af1883d260a430119f2eb72213d8cc16
+  data.tar.gz: 864fffbf37c36d63a3a72e19f56ce7f288c26b7d6b546e55338ea0fb61fc963fb99704be28124e33fbb49d5098c3997409ecdac13735fd9cd52253b545346f4b

data/.claude/settings.local.json

@@ -46,7 +46,9 @@
       "Bash(claude-memory recall:*)",
       "Bash(claude-memory stats:*)",
       "Bash(claude-memory search:*)",
-      "Bash(bundle exec:*)"
+      "Bash(bundle exec:*)",
+      "Skill(improve)",
+      "Skill(improve:*)"
     ]
   },
   "enableAllProjectMcpServers": true

data/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.7.0",
+      "version": "0.7.1",
       "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.7.0",
+  "version": "0.7.1",
   "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
   "author": {
     "name": "Valentino Stoll",
@@ -16,7 +16,6 @@
       "args": []
     }
   },
-  "hooks": "./hooks/hooks.json",
   "skills": "./skills/",
   "commands": "./commands/",
   "outputStyles": "./output-styles/"

data/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.7.1] - 2026-03-17
+
+### 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)
+
 ## [0.7.0] - 2026-03-12
 
 ### Added

data/CLAUDE.md

@@ -24,13 +24,15 @@ bin/setup              # Install dependencies
 
 ### Testing
 ```bash
-bundle exec rspec                              # Run all tests
+bundle exec rspec                              # Run unit/integration tests (~76s)
 bundle exec rspec spec/claude_memory/cli_spec.rb  # Run single test file
 bundle exec rspec spec/claude_memory/cli_spec.rb:42  # Run specific test by line number
 bundle exec rake spec                          # Alternative test command
 bundle exec rake                               # Run tests + Standard linter (default task)
 ```
 
+**Note:** Benchmarks and evals are excluded from the default `rspec` run via `.rspec`. See the [Evals](#evals) and [Benchmarks](#benchmarks-devmembench) sections for running those separately.
+
 ### Linting
 ```bash
 bundle exec rake standard        # Run Standard Ruby linter

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:** 1435 examples, 100% core coverage
+- **Testing:** 1477 examples (1375 unit/integration + 102 benchmarks/evals), 100% core coverage
 - **Code Style:** Standard Ruby
 
 ```bash

data/docs/improvements.md

@@ -1,6 +1,6 @@
 # Improvements to Consider
 
-*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.*
+*Updated: 2026-03-16 - Implemented 4 features: Dynamic MCP Instructions (#11), Structured Error Classification (#16), Content-Addressed Dedup for Embeddings (#19), Dedup Before Vector Scoring (#20). Studied lossless-claw (v0.3.0). Other 6 repos unchanged since 2026-03-10.*
 *Sources:*
 - *[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)*
@@ -8,6 +8,7 @@
 - *[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)*
+- *[martian-engineering/lossless-claw](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.3.0, studied 2026-03-16)*
 
 This document contains only unimplemented improvements. Completed items are removed.
 
@@ -69,25 +70,13 @@ Source: episodic-memory study (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 ⭐
+### ~~10. Dedicated Maintenance Class~~ ✅ Implemented 2026-03-16
 
-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
+Extracted `Sweep::Maintenance` class from Sweeper with 8 individual operations, each returning affected counts: `expire_proposed_facts`, `expire_disputed_facts`, `prune_orphaned_provenance`, `prune_old_content`, `backfill_vec_index`, `cleanup_vec_expired`, `checkpoint_wal`, `vacuum`. Sweeper now delegates to Maintenance internally.
 
-### 11. Dynamic MCP Instructions Enhancement ⭐
-
-Source: QMD v2.0.1 study (2026-03-10)
+### ~~11. Dynamic MCP Instructions Enhancement~~ ✅ Implemented 2026-03-16
 
-- **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
+Enhanced InstructionsBuilder with knowledge summary (decision/convention/entity counts by predicate pattern), vec availability detection, and dynamic usage tips that adapt based on available capabilities. Semantic search guidance included when sqlite-vec is loaded.
 
 ### 12. Embedded Skill Distribution ⭐
 
@@ -99,17 +88,29 @@ Source: QMD v2.0.1 study (2026-03-10)
 - **Effort**: 1-2 days
 - **Recommendation**: ADOPT
 
-### 13. Structured Error Classification
+### 13. Depth-Aware Prompt Templates for Distiller ⭐
 
-Source: claude-supermemory v2.0.1 study (2026-03-09)
+Source: lossless-claw v0.3.0 study (2026-03-16)
 
-- **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
+- **Value**: Graduated extraction prompts based on context depth — fresh conversations get detailed extraction, well-established facts get consolidation prompts. Parallels lossless-claw's leaf/d1/d2/d3+ prompt hierarchy
+- **Implementation**: Create prompt templates for distiller stages: initial extraction (detailed), re-extraction (consolidation), contradiction resolution (focused). Use depth/freshness to select template
+- **Evidence**: `tui/prompts/leaf.tmpl`, `tui/prompts/condensed-d1.tmpl`, `condensed-d2.tmpl`, `condensed-d3.tmpl` — four distinct prompt templates with increasing abstraction
+- **Effort**: 1-2 days (when building real distiller)
 - **Recommendation**: ADOPT
 
-### 14. Entity Context Extraction Prompts
+### ~~14. Three-Level Escalation for Sweep/Maintenance~~ ✅ Implemented 2026-03-16
+
+Added `run_with_escalation!` to Sweeper: normal (standard TTLs) → aggressive (halved TTLs) → fallback (force-expire oldest 10 proposed/disputed). Stats include `:escalation_level`. MCP `memory.sweep_now` gains `escalate: true` parameter. TextSummary shows escalation level in output.
+
+### ~~15. Tool Escalation Workflow in MCP Instructions~~ ✅ Implemented 2026-03-16
+
+Restructured QueryGuide with 4-tier escalation hierarchy (Fast Lookup → Broad Search → Targeted Deep Dive → Relationship Exploration). Each tool annotated with cost estimates (tokens per call). Added "Recommended Workflow" section. InstructionsBuilder usage hint updated with escalation guidance.
+
+### ~~16. Structured Error Classification~~ ✅ Implemented 2026-03-16
+
+Added `MCP::ErrorClassifier` with three-tier classification: benign (empty results, first use — no alarm), retryable (DB locked, I/O errors — retry flag), fatal (disk full, corruption — recommendations). MCP tools use classified errors with severity, retry hints, and actionable recommendations.
+
+### 17. Entity Context Extraction Prompts
 
 Source: claude-supermemory v2.0.1 study (2026-03-09)
 
@@ -123,7 +124,7 @@ Source: claude-supermemory v2.0.1 study (2026-03-09)
 
 ## Medium Priority
 
-### 15. Shell Completion for CLI
+### 18. Shell Completion for CLI
 
 Source: grepai study (2026-03-09)
 
@@ -133,27 +134,15 @@ Source: grepai study (2026-03-09)
 - **Effort**: 1-2 days
 - **Recommendation**: CONSIDER
 
-### 16. Content-Addressed Deduplication for Embeddings
+### ~~19. Content-Addressed Deduplication for Embeddings~~ ✅ Implemented 2026-03-16
 
-Source: grepai study (2026-03-09)
+IndexCommand builds text→embedding cache from already-embedded facts before indexing. Identical fact texts reuse cached vectors, skipping generation. Cache hits tracked and reported (e.g., "Cache hits: 3/10 (30% dedup)").
 
-- **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
+### ~~20. Deduplication Before Vector Scoring~~ ✅ Implemented 2026-03-16
 
-### 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
+In Ruby fallback path (`search_by_vector_fallback`), facts are grouped by `embedding_json` before cosine similarity computation. Unique embeddings scored once, results fanned out to all matching fact_ids. Native sqlite-vec path unaffected (handles own dedup).
 
-### 18. Incremental Indexing with File Watching
+### 21. Incremental Indexing with File Watching
 
 Source: grepai study (reinforced 2026-03-02)
 
@@ -163,7 +152,7 @@ Source: grepai study (reinforced 2026-03-02)
 - **Effort**: 2-3 days
 - **Trade-off**: Background process ~10MB memory overhead
 
-### 19. Document Chunking for Long Transcripts
+### 22. Document Chunking for Long Transcripts
 
 Source: QMD study (updated 2026-03-02)
 
@@ -181,7 +170,7 @@ Source: QMD study (updated 2026-03-02)
 
 ## Low Priority / Defer
 
-### 20. REST API Endpoint
+### 23. REST API Endpoint
 
 Source: QMD v2.0.1 study (2026-03-10)
 
@@ -192,7 +181,7 @@ Source: QMD v2.0.1 study (2026-03-10)
 - **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
+### 24. Signal-Based Ingestion Filtering
 
 Source: claude-supermemory study (2026-03-02)
 
@@ -203,7 +192,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
 
-### 22. HTTP MCP Transport
+### 25. HTTP MCP Transport
 
 Source: QMD study (2026-03-02)
 
@@ -261,6 +250,13 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
 - **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
+- **DAG-Based Conversation Compaction** — lossless-claw compresses conversations into a summary hierarchy; we distill structured facts. Fundamentally different paradigms that are complementary, not competing
+- **LLM-Heavy Compaction Pipeline** — Every compaction in lossless-claw requires LLM summarization calls. Our no-LLM retrieval path is a significant cost and latency advantage
+- **Go TUI for Debugging** — Adding a second language for an interactive debugging tool is over-engineering. CLI commands are sufficient (lossless-claw)
+- **Per-Conversation Scoping** — lossless-claw scopes knowledge per-conversation only. Our dual-database (global/project) is more useful for knowledge spanning conversations
+- **Sub-Agent Delegation for Deep Recall** — lossless-claw spawns sub-agents for DAG traversal. Adds latency and complexity; our direct MCP tool responses are simpler and faster
+- **Message Parts Polymorphism** — lossless-claw's 10-column message_parts for tool calls, reasoning, patches. We don't store raw messages, so irrelevant
+- **OpenClaw ContextEngine Interface** — Tight framework coupling. Our MCP + hooks approach is more portable
 
 ---
 
@@ -288,6 +284,7 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
 - [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)
+- [lossless-claw GitHub](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.3.0)
 
 Influence documents:
 - [docs/influence/qmd.md](influence/qmd.md) - Updated 2026-03-10
@@ -296,7 +293,8 @@ Influence documents:
 - [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)
+- [docs/influence/lossless-claw.md](influence/lossless-claw.md) - Updated 2026-03-16
 
 ---
 
-*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.*
+*Last updated: 2026-03-16 - Implemented 7 features total: Dynamic MCP Instructions (#11), Structured Error Classification (#16), Content-Addressed Dedup (#19), Dedup Before Vector Scoring (#20), Dedicated Maintenance Class (#10), Three-Level Escalation (#14), Tool Escalation Workflow (#15). Studied lossless-claw (v0.3.0), added Depth-Aware Prompt Templates (#13). Previously: Re-studied QMD (v2.0.1). Implemented: MCP Tool Annotations, MCP Stdout Protection, Worktree-Aware Git Root, Self-Excluding Conversations, Plugin Distribution, sqlite-vec, Database Compact, Fact Export, Background Processing, MCP Discovery Tools.*