claude_memory 0.7.1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. checksums.yaml +4 -4
  2. data/.claude/memory.sqlite3 +0 -0
  3. data/.claude/rules/claude_memory.generated.md +32 -2
  4. data/.claude/settings.json +65 -15
  5. data/.claude/settings.local.json +5 -2
  6. data/.claude/skills/improve/SKILL.md +113 -25
  7. data/.claude/skills/upgrade-dependencies/SKILL.md +154 -0
  8. data/.claude-plugin/commands/distill-transcripts.md +98 -0
  9. data/.claude-plugin/commands/memory-recall.md +67 -0
  10. data/.claude-plugin/marketplace.json +2 -2
  11. data/.claude-plugin/plugin.json +3 -3
  12. data/.claude-plugin/scripts/hook-runner.sh +14 -0
  13. data/.claude-plugin/scripts/serve-mcp.sh +14 -0
  14. data/.ruby-version +1 -1
  15. data/CHANGELOG.md +90 -1
  16. data/CLAUDE.md +56 -18
  17. data/README.md +35 -0
  18. data/db/migrations/013_add_mcp_tool_calls.rb +26 -0
  19. data/db/migrations/014_canonicalize_predicates.rb +30 -0
  20. data/docs/improvements.md +74 -74
  21. data/docs/influence/claude-mem.md +1 -0
  22. data/docs/influence/claude-supermemory.md +1 -0
  23. data/docs/influence/episodic-memory.md +1 -0
  24. data/docs/influence/grepai.md +1 -0
  25. data/docs/influence/kbs.md +1 -0
  26. data/docs/influence/lossless-claw.md +1 -0
  27. data/docs/influence/qmd.md +1 -0
  28. data/docs/quality_review.md +119 -224
  29. data/hooks/hooks.json +39 -7
  30. data/lib/claude_memory/commands/checks/distill_check.rb +61 -0
  31. data/lib/claude_memory/commands/checks/hooks_check.rb +2 -2
  32. data/lib/claude_memory/commands/checks/vec_check.rb +2 -1
  33. data/lib/claude_memory/commands/completion_command.rb +149 -0
  34. data/lib/claude_memory/commands/doctor_command.rb +2 -0
  35. data/lib/claude_memory/commands/embeddings_command.rb +198 -0
  36. data/lib/claude_memory/commands/help_command.rb +12 -1
  37. data/lib/claude_memory/commands/hook_command.rb +2 -1
  38. data/lib/claude_memory/commands/index_command.rb +85 -78
  39. data/lib/claude_memory/commands/initializers/database_ensurer.rb +16 -0
  40. data/lib/claude_memory/commands/initializers/global_initializer.rb +2 -1
  41. data/lib/claude_memory/commands/initializers/hooks_configurator.rb +55 -11
  42. data/lib/claude_memory/commands/initializers/project_initializer.rb +2 -1
  43. data/lib/claude_memory/commands/install_skill_command.rb +78 -0
  44. data/lib/claude_memory/commands/registry.rb +47 -32
  45. data/lib/claude_memory/commands/reject_command.rb +62 -0
  46. data/lib/claude_memory/commands/restore_command.rb +77 -0
  47. data/lib/claude_memory/commands/skills/distill-transcripts.md +102 -0
  48. data/lib/claude_memory/commands/skills/memory-recall.md +67 -0
  49. data/lib/claude_memory/commands/stats_command.rb +98 -2
  50. data/lib/claude_memory/configuration.rb +14 -1
  51. data/lib/claude_memory/core/fact_ranker.rb +2 -2
  52. data/lib/claude_memory/core/rr_fusion.rb +23 -6
  53. data/lib/claude_memory/core/snippet_extractor.rb +7 -3
  54. data/lib/claude_memory/core/text_builder.rb +11 -0
  55. data/lib/claude_memory/distill/json_schema.md +8 -4
  56. data/lib/claude_memory/distill/null_distiller.rb +2 -0
  57. data/lib/claude_memory/domain/entity.rb +13 -1
  58. data/lib/claude_memory/domain/fact.rb +26 -2
  59. data/lib/claude_memory/domain/provenance.rb +0 -1
  60. data/lib/claude_memory/embeddings/api_adapter.rb +97 -0
  61. data/lib/claude_memory/embeddings/dimension_check.rb +23 -0
  62. data/lib/claude_memory/embeddings/fastembed_adapter.rb +46 -12
  63. data/lib/claude_memory/embeddings/generator.rb +4 -0
  64. data/lib/claude_memory/embeddings/inspector.rb +91 -0
  65. data/lib/claude_memory/embeddings/model_registry.rb +210 -0
  66. data/lib/claude_memory/embeddings/resolver.rb +44 -0
  67. data/lib/claude_memory/hook/context_injector.rb +58 -2
  68. data/lib/claude_memory/hook/distillation_runner.rb +46 -0
  69. data/lib/claude_memory/hook/handler.rb +11 -2
  70. data/lib/claude_memory/index/vector_index.rb +15 -2
  71. data/lib/claude_memory/infrastructure/schema_validator.rb +3 -3
  72. data/lib/claude_memory/ingest/ingester.rb +17 -0
  73. data/lib/claude_memory/mcp/handlers/context_handlers.rb +38 -0
  74. data/lib/claude_memory/mcp/handlers/management_handlers.rb +169 -0
  75. data/lib/claude_memory/mcp/handlers/query_handlers.rb +115 -0
  76. data/lib/claude_memory/mcp/handlers/setup_handlers.rb +211 -0
  77. data/lib/claude_memory/mcp/handlers/shortcut_handlers.rb +37 -0
  78. data/lib/claude_memory/mcp/handlers/stats_handlers.rb +205 -0
  79. data/lib/claude_memory/mcp/instructions_builder.rb +19 -1
  80. data/lib/claude_memory/mcp/query_guide.rb +10 -0
  81. data/lib/claude_memory/mcp/response_formatter.rb +1 -0
  82. data/lib/claude_memory/mcp/server.rb +22 -1
  83. data/lib/claude_memory/mcp/telemetry.rb +86 -0
  84. data/lib/claude_memory/mcp/text_summary.rb +26 -0
  85. data/lib/claude_memory/mcp/tool_definitions.rb +116 -4
  86. data/lib/claude_memory/mcp/tool_helpers.rb +43 -0
  87. data/lib/claude_memory/mcp/tools.rb +50 -679
  88. data/lib/claude_memory/publish.rb +40 -5
  89. data/lib/claude_memory/recall/dual_engine.rb +105 -0
  90. data/lib/claude_memory/recall/legacy_engine.rb +138 -0
  91. data/lib/claude_memory/recall/query_core.rb +371 -0
  92. data/lib/claude_memory/recall.rb +121 -673
  93. data/lib/claude_memory/resolve/predicate_policy.rb +63 -3
  94. data/lib/claude_memory/resolve/resolver.rb +43 -0
  95. data/lib/claude_memory/shortcuts.rb +4 -4
  96. data/lib/claude_memory/store/retry_handler.rb +61 -0
  97. data/lib/claude_memory/store/schema_manager.rb +68 -0
  98. data/lib/claude_memory/store/sqlite_store.rb +334 -201
  99. data/lib/claude_memory/store/store_manager.rb +50 -1
  100. data/lib/claude_memory/sweep/maintenance.rb +115 -1
  101. data/lib/claude_memory/sweep/sweeper.rb +3 -0
  102. data/lib/claude_memory/templates/hooks.example.json +26 -7
  103. data/lib/claude_memory/version.rb +1 -1
  104. data/lib/claude_memory.rb +16 -0
  105. metadata +48 -8
  106. data/.claude/memory.sqlite3-shm +0 -0
  107. data/.claude/memory.sqlite3-wal +0 -0
