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.
- checksums.yaml +4 -4
- data/.claude/memory.sqlite3 +0 -0
- data/.claude/rules/claude_memory.generated.md +32 -2
- data/.claude/settings.json +65 -15
- data/.claude/settings.local.json +5 -2
- data/.claude/skills/improve/SKILL.md +113 -25
- data/.claude/skills/upgrade-dependencies/SKILL.md +154 -0
- data/.claude-plugin/commands/distill-transcripts.md +98 -0
- data/.claude-plugin/commands/memory-recall.md +67 -0
- data/.claude-plugin/marketplace.json +2 -2
- data/.claude-plugin/plugin.json +3 -3
- data/.claude-plugin/scripts/hook-runner.sh +14 -0
- data/.claude-plugin/scripts/serve-mcp.sh +14 -0
- data/.ruby-version +1 -1
- data/CHANGELOG.md +90 -1
- data/CLAUDE.md +56 -18
- data/README.md +35 -0
- data/db/migrations/013_add_mcp_tool_calls.rb +26 -0
- data/db/migrations/014_canonicalize_predicates.rb +30 -0
- data/docs/improvements.md +74 -74
- data/docs/influence/claude-mem.md +1 -0
- data/docs/influence/claude-supermemory.md +1 -0
- data/docs/influence/episodic-memory.md +1 -0
- data/docs/influence/grepai.md +1 -0
- data/docs/influence/kbs.md +1 -0
- data/docs/influence/lossless-claw.md +1 -0
- data/docs/influence/qmd.md +1 -0
- data/docs/quality_review.md +119 -224
- data/hooks/hooks.json +39 -7
- data/lib/claude_memory/commands/checks/distill_check.rb +61 -0
- data/lib/claude_memory/commands/checks/hooks_check.rb +2 -2
- data/lib/claude_memory/commands/checks/vec_check.rb +2 -1
- data/lib/claude_memory/commands/completion_command.rb +149 -0
- data/lib/claude_memory/commands/doctor_command.rb +2 -0
- data/lib/claude_memory/commands/embeddings_command.rb +198 -0
- data/lib/claude_memory/commands/help_command.rb +12 -1
- data/lib/claude_memory/commands/hook_command.rb +2 -1
- data/lib/claude_memory/commands/index_command.rb +85 -78
- data/lib/claude_memory/commands/initializers/database_ensurer.rb +16 -0
- data/lib/claude_memory/commands/initializers/global_initializer.rb +2 -1
- data/lib/claude_memory/commands/initializers/hooks_configurator.rb +55 -11
- data/lib/claude_memory/commands/initializers/project_initializer.rb +2 -1
- data/lib/claude_memory/commands/install_skill_command.rb +78 -0
- data/lib/claude_memory/commands/registry.rb +47 -32
- data/lib/claude_memory/commands/reject_command.rb +62 -0
- data/lib/claude_memory/commands/restore_command.rb +77 -0
- data/lib/claude_memory/commands/skills/distill-transcripts.md +102 -0
- data/lib/claude_memory/commands/skills/memory-recall.md +67 -0
- data/lib/claude_memory/commands/stats_command.rb +98 -2
- data/lib/claude_memory/configuration.rb +14 -1
- data/lib/claude_memory/core/fact_ranker.rb +2 -2
- data/lib/claude_memory/core/rr_fusion.rb +23 -6
- data/lib/claude_memory/core/snippet_extractor.rb +7 -3
- data/lib/claude_memory/core/text_builder.rb +11 -0
- data/lib/claude_memory/distill/json_schema.md +8 -4
- data/lib/claude_memory/distill/null_distiller.rb +2 -0
- data/lib/claude_memory/domain/entity.rb +13 -1
- data/lib/claude_memory/domain/fact.rb +26 -2
- data/lib/claude_memory/domain/provenance.rb +0 -1
- data/lib/claude_memory/embeddings/api_adapter.rb +97 -0
- data/lib/claude_memory/embeddings/dimension_check.rb +23 -0
- data/lib/claude_memory/embeddings/fastembed_adapter.rb +46 -12
- data/lib/claude_memory/embeddings/generator.rb +4 -0
- data/lib/claude_memory/embeddings/inspector.rb +91 -0
- data/lib/claude_memory/embeddings/model_registry.rb +210 -0
- data/lib/claude_memory/embeddings/resolver.rb +44 -0
- data/lib/claude_memory/hook/context_injector.rb +58 -2
- data/lib/claude_memory/hook/distillation_runner.rb +46 -0
- data/lib/claude_memory/hook/handler.rb +11 -2
- data/lib/claude_memory/index/vector_index.rb +15 -2
- data/lib/claude_memory/infrastructure/schema_validator.rb +3 -3
- data/lib/claude_memory/ingest/ingester.rb +17 -0
- data/lib/claude_memory/mcp/handlers/context_handlers.rb +38 -0
- data/lib/claude_memory/mcp/handlers/management_handlers.rb +169 -0
- data/lib/claude_memory/mcp/handlers/query_handlers.rb +115 -0
- data/lib/claude_memory/mcp/handlers/setup_handlers.rb +211 -0
- data/lib/claude_memory/mcp/handlers/shortcut_handlers.rb +37 -0
- data/lib/claude_memory/mcp/handlers/stats_handlers.rb +205 -0
- data/lib/claude_memory/mcp/instructions_builder.rb +19 -1
- data/lib/claude_memory/mcp/query_guide.rb +10 -0
- data/lib/claude_memory/mcp/response_formatter.rb +1 -0
- data/lib/claude_memory/mcp/server.rb +22 -1
- data/lib/claude_memory/mcp/telemetry.rb +86 -0
- data/lib/claude_memory/mcp/text_summary.rb +26 -0
- data/lib/claude_memory/mcp/tool_definitions.rb +116 -4
- data/lib/claude_memory/mcp/tool_helpers.rb +43 -0
- data/lib/claude_memory/mcp/tools.rb +50 -679
- data/lib/claude_memory/publish.rb +40 -5
- data/lib/claude_memory/recall/dual_engine.rb +105 -0
- data/lib/claude_memory/recall/legacy_engine.rb +138 -0
- data/lib/claude_memory/recall/query_core.rb +371 -0
- data/lib/claude_memory/recall.rb +121 -673
- data/lib/claude_memory/resolve/predicate_policy.rb +63 -3
- data/lib/claude_memory/resolve/resolver.rb +43 -0
- data/lib/claude_memory/shortcuts.rb +4 -4
- data/lib/claude_memory/store/retry_handler.rb +61 -0
- data/lib/claude_memory/store/schema_manager.rb +68 -0
- data/lib/claude_memory/store/sqlite_store.rb +334 -201
- data/lib/claude_memory/store/store_manager.rb +50 -1
- data/lib/claude_memory/sweep/maintenance.rb +115 -1
- data/lib/claude_memory/sweep/sweeper.rb +3 -0
- data/lib/claude_memory/templates/hooks.example.json +26 -7
- data/lib/claude_memory/version.rb +1 -1
- data/lib/claude_memory.rb +16 -0
- metadata +48 -8
- data/.claude/memory.sqlite3-shm +0 -0
- 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-
|
|
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.
|
|
6
|
-
- *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15, studied 2026-03-
|
|
7
|
-
- *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search (
|
|
8
|
-
- *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory (v2.0.1, studied 2026-03-
|
|
9
|
-
- *[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-
|
|
11
|
-
- *[martian-engineering/lossless-claw](https://github.com/martian-engineering/lossless-claw) - DAG-based lossless context management (v0.
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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.
|
|
283
|
-
- [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search (
|
|
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.
|
|
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) -
|
|
291
|
-
- [docs/influence/episodic-memory.md](influence/episodic-memory.md) -
|
|
292
|
-
- [docs/influence/claude-mem.md](influence/claude-mem.md) -
|
|
293
|
-
- [docs/influence/grepai.md](influence/grepai.md) -
|
|
294
|
-
- [docs/influence/claude-supermemory.md](influence/claude-supermemory.md) -
|
|
295
|
-
- [docs/influence/kbs.md](influence/kbs.md) -
|
|
296
|
-
- [docs/influence/lossless-claw.md](influence/lossless-claw.md) -
|
|
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-
|
|
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
|
|
data/docs/influence/grepai.md
CHANGED
|
@@ -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
|
|
data/docs/influence/kbs.md
CHANGED
|
@@ -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
|
|
data/docs/influence/qmd.md
CHANGED
|
@@ -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
|
|