claude_memory 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfbba4c01acb3ad07b9114c6781ee7b6dbb197007ff61c72d7fa8b2ec164643e
-  data.tar.gz: 41df94bae4dc18bd00321ebca1fc80145faa6b180bb3ec00ff3d72a8cf091041
+  metadata.gz: 1483a3663c9c589abad58f80c71d772c592f13727d3fd1339418c2ba1a3db875
+  data.tar.gz: 34beebdf5e3cc8a70d383757ffaf7e21fde0724f963532e2d2548ec2e63ba329
 SHA512:
-  metadata.gz: f9e8278553ef1ba3c6d490304c9118c519612d5c6cd61230e94dc0dccca40ef653118e7c364e35ba2e58b2fb66d6b7fea39455f12723df6ddf8a8a9d55bc4d71
-  data.tar.gz: db870500e372150fbb6133ce43396aa57c2338e9aa392939219c4e2435d8bcaaac0724f858f387c97c3c9187a7b1409268b7246d91ad6018324935089daa149e
+  metadata.gz: 514022df68751e4421942d914c003a1e104a5c2b5ab4a639619ca05bb4d6bafd722d87009dc898a5b578f1b7efdae50df68b5b8232e1cf42a8bb5e88a06e66c3
+  data.tar.gz: 68c5a36361d3048e4c92bba7127e7fa0bc9ff09f6de3779ae59f7799cd4152d63030386ea2b124a90b345063545028b0da0401c9144f284c7e34290b2d674ba7

data/.claude/settings.json

@@ -6,7 +6,16 @@
           {
             "type": "command",
             "command": "claude-memory hook ingest",
-            "timeout": 10
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 5
           }
         ]
       }
@@ -14,11 +23,6 @@
     "SessionStart": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 10
-          },
           {
             "type": "command",
             "command": "claude-memory hook context",
@@ -41,6 +45,20 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          }
+        ]
       }
     ],
     "SessionEnd": [
@@ -57,6 +75,60 @@
             "timeout": 30
           }
         ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "TeammateIdle": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest",
+            "timeout": 15
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 15
+          }
+        ]
       }
     ]
   }

data/.claude/settings.local.json

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

data/.claude/skills/improve/SKILL.md

@@ -3,23 +3,88 @@ name: improve
 description: Incrementally implement feature improvements from docs/improvements.md with tests and atomic commits. Focuses on new functionality rather than refactoring.
 agent: general-purpose
 allowed-tools: Read, Grep, Edit, Write, Bash
+arguments:
+  - name: mode
+    description: "Execution mode: 'sub-agent' (default, sequential) or 'agent-team' (parallel via agent teams)"
+    required: false
+    default: "sub-agent"
 ---
 
 # Feature Improvements - Incremental Implementation
 
 Systematically implement feature improvements from `docs/improvements.md`, making tested, atomic commits for each feature addition.
 
+## Execution Modes
+
+This skill supports two modes, passed as the first argument:
+
+- **`sub-agent`** (default): A single agent works through improvements sequentially. Best for small batches (1-3 features) or features with dependencies.
+- **`agent-team`**: Spawns a coordinated team of agents that implement independent features in parallel. Best for larger batches (3+) of independent features.
+
+---
+
+## Mode: agent-team
+
+When invoked with `agent-team`, follow this process:
+
+### Step 1: Read and Assess Improvements
+
+Read `docs/improvements.md` and identify all implementable features using the same feasibility criteria as sub-agent mode (skip Categories D-F, "Features to Avoid", "If Requested" items).
+
+### Step 2: Group Independent Features
+
+Partition implementable features into independent groups:
+- Features touching **different files** can be parallelized
+- Features sharing files or with dependencies must be sequential
+- Aim for 3-5 teammates maximum
+
+### Step 3: Create the Agent Team
+
+Create an agent team. For each teammate:
+
+1. **Assign one or two related features** per teammate
+2. **Provide full context** — teammates don't share your conversation history
+3. **Include these instructions for each teammate**:
+   - Read relevant existing code before making changes
+   - Follow the project's code style (Standard Ruby, frozen_string_literal)
+   - Write tests for all new functionality
+   - Run `bundle exec rake standard:fix` before committing
+   - Run relevant spec file after each edit, full suite before committing
+   - Run `bundle exec rspec` to verify all tests pass
+   - Make atomic commits with `[Feature]` prefix format
+   - Update `docs/improvements.md` to mark features as implemented
+   - Reference `.claude/skills/improve/feature-patterns.md` for implementation recipes
+
+### Step 4: Monitor and Coordinate
+
+- Wait for all teammates to complete their tasks
+- If a teammate reports a blocker or conflict, help resolve it
+- Do NOT implement tasks yourself — let teammates do the work
+
+### Step 5: Validate and Report
+
+After all teammates finish:
+
+1. Run the full test suite: `bundle exec rspec`
+2. Run the linter: `bundle exec rake standard:fix`
+3. If any failures, fix them or coordinate with the relevant teammate
+4. Provide a consolidated progress report (same Final Report format as sub-agent mode)
+
+---
+
+## Mode: sub-agent (default)
+
 ## Process Overview
 
 1. **Check memory health** by calling `memory.check_setup` to verify the system is operational
 2. **Read the improvements document** from `docs/improvements.md`
