claude_memory 0.7.1 → 0.8.0

data/lib/claude_memory/mcp/handlers/setup_handlers.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module MCP
+    module Handlers
+      # Setup and discovery tool handlers
+      module SetupHandlers
+        def check_setup
+          issues = []
+          warnings = []
+          config = Configuration.new
+
+          global_db_exists = check_global_database(config, issues)
+          project_db_exists = check_project_database(config, warnings)
+          current_version, version_status, claude_md_exists = check_claude_md_version(warnings)
+          hooks_configured = check_hooks_configuration(warnings)
+
+          build_setup_result(
+            global_db_exists, project_db_exists, claude_md_exists,
+            hooks_configured, current_version, version_status,
+            issues, warnings
+          )
+        end
+
+        def list_projects
+          result = {global: nil, current_project: nil, other_projects: []}
+
+          if @manager
+            result[:global] = list_global_database
+            result[:current_project] = list_current_project
+            result[:other_projects] = discover_other_projects
+          elsif @legacy_store
+            result[:global] = {
+              exists: true,
+              path: @legacy_store.db.opts[:database],
+              facts_active: @legacy_store.facts.where(status: "active").count,
+              entities: @legacy_store.entities.count
+            }
+          end
+
+          result[:project_count] = 1 + result[:other_projects].size
+          result
+        end
+
+        private
+
+        def check_global_database(config, issues)
+          exists = File.exist?(config.global_db_path)
+          issues << "Global database not found at #{config.global_db_path}" unless exists
+          exists
+        end
+
+        def check_project_database(config, warnings)
+          exists = File.exist?(config.project_db_path)
+          warnings << "Project database not found at #{config.project_db_path}" unless exists
+          exists
+        end
+
+        def check_claude_md_version(warnings)
+          claude_md_path = ".claude/CLAUDE.md"
+          unless File.exist?(claude_md_path)
+            warnings << "No .claude/CLAUDE.md found"
+            return [nil, nil, false]
+          end
+
+          content = File.read(claude_md_path)
+          unless content.include?("ClaudeMemory")
+            warnings << "CLAUDE.md exists but no ClaudeMemory configuration found"
+            return [nil, nil, true]
+          end
+
+          current_version = SetupStatusAnalyzer.extract_version(content)
+          unless current_version
+            warnings << "CLAUDE.md has ClaudeMemory section but no version marker"
+            return [nil, "no_version_marker", true]
+          end
+
+          version_status = SetupStatusAnalyzer.determine_version_status(current_version, ClaudeMemory::VERSION)
+          if version_status == "outdated"
+            warnings << "Configuration version (v#{current_version}) is older than ClaudeMemory (v#{ClaudeMemory::VERSION}). Consider running upgrade."
+          end
+
+          [current_version, version_status, true]
+        end
+
+        def check_hooks_configuration(warnings)
+          settings_paths = [".claude/settings.json", ".claude/settings.local.json"]
+          settings_paths.each do |path|
+            next unless File.exist?(path)
+            begin
+              config_data = JSON.parse(File.read(path))
+              return true if config_data["hooks"]&.any?
+            rescue JSON::ParserError
+              warnings << "Invalid JSON in #{path}"
+            end
+          end
+
+          warnings << "No hooks configured for automatic ingestion"
+          false
+        end
+
+        def build_setup_result(global_db_exists, project_db_exists, claude_md_exists, hooks_configured, current_version, version_status, issues, warnings)
+          initialized = global_db_exists && claude_md_exists
+          status = SetupStatusAnalyzer.determine_status(global_db_exists, claude_md_exists, version_status)
+          recommendations = SetupStatusAnalyzer.generate_recommendations(initialized, version_status, warnings.any?)
+
+          {
+            status: status,
+            initialized: initialized,
+            version: {
+              current: current_version || "unknown",
+              latest: ClaudeMemory::VERSION,
+              status: version_status || "unknown"
+            },
+            components: {
+              global_database: global_db_exists,
+              project_database: project_db_exists,
+              claude_md: claude_md_exists,
+              hooks_configured: hooks_configured
+            },
+            issues: issues,
+            warnings: warnings,
+            recommendations: recommendations
+          }
+        end
+
+        def list_global_database
+          if @manager.global_exists?
+            @manager.ensure_global!
+            store = @manager.global_store
+            {
+              exists: true,
+              path: @manager.global_db_path,
+              facts_active: store.facts.where(status: "active").count,
+              facts_total: store.facts.count,
+              entities: store.entities.count
+            }
+          else
+            {exists: false, path: @manager.global_db_path}
+          end
+        end
+
+        def list_current_project
+          if @manager.project_exists?
+            @manager.ensure_project!
+            store = @manager.project_store
+            {
+              exists: true,
+              path: @manager.project_path,
+              db_path: @manager.project_db_path,
+              facts_active: store.facts.where(status: "active").count,
+              facts_total: store.facts.count,
+              entities: store.entities.count
+            }
+          else
+            {exists: false, path: @manager.project_path, db_path: @manager.project_db_path}
+          end
+        end
+
+        def discover_other_projects
+          return [] unless @manager.global_exists?
+
+          @manager.ensure_global!
+          global = @manager.global_store
+
+          promoted_paths = global.facts
+            .where(Sequel.like(:created_from, "promoted:%"))
+            .select(:created_from)
+            .distinct
+            .all
+            .filter_map { |f|
+              match = f[:created_from]&.match(/\Apromoted:(.+):\d+\z/)
+              match[1] if match
+            }
+            .uniq
+
+          fact_paths = global.facts
+            .exclude(project_path: nil)
+            .select(:project_path)
+            .distinct
+            .all
+            .map { |f| f[:project_path] }
+
+          all_paths = (promoted_paths + fact_paths).uniq
+          current = @manager.project_path
+
+          all_paths.filter_map { |path|
+            next if path == current
+
+            db_path = File.join(path, ".claude", "memory.sqlite3")
+            entry = {path: path, db_path: db_path, exists: File.exist?(db_path)}
+
+            if entry[:exists]
+              begin
+                temp_store = Store::SQLiteStore.new(db_path)
+                entry[:facts_active] = temp_store.facts.where(status: "active").count
+                entry[:facts_total] = temp_store.facts.count
+                entry[:entities] = temp_store.entities.count
+                temp_store.close
+              rescue Sequel::DatabaseError, Extralite::Error, IOError => _e
+                entry[:error] = "Could not read database"
+              end
+            end
+
+            entry
+          }
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/mcp/handlers/shortcut_handlers.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module MCP
+    module Handlers
+      # Shortcut tool handlers (decisions, conventions, architecture)
+      module ShortcutHandlers
+        def decisions(args)
+          return {error: "Decisions shortcut requires StoreManager"} unless @manager
+
+          results = Recall.recent_decisions(@manager, limit: args["limit"] || 10)
+          format_shortcut_results(results, "decisions")
+        end
+
+        def conventions(args)
+          return {error: "Conventions shortcut requires StoreManager"} unless @manager
+
+          results = Recall.conventions(@manager, limit: args["limit"] || 20)
+          format_shortcut_results(results, "conventions")
+        end
+
+        def architecture(args)
+          return {error: "Architecture shortcut requires StoreManager"} unless @manager
+
+          results = Recall.architecture_choices(@manager, limit: args["limit"] || 10)
+          format_shortcut_results(results, "architecture")
+        end
+
+        private
+
+        def format_shortcut_results(results, category)
+          ResponseFormatter.format_shortcut_results(category, results)
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/mcp/handlers/stats_handlers.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module MCP
+    module Handlers
+      # Status and statistics tool handlers
+      module StatsHandlers
+        def status
+          result = {databases: {}}
+
+          if @manager
+            if @manager.global_exists?
+              @manager.ensure_global!
+              result[:databases][:global] = db_stats(@manager.global_store)
+            else
+              result[:databases][:global] = {exists: false}
+            end
+
+            if @manager.project_exists?
+              @manager.ensure_project!
+              result[:databases][:project] = db_stats(@manager.project_store)
+            else
+              result[:databases][:project] = {exists: false}
+            end
+          else
+            result[:databases][:legacy] = db_stats(@legacy_store)
+          end
+
+          result[:pending_distillation] = pending_distillation_count
+          result
+        end
+
+        def stats(args)
+          scope = args["scope"] || "all"
+          result = {scope: scope, databases: {}}
+
+          if @manager
+            if scope == "all" || scope == "global"
+              if @manager.global_exists?
+                @manager.ensure_global!
+                result[:databases][:global] = detailed_stats(@manager.global_store)
+              else
+                result[:databases][:global] = {exists: false}
+              end
+            end
+
+            if scope == "all" || scope == "project"
+              if @manager.project_exists?
+                @manager.ensure_project!
+                result[:databases][:project] = detailed_stats(@manager.project_store)
+              else
+                result[:databases][:project] = {exists: false}
+              end
+            end
+          else
+            result[:databases][:legacy] = detailed_stats(@legacy_store)
+          end
+
+          result
+        end
+
+        private
+
+        def pending_distillation_count
+          stores = if @manager
+            [@manager.global_exists? ? @manager.global_store : nil,
+              @manager.project_exists? ? @manager.project_store : nil].compact
+          elsif @legacy_store
+            [@legacy_store]
+          else
+            []
+          end
+
+          stores.sum { |store| store.count_undistilled(min_length: 200) }
+        end
+
+        def db_stats(store)
+          stats = {
+            exists: true,
+            facts_total: store.facts.count,
+            facts_active: store.facts.where(status: "active").count,
+            content_items: store.content_items.count,
+            open_conflicts: store.conflicts.where(status: "open").count,
+            schema_version: store.schema_version
+          }
+
+          vec_index = store.vector_index
+          stats[:vec_available] = vec_index.available?
+          stats[:vec_indexed] = vec_index.coverage_stats[:vec_indexed] if vec_index.available?
+
+          if fts_legacy?(store)
+            stats[:fts_legacy] = true
+            stats[:optimization_hint] = "Run 'claude-memory compact' to reduce database size by ~40%"
+          end
+
+          stats
+        end
+
+        def fts_legacy?(store)
+          row = store.db.fetch("SELECT sql FROM sqlite_master WHERE name = 'content_fts' AND type = 'table'").first
+          row && !row[:sql].to_s.include?("content=''")
+        rescue
+          false
+        end
+
+        def detailed_stats(store)
+          active_facts = store.facts.where(status: "active").count
+
+          stats = {
+            exists: true,
+            facts: fact_stats(store, active_facts),
+            entities: entity_stats(store),
+            content_items: content_stats(store),
+            provenance: provenance_stats(store, active_facts),
+            conflicts: conflict_stats(store),
+            schema_version: store.schema_version
+          }
+
+          stats[:vec] = vec_stats(store, active_facts)
+
+          stats
+        end
+
+        def fact_stats(store, active_facts)
+          stats = {
+            total: store.facts.count,
+            active: active_facts,
+            superseded: store.facts.where(status: "superseded").count
+          }
+
+          if active_facts > 0
+            stats[:top_predicates] = store.db[:facts]
+              .where(status: "active")
+              .group_and_count(:predicate)
+              .order(Sequel.desc(:count))
+              .limit(10)
+              .all
+              .map { |row| {predicate: row[:predicate], count: row[:count]} }
+          end
+
+          stats
+        end
+
+        def entity_stats(store)
+          {
+            total: store.entities.count,
+            by_type: store.db[:entities]
+              .group_and_count(:type)
+              .order(Sequel.desc(:count))
+              .all
+              .map { |row| {type: row[:type], count: row[:count]} }
+          }
+        end
+
+        def content_stats(store)
+          count = store.content_items.count
+          stats = {total: count}
+
+          if count > 0
+            stats[:date_range] = {
+              first: store.content_items.min(:occurred_at),
+              last: store.content_items.max(:occurred_at)
+            }
+          end
+
+          stats
+        end
+
+        def provenance_stats(store, active_facts)
+          return {facts_with_sources: 0, total_active_facts: 0, coverage_percentage: 0} if active_facts == 0
+
+          facts_with_provenance = store.db[:provenance]
+            .join(:facts, id: :fact_id)
+            .where(Sequel[:facts][:status] => "active")
+            .select(Sequel[:provenance][:fact_id])
+            .distinct
+            .count
+
+          {
+            facts_with_sources: facts_with_provenance,
+            total_active_facts: active_facts,
+            coverage_percentage: (facts_with_provenance * 100.0 / active_facts).round(1)
+          }
+        end
+
+        def vec_stats(store, _active_facts)
+          vec_index = store.vector_index
+          result = {available: vec_index.available?}
+          result.merge!(vec_index.coverage_stats) if vec_index.available?
+          result
+        end
+
+        def conflict_stats(store)
+          open = store.conflicts.where(status: "open").count
+          resolved = store.conflicts.where(status: "resolved").count
+
+          {open: open, resolved: resolved, total: open + resolved}
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/mcp/instructions_builder.rb