data/docs/improvements.md CHANGED
@@ -1,14 +1,14 @@
1
1
  # Improvements to Consider
2
2
 
3
- *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.*
3
+ *Updated: 2026-03-30 - Re-studied all 7 influencer repos. New recommendations: CLAUDE_CONFIG_DIR support (#26, from episodic-memory), Usage Stats / ROI Tracking (#27, from grepai v0.35.0). New Features to Avoid: AST-Aware Code Chunking (QMD), Custom Instructions via Env Var (lossless-claw v0.5.2), OpenClaw Context Injection (claude-mem v10.6.0). Repos with no changes: kbs (v0.2.1), claude-supermemory (v2.0.1), episodic-memory (v1.0.15). Previously: 14 features implemented through 2026-03-24.*
4
4
  *Sources:*
5
- - *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.5, studied 2026-03-09)*
6
- - *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15, studied 2026-03-09)*
7
- - *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search (latest, studied 2026-03-09)*
8
- - *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory (v2.0.1, studied 2026-03-09)*
9
- - *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (v2.0.1, studied 2026-03-10)*
10
- - *[MadBomber/kbs](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1, studied 2026-03-09 — no changes)*
11
- - *[martian-engineering/lossless-claw](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.3.0, studied 2026-03-16)*
5
+ - *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.6.3, re-studied 2026-03-30)*
6
+ - *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15, re-studied 2026-03-30 — no changes)*
7
+ - *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search (v0.35.0, re-studied 2026-03-30)*
8
+ - *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory (v2.0.1, re-studied 2026-03-30 — no changes)*
9
+ - *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (v2.0.1+unreleased, re-studied 2026-03-30)*
10
+ - *[MadBomber/kbs](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1, studied 2026-03-30 — no changes)*
11
+ - *[martian-engineering/lossless-claw](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.5.2, re-studied 2026-03-30)*
12
12
 