-2. **Identify unimplemented features** from "Remaining Tasks" section
-3. **Prioritize by stated priority** (Medium → Low)
-4. **Assess feasibility** (skip if too complex or requires external services)
-5. **Implement features incrementally** (one logical feature at a time)
-6. **Run tests after each change** to ensure nothing breaks
-7. **Make atomic commits** that capture the feature and its purpose
-8. **Update improvements.md** to mark features as implemented
+3. **Identify unimplemented features** from "Remaining Tasks" section
+4. **Prioritize by stated priority** (Medium → Low)
+5. **Assess feasibility** (skip if too complex or requires external services)
+6. **Implement features incrementally** (one logical feature at a time)
+7. **Run tests after each change** to ensure nothing breaks
+8. **Make atomic commits** that capture the feature and its purpose
+9. **Update improvements.md** to mark features as implemented
 
 ## Detailed Steps
 
@@ -100,11 +165,15 @@ For each feature:
    ```bash
    bundle exec rake standard:fix
    ```
-5. **Run tests**:
+5. **Run targeted tests** after each edit:
+   ```bash
+   bundle exec rspec spec/claude_memory/<relevant_spec>.rb
+   ```
+6. **Run full suite** before committing:
    ```bash
    bundle exec rspec
    ```
-6. **Fix any test failures** before proceeding
+7. **Fix any test failures** before proceeding
 
 ### Step 5: Make Atomic Commit
 
@@ -300,9 +369,15 @@ Is it marked "Features to Avoid"?
                 ↓
                 Category D (Background)?
                 ├─ YES → Assess carefully, may skip
-                └─ NO → Implement (Categories A-C safe)
+                └─ NO → Continue
                     ↓
-                    Implement the feature
+                    Does it have dependencies on other features?
+                    ├─ YES → Are dependencies complete?
+                    │   ├─ NO → SKIP, note dependency
+                    │   └─ YES → Continue
+                    └─ NO → Implement (Categories A-C safe)
+                        ↓
+                        Implement the feature
                     ↓
                     Run tests
                     ↓
@@ -324,11 +399,15 @@ Is it marked "Features to Avoid"?
 ## Time Budgets
 
 **Per Feature:**
-- Category A (Schema): Max 20 minutes
-- Category B (Reporting): Max 30 minutes
-- Category C (CLI): Max 30 minutes
-- Category D (Background): Max 60 minutes (or skip)
-- Category E (External): Max 45 minutes (or skip)
+- Category A (Schema): Max 15 minutes — skip if stuck after 15
+- Category B (Reporting): Max 20 minutes — skip if stuck after 20
+- Category C (CLI): Max 30 minutes — skip if stuck after 30
+- Category D (Background): Max 45 minutes (or skip at first sign of daemon complexity)
+- Category E (External): Max 30 minutes (or skip at first sign of dependency issues)
+
+**Per Debug Cycle:**
+- Test failure fix: Max 15 minutes — if you can't fix it in 15 minutes, revert and skip
+- Understanding code: Max 10 minutes — if unclear after 10 minutes, skip and report
 
 **Session Total:** Max 2 hours
 
