claude_memory 0.7.1 → 0.9.0

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

@@ -0,0 +1,205 @@
+# 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
+            all_predicates = store.db[:facts]
+              .where(status: "active")
+              .group_and_count(:predicate)
+              .order(Sequel.desc(:count))
+              .all
+              .map { |row| {predicate: row[:predicate], count: row[:count]} }
+
+            stats[:top_predicates] = all_predicates.first(10)
+            stats[:predicates_known], stats[:predicates_novel] =
+              all_predicates.partition { |row| Resolve::PredicatePolicy.known_predicates.include?(row[:predicate]) }
+          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
 
@@ -107,9 +108,26 @@ module ClaudeMemory
 
         escalation = vec ? "recall_semantic, explain, or fact_graph" : "explain or fact_graph"
         lines << "Start with fast tools (recall, decisions, conventions) before escalating to #{escalation}."
+
+        lines << proactive_recall_guidance
         lines.join("\n")
       end
 
+      # Directive guidance for when Claude should proactively consult memory.
+      # Validated by A/B testing: without these directives, Claude writes code
+      # using known-dangerous patterns (e.g. Sequel.sqlite) and hallucinates
+      # file paths instead of consulting memory for the correct structure.
+      def proactive_recall_guidance
+        <<~GUIDANCE.strip
+          IMPORTANT — check memory proactively in these situations:
+          - Before writing code: call memory.conventions to verify project patterns and avoid known gotchas
+          - Before explaining architecture: call memory.architecture for structural knowledge without file traversal
+          - Before refactoring: call memory.decisions to understand why past choices were made
+          - When asked about preferences: global facts store user environment and style preferences across all projects
+          - When adding to the codebase: recall which files and patterns to follow (memory knows correct paths and relationships)
+        GUIDANCE
+      end
+
       def count_by_predicates(store, predicates)
         store.facts
           .where(status: "active")

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/server.rb

@@ -5,20 +5,30 @@ require_relative "instructions_builder"
 require_relative "query_guide"
 require_relative "text_summary"
 require_relative "error_classifier"
+require_relative "telemetry"
 
 module ClaudeMemory
   module MCP
+    # MCP JSON-RPC server over stdio.
+    # Reads newline-delimited JSON requests from input, dispatches to Tools,
+    # and writes JSON responses to output.
     class Server
       PROTOCOL_VERSION = "2024-11-05"
 
+      # @param store_or_manager [Store::SQLiteStore, Store::StoreManager] database backend
+      # @param input [IO] input stream for JSON-RPC requests (default: $stdin)
+      # @param output [IO] output stream for JSON-RPC responses (default: $stdout)
       def initialize(store_or_manager, input: $stdin, output: $stdout)
         @store_or_manager = store_or_manager
         @tools = Tools.new(store_or_manager)
+        @telemetry = Telemetry.new(store_or_manager)
         @input = input
         @output = output
         @running = false
       end
 
+      # Start the read loop, blocking until input is exhausted or stop is called.
+      # @return [void]
       def run
         @running = true
         while @running
@@ -29,12 +39,15 @@ module ClaudeMemory
         end
       end
 
+      # Signal the read loop to exit after the current message.
+      # @return [void]
       def stop
         @running = false
       end
 
       private
 
+      # @return [void]
       def handle_message(line)
         return if line.empty?
 
@@ -51,6 +64,7 @@ module ClaudeMemory
         end
       end
 
+      # @return [Hash, nil] JSON-RPC response hash, or nil for notifications
       def process_request(request)
         id = request["id"]
         method = request["method"]
@@ -74,6 +88,7 @@ module ClaudeMemory
         end
       end
 
+      # @return [Hash] initialize response with capabilities and server info
       def handle_initialize(id, _params)
         {
           jsonrpc: "2.0",
@@ -93,6 +108,7 @@ module ClaudeMemory
         }
       end
 
+      # @return [Hash] list of available tool definitions
       def handle_tools_list(id)
         {
           jsonrpc: "2.0",
@@ -103,11 +119,14 @@ module ClaudeMemory
         }
       end
 
+      # @return [Hash] tool result with dual content/structuredContent
       def handle_tools_call(id, params)
         name = params["name"]
         arguments = params["arguments"] || {}
 
-        result = @tools.call(name, arguments)
+        result = @telemetry.record(name, arguments) do
+          @tools.call(name, arguments)
+        end
 
         # Release database connections after each tool call
         # This prevents lock contention with hook commands
@@ -128,6 +147,7 @@ module ClaudeMemory
         }
       end
 
+      # @return [Hash] list of available prompt definitions
       def handle_prompts_list(id)
         {
           jsonrpc: "2.0",
@@ -138,6 +158,7 @@ module ClaudeMemory
         }
       end
 
+      # @return [Hash] prompt content or error if unknown
       def handle_prompts_get(id, params)
         name = params&.dig("name")
 

data/lib/claude_memory/mcp/telemetry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module MCP
+    # Records MCP tool invocations into the project database for usage stats.
+    # Timing and error capture wrap the tool call; the insert is synchronous
+    # and best-effort — telemetry failures are swallowed so they never break
+    # a real tool response.
+    class Telemetry
+      def initialize(store_or_manager)
+        @store_or_manager = store_or_manager
+      end
+
+      # Time a tool invocation and record the outcome. Yields to the caller
+      # and returns whatever the block returns; re-raises any exception after
+      # recording it as an error.
+      def record(tool_name, arguments)
+        started = monotonic_ms
+        begin
+          result = yield
+        rescue => e
+          duration = monotonic_ms - started
+          write(
+            tool_name: tool_name,
+            duration_ms: duration,
+            result_count: nil,
+            scope: extract_scope(arguments),
+            error_class: e.class.name
+          )
+          raise
+        end
+
+        duration = monotonic_ms - started
+        write(
+          tool_name: tool_name,
+          duration_ms: duration,
+          result_count: extract_result_count(result),
+          scope: extract_scope(arguments),
+          error_class: nil
+        )
+        result
+      end
+
+      private
+
+      def monotonic_ms
+        (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i
+      end
+
+      def write(**row)
+        store = writable_store
+        return unless store
+        store.insert_mcp_tool_call(**row)
+      rescue Sequel::DatabaseError, Extralite::Error
+        # Telemetry is best-effort; never fail the user's tool call
+        # because stats couldn't be written.
+      end
+
+      def writable_store
+        if @store_or_manager.is_a?(Store::StoreManager)
+          @store_or_manager.ensure_project!
+        elsif @store_or_manager.respond_to?(:insert_mcp_tool_call)
+          @store_or_manager
+        end
+      end
+
+      def extract_scope(arguments)
+        return nil unless arguments.is_a?(Hash)
+        arguments["scope"] || arguments[:scope]
+      end
+
+      # Inspect a tool result for a countable field. Most query tools
+      # return hashes with :facts, :results, :conflicts, or :changes;
+      # fall back to nil for shapes we don't recognize.
+      def extract_result_count(result)
+        return nil unless result.is_a?(Hash)
+
+        %i[facts results conflicts changes entities items].each do |key|
+          value = result[key] || result[key.to_s]
+          return value.size if value.is_a?(Array)
+        end
+        nil
+      end
+    end
+  end
+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]})"