13
13
  This document contains only unimplemented improvements. Completed items are removed.
14
14
 
@@ -24,29 +24,17 @@ Schema migration v12 with `facts_vec` virtual table (vec0, cosine distance). Two
24
24
 
25
25
  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.
26
26
 
27
- ### 3. Intent Parameter for Recall
27
+ ### ~~3. Intent Parameter for Recall~~ ✅ Implemented 2026-03-23
28
28
 
29
- Source: QMD v1.1.5 study (2026-03-09)
30
-
31
- - **Value**: Disambiguate ambiguous queries (e.g., "database" with intent "migration" vs "performance")
32
- - **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)
33
- - **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
34
- - **Effort**: 2-3 days
35
- - **Recommendation**: ADOPT
29
+ Optional `intent` parameter added to `Recall#query`, `#query_index`, and `#query_semantic`. Threaded through DualEngine/LegacyEngine via `QueryCore#intent_augmented_query`. Intent appended to search query (0.5x weight for chunk selection, 0.3x for semantic). Disables BM25 shortcut when intent provided so vector search always runs. Exposed via `memory.recall`, `memory.recall_index`, and `memory.recall_semantic` MCP tools.
36
30
 
37
31
  ### ~~4. MCP Tool Annotations~~ ✅ Implemented 2026-03-09
38
32
 
39
- 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.
33
+ Added `readOnlyHint`, `idempotentHint`, `destructiveHint` annotations to all 23 MCP tools via shared constants (READ_ONLY, WRITE, WRITE_IDEMPOTENT). 19 query tools marked read-only, store_extraction/sweep_now/mark_distilled as write, promote as write-idempotent.
40
34
 
41
- ### 5. Retrieval Score Traces
35
+ ### ~~5. Retrieval Score Traces~~ ✅ Implemented 2026-03-20
42
36
 
43
- Source: QMD v1.1.5 study (2026-03-09)
44
-
45
- - **Value**: Transparency into why facts were retrieved — FTS score, vector similarity, RRF contribution, final blend
46
- - **Implementation**: Add optional `explain: true` param to recall tools, return score breakdown per result. Enhances `memory.explain` and `memory.recall_details`
47
- - **Evidence**: QMD `store.ts:2477-2540` — `--explain` flag with per-document RRF contribution traces
48
- - **Effort**: 2 days
49
- - **Recommendation**: ADOPT
37
+ Added `explain: true` parameter to `memory.recall_semantic` MCP tool. When enabled, each result includes `score_trace` with `vec_rank`, `vec_score`, `vec_rrf`, `fts_rank`, `fts_score`, `fts_rrf`, and `rrf_final`. Threaded through Recall → DualEngine/LegacyEngine → QueryCore → RRFusion. Components show nil for sources that didn't contribute.
50
38
 
51
39
  ### ~~6. MCP Stdout Protection Audit~~ ✅ Implemented 2026-03-09
52
40
 