@@ -26,8 +26,9 @@ module ClaudeMemory
 
         parts << usage_hint(store_or_manager)
         parts.compact.join("\n\n")
-      rescue => _e
+      rescue => e
         # Never fail initialization — return minimal instructions
+        ClaudeMemory.logger.debug("InstructionsBuilder failed: #{e.message}")
         "ClaudeMemory v#{ClaudeMemory::VERSION} — long-term memory for Claude Code."
       end
 

data/lib/claude_memory/mcp/query_guide.rb

@@ -66,6 +66,16 @@ module ClaudeMemory
         - Use when: you need facts from a specific workflow context
         - Cost: ~300-800 tokens per call
 
+        ### Tier 5: Distillation Management
+
+        **memory.undistilled** — List content items not yet deeply distilled
+        - Use when: you want to find ingested content that hasn't been processed by LLM extraction
+        - Cost: ~200-400 tokens per call
+
+        **memory.mark_distilled** — Mark a content item as distilled after extraction
+        - Use after: performing LLM-based fact extraction on undistilled content
+        - Cost: ~100 tokens per call
+
         ## Recommended Workflow
 
         1. **Start broad**: `memory.recall` or shortcut tools (decisions/conventions/architecture)

data/lib/claude_memory/mcp/response_formatter.rb