@@ -337,26 +416,35 @@ If time budget exceeded: SKIP remaining features and report.
 ## Testing Strategy
 
 ### Test Frequency
-- After schema changes: Run all specs
-- After new command: Run command specs + integration
-- After reporting changes: Run relevant specs
-- Before commit: Full test suite
+- After each file edit: Run the relevant spec file
+- After schema changes: Run `spec/claude_memory/store/`
+- After new command: Run `spec/claude_memory/commands/`
+- Before each commit: Full test suite
+- If >5 files changed: Full test suite immediately
 
 ### Test Commands
 ```bash
-# Specific command tests
-bundle exec rspec spec/claude_memory/commands/
+# Single relevant spec (fastest feedback)
+bundle exec rspec spec/claude_memory/commands/metrics_command_spec.rb
 
-# Schema tests
+# Module-level specs
+bundle exec rspec spec/claude_memory/commands/
 bundle exec rspec spec/claude_memory/store/
 
-# Full suite
+# Full suite (before commit)
 bundle exec rspec
 
-# With linting
+# With linting (final check)
 bundle exec rake
 ```
 
+### Test Failure Response
+1. Read error message carefully
+2. Check if your change caused it (vs pre-existing)
+3. If your change: fix within 15 minutes or revert and skip
+4. If pre-existing: note and continue
+5. If unsure: revert change and skip item
+
 ### New Feature Tests
 
 Always add tests for new features:

data/.claude-plugin/commands/distill-transcripts.md

@@ -0,0 +1,98 @@
+# Distill Transcripts
+
+Extract structured knowledge (facts, entities, decisions) from undistilled transcript content and persist it to long-term memory.
+
+## Usage
+
+```
+/distill-transcripts
+/distill-transcripts --limit 10
+```
+
+## Instructions
+
+You are a knowledge extraction specialist. Your job is to read raw transcript content and extract structured facts, entities, and decisions, then persist them via the memory.store_extraction MCP tool.
+
+### Step 1: Get Undistilled Content
+
+Call `memory.undistilled` with `limit: 10` to get transcript content that hasn't been processed yet.
+
+If no items are returned, report "No undistilled content found" and stop.
+
+### Step 2: Extract Knowledge (per item)
+
+For each content item, carefully read the raw_text and extract:
+
+**Entities** — Named things mentioned:
+- type: database, framework, language, platform, repo, module, person, service
+- name: Canonical name (e.g., "PostgreSQL" not "postgres")
+- confidence: 0.0-1.0
+
+**Facts** — Knowledge learned:
+- subject: Entity name or "repo" for project-level facts
+- predicate: uses_database, uses_framework, convention, decision, auth_method, deployment_platform, depends_on, testing_strategy
+- object: The value
+- confidence: 0.0-1.0
+- quote: Source excerpt (max 200 chars)
+- strength: "stated" (explicitly said) or "inferred" (implied)
+- scope_hint: "project" (this project only) or "global" (all projects)
+
+**Decisions** — Choices made:
+- title: Short summary (max 100 chars)
+- summary: Full description
+- status_hint: "accepted", "proposed", or "rejected"
+
+### What to Extract
+
+- Technology choices ("we use PostgreSQL", "switched to React")
+- Conventions ("always use frozen_string_literal", "test files go in spec/")
+- Architectural decisions ("API uses REST", "auth via JWT")
+- Preferences ("prefer 4-space indent", "use Standard Ruby")
+- Project structure ("migrations in db/migrations/", "commands in commands/")
+
+### What to Skip
+
+- Debugging steps and transient errors
+- Code output and tool observations
+- File contents that were just being read
+- Ephemeral task details ("fix this test", "run the linter")
+- Information already obvious from the codebase itself
+
+### Scope Detection
+
+Set scope_hint to "global" when the text contains signals like:
+- "I always...", "in all my projects...", "my preference is..."
+- "everywhere", "across all repos"
+
+Default to "project" for everything else.
+
+### Step 3: Persist Each Extraction
+
+For each content item with extracted knowledge:
+
+1. Call `memory.store_extraction` with the entities, facts, and decisions arrays
+2. Call `memory.mark_distilled` with the content_item_id and facts_extracted count
+3. If nothing was extracted, still call `memory.mark_distilled` with facts_extracted: 0
+
+### Step 4: Report
+
+Return a summary:
+
+```
+## Distillation Complete
+
+- Items processed: N
+- Facts extracted: N
+- Entities found: N
+- Decisions captured: N
+- Items skipped (nothing to extract): N
+```
+
+### Guidelines
+
+- Process items one at a time to keep extractions focused
+- Use `compact: true` on `memory.undistilled` for smaller responses
+- Be conservative — only extract facts you're confident about (>0.7)
+- Prefer "stated" strength over "inferred" unless clearly implied
+- Do NOT fabricate facts — only extract what's actually in the text
+- If text is mostly code/tool output with no conversational knowledge, mark as distilled with 0 facts