@@ -56,15 +44,9 @@ ServeMcpCommand captures real stdout for MCP transport, redirects `$stdout` to `
56
44
 
57
45
  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.
58
46
 
59
- ### 8. Search Agent Delegation Pattern
47
+ ### ~~8. Search Agent Delegation Pattern~~ ✅ Implemented 2026-03-20
60
48
 
61
- Source: episodic-memory study (2026-03-09)
62
-
63
- - **Value**: Save 50-100x main-agent context by delegating memory search to a subagent that chains recall → explain → fact_graph
64
- - **Implementation**: Create `agents/memory-recall.md` subagent definition in plugin that chains our MCP tools and synthesizes results
65
- - **Evidence**: episodic-memory `agents/search-conversations.md:1-162` — subagent-delegated search pattern
66
- - **Effort**: 1-2 days
67
- - **Recommendation**: ADOPT
49
+ Created `memory-recall.md` agent definition that chains recall → explain → fact_graph with 4-step workflow (fast lookup → semantic search → enrich → synthesize). Available as `/memory-recall` slash command after installation. Bundled in plugin commands directory and installable via `claude-memory install-skill memory-recall`.
68
50
 
69
51
  ### ~~9. Self-Excluding Agent Conversations~~ ✅ Implemented 2026-03-09
70
52
 
@@ -78,25 +60,15 @@ Extracted `Sweep::Maintenance` class from Sweeper with 8 individual operations,
78
60
 
79
61
  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.
80
62
 
81
- ### 12. Embedded Skill Distribution
63
+ ### ~~12. Embedded Skill Distribution~~ ✅ Implemented 2026-03-20
82
64
 
83
- Source: QMD v2.0.1 study (2026-03-10)
65
+ Added `claude-memory install-skill` command. Skills shipped as markdown files in `lib/claude_memory/commands/skills/`. Supports `--list`, `--force`, and auto-creates `~/.claude/commands/` directory. Registry-based design supports future skill additions. Paired with Search Agent Delegation (#8).
84
66
 
85
- - **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
86
- - **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)
87
- - **Evidence**: QMD `src/embedded-skills.ts:1-22` — base64-encoded SKILL.md + references; CLI `skill install` command
88
- - **Effort**: 1-2 days
89
- - **Recommendation**: ADOPT
90
-
91
- ### 13. Depth-Aware Prompt Templates for Distiller ⭐
67
+ ### ~~13. Depth-Aware Prompt Templates for Distiller~~ Partially Implemented 2026-03-24
92
68
 
93
69
  Source: lossless-claw v0.3.0 study (2026-03-16)
94
70
 
95
- - **Value**: Graduated extraction prompts based on context depthfresh conversations get detailed extraction, well-established facts get consolidation prompts. Parallels lossless-claw's leaf/d1/d2/d3+ prompt hierarchy
96
- - **Implementation**: Create prompt templates for distiller stages: initial extraction (detailed), re-extraction (consolidation), contradiction resolution (focused). Use depth/freshness to select template
97
- - **Evidence**: `tui/prompts/leaf.tmpl`, `tui/prompts/condensed-d1.tmpl`, `condensed-d2.tmpl`, `condensed-d3.tmpl` — four distinct prompt templates with increasing abstraction
98
- - **Effort**: 1-2 days (when building real distiller)
99
- - **Recommendation**: ADOPT
71
+ Three-layer automatic distillation pipeline: (1) NullDistiller wired into ingest hooks for instant regex extraction on Stop/SessionStart/PreCompact/SessionEnd/TaskCompleted/TeammateIdle, (2) Context hook injection at SessionStart includes undistilled content with extraction instructions Claude Code acts as the LLM distiller at zero extra cost, (3) `/distill-transcripts` skill for manual deep extraction. New MCP tools: `memory.undistilled`, `memory.mark_distilled`. Depth-aware prompt selection (initial vs consolidation vs contradiction) deferred to skill enhancement — no Ruby code needed, just skill file edits.
100
72
 
101
73
  ### ~~14. Three-Level Escalation for Sweep/Maintenance~~ ✅ Implemented 2026-03-16
102
74
 
@@ -110,29 +82,19 @@ Restructured QueryGuide with 4-tier escalation hierarchy (Fast Lookup → Broad
110
82
 
111
83
  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.
112
84
 
113
- ### 17. Entity Context Extraction Prompts
85
+ ### ~~17. Entity Context Extraction Prompts~~ ✅ Implemented 2026-03-24
114
86
 
115
87
  Source: claude-supermemory v2.0.1 study (2026-03-09)
116
88
 
117
- - **Value**: Structured prompt templates for distiller defining what to extract (decisions, preferences, conventions) vs what to skip
118
- - **Implementation**: Apply when replacing NullDistiller. Rich prompt with concrete examples in table format, separate personal vs repo context
119
- - **Evidence**: supermemory `src/lib/supermemory-client.js:21-58` — extraction prompts with examples
120
- - **Effort**: 1-2 days (when building real distiller)
121
- - **Recommendation**: ADOPT — template for distiller replacement
89
+ Extraction instructions embedded in `/distill-transcripts` skill and context hook injection prompt. Defines what to extract (technology decisions, conventions, preferences, architecture, entities by type) vs what to skip (debugging steps, code output, transient errors). Scope detection for global vs project facts. Claude Code itself performs extraction — no separate API call needed.
122
90
 
123
91
  ---
124
92
 
125
93
  ## Medium Priority
126
94
 
127
- ### 18. Shell Completion for CLI
128
-
129
- Source: grepai study (2026-03-09)
95
+ ### ~~18. Shell Completion for CLI~~ ✅ Implemented 2026-03-20
130
96
 
131
- - **Value**: Tab completion for commands and flags in zsh/bash
132
- - **Implementation**: Generate completion scripts from OptionParser. Dynamic completions for project names
133
- - **Evidence**: grepai `cli/completion.go` — static + dynamic completions
134
- - **Effort**: 1-2 days
135
- - **Recommendation**: CONSIDER
97
+ Added `claude-memory completion` command generating zsh and bash completion scripts. Auto-detects shell from `$SHELL`. Includes all 25 CLI commands, hook subcommands (ingest/sweep/publish/context), and context-aware flag completions for scope, index, and install-skill. Usage: `eval "$(claude-memory completion)"`.
136
98
 
137
99
  ### ~~19. Content-Addressed Deduplication for Embeddings~~ ✅ Implemented 2026-03-16
138
100
 
@@ -166,10 +128,43 @@ Source: QMD study (updated 2026-03-02)
166
128
 
167
129
  `--async` flag on hook ingest/sweep/publish subcommands. Fork+detach for non-blocking execution, fallback to sync when fork unavailable.
168
130
 
131
+ ### ~~26. CLAUDE_CONFIG_DIR Support~~ ✅ Implemented 2026-04-13
132
+
133
+ `Configuration#claude_config_dir` reads `CLAUDE_CONFIG_DIR` env var before falling back to `~/.claude`. `global_db_path` routes through it, so users with non-standard Claude Code config locations (or multiple profiles) can point the global memory DB anywhere without touching project DB resolution.
134
+
135
+ ### 28. Code-Aware Transcript Chunking
136
+
137
+ Source: QMD v2.0.1+unreleased re-study (2026-03-30)
138
+
139
+ - **Value**: Better embeddings for transcripts containing code — detect fenced code blocks and apply AST-aware break points (function/class/import boundaries) rather than naive text splitting
140
+ - **Implementation**: Detect ` ```language ` fences in transcript content, parse code blocks with tree-sitter (via ruby_tree_sitter gem or shelling out), score break points (class=100, func=90, type=80, import=60), merge with markdown break points from #22
141
+ - **Evidence**: QMD `src/ast.ts` (392 lines) — web-tree-sitter with WASM grammars, `mergeBreakPoints()` combining AST + regex scores, graceful degradation on parse failure
142
+ - **Consideration**: Only useful in combination with #22 (Document Chunking). Transcripts often contain significant code in tool_use results and assistant responses
143
+ - **Effort**: 2-3 days (after #22)
144
+ - **Trade-off**: Adds tree-sitter dependency; graceful fallback to regex-only chunking when grammar unavailable
145
+
146
+ ### 30. Predicate Census Command
147
+
148
+ Source: predicate retrospective (2026-04-15)
149
+
150
+ - **Value**: Aggregate predicate usage data across many project databases for informed vocabulary decisions — without exposing content. Enables data-sharing across machines (work/personal) via a privacy-safe JSON report.
151
+ - **Implementation**: `claude-memory census [--root ~/src]`. Finds all `.claude/memory.sqlite3` files under root, opens each read-only, collects per-DB predicate × status counts, entity type counts, schema version, novel predicates, synonym canonicalization candidates. Outputs aggregated JSON with **no object_literal, no entity names, no project paths, no quotes** — only schema-level signal.
152
+ - **Evidence**: The multi-project survey that caught the `uses_framework` cardinality bug (commit `29818c2`) was a manual bash loop. Productizing it means any user can contribute usage data for vocabulary curation without privacy risk.
153
+ - **Effort**: 0.5 days
154
+ - **Trade-off**: None — purely additive, read-only, privacy-safe by design
155
+
156
+ ### ~~27. Usage Stats / ROI Tracking~~ ✅ Implemented 2026-04-15
157
+
158
+ Schema migration v13 adds `mcp_tool_calls` telemetry table (tool_name, called_at, duration_ms, result_count, scope, error_class). `MCP::Telemetry` wraps `Server#handle_tools_call` with monotonic-clock timing, captures errors, and records to the project DB; DB errors are swallowed so telemetry never fails a real tool call. `StatsCommand` gains `--tools` and `--since DAYS` flags showing total calls, error rate, and per-tool breakdown (calls, avg ms, p95 ms, error rate). `Sweep::Maintenance#prune_old_mcp_tool_calls` enforces a 90-day retention window, wired into `Sweeper#run!`. Rejected NDJSON in favor of SQLite for schema/query consistency with the rest of the gem. Dropped query-text capture (YAGNI — the dedup insight the hash would enable also needs raw text). Also fixed a latent bug where `StatsCommand` opened the DB via `Sequel.sqlite` (requiring the unlisted `sqlite3` gem); now uses the extralite adapter consistently.
159
+
169
160
  ---