@@ -278,6 +278,7 @@ module ClaudeMemory
           source: result[:source],
           similarity: result[:similarity]
         }
+        fact[:score_trace] = result[:score_trace] if result[:score_trace]
         fact[:receipts] = result[:receipts].map { |r| format_receipt(r, query: query) } unless compact
         fact
       end

data/lib/claude_memory/mcp/text_summary.rb

@@ -28,6 +28,8 @@ module ClaudeMemory
         when "memory.recall_semantic" then summarize_semantic(result)
         when "memory.search_concepts" then summarize_concepts(result)
         when "memory.fact_graph" then summarize_fact_graph(result)
+        when "memory.undistilled" then summarize_undistilled(result)
+        when "memory.mark_distilled" then summarize_mark_distilled(result)
         when "memory.check_setup" then summarize_check_setup(result)
         else JSON.generate(result)
         end
@@ -122,6 +124,10 @@ module ClaudeMemory
             "- #{name}: #{info[:facts_active]} active facts, #{info[:open_conflicts]} conflicts (schema v#{info[:schema_version]})"
           end
         end
+
+        pending = result[:pending_distillation] || 0
+        lines << "Pending distillation: #{pending}" if pending > 0
+
         lines.join("\n")
       end
 
@@ -233,6 +239,26 @@ module ClaudeMemory
         lines.join("\n")
       end
 
