claude_memory 0.6.0 → 0.7.1
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/CLAUDE.md +1 -1
- data/.claude/memory.sqlite3 +0 -0
- data/.claude/memory.sqlite3-shm +0 -0
- data/.claude/memory.sqlite3-wal +0 -0
- data/.claude/settings.local.json +13 -1
- data/.claude-plugin/marketplace.json +1 -1
- data/.claude-plugin/plugin.json +1 -2
- data/.gitattributes +1 -0
- data/CHANGELOG.md +61 -0
- data/CLAUDE.md +4 -2
- data/README.md +1 -1
- data/docs/improvements.md +164 -22
- data/docs/influence/lossless-claw.md +409 -0
- data/docs/influence/qmd.md +201 -130
- data/docs/quality_review.md +344 -56
- data/lib/claude_memory/commands/checks/database_check.rb +7 -0
- data/lib/claude_memory/commands/compact_command.rb +10 -0
- data/lib/claude_memory/commands/export_command.rb +14 -6
- data/lib/claude_memory/commands/git_lfs_command.rb +117 -0
- data/lib/claude_memory/commands/index_command.rb +30 -2
- data/lib/claude_memory/commands/registry.rb +2 -1
- data/lib/claude_memory/commands/serve_mcp_command.rb +10 -1
- data/lib/claude_memory/commands/stats_command.rb +12 -1
- data/lib/claude_memory/configuration.rb +40 -1
- data/lib/claude_memory/core/snippet_extractor.rb +21 -19
- data/lib/claude_memory/index/lexical_fts.rb +88 -16
- data/lib/claude_memory/ingest/ingester.rb +1 -1
- data/lib/claude_memory/mcp/error_classifier.rb +171 -0
- data/lib/claude_memory/mcp/instructions_builder.rb +62 -4
- data/lib/claude_memory/mcp/query_guide.rb +41 -22
- data/lib/claude_memory/mcp/response_formatter.rb +3 -1
- data/lib/claude_memory/mcp/server.rb +1 -0
- data/lib/claude_memory/mcp/text_summary.rb +2 -1
- data/lib/claude_memory/mcp/tool_definitions.rb +54 -23
- data/lib/claude_memory/mcp/tools.rb +33 -16
- data/lib/claude_memory/recall.rb +51 -5
- data/lib/claude_memory/resolve/resolver.rb +22 -18
- data/lib/claude_memory/store/store_manager.rb +19 -24
- data/lib/claude_memory/sweep/maintenance.rb +126 -0
- data/lib/claude_memory/sweep/sweeper.rb +82 -67
- data/lib/claude_memory/version.rb +1 -1
- data/lib/claude_memory.rb +8 -0
- data/v0.6.0.ANNOUNCE +32 -0
- metadata +10 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 00a7e67707543e2a5266200eab3a276a5b70d25a41ebbc8a5eab8767c44952a8
|
|
4
|
+
data.tar.gz: 261f86e807d5638739a7462872ae9f5472451afd7aea5496c1cf785b54a76dc6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 79ffe3d19420ae16dd26e2083a45c3725be43fd955bf707e3a1e157e04d790821cd5d199b8c67ea713c354c82314a931af1883d260a430119f2eb72213d8cc16
|
|
7
|
+
data.tar.gz: 864fffbf37c36d63a3a72e19f56ce7f288c26b7d6b546e55338ea0fb61fc963fb99704be28124e33fbb49d5098c3997409ecdac13735fd9cd52253b545346f4b
|
data/.claude/CLAUDE.md
CHANGED
|
Binary file
|
|
Binary file
|
|
Binary file
|
data/.claude/settings.local.json
CHANGED
|
@@ -36,7 +36,19 @@
|
|
|
36
36
|
"Skill(study-repo)",
|
|
37
37
|
"WebFetch(domain:www.rubydoc.info)",
|
|
38
38
|
"Bash(git status:*)",
|
|
39
|
-
"WebFetch(domain:github.com)"
|
|
39
|
+
"WebFetch(domain:github.com)",
|
|
40
|
+
"mcp__memory__memory_stats",
|
|
41
|
+
"mcp__memory__memory_recall_index",
|
|
42
|
+
"Bash(mkdir -p /tmp/study-repos)",
|
|
43
|
+
"Read(//tmp/**)",
|
|
44
|
+
"Bash(ls:*)",
|
|
45
|
+
"Bash(sort -k2 -rn)",
|
|
46
|
+
"Bash(claude-memory recall:*)",
|
|
47
|
+
"Bash(claude-memory stats:*)",
|
|
48
|
+
"Bash(claude-memory search:*)",
|
|
49
|
+
"Bash(bundle exec:*)",
|
|
50
|
+
"Skill(improve)",
|
|
51
|
+
"Skill(improve:*)"
|
|
40
52
|
]
|
|
41
53
|
},
|
|
42
54
|
"enableAllProjectMcpServers": true
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
"plugins": [
|
|
8
8
|
{
|
|
9
9
|
"name": "claude-memory",
|
|
10
|
-
"version": "0.
|
|
10
|
+
"version": "0.7.1",
|
|
11
11
|
"source": "./",
|
|
12
12
|
"description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
|
|
13
13
|
"repository": "https://github.com/codenamev/claude_memory"
|
data/.claude-plugin/plugin.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "claude-memory",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.1",
|
|
4
4
|
"description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Valentino Stoll",
|
|
@@ -16,7 +16,6 @@
|
|
|
16
16
|
"args": []
|
|
17
17
|
}
|
|
18
18
|
},
|
|
19
|
-
"hooks": "./hooks/hooks.json",
|
|
20
19
|
"skills": "./skills/",
|
|
21
20
|
"commands": "./commands/",
|
|
22
21
|
"outputStyles": "./output-styles/"
|
data/.gitattributes
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
.claude/memory.sqlite3* filter=lfs diff=lfs merge=lfs -text
|
data/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,67 @@ All notable changes to this project will be documented in this file.
|
|
|
4
4
|
|
|
5
5
|
## [Unreleased]
|
|
6
6
|
|
|
7
|
+
## [0.7.1] - 2026-03-17
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
**Three-Level Sweep Escalation**
|
|
12
|
+
- `Maintenance` class with light/standard/deep sweep levels for progressive database maintenance
|
|
13
|
+
- Exposed sweep escalation via `memory.sweep_now` MCP tool with configurable level
|
|
14
|
+
- Tool escalation workflow added to MCP QueryGuide documentation
|
|
15
|
+
|
|
16
|
+
**Embedding Deduplication**
|
|
17
|
+
- Content-addressed deduplication for embeddings using SHA256 hashing
|
|
18
|
+
- Deduplication before vector scoring in fallback path to prevent duplicate results
|
|
19
|
+
|
|
20
|
+
**MCP Enhancements**
|
|
21
|
+
- Structured error classification for MCP tools via `ErrorClassifier` module
|
|
22
|
+
- Dynamic knowledge summary in MCP server instructions via `InstructionsBuilder`
|
|
23
|
+
|
|
24
|
+
### Fixed
|
|
25
|
+
|
|
26
|
+
- **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
|
|
27
|
+
|
|
28
|
+
### Internal
|
|
29
|
+
- Influence study: lossless-claw v0.3.0 DAG-based lossless context management
|
|
30
|
+
- Marked 7 improvements as implemented (#10, #11, #14, #15, #16, #19, #20)
|
|
31
|
+
|
|
32
|
+
## [0.7.0] - 2026-03-12
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
|
|
36
|
+
**FTS5 Contentless Mode**
|
|
37
|
+
- FTS5 tables now created with `content=''` for ~40% smaller databases
|
|
38
|
+
- Auto-detection: both legacy and contentless formats work seamlessly
|
|
39
|
+
- `compact` command rebuilds FTS index to contentless format
|
|
40
|
+
- `stats` command reports FTS format and optimization hints
|
|
41
|
+
|
|
42
|
+
**Worktree-Aware Project Paths**
|
|
43
|
+
- Project database now resolves to main repository root across git worktrees
|
|
44
|
+
- Prevents duplicate project databases when using `git worktree`
|
|
45
|
+
- Opt-out: set `CLAUDE_MEMORY_ISOLATE_WORKTREES=1` for per-worktree isolation
|
|
46
|
+
|
|
47
|
+
**MCP Enhancements**
|
|
48
|
+
- Tool annotations: `readOnlyHint`, `idempotentHint`, `destructiveHint` on all 21 tools
|
|
49
|
+
- Stdout protection: MCP server redirects `$stdout` to `$stderr` to prevent protocol corruption from accidental `puts`/`print` calls
|
|
50
|
+
- Self-excluding agent conversations via `SELF_CONTEXT_MARKER` to prevent meta-pollution
|
|
51
|
+
|
|
52
|
+
**New Commands**
|
|
53
|
+
- `git-lfs` command for setting up git-lfs tracking of project memory databases
|
|
54
|
+
|
|
55
|
+
### Fixed
|
|
56
|
+
|
|
57
|
+
- Narrowed rescue clauses in `discover_other_projects` (was bare `rescue`, now catches specific `Sequel::DatabaseError`, `Extralite::Error`, `IOError`)
|
|
58
|
+
- FTS entries now cleaned up when content is pruned by sweeper (prevents orphaned index entries)
|
|
59
|
+
- FTS index rebuilt during `compact` for consistent state after upgrades
|
|
60
|
+
- Real evals CI: install gem and use correct release API
|
|
61
|
+
|
|
62
|
+
### Internal
|
|
63
|
+
- Resolver refactored to pass `project_path`/`scope` as parameters instead of instance variables (better thread safety)
|
|
64
|
+
- `SnippetExtractor` refactored to eliminate duplication between `extract` and `extract_with_lines`
|
|
65
|
+
- `StoreManager.promote_fact` inlined `copy_provenance` for single-transaction safety
|
|
66
|
+
- Influence study: QMD v2.0.1 SDK-first architecture analysis
|
|
67
|
+
|
|
7
68
|
## [0.6.0] - 2026-03-06
|
|
8
69
|
|
|
9
70
|
### Added
|
data/CLAUDE.md
CHANGED
|
@@ -24,13 +24,15 @@ bin/setup # Install dependencies
|
|
|
24
24
|
|
|
25
25
|
### Testing
|
|
26
26
|
```bash
|
|
27
|
-
bundle exec rspec # Run
|
|
27
|
+
bundle exec rspec # Run unit/integration tests (~76s)
|
|
28
28
|
bundle exec rspec spec/claude_memory/cli_spec.rb # Run single test file
|
|
29
29
|
bundle exec rspec spec/claude_memory/cli_spec.rb:42 # Run specific test by line number
|
|
30
30
|
bundle exec rake spec # Alternative test command
|
|
31
31
|
bundle exec rake # Run tests + Standard linter (default task)
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
+
**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.
|
|
35
|
+
|
|
34
36
|
### Linting
|
|
35
37
|
```bash
|
|
36
38
|
bundle exec rake standard # Run Standard Ruby linter
|
|
@@ -133,7 +135,7 @@ Transcripts → Ingest → Index (FTS5)
|
|
|
133
135
|
- Each command is a separate class (HelpCommand, DoctorCommand, etc.)
|
|
134
136
|
- All commands inherit from BaseCommand
|
|
135
137
|
- Dependency injection for I/O (stdout, stderr, stdin)
|
|
136
|
-
-
|
|
138
|
+
- 22 commands total, each focused on single responsibility
|
|
137
139
|
|
|
138
140
|
- **`Configuration`**: Centralized ENV access (`configuration.rb`)
|
|
139
141
|
- Single source of truth for paths and environment variables
|
data/README.md
CHANGED
|
@@ -257,7 +257,7 @@ The benchmark dataset draws from real CLAUDE.md patterns and is designed specifi
|
|
|
257
257
|
|
|
258
258
|
- **Language:** Ruby 3.2+
|
|
259
259
|
- **Storage:** SQLite3 (no external services)
|
|
260
|
-
- **Testing:**
|
|
260
|
+
- **Testing:** 1477 examples (1375 unit/integration + 102 benchmarks/evals), 100% core coverage
|
|
261
261
|
- **Code Style:** Standard Ruby
|
|
262
262
|
|
|
263
263
|
```bash
|
data/docs/improvements.md
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
# Improvements to Consider
|
|
2
2
|
|
|
3
|
-
*Updated: 2026-03-
|
|
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.*
|
|
4
4
|
*Sources:*
|
|
5
|
-
- *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.
|
|
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.
|
|
9
|
-
- *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (
|
|
10
|
-
- *[MadBomber/kbs](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1, studied 2026-03-
|
|
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)*
|
|
11
12
|
|
|
12
13
|
This document contains only unimplemented improvements. Completed items are removed.
|
|
13
14
|
|
|
@@ -23,11 +24,125 @@ Schema migration v12 with `facts_vec` virtual table (vec0, cosine distance). Two
|
|
|
23
24
|
|
|
24
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.
|
|
25
26
|
|
|
27
|
+
### 3. Intent Parameter for Recall ⭐
|
|
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
|
|
36
|
+
|
|
37
|
+
### ~~4. MCP Tool Annotations~~ ✅ Implemented 2026-03-09
|
|
38
|
+
|
|
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.
|
|
40
|
+
|
|
41
|
+
### 5. Retrieval Score Traces ⭐
|
|
42
|
+
|
|
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
|
|
50
|
+
|
|
51
|
+
### ~~6. MCP Stdout Protection Audit~~ ✅ Implemented 2026-03-09
|
|
52
|
+
|
|
53
|
+
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.
|
|
54
|
+
|
|
55
|
+
### ~~7. Worktree-Aware Git Root Detection~~ ✅ Implemented 2026-03-09
|
|
56
|
+
|
|
57
|
+
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
|
+
|
|
59
|
+
### 8. Search Agent Delegation Pattern ⭐
|
|
60
|
+
|
|
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
|
|
68
|
+
|
|
69
|
+
### ~~9. Self-Excluding Agent Conversations~~ ✅ Implemented 2026-03-09
|
|
70
|
+
|
|
71
|
+
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.
|
|
72
|
+
|
|
73
|
+
### ~~10. Dedicated Maintenance Class~~ ✅ Implemented 2026-03-16
|
|
74
|
+
|
|
75
|
+
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.
|
|
76
|
+
|
|
77
|
+
### ~~11. Dynamic MCP Instructions Enhancement~~ ✅ Implemented 2026-03-16
|
|
78
|
+
|
|
79
|
+
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
|
+
|
|
81
|
+
### 12. Embedded Skill Distribution ⭐
|
|
82
|
+
|
|
83
|
+
Source: QMD v2.0.1 study (2026-03-10)
|
|
84
|
+
|
|
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 ⭐
|
|
92
|
+
|
|
93
|
+
Source: lossless-claw v0.3.0 study (2026-03-16)
|
|
94
|
+
|
|
95
|
+
- **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
|
|
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
|
|
100
|
+
|
|
101
|
+
### ~~14. Three-Level Escalation for Sweep/Maintenance~~ ✅ Implemented 2026-03-16
|
|
102
|
+
|
|
103
|
+
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.
|
|
104
|
+
|
|
105
|
+
### ~~15. Tool Escalation Workflow in MCP Instructions~~ ✅ Implemented 2026-03-16
|
|
106
|
+
|
|
107
|
+
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.
|
|
108
|
+
|
|
109
|
+
### ~~16. Structured Error Classification~~ ✅ Implemented 2026-03-16
|
|
110
|
+
|
|
111
|
+
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
|
+
|
|
113
|
+
### 17. Entity Context Extraction Prompts
|
|
114
|
+
|
|
115
|
+
Source: claude-supermemory v2.0.1 study (2026-03-09)
|
|
116
|
+
|
|
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
|
|
122
|
+
|
|
26
123
|
---
|
|
27
124
|
|
|
28
125
|
## Medium Priority
|
|
29
126
|
|
|
30
|
-
###
|
|
127
|
+
### 18. Shell Completion for CLI
|
|
128
|
+
|
|
129
|
+
Source: grepai study (2026-03-09)
|
|
130
|
+
|
|
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
|
|
136
|
+
|
|
137
|
+
### ~~19. Content-Addressed Deduplication for Embeddings~~ ✅ Implemented 2026-03-16
|
|
138
|
+
|
|
139
|
+
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)").
|
|
140
|
+
|
|
141
|
+
### ~~20. Deduplication Before Vector Scoring~~ ✅ Implemented 2026-03-16
|
|
142
|
+
|
|
143
|
+
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).
|
|
144
|
+
|
|
145
|
+
### 21. Incremental Indexing with File Watching
|
|
31
146
|
|
|
32
147
|
Source: grepai study (reinforced 2026-03-02)
|
|
33
148
|
|
|
@@ -37,7 +152,7 @@ Source: grepai study (reinforced 2026-03-02)
|
|
|
37
152
|
- **Effort**: 2-3 days
|
|
38
153
|
- **Trade-off**: Background process ~10MB memory overhead
|
|
39
154
|
|
|
40
|
-
###
|
|
155
|
+
### 22. Document Chunking for Long Transcripts
|
|
41
156
|
|
|
42
157
|
Source: QMD study (updated 2026-03-02)
|
|
43
158
|
|
|
@@ -55,7 +170,18 @@ Source: QMD study (updated 2026-03-02)
|
|
|
55
170
|
|
|
56
171
|
## Low Priority / Defer
|
|
57
172
|
|
|
58
|
-
###
|
|
173
|
+
### 23. REST API Endpoint
|
|
174
|
+
|
|
175
|
+
Source: QMD v2.0.1 study (2026-03-10)
|
|
176
|
+
|
|
177
|
+
- **Value**: POST `/query` alongside MCP — enables search from curl, scripts, CI, and non-MCP clients without the full MCP protocol handshake
|
|
178
|
+
- **Implementation**: Add optional HTTP server mode to `claude-memory serve-mcp --http` with POST `/recall` endpoint. Accept `{ query, scope, limit }`, return JSON facts
|
|
179
|
+
- **Evidence**: QMD `src/mcp/server.ts:626-675` — `/query` and `/search` endpoints with structured JSON
|
|
180
|
+
- **Effort**: 2 days
|
|
181
|
+
- **Trade-off**: Requires WEBrick or similar Ruby HTTP server dependency
|
|
182
|
+
- **Recommendation**: CONSIDER — Useful for CI/scripting, but MCP covers primary use case
|
|
183
|
+
|
|
184
|
+
### 24. Signal-Based Ingestion Filtering
|
|
59
185
|
|
|
60
186
|
Source: claude-supermemory study (2026-03-02)
|
|
61
187
|
|
|
@@ -66,7 +192,7 @@ Source: claude-supermemory study (2026-03-02)
|
|
|
66
192
|
- **Trade-off**: May miss important but subtly-expressed facts. Our distiller already extracts structured facts, which inherently filters noise.
|
|
67
193
|
- **Recommendation**: DEFER — Distiller handles this naturally
|
|
68
194
|
|
|
69
|
-
###
|
|
195
|
+
### 25. HTTP MCP Transport
|
|
70
196
|
|
|
71
197
|
Source: QMD study (2026-03-02)
|
|
72
198
|
|
|
@@ -117,6 +243,20 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
|
|
|
117
243
|
- **KBS Redis Backend** — Redis store adds operational complexity; SQLite + Extralite is fast enough for our use case
|
|
118
244
|
- **KBS Message Queue** — Hook ordering already handles coordination; message queue adds unnecessary complexity
|
|
119
245
|
- **KBS Declarative Rule DSL** — Expressive but wrong paradigm for knowledge recall; our query/search approach is more appropriate
|
|
246
|
+
- **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
|
|
247
|
+
- **Config Inheritance Pattern** — claude-mem's `parent--override` naming with deep merge. Not enough configuration variants to justify the complexity
|
|
248
|
+
- **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
|
|
249
|
+
- **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
|
|
250
|
+
- **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
|
|
251
|
+
- **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
|
|
252
|
+
- **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
|
|
253
|
+
- **DAG-Based Conversation Compaction** — lossless-claw compresses conversations into a summary hierarchy; we distill structured facts. Fundamentally different paradigms that are complementary, not competing
|
|
254
|
+
- **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
|
|
255
|
+
- **Go TUI for Debugging** — Adding a second language for an interactive debugging tool is over-engineering. CLI commands are sufficient (lossless-claw)
|
|
256
|
+
- **Per-Conversation Scoping** — lossless-claw scopes knowledge per-conversation only. Our dual-database (global/project) is more useful for knowledge spanning conversations
|
|
257
|
+
- **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
|
+
- **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
|
|
120
260
|
|
|
121
261
|
---
|
|
122
262
|
|
|
@@ -139,20 +279,22 @@ Added `claude-memory export` command. Dumps facts with entities and provenance t
|
|
|
139
279
|
## References
|
|
140
280
|
|
|
141
281
|
- [episodic-memory GitHub](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15)
|
|
142
|
-
- [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.
|
|
143
|
-
- [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search (
|
|
144
|
-
- [claude-supermemory GitHub](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed memory (v2.0.
|
|
145
|
-
- [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine (
|
|
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)
|
|
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)
|
|
146
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)
|
|
147
288
|
|
|
148
289
|
Influence documents:
|
|
149
|
-
- [docs/influence/qmd.md](influence/qmd.md) - Updated 2026-03-
|
|
150
|
-
- [docs/influence/episodic-memory.md](influence/episodic-memory.md) -
|
|
151
|
-
- [docs/influence/claude-mem.md](influence/claude-mem.md) -
|
|
152
|
-
- [docs/influence/grepai.md](influence/grepai.md) - Updated 2026-03-
|
|
153
|
-
- [docs/influence/claude-supermemory.md](influence/claude-supermemory.md) - Updated 2026-03-
|
|
154
|
-
- [docs/influence/kbs.md](influence/kbs.md) -
|
|
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
|
|
155
297
|
|
|
156
298
|
---
|
|
157
299
|
|
|
158
|
-
*Last updated: 2026-03-
|
|
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.*
|