170
161
 
171
162
  ## Low Priority / Defer
172
163
 
164
+ ### ~~29. Derive CompletionCommand Descriptions from Registry~~ ✅ Implemented 2026-04-15
165
+
166
+ `Registry::COMMANDS` now stores `{class:, description:}` entries as the single source of truth. New `Registry.description` and `Registry.descriptions` accessors. `CompletionCommand` reads descriptions via `Registry.descriptions` instead of maintaining its own parallel hash. `Registry.find` also simplified — class references stored directly since command files are required before the Registry, eliminating `const_get` string indirection. Drift between the command list and completion output is now impossible without a deliberate edit to a single file.
167
+
173
168
  ### 23. REST API Endpoint
174
169
 
175
170
  Source: QMD v2.0.1 study (2026-03-10)
@@ -220,7 +215,7 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
220
215
  ## Features to Avoid
221
216
 
222
217
  - **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)
223
- - **Claude Agent SDK for Distillation** — Direct API calls via `anthropic-rb` gem
218
+ - **Claude Agent SDK for Distillation** — Direct API calls via `anthropic-rb` gem. Instead, Claude Code itself serves as the distiller via context hook injection and `/distill-transcripts` skill — zero extra cost
224
219
  - **Worker Service Background Process** — Keep stdio-based MCP server. claude-mem's worker architecture adds significant complexity and failure modes.