+      def self.summarize_undistilled(result)
+        items = result[:items] || []
+        return "No undistilled content items." if items.empty?
+
+        lines = ["#{result[:count]} undistilled content item(s):"]
+        items.each do |i|
+          ago = i[:occurred_ago] || "unknown"
+          lines << "- Item ##{i[:content_item_id]} (#{ago}): #{(i[:raw_text] || "")[0, 80]}..."
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_mark_distilled(result)
+        if result[:success]
+          "Marked content item ##{result[:content_item_id]} as distilled (#{result[:facts_extracted]} facts extracted)"
+        else
+          result[:error]
+        end
+      end
+
       def self.summarize_check_setup(result)
         lines = ["Setup status: #{result[:status]}"]
         lines << "Version: #{result[:version][:current]} (latest: #{result[:version][:latest]})"

data/lib/claude_memory/mcp/tool_definitions.rb

@@ -25,6 +25,7 @@ module ClaudeMemory
               type: "object",
               properties: {
                 query: {type: "string", description: "Search query for existing knowledge (e.g., 'authentication flow', 'error handling', 'database setup')"},
+                intent: {type: "string", description: "Optional intent to disambiguate the query (e.g., 'migration' or 'performance' when query is 'database'). Steers search without replacing the query."},
                 limit: {type: "integer", description: "Max results", default: 10},
                 scope: {type: "string", enum: ["all", "global", "project"], description: "Filter by scope: 'all' (default), 'global', or 'project'", default: "all"},
                 compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false}
