claude_memory 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e80122650f18772c74f205c856323762c83353e41dff45e5e042122a10bdabd
-  data.tar.gz: 5e08c7d46b7d064266052f9e7871a507911298994590905bf62a156060ec4944
+  metadata.gz: d32c7aa8093eedade1783eefa7109c996aa134d01dea01b67794612c126cf068
+  data.tar.gz: 78fe0f2ff602c740b6ab727a0fde88d07fb235f38b1143b644b4e7498f07079f
 SHA512:
-  metadata.gz: 04f9ed69ac3bd2bb4ae8457e916d8bb9e616b26d4b2ab37f75ab89e890a838c033f1fc692d9b323f2eb3f065ce43bdfe7721fac41611413f225e28cf688e44b0
-  data.tar.gz: e8348331eaa260add3a48e793cf501ec4c9c35421ce6dc115388a2a3bb68a739a817beab7e4ed7531ef59d85edb57342117c9f25045712c1e63d42e7285cb39f
+  metadata.gz: be68b153e9e25ef3b8e5ad71ba7fdd89e5ace40f0848125b480bf35c96ad8b0a73b1fd891e59faf5807bc99d8d637f0c6d647e2b1d6c86ad0654b9df69c1ab45
+  data.tar.gz: 92ee3e92e7967e03f642a5736a84f70563dd6e9f00fc3a7b24714b97294348e35645cdbfdd4b760bc5ee21301bb869bccbc686050cbc95e2bf7399c38508a32e

data/.claude/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- ClaudeMemory v0.4.0 -->
+<!-- ClaudeMemory v0.5.0 -->
 # Project Memory
 
 @.claude/rules/claude_memory.generated.md

data/.claude/rules/claude_memory.generated.md

@@ -1,8 +1,21 @@
 <!-- 
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-02-02T17:26:07Z
+  Generated: 2026-02-04T16:37:00Z
 -->
 
 # Project Memory
 
+## Current Decisions
+
+- From QMD 2026-02-02 restudy: adopt Claude Code plugin format, MCP structured content pattern, MCP query guide prompt, inline status checks. Carry forward sqlite-vec, RRF, docids, smart expansion from 2026-01-26. Reject custom fine-tuned models, LLM reranking, YAML collections.
+- From claude-supermemory study: adopt SessionStart hook context injection (hookSpecificOutput.additionalContext), tool-specific observation compression, and relative time formatting. Reject cloud storage dependency and no-test approach.
+
+## Conventions
+
+- MCP tools return dual content (text summary) + structuredContent (JSON) via TextSummary module and Server#handle_tools_call. Compact mode (compact: true) omits receipts for ~60% smaller responses.
+- ContentSanitizer strips system-reminder, local-command-caveat, command-message, command-name, command-args tags in addition to private/no-memory/secret/claude-memory-context.
+- Core::RelativeTime module provides progressive time formatting: just now → Xm ago → Xh ago → Xd ago → YYYY-MM-DD. Used in ResponseFormatter for *_ago fields.
+- MCP server registers memory_guide prompt via prompts/list and prompts/get endpoints. QueryGuide module holds prompt content.
+- Claude Code plugin with marketplace.json, skill definitions, MCP server bundling. 5,700+ stars, by Tobi Lütke. Custom fine-tuned query expansion (Qwen3-1.7B, SFT+GRPO). Dual content/structuredContent MCP pattern.
+- Cloud-backed Claude Code plugin (~1,195 LOC JavaScript) using Supermemory API for persistent memory across sessions. Uses hooks for SessionStart context injection and Stop transcript capture. No local database.

data/.claude/skills/check-memory/SKILL.md

@@ -16,6 +16,16 @@ The user is asking about: $ARGUMENTS
 
 ## Step-by-Step Workflow
 
+### 0. Verify Memory Health
+
+Before querying, confirm the memory system is operational:
+
+```
+memory.check_setup
+```
+
+If status is not "healthy", inform the user and suggest running `claude-memory doctor` for details.
+
 ### 1. Query Memory (REQUIRED FIRST STEP)
 
 Run multiple memory queries to find existing knowledge:

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

@@ -11,7 +11,8 @@ Systematically implement feature improvements from `docs/improvements.md`, makin
 
 ## Process Overview
 
-1. **Read the improvements document** from `docs/improvements.md`
+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)
@@ -22,6 +23,16 @@ Systematically implement feature improvements from `docs/improvements.md`, makin
 
 ## Detailed Steps
 