225
220
  - **Web Viewer UI** — CLI output is sufficient. Add if users request it
226
221
  - **Neural Embeddings (EmbeddingGemma)** — Superseded by FastEmbed (BAAI/bge-small-en-v1.5)
@@ -257,6 +252,11 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
257
252
  - **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
258
253
  - **Message Parts Polymorphism** — lossless-claw's 10-column message_parts for tool calls, reasoning, patches. We don't store raw messages, so irrelevant
259
254
  - **OpenClaw ContextEngine Interface** — Tight framework coupling. Our MCP + hooks approach is more portable
255
+ - **Chunk Strategy Option** — QMD's `--chunk-strategy auto` for code files. ClaudeMemory has no standalone chunking pipeline to configure (QMD v0.35.0)
256
+ - **Custom Instructions via Env Var** — lossless-claw's `LCM_CUSTOM_INSTRUCTIONS` config stub exists but is never wired to summarization prompts. Incomplete pattern; our skill-based prompts are better (lossless-claw v0.5.2)
257
+ - **OpenClaw Context Injection** — claude-mem v10.6.0's `appendSystemContext` with 60s cache replaces MEMORY.md writes. Our SessionStart hook context injection already does this (claude-mem v10.6.0)
258
+ - **Message Parts Polymorphism** — lossless-claw's 10-column message_parts for tool calls, reasoning, patches. We don't store raw messages, so irrelevant
259
+ - **OpenClaw ContextEngine Interface** — Tight framework coupling. Our MCP + hooks approach is more portable
260
260
 