data/.claude-plugin/commands/memory-recall.md

@@ -0,0 +1,67 @@
+# Memory Recall Agent
+
+Search long-term memory for facts, decisions, conventions, and architectural knowledge. Chains multiple memory tools to build comprehensive answers while saving main-agent context.
+
+## Usage
+
+Provide a natural language query describing what you want to recall:
+
+```
+/memory-recall database migration strategy
+/memory-recall authentication decisions
+/memory-recall testing conventions
+```
+
+## Workflow
+
+1. **Fast lookup** — Start with `memory.recall` for keyword matches
+2. **Semantic search** — If recall returns few results, try `memory.recall_semantic` for conceptual matches
+3. **Shortcuts** — For known categories, use `memory.decisions`, `memory.conventions`, or `memory.architecture`
+4. **Deep dive** — For specific facts, use `memory.explain` to get provenance and `memory.fact_graph` to see relationships
+5. **Synthesize** — Combine findings into a concise, structured answer
+
+## Instructions
+
+You are a memory recall specialist. Given a query, search ClaudeMemory using the available MCP tools and return a synthesized answer.
+
+### Step 1: Initial Search
+
+Run `memory.recall` with the user's query. If the query mentions decisions, conventions, or architecture, also run the appropriate shortcut tool in parallel.
+
+### Step 2: Expand if Needed
+
+If Step 1 returns fewer than 3 results:
+- Try `memory.recall_semantic` with a rephrased version of the query
+- Try `memory.search_concepts` with 2-3 key concepts extracted from the query
+
+### Step 3: Enrich Key Facts
+
+For the top 2-3 most relevant facts:
+- Run `memory.explain` to get provenance (where the fact came from)
+- If relationships matter, run `memory.fact_graph` to see connected facts
+
+### Step 4: Synthesize
+
+Return a structured response:
+
+```
+## Memory Recall Results
+
+### Key Facts
+- [Fact 1 with provenance]
+- [Fact 2 with provenance]
+
+### Context
+[How these facts relate to the query]
+
+### Confidence
+[High/Medium/Low based on number and freshness of supporting facts]
+```
+
+### Guidelines
+
+- Prefer `memory.recall` (fast, token-efficient) before escalating to semantic search
+- Use `compact: true` on all tool calls to minimize token usage
+- Do NOT fabricate facts — only report what memory tools return
+- If no relevant facts found, say so clearly rather than guessing
+- Include fact IDs so the main agent can reference them

data/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.7.0",
+      "version": "0.8.0",
       "source": "./",
       "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
       "repository": "https://github.com/codenamev/claude_memory"

data/.claude-plugin/plugin.json

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