+### Step 0: Verify Memory Health
+
+Before starting, confirm the memory system is operational:
+
+```
+memory.check_setup
+```
+
+If status is not "healthy", address any issues before proceeding.
+
 ### Step 1: Read and Parse Improvements Document
 
 ```bash

data/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
   "author": {
     "name": "Valentino Stoll"

data/CHANGELOG.md

@@ -4,6 +4,76 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-02-04
+
+### Added
+
+**MCP Structured Content & Compact Mode**
+- Dual content (text summary) + structuredContent (JSON) for all MCP tools
+  - `TextSummary` module generates human-readable summaries alongside structured data
+  - Compact mode (`compact: true`) omits provenance receipts for ~60% smaller responses
+- MCP query guide prompt registered via `prompts/list` and `prompts/get` endpoints
+  - `QueryGuide` module provides tool selection guidance to Claude
+
+**Search & Retrieval Improvements**
+- Reciprocal Rank Fusion (RRF) replacing naive merge for hybrid search
+  - Better result ordering when combining FTS5 and semantic search results
+- Smart expansion detection to skip unnecessary vector search
+  - Reduces latency when FTS5 already provides strong matches
+- Enhanced snippet extraction for search results
+  - Better context windows around matched terms
+
+**Provenance & Traceability**
+- Line-range references in provenance for precise source linking
+  - Facts now track exact line ranges in source transcripts
+- Fact dependency graph visualization via BFS traversal
+  - Trace supersession and conflict chains between facts
+
+**User-Friendly Identifiers**
+- Docid short hash system for user-friendly fact references
+  - Short, memorable identifiers instead of raw integer IDs
+
+**Caching & Performance**
+- LLM response caching schema and store methods
+  - Cache layer for expensive extraction operations
+- Structured JSON logging with level filtering
+  - Configurable log levels (debug, info, warn, error)
+  - JSON format for machine-parseable log output
+
+**Ingestion & Content Processing**
+- Configurable tool capture filtering for ingestion
+  - Control which tool outputs are captured during transcript processing
+- ContentSanitizer now strips `system-reminder`, `local-command-caveat`, `command-message`,
+  `command-name`, and `command-args` tags in addition to privacy tags
+- Relative time formatting in MCP recall output
+  - Progressive format: just now → Xm ago → Xh ago → Xd ago → YYYY-MM-DD
+
+**Developer Tools**
+- `--brief` flag for doctor command and health checks in skills
+  - Quick pass/fail output for automated workflows
+
+### Fixed
+- Preserve SQLite PRAGMAs across connection reconnects
+  - WAL mode and other pragmas now survive reconnection cycles
+- Timestamp-only churn in publish output
+  - Publish no longer regenerates files when only the timestamp changed
+
+### Internal
+
+**Code Quality Improvements**
+- Extract duplicates and decompose long methods across codebase
+- Extract ingester transaction body into focused methods
+- Decompose `resolve_fact` into intention-revealing methods
+- Extract `check_setup` and `detailed_stats` into focused helpers
+- Fix N+1 query patterns in `recall.rb`
+- Fix 6 quick wins from quality review (frozen strings, method sizes, naming)
+
+**Research & Studies**
+- QMD restudy (2026-02-02): adopt Claude Code plugin format, MCP structured content pattern,
+  MCP query guide prompt, inline status checks
+- claude-supermemory study: adopt SessionStart hook context injection, tool-specific observation
+  compression, and relative time formatting
+
 ## [0.4.0] - 2026-02-02
 
 ### Added

data/db/migrations/008_add_provenance_line_range.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Migration v8: Add line range references to provenance
+# - Adds line_start and line_end columns for precise source linking
+# - Enables fact verification by pointing to exact location in source content
+# - 1-indexed line numbers matching standard editor conventions
+Sequel.migration do
+  up do
+    alter_table(:provenance) do
+      add_column :line_start, Integer  # 1-indexed start line in source content
+      add_column :line_end, Integer    # 1-indexed end line in source content
+    end
+  end
+
+  down do
+    alter_table(:provenance) do
+      drop_column :line_start
+      drop_column :line_end
+    end
+  end
+end

data/db/migrations/009_add_docid.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Migration v9: Add docid (short hash identifier) to facts
+# - Adds docid column for user-friendly fact references (e.g., "abc123de")
+# - Docids are 8-character hex strings derived from SHA256 of fact content
+# - Enables cross-database references and better UX in CLI/MCP
+# - Backfills existing facts with generated docids
+require "digest"
+
+Sequel.migration do
+  up do
+    alter_table(:facts) do
+      add_column :docid, String, size: 8
+    end
+
+    run "CREATE UNIQUE INDEX IF NOT EXISTS idx_facts_docid ON facts(docid)"
+
+    # Backfill existing facts with docids
+    self[:facts].each do |fact|
+      input = "#{fact[:subject_entity_id]}:#{fact[:predicate]}:#{fact[:object_literal]}:#{fact[:created_at]}"
+      docid = Digest::SHA256.hexdigest(input)[0, 8]
+
+      # Handle unlikely collisions by appending id
+      existing = self[:facts].where(docid: docid).exclude(id: fact[:id]).first
+      if existing
+        docid = Digest::SHA256.hexdigest("#{input}:#{fact[:id]}")[0, 8]
+      end
+
+      self[:facts].where(id: fact[:id]).update(docid: docid)
+    end
+  end
+
+  down do
+    run "DROP INDEX IF EXISTS idx_facts_docid"
+    alter_table(:facts) do
+      drop_column :docid
+    end
+  end
+end

data/db/migrations/010_add_llm_cache.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Migration v10: Add LLM response cache for distillation cost reduction
+# - Creates llm_cache table to cache API responses by content hash
+# - Cache key: SHA256(operation + model + input)
+# - Enables significant cost savings for repeated/similar distillation requests
+# - Includes TTL support via created_at for future cache expiration
+Sequel.migration do
+  up do
+    create_table?(:llm_cache) do
+      primary_key :id
+      String :cache_key, null: false, unique: true  # SHA256 hex digest
+      String :operation, null: false                 # e.g., "distill", "extract"
+      String :model, null: false                     # e.g., "claude-sonnet-4-20250514"
+      String :input_hash, null: false                # SHA256 of input content
+      String :result_json, text: true, null: false   # Cached JSON response
+      Integer :input_tokens                          # Tokens in request
+      Integer :output_tokens                         # Tokens in response
+      String :created_at, null: false
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_llm_cache_key ON llm_cache(cache_key)"
+    run "CREATE INDEX IF NOT EXISTS idx_llm_cache_created_at ON llm_cache(created_at)"
+    run "CREATE INDEX IF NOT EXISTS idx_llm_cache_operation ON llm_cache(operation)"
+  end
+
+  down do
+    drop_table?(:llm_cache)
+  end
+end