261
261
  ---
262
262
 
@@ -279,22 +279,22 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
279
279
  ## References
280
280
 
281
281
  - [episodic-memory GitHub](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15)
282
- - [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.5)
283
- - [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search (latest)
282
+ - [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.6.3)
283
+ - [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search (v0.35.0)
284
284
  - [claude-supermemory GitHub](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed memory (v2.0.1)
285
- - [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine (v2.0.1)
285
+ - [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine (v2.0.1+unreleased)
286
286
  - [KBS GitHub](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1)
287
- - [lossless-claw GitHub](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.3.0)
287
+ - [lossless-claw GitHub](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.5.2)
288
288
 
289
289
  Influence documents:
290
- - [docs/influence/qmd.md](influence/qmd.md) - Updated 2026-03-10
291
- - [docs/influence/episodic-memory.md](influence/episodic-memory.md) - Updated 2026-03-09
292
- - [docs/influence/claude-mem.md](influence/claude-mem.md) - Updated 2026-03-09
293
- - [docs/influence/grepai.md](influence/grepai.md) - Updated 2026-03-09
294
- - [docs/influence/claude-supermemory.md](influence/claude-supermemory.md) - Updated 2026-03-09
295
- - [docs/influence/kbs.md](influence/kbs.md) - Updated 2026-03-09 (no changes)
296
- - [docs/influence/lossless-claw.md](influence/lossless-claw.md) - Updated 2026-03-16
290
+ - [docs/influence/qmd.md](influence/qmd.md) - Re-studied 2026-03-30
291
+ - [docs/influence/episodic-memory.md](influence/episodic-memory.md) - Re-studied 2026-03-30
292
+ - [docs/influence/claude-mem.md](influence/claude-mem.md) - Re-studied 2026-03-30
293
+ - [docs/influence/grepai.md](influence/grepai.md) - Re-studied 2026-03-30
294
+ - [docs/influence/claude-supermemory.md](influence/claude-supermemory.md) - Re-studied 2026-03-30
295
+ - [docs/influence/kbs.md](influence/kbs.md) - Re-studied 2026-03-30 (no changes)
296
+ - [docs/influence/lossless-claw.md](influence/lossless-claw.md) - Re-studied 2026-03-30
297
297
 
298
298
  ---
299
299
 
300
- *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.*
300
+ *Last updated: 2026-04-15 - Predicate retrospective: fixed uses_framework cardinality bug, curated vocabulary to 8 predicates, added synonym canonicalization + novel-predicate warnings. Also: reject/restore commands, #26 CLAUDE_CONFIG_DIR, #27 telemetry, #29 Registry descriptions.*
@@ -3,6 +3,7 @@
3
3
  *Analysis Date: 2026-03-02*
4
4
  *Repository: https://github.com/thedotmack/claude-mem*
5
5
  *Version: 10.5.2 (commit ecb09df)*
6
+ *Re-studied: 2026-03-30 — v10.6.3 (commit d068821). 4 releases since last study (v10.5.6, v10.6.0, v10.6.1, v10.6.2, v10.6.3). Key changes: OpenClaw system prompt context injection replacing MEMORY.md writes (v10.6.0), compressed context output ~53% smaller (v10.6.1), timeline report skill (v10.6.1), process supervisor hardening with PID 0 fix and signal race condition fix (v10.5.6), activity spinner orphan session fix (v10.6.2), Gemini CLI integration (v10.6.3), 7 critical cross-platform bug fixes (v10.6.3). Context injection pattern (appendSystemContext with 60s cache) aligns with our SessionStart hook approach. Compressed context format worth studying. No new adoptable patterns beyond what we already implement.*
6
7
 
7
8
  ---
8
9
 
@@ -2,6 +2,7 @@
2
2
 
3
3
  *Analysis Date: 2026-03-02*
4
4
  *Previous Analysis: 2026-02-02*
5
+ *Re-studied: 2026-03-30 — No meaningful code changes since v2.0.1. marketplace.json bumped to 0.0.3, added claude-code-review GitHub Action (anthropics/claude-code-action@v1). All findings remain current.*
5
6
  *Repository: https://github.com/supermemoryai/claude-supermemory*
6
7
  *Version: 2.0.0 (commit de39413)*
7
8
 
@@ -3,6 +3,7 @@
3
3
  *Analysis Date: 2026-03-02*
4
4
  *Repository: https://github.com/obra/episodic-memory*
5
5
  *Version: 1.0.15 (commit 6feaa5b)*
6
+ *Re-studied: 2026-03-30 — No changes since v1.0.15. Repo dormant. One adoptable pattern identified: CLAUDE_CONFIG_DIR env var support (`src/paths.ts:20-22`) for configurable Claude config directory. Orphaned MCP process prevention (SIGHUP handler in wrapper) not applicable — ClaudeMemory runs as single Ruby process, no wrapper/child architecture.*
6
7
 
7
8
  ---
8
9
 
@@ -4,6 +4,7 @@
4
4
  *Previous Analysis: 2026-01-29*
5
5
  *Repository: https://github.com/yoanbernabeu/grepai*
6
6
  *Version: 0.34.0 (commit 1c7aba9)*
7
+ *Re-studied: 2026-03-30 — v0.35.0. One release since last study (2026-03-16). Key addition: privacy-first usage stats tracking (`stats/` package) recording every search/trace to NDJSON file (`.grepai/stats.json`), computing output tokens vs grep-equivalent tokens with savings percentages and optional USD cost savings. Fire-and-forget recording via goroutine with 100ms timeout, file-locking for cross-process safety. Shell completion also added (we already have this via #18). `.grepaiignore` support not relevant.*
7
8
 
8
9
  ---
9
10
 
@@ -1,6 +1,7 @@
1
1
  # KBS (Knowledge-Based System) Analysis
2
2
 
3
3
  *Analysis Date: 2026-03-02*
4
+ *Re-studied: 2026-03-30 — no changes since v0.2.1*
4
5
  *Repository: https://github.com/MadBomber/kbs*
5
6
  *Version: v0.2.1 (commit c04561d)*
6
7
 
@@ -3,6 +3,7 @@
3
3
  *Analysis Date: 2026-03-16*
4
4
  *Repository: https://github.com/martian-engineering/lossless-claw*
5
5
  *Version: 0.3.0 (commit 49949fb)*
6
+ *Re-studied: 2026-03-30 — v0.5.2. 5 releases since last study. Core DAG architecture unchanged; changes are operational hardening. Custom Instructions (`LCM_CUSTOM_INSTRUCTIONS`) — config stub exists but never wired to summarization prompts, do not adopt. Session exclusion patterns (ignore + stateless) — clean implementation but low priority (we already have ContentSanitizer exclusion tags). Prompt Slot Pattern — does not exist in codebase, not applicable. New: CJK-aware FTS5 fallback with `icu` tokenizer detection worth considering. Also: provider auth error surfacing, summarizer timeouts, bootstrap checkpoints, Docker support, TUI doctor command.*
6
7
 
7
8
  ---
8
9
 
@@ -4,6 +4,7 @@
4
4
  *Previous Analysis: 2026-03-02, 2026-02-02*
5
5
  *Repository: https://github.com/tobi/qmd*
6
6
  *Version: 2.0.1 (commit ae3604c)*
7
+ *Re-studied: 2026-03-30 — v2.0.1+unreleased. One significant addition: AST-aware chunking (`src/ast.ts`, 392 lines) using web-tree-sitter with WASM grammars for TS/JS/Python/Go/Rust. Detects language from extension, parses AST, extracts break points at function/class/import boundaries (class=100, func=90, type=80, import=60). Merged with regex break points via `mergeBreakPoints()`. Opt-in via `--chunk-strategy auto`. While we ingest transcripts rather than source code, transcripts frequently contain embedded code in tool results and assistant responses. AST-aware break points could improve embedding quality for code-heavy transcripts when combined with Document Chunking (#22). Added as improvement #28 (Code-Aware Transcript Chunking).*
7
8
 
8
9
  ---
9
10