data/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-03-30
+
+### Added
+
+**Three-Layer Distillation Pipeline**
+- Automatic distillation via NullDistiller in ingest pipeline (Layer 1: regex-based, P95 < 5ms)
+- Context hook injection for LLM-based extraction at SessionStart (Layer 2: Claude Code as distiller, zero extra cost)
+- `/distill-transcripts` skill for manual deep extraction (Layer 3: on-demand, depth-aware prompts)
+- `memory.undistilled` and `memory.mark_distilled` MCP tools for distillation tracking
+- `Hook::DistillationRunner` extracted from Handler for context hook injection
+- `TaskCompleted` and `TeammateIdle` hook events for ingest triggers
+- Distillation metrics backfill on database initialization
+- Doctor check for undistilled content
+- Pending distillation count in `memory.status` output
+
+**Recall Enhancements**
+- Intent parameter for recall query disambiguation (#3)
+- Retrieval score traces for semantic search (#5)
+- Configurable embedding providers with dimension checking
+
+**Hook Enhancements**
+- `statusMessage` on all hooks for descriptive spinner text during hook execution
+- `StopFailure` hook to capture transcript data even on session errors (rate limits, server errors)
+- `Notification` hook with `idle_prompt` matcher for opportunistic sweep during idle
+
+**New Commands & Skills**
+- `install-skill` command and `memory-recall` agent (#8, #12)
+- Shell completion command for bash and zsh (#18)
+
+**Distillation Benchmark Results**
+- NullDistiller: Concept Recall 0.952, Fact Precision/Recall 1.000 (31 test cases)
+- Claude Code LLM: Concept Recall 0.902 (all 41 cases), 0.900 on semantic cases (vs 0.333 for regex)
+- Average 1.6 facts stored per case across LLM extraction
+- E2E distillation recall benchmark and extraction quality benchmarks
+- Concept-based matching for distiller-agnostic benchmark comparison
+
+### Fixed
+
+- `--allowedTools` added to `ClaudeCliRunner` for MCP tool permissions
+- Test isolation for context hook when global database has facts
+
+### Internal
+- Extracted `RetryHandler` and `SchemaManager` modules from `SQLiteStore`
+- Extracted `Recall` into engine strategy pattern with `DualEngine`, `LegacyEngine`, and shared `QueryCore`
+- Extracted `Tools` god object into 6 handler modules
+- Added 36 specs for 5 previously untested files
+- All 3 god objects eliminated, 0 files over 500 lines
+
+## [0.7.1] - 2026-03-17
+
+### Added
+
+**Three-Level Sweep Escalation**
+- `Maintenance` class with light/standard/deep sweep levels for progressive database maintenance
+- Exposed sweep escalation via `memory.sweep_now` MCP tool with configurable level
+- Tool escalation workflow added to MCP QueryGuide documentation
+
+**Embedding Deduplication**
+- Content-addressed deduplication for embeddings using SHA256 hashing
+- Deduplication before vector scoring in fallback path to prevent duplicate results
+
+**MCP Enhancements**
+- Structured error classification for MCP tools via `ErrorClassifier` module
+- Dynamic knowledge summary in MCP server instructions via `InstructionsBuilder`
+
+### Fixed
+
+- **Plugin hook loading error**: Removed explicit `hooks` reference from `plugin.json` manifest — Claude Code auto-loads `hooks/hooks.json` from the plugin root, so declaring it caused "Duplicate hooks file detected" errors on plugin install
+
+### Internal
+- Influence study: lossless-claw v0.3.0 DAG-based lossless context management
+- Marked 7 improvements as implemented (#10, #11, #14, #15, #16, #19, #20)
+
 ## [0.7.0] - 2026-03-12
 
 ### Added
@@ -20,7 +93,7 @@ All notable changes to this project will be documented in this file.
 - Opt-out: set `CLAUDE_MEMORY_ISOLATE_WORKTREES=1` for per-worktree isolation
 
 **MCP Enhancements**
-- Tool annotations: `readOnlyHint`, `idempotentHint`, `destructiveHint` on all 21 tools
+- Tool annotations: `readOnlyHint`, `idempotentHint`, `destructiveHint` on all 23 tools
 - Stdout protection: MCP server redirects `$stdout` to `$stderr` to prevent protocol corruption from accidental `puts`/`print` calls
 - Self-excluding agent conversations via `SELF_CONTEXT_MARKER` to prevent meta-pollution