@@ -40,6 +41,7 @@ module ClaudeMemory
               type: "object",
               properties: {
                 query: {type: "string", description: "Search query for existing knowledge (e.g., 'client errors', 'database choice')"},
+                intent: {type: "string", description: "Optional intent to disambiguate the query (e.g., 'schema' or 'optimization' when query is 'database'). Steers search without replacing the query."},
                 limit: {type: "integer", description: "Maximum results to return", default: 20},
                 scope: {type: "string", enum: ["all", "global", "project"], description: "Scope: 'all' (both), 'global' (user-wide), 'project' (current only)", default: "all"}
               },
@@ -265,10 +267,12 @@ module ClaudeMemory
               type: "object",
               properties: {
                 query: {type: "string", description: "Search query"},
+                intent: {type: "string", description: "Optional intent to disambiguate the query (e.g., 'security' when query is 'authentication'). Disables BM25 shortcut to ensure vector search runs."},
                 mode: {type: "string", enum: ["vector", "text", "both"], default: "both", description: "Search mode: vector (embeddings), text (FTS), or both (hybrid)"},
                 limit: {type: "integer", default: 10, description: "Maximum results to return"},
                 scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"},
-                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false}
+                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false},
+                explain: {type: "boolean", description: "Include per-result score traces showing FTS rank, vector similarity, and RRF contribution", default: false}
               },
               required: ["query"]
             },
@@ -309,6 +313,31 @@ module ClaudeMemory
             },
             annotations: READ_ONLY
           },
+          {
+            name: "memory.undistilled",
+            description: "List content items not yet deeply distilled. Returns raw transcript text for knowledge extraction.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                limit: {type: "integer", default: 3, description: "Max items to return"},
+                min_length: {type: "integer", default: 200, description: "Min text length (skip tiny deltas)"}
+              }
+            },
+            annotations: READ_ONLY
+          },
+          {
+            name: "memory.mark_distilled",
+            description: "Mark a content item as distilled after extracting facts from it.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                content_item_id: {type: "integer", description: "ID of the distilled content item"},
+                facts_extracted: {type: "integer", default: 0, description: "Number of facts extracted"}
+              },
+              required: ["content_item_id"]
+            },
+            annotations: WRITE_IDEMPOTENT
+          },
           {
             name: "memory.check_setup",
             description: "Check ClaudeMemory initialization status. Returns version info, issues found, and recommendations.",

data/lib/claude_memory/mcp/tool_helpers.rb

@@ -75,6 +75,49 @@ module ClaudeMemory
       def extract_limit(args, default: 10)
         args["limit"] || default
       end
+
+      # Extract optional intent parameter for query disambiguation
+      # @param args [Hash] Tool arguments
+      # @return [String, nil] Intent string or nil if not provided/blank
+      def extract_intent(args)
+        intent = args["intent"]
+        (intent.nil? || intent.to_s.strip.empty?) ? nil : intent.to_s.strip
+      end
+
+      # Collect undistilled content items from both stores (or legacy store)
+      # @param limit [Integer] Maximum items to return
+      # @param min_length [Integer] Minimum byte_len to include
+      # @return [Array<Hash>] Undistilled items sorted by recency
+      def collect_undistilled_items(limit:, min_length: 200)
+        if @manager
+          stores = []
+          stores << @manager.project_store if @manager.project_exists?
+          stores << @manager.global_store if @manager.global_exists?
+          items = stores.flat_map { |s| s.undistilled_content_items(limit: limit, min_length: min_length) }
+          items.sort_by { |i| i[:occurred_at] || "" }.reverse.first(limit)
+        elsif @legacy_store
+          @legacy_store.undistilled_content_items(limit: limit, min_length: min_length)
+        else
+          []
+        end
+      end
+
+      # Find the store containing a given content item
+      # @param content_item_id [Integer] Content item ID to locate
+      # @return [Store::SQLiteStore, nil] The store containing the item, or nil
+      def find_store_for_content_item(content_item_id)
+        if @manager
+          if @manager.project_store&.content_items&.where(id: content_item_id)&.any?
+            @manager.project_store
+          elsif @manager.global_store&.content_items&.where(id: content_item_id)&.any?
+            @manager.global_store
+          end
+        elsif @legacy_store
+          if @legacy_store.content_items.where(id: content_item_id).any?
+            @legacy_store
+          end
+        end
+      end
     end
   end
 end