claude_memory 0.5.0 → 0.6.0

data/docs/improvements.md

@@ -1,104 +1,102 @@
 # Improvements to Consider
 
-*Updated: 2026-02-03 - Removed Docid Short Hash System, LLM Response Caching, Structured Logging (implemented)*
+*Updated: 2026-03-02 - Re-studied all 5 influencer repos + new KBS study. Added new items from episodic-memory, claude-mem, updated QMD/grepai/supermemory findings.*
 *Sources:*
-- *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system*
-- *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search*
-- *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search with vector embeddings*
-- *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory plugin*
-- *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (updated 2026-02-02)*
+- *[thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.2, studied 2026-03-02)*
+- *[obra/episodic-memory](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15, studied 2026-03-02)*
+- *[yoanbernabeu/grepai](https://github.com/yoanbernabeu/grepai) - Semantic code search (v0.34.0, studied 2026-03-02)*
+- *[supermemoryai/claude-supermemory](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed persistent memory (v2.0.0, studied 2026-03-02)*
+- *[tobi/qmd](https://github.com/tobi/qmd) - On-device hybrid search engine (v1.1.0, studied 2026-03-02)*
+- *[MadBomber/kbs](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1, studied 2026-03-02)*
 
 This document contains only unimplemented improvements. Completed items are removed.
 
 ---
 
-## High Priority (QMD-Inspired)
+## High Priority
 
-### 1. Native Vector Storage (sqlite-vec) ⭐ CRITICAL
+### ~~1. Native Vector Storage (sqlite-vec)~~ ✅ Implemented 2026-03-04
 
-- **Value**: 10-100x faster KNN queries, enables larger fact databases
-- **QMD Proof**: Handles 10,000+ documents with sub-second vector queries
-- **Current Issue**: JSON embedding storage requires loading all facts, O(n) Ruby similarity calculation
-- **Solution**: sqlite-vec extension with native C KNN queries
-- **Implementation**:
-  - Schema migration v11: Create `facts_vec` virtual table using `vec0`
-  - Two-step query pattern (avoid JOINs - they hang with vec tables!)
-  - Update `Embeddings::Similarity` class
-  - Backfill existing embeddings
-- **Trade-off**: Adds native dependency (acceptable, well-maintained, cross-platform)
+Schema migration v12 with `facts_vec` virtual table (vec0, cosine distance). Two-step query pattern (KNN → batch hydration). VectorIndex class with native C KNN search, fallback to O(n) Ruby. Backfill via `claude-memory index --vec` and sweeper. Doctor check with coverage stats. Cross-platform: arm64-darwin, x86_64-darwin, x86_64-linux.
 
----
-
-## High Priority (Study-Inspired)
+### ~~2. Claude Code Plugin Distribution Format~~ ✅ Implemented 2026-03-04
 
-### 2. SessionStart Context Injection via Hook ⭐
+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.
 
-Source: claude-supermemory study
+---
 
-- **Value**: Guarantees Claude sees memory context immediately, supplements existing `.claude/rules/` publish
-- **Implementation**: Inject recalled facts into Claude's context at session start using `hookSpecificOutput.additionalContext`
-- **Evidence**: `context-hook.js:72-74` — uses hook response to inject `<supermemory-context>` XML
-- **Effort**: 1-2 days (hook handler, context formatter, settings)
+## Medium Priority
 
-### 3. Tool-Specific Observation Compression ⭐
+### 3. Incremental Indexing with File Watching
 
-Source: claude-supermemory study
+Source: grepai study (reinforced 2026-03-02)
 
-- **Value**: ~70% token reduction vs raw tool I/O in provenance descriptions
-- **Implementation**: Compact per-tool summarization for provenance (e.g., `Edited auth.js: "login()" → "async login()"`)
-- **Evidence**: `compress.js:13-75` — 10 tool handlers with human-readable output
-- **Effort**: 4-6 hours (class + tests + ingest integration)
+- **Value**: Eliminates manual `claude-memory ingest` calls
+- **Implementation**: Add `Listen` gem, watch `.claude/projects/*/transcripts/*.jsonl`, debounce 500ms, trigger IngestCommand automatically
+- **Evidence**: `watcher/watcher.go:30-59` — fsnotify with debouncing (300ms default), gitignore respect, event deduplication
+- **Effort**: 2-3 days
+- **Trade-off**: Background process ~10MB memory overhead
 
-### 4. Claude Code Plugin Distribution Format ⭐
+### 4. Document Chunking for Long Transcripts
 
-Source: QMD study
+Source: QMD study (updated 2026-03-02)
 
-- **Value**: 10x easier installation (one command vs multi-step gem + MCP + hook config)
-- **Implementation**: Package ClaudeMemory as marketplace plugin for single-command installation
-- **Evidence**: `.claude-plugin/marketplace.json` — complete plugin spec with MCP server bundling and skill definitions
+- **Value**: Better embeddings for long content (>3000 chars)
+- **Implementation**: 900 tokens/chunk, 15% overlap, markdown-aware break points
+- **Evidence**: QMD v1.1.0 `store.ts:53-219` — scored break point patterns (h1=100 → newline=1), code fence detection, squared distance decay
+- **Consideration**: Only if users report issues with long transcripts
 - **Effort**: 2-3 days
 
+### ~~5. Background Processing for Hooks~~ ✅ Implemented 2026-03-02
+
+`--async` flag on hook ingest/sweep/publish subcommands. Fork+detach for non-blocking execution, fallback to sync when fork unavailable.
+
 ---
 
-## Medium Priority
+## Low Priority / Defer
 
-### 5. Incremental Indexing with File Watching
+### 5. Signal-Based Ingestion Filtering
 
-Source: grepai study
+Source: claude-supermemory study (2026-03-02)
 
-- **Value**: Eliminates manual `claude-memory ingest` calls
-- **Implementation**: Add `Listen` gem, watch `.claude/projects/*/transcripts/*.jsonl`, debounce 500ms, trigger IngestCommand automatically
-- **Evidence**: `watcher/watcher.go:44` — `fsnotify` with debouncing (300ms default), gitignore respect
-- **Effort**: 2-3 days
-- **Trade-off**: Background process ~10MB memory overhead
+- **Value**: Reduce noise by prioritizing transcript sections with signal keywords
+- **Evidence**: supermemory `settings.json:signalKeywords` — keyword-triggered capture with context window
+- **Implementation**: During ingest, weight transcript sections containing signal keywords ("decided", "convention", "always", "never", "prefer") higher
+- **Effort**: 1-2 days
+- **Trade-off**: May miss important but subtly-expressed facts. Our distiller already extracts structured facts, which inherently filters noise.
+- **Recommendation**: DEFER — Distiller handles this naturally
 
-### 6. Background Processing for Hooks
+### 6. HTTP MCP Transport
 
-Source: episodic-memory study
+Source: QMD study (2026-03-02)
 
-- **Value**: Non-blocking hooks for better UX
-- **Implementation**: `--async` flag on hook commands, fork and detach
-- **Trade-off**: Background process management complexity, potential race conditions
+- **Value**: Shared server, models stay loaded, faster subsequent queries
+- **Evidence**: QMD `mcp.ts:119-137` — WebStandardStreamableHTTPServerTransport with daemon mode
+- **Implementation**: Add HTTP transport option alongside stdio
+- **Effort**: 2-3 days
+- **Trade-off**: Process management complexity
+- **Recommendation**: DEFER — Only if MCP startup latency becomes an issue
 
-### 7. Document Chunking for Long Transcripts
+### ~~7. MCP Discovery Tools~~ ✅ Implemented 2026-03-02
 
-Source: QMD study
+Added `memory.list_projects` MCP tool. Shows global DB, current project, and discovers other projects from promoted facts/global fact paths with stats.
 
-- **Value**: Better embeddings for long content (>3000 chars)
-- **Implementation**: 800 tokens, 15% overlap, semantic boundary detection
-- **Consideration**: Only if users report issues with long transcripts
+### ~~8. Database Compact Command~~ ✅ Implemented 2026-03-02
 
----
+Added `claude-memory compact` command. Runs SQLite VACUUM with optional integrity check (`--check`). Supports `--scope` for global/project/all. Reports size before/after with savings.
+
+### ~~9. Fact Export Command~~ ✅ Implemented 2026-03-02
+
+Added `claude-memory export` command. Dumps facts with entities and provenance to JSON. Supports `--scope`, `--status` (active/all), `--output` (file), `--pretty`. Includes version metadata for import compatibility.
 
 ---
 
 ## Features to Avoid
 
-- **Chroma Vector Database** — We use fastembed-rb with local ONNX model instead
+- **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)
 - **Claude Agent SDK for Distillation** — Direct API calls via `anthropic-rb` gem
-- **Worker Service Background Process** — Keep stdio-based MCP server
+- **Worker Service Background Process** — Keep stdio-based MCP server. claude-mem's worker architecture adds significant complexity and failure modes.
 - **Web Viewer UI** — CLI output is sufficient. Add if users request it
-- **Configuration-Driven Context** — Default config is sufficient. Add if users request it
 - **Neural Embeddings (EmbeddingGemma)** — Superseded by FastEmbed (BAAI/bge-small-en-v1.5)
 - **Cross-Encoder Reranking (Qwen3-Reranker-0.6B)** — Over-engineering for fact retrieval
 - **Query Expansion (LLM, Qwen3-1.7B)** — No LLM in recall path, too heavy
@@ -106,6 +104,19 @@ Source: QMD study
 - **YAML Collection System** — Our dual-database approach is cleaner
 - **Content-Addressable Storage** — Facts deduplicated by signature, not content hash
 - **Virtual Path System** — Dual-database provides clear namespace
+- **Cloud Storage Dependency** — Local-first is superior (supermemory's weakness)
+- **Tree-Sitter AST Code Navigation** — Out of scope for memory/fact retrieval (claude-mem's Smart Explore)
+- **RPG Semantic Code Graph** — Wrong domain; code structure graph vs fact knowledge graph (grepai)
+- **AGPL Licensing** — Too restrictive for developer tools (claude-mem)
+- **Multiple AI Providers (Gemini/OpenRouter)** — Over-engineering; anthropic-rb is sufficient
+- **Bubble Tea TUI** — CLI output is sufficient (grepai)
+- **Query Document Format (lex/vec/hyde)** — Over-engineering for fact retrieval (QMD)
+- **Team Memory via Cloud Sync** — Our dual-database handles scope well; cloud sync adds complexity (supermemory)
+- **Raw Conversation Storage** — We distill into structured facts (episodic-memory stores raw exchanges)
+- **KBS as Dependency (RETE inference engine)** — KBS (MadBomber/kbs) provides RETE inference, but solves a fundamentally different problem (forward-chaining rules vs knowledge recall). Architectural mismatch, schema incompatibility (JSON blobs vs normalized triples), performance regression (raw sqlite3 vs Sequel+Extralite), low adoption (2 stars, sole maintainer). See `docs/influence/kbs.md`.
+- **KBS Redis Backend** — Redis store adds operational complexity; SQLite + Extralite is fast enough for our use case
+- **KBS Message Queue** — Hook ordering already handles coordination; message queue adds unnecessary complexity
+- **KBS Declarative Rule DSL** — Expressive but wrong paradigm for knowledge recall; our query/search approach is more appropriate
 
 ---
 
@@ -127,12 +138,21 @@ Source: QMD study
 
 ## References
 
-- [episodic-memory GitHub](https://github.com/obra/episodic-memory) - Semantic conversation search
-- [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system
-- [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search
-- [claude-supermemory GitHub](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed memory
-- [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine
+- [episodic-memory GitHub](https://github.com/obra/episodic-memory) - Semantic conversation search (v1.0.15)
+- [claude-mem GitHub](https://github.com/thedotmack/claude-mem) - Memory compression system (v10.5.2)
+- [grepai GitHub](https://github.com/yoanbernabeu/grepai) - Semantic code search (v0.34.0)
+- [claude-supermemory GitHub](https://github.com/supermemoryai/claude-supermemory) - Cloud-backed memory (v2.0.0)
+- [QMD GitHub](https://github.com/tobi/qmd) - On-device hybrid search engine (v1.1.0)
+- [KBS GitHub](https://github.com/MadBomber/kbs) - Knowledge-Based System with RETE inference (v0.2.1)
+
+Influence documents:
+- [docs/influence/qmd.md](influence/qmd.md) - Updated 2026-03-02
+- [docs/influence/episodic-memory.md](influence/episodic-memory.md) - New 2026-03-02
+- [docs/influence/claude-mem.md](influence/claude-mem.md) - New 2026-03-02
+- [docs/influence/grepai.md](influence/grepai.md) - Updated 2026-03-02
+- [docs/influence/claude-supermemory.md](influence/claude-supermemory.md) - Updated 2026-03-02
+- [docs/influence/kbs.md](influence/kbs.md) - New 2026-03-02
 
 ---
 
-*Last updated: 2026-02-03 - Removed Docid, LLM Cache, Structured Logging (implemented). Renumbered items.*
+*Last updated: 2026-03-04 - Marked Claude Code Plugin Distribution Format as implemented. Previous: sqlite-vec (Native Vector Storage), Database Compact Command, Fact Export Command, Background Processing for Hooks (--async), MCP Discovery Tools (memory.list_projects), Hook Error Classification, Dynamic MCP Server Instructions, Progressive Disclosure Documentation, Conversation Exclusion Markers.*

data/docs/influence/claude-mem.md

@@ -0,0 +1,253 @@
+# Claude-Mem Analysis
+
+*Analysis Date: 2026-03-02*
+*Repository: https://github.com/thedotmack/claude-mem*
+*Version: 10.5.2 (commit ecb09df)*
+
+---
+
+## Executive Summary
+
+### Project Purpose
+
+Claude-Mem is a persistent memory compression system for Claude Code. It captures tool usage observations during sessions, generates semantic summaries, and injects relevant context into future sessions. The largest and most actively developed memory plugin in the ecosystem.
+
+### Key Innovation
+
+1. **Progressive Disclosure Pattern**: 3-layer token-efficient workflow — search (compact index, ~50-100 tokens/result) → timeline (chronological context) → get_observations (full details, ~500-1000 tokens/result). Claims ~10x token savings by filtering before fetching.
+
+2. **Worker Service Architecture**: Background HTTP server (port 37777) with web viewer UI, managed by Bun. Decouples hook processing from worker logic.
+
+3. **Smart Explore** (v10.5.0): Tree-sitter AST-powered code navigation with 3 MCP tools (`smart_search`, `smart_outline`, `smart_unfold`). Claims 6-12x token savings vs full file reads.
+
+4. **Multi-Platform Support**: Claude Code + Cursor + OpenClaw gateway adapters.
+
+### Technology Stack
+
+| Component | Technology |
+|-----------|-----------|
+| **Language** | TypeScript (ESM) |
+| **Runtime** | Bun (worker), Node.js (hooks) |
+| **Database** | SQLite (sessions, observations, summaries) |
+| **Vector Search** | Chroma vector database (hybrid semantic + keyword) |
+| **Summarization** | Claude Agent SDK + Gemini + OpenRouter agents |
+| **MCP** | @modelcontextprotocol/sdk v1.25.1 |
+| **Web UI** | React 18 + Express (port 37777) |
+| **AST Parsing** | tree-sitter (10 languages) |
+| **Build** | esbuild |
+| **Testing** | Bun test runner |
+| **Plugin** | Claude Code marketplace format |
+| **License** | AGPL-3.0 |
+
+### Production Readiness
+
+- **Maturity**: Production (v10.5.2, very active development)
+- **Test Coverage**: Extensive test suite (70+ test files across sqlite, worker, agents, search, context, infrastructure)
+- **Documentation**: Professional docs site (docs.claude-mem.ai)
+- **Community**: Large user base, active issue tracker
+- **Complexity**: High — worker service, Chroma, multiple AI providers, web UI
+
+---
+
+## Architecture Overview
+
+### Data Model
+
+```
+Lifecycle Hooks (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd)
+    ↓
+Hook Scripts → JSON stdin → Platform Adapter → Event Handler
+    ↓
+Worker Service (HTTP API on port 37777)
+    ↓
+┌─────────────────┐    ┌──────────────────┐
+│  SQLite DB      │    │  Chroma Vector DB│
+│  - sessions     │    │  - embeddings    │
+│  - observations │    │  - hybrid search │
+│  - summaries    │    │  - keyword index │
+│  - prompts      │    │                  │
+└─────────────────┘    └──────────────────┘
+    ↓
+MCP Tools (search, timeline, get_observations, smart_*)
+    ↓
+Web Viewer UI (React, port 37777)
+```
+
+### Key Design Patterns
+
+1. **Platform Adapter Pattern** (`src/cli/adapters/`): Claude Code and Cursor have different hook formats. Adapters normalize input for shared event handlers.
+
+2. **Progressive Disclosure** (`README:199-232`): 3-layer workflow for token-efficient memory retrieval:
+   - Layer 1: `search` — compact index with IDs (~50-100 tokens/result)
+   - Layer 2: `timeline` — chronological context around results
+   - Layer 3: `get_observations` — full details for filtered IDs
+
+3. **Worker Service** (`src/services/worker/`): Background HTTP server manages state, search, SSE broadcasting, and AI agent calls. Hooks are thin clients that POST to the worker.
+
+4. **Graceful Degradation** (`src/cli/hook-command.ts:26-66`): Sophisticated error classification — transport failures (worker down) return exit 0 (graceful), client bugs (4xx) return exit 2 (blocking).
+
+5. **Smart Explore** (v10.5.0): Tree-sitter AST parsing for structural code navigation. `smart_search` → `smart_outline` → `smart_unfold` progressive disclosure.
+
+### Comparison with ClaudeMemory
+
+| Aspect | Claude-Mem | ClaudeMemory | Notes |
+|--------|-----------|--------------|-------|
+| **Data Model** | Observations + summaries | Subject-predicate-object facts | They store raw observations; we extract knowledge |
+| **Storage** | SQLite + Chroma | Dual SQLite (project + global) | They need separate Chroma process |
+| **Vector Search** | Chroma (external) | fastembed-rb (embedded) | We're simpler, they're more capable |
+| **Architecture** | Worker service + hooks | MCP server + hooks | They have background process overhead |
+| **MCP Tools** | search, timeline, get_observations, smart_* | 18 recall/management tools | Different focus |
+| **Plugin Format** | marketplace.json | Ruby gem | They're easier to install |
+| **Web UI** | React viewer at :37777 | None | Feature we don't need |
+| **AI Providers** | Claude SDK + Gemini + OpenRouter | anthropic-rb | They're more flexible |
+| **License** | AGPL-3.0 | MIT | Our license is more permissive |
+| **Complexity** | Very high (~10K+ LOC) | Moderate (~5K LOC) | We're simpler by design |
+
+---
+
+## Key Components Deep-Dive
+
+### Component 1: Progressive Disclosure Search
+
+**Purpose**: Minimize token usage during memory retrieval.
+
+**Location**: `README:199-232`, MCP tools
+
+**Implementation**:
+```
+Step 1: search(query="auth bug", type="bugfix", limit=10)
+        → Returns compact index with IDs (~50-100 tokens/result)
+Step 2: Review index, identify relevant IDs (e.g., #123, #456)
+Step 3: get_observations(ids=[123, 456])
+        → Returns full details (~500-1000 tokens/result)
+```
+
+**Design Decisions**:
+- ~10x token savings by filtering before fetching details
+- Timeline layer provides chronological context
+- Batch ID fetching for efficiency
+
+### Component 2: Hook Error Classification
+
+**Purpose**: Distinguish worker unavailability from actual bugs.
+
+**Location**: `src/cli/hook-command.ts:26-66`
+
+```typescript
+// Transport failures → exit 0 (graceful degradation)
+const transportPatterns = [
+  'econnrefused', 'econnreset', 'epipe', 'etimedout',
+  'fetch failed', 'socket hang up',
+];
+// HTTP 4xx → exit 2 (blocking error, developer needs to see)
+// HTTP 5xx → exit 0 (server issues, degrade gracefully)
+```
+
+**Design Decisions**:
+- Conservative: unknown errors are blocking (surface bugs)
+- Transport failures never block Claude Code sessions
+- Hook stderr suppressed (Claude Code shows stderr as error UI)
+
+### Component 3: Smart Explore (Tree-Sitter AST)
+
+**Purpose**: Token-optimized structural code search.
+
+**Location**: v10.5.0 changelog, plugin skills
+
+**Design Decisions**:
+- 10 languages via tree-sitter grammars
+- 3-tool progressive disclosure: search → outline → unfold
+- Claims 6-12x token savings vs full file reads
+- Complements rather than replaces Read tool
+
+---
+
+## Comparative Analysis
+
+### What They Do Well
+
+1. **Progressive Disclosure**: Elegant token-saving pattern for search results
+2. **Graceful Degradation**: Sophisticated error classification prevents blocking Claude sessions
+3. **Platform Adapters**: Clean abstraction for Claude Code vs Cursor
+4. **Smart Explore**: AST-powered code navigation is genuinely useful
+5. **Web Viewer**: Real-time memory stream with SSE
+
+### What We Do Well
+
+1. **Knowledge Distillation**: Structured facts > raw observations
+2. **Truth Maintenance**: Supersession and conflict resolution
+3. **Simplicity**: No background process, no external database
+4. **Dual-Database System**: Clean project/global separation
+5. **License**: MIT vs AGPL-3.0
+6. **Test Architecture**: Focused, fast, no I/O in tests
+
+---
+
+## Adoption Opportunities
+
+### High Priority ⭐
+
+#### 1. Progressive Disclosure Pattern for Recall
+- **Value**: ~10x token savings on large result sets
+- **Evidence**: `README:199-232` — 3-layer search → timeline → details workflow
+- **Implementation**: Our `memory.recall_index` + `memory.recall_details` already implements this! Validate it matches their token savings pattern.
+- **Effort**: 0.5 days (validation and documentation)
+- **Trade-off**: None — we already have the infrastructure
+- **Recommendation**: **ADOPT** (document our existing progressive disclosure)
+
+#### 2. Hook Error Classification
+- **Value**: Prevent memory system errors from blocking Claude Code sessions
+- **Evidence**: `src/cli/hook-command.ts:26-66` — transport vs client error classification
+- **Implementation**: Add similar classification to our hook commands. Exit 0 for transport failures, exit 1 for bugs.
+- **Effort**: 1 day
+- **Trade-off**: Minimal
+- **Recommendation**: **ADOPT**
+
+### Medium Priority
+
+#### 3. Platform Adapter Pattern
+- **Value**: Clean abstraction for supporting multiple AI code editors
+- **Evidence**: `src/cli/adapters/` — Claude Code, Cursor adapters
+- **Implementation**: Extract hook input normalization into adapter interface
+- **Effort**: 2-3 days
+- **Trade-off**: Premature if we only support Claude Code
+- **Recommendation**: **DEFER** — Only if Cursor/Windsurf support is requested
+
+#### 4. Compact Result Mode Documentation
+- **Value**: Our `compact: true` mode already provides token savings — document it better
+- **Evidence**: Their progressive disclosure docs show clear token economics
+- **Implementation**: Add token estimates to our MCP tool descriptions
+- **Effort**: 0.5 days
+- **Recommendation**: **ADOPT**
+
+### Features to Avoid
+
+- **Worker Service Architecture**: Background process adds complexity and failure modes. Our stdio MCP server is simpler and sufficient.
+- **Chroma Vector Database**: External dependency. sqlite-vec (from QMD/episodic-memory) is better fit.
+- **Web Viewer UI**: CLI output is sufficient. CLAUDE.md already says to avoid this.
+- **AGPL License**: Restrictive for a developer tool.
+- **Multiple AI Providers**: Over-engineering. We use anthropic-rb directly.
+- **Smart Explore**: Interesting but out of scope — code search is not our domain.
+- **Tree-Sitter AST Parsing**: Not relevant to memory/fact retrieval.
+
+---
+
+## Key Takeaways
+
+### Main Learnings
+1. Progressive disclosure is the right pattern for token-efficient retrieval — we already have it
+2. Hook error classification is important for not blocking user sessions
+3. Worker service architecture adds significant complexity
+4. Chroma is being used but sqlite-vec (from QMD/episodic-memory) is simpler
+5. AGPL licensing is unusual for developer tools
+
+### Recommended Adoption Order
+1. **Document progressive disclosure**: We already have recall_index + recall_details
+2. **Add hook error classification**: Prevent hook failures from blocking sessions
+3. **Add token estimates to tool descriptions**: Help Claude use tools efficiently
+
+---
+
+*Analysis completed: 2026-03-02*
+*Analyst: Claude Code*
+*Review Status: Draft*