claude_memory 0.2.0 → 0.3.0

data/lib/claude_memory/mcp/tools.rb

@@ -2,10 +2,16 @@
 
 require "json"
 require "digest"
+require_relative "tool_helpers"
+require_relative "response_formatter"
+require_relative "tool_definitions"
+require_relative "setup_status_analyzer"
 
 module ClaudeMemory
   module MCP
     class Tools
+      include ToolHelpers
+
       def initialize(store_or_manager)
         @recall = Recall.new(store_or_manager)
 
@@ -17,194 +23,7 @@ module ClaudeMemory
       end
 
       def definitions
-        [
-          {
-            name: "memory.recall",
-            description: "Recall facts matching a query. Searches both global and project databases.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                query: {type: "string", description: "Search 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"}
-              },
-              required: ["query"]
-            }
-          },
-          {
-            name: "memory.recall_index",
-            description: "Layer 1: Search for facts and get lightweight index (IDs, previews, token counts). Use this first before fetching full details.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                query: {type: "string", description: "Search query for fact discovery"},
-                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"}
-              },
-              required: ["query"]
-            }
-          },
-          {
-            name: "memory.recall_details",
-            description: "Layer 2: Fetch full details for specific fact IDs from the index. Use after memory.recall_index to get complete information.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                fact_ids: {type: "array", items: {type: "integer"}, description: "Fact IDs from memory.recall_index"},
-                scope: {type: "string", enum: ["project", "global"], description: "Database to query", default: "project"}
-              },
-              required: ["fact_ids"]
-            }
-          },
-          {
-            name: "memory.explain",
-            description: "Get detailed explanation of a fact with provenance",
-            inputSchema: {
-              type: "object",
-              properties: {
-                fact_id: {type: "integer", description: "Fact ID to explain"},
-                scope: {type: "string", enum: ["global", "project"], description: "Which database to look in", default: "project"}
-              },
-              required: ["fact_id"]
-            }
-          },
-          {
-            name: "memory.changes",
-            description: "List recent fact changes from both databases",
-            inputSchema: {
-              type: "object",
-              properties: {
-                since: {type: "string", description: "ISO timestamp"},
-                limit: {type: "integer", default: 20},
-                scope: {type: "string", enum: ["all", "global", "project"], default: "all"}
-              }
-            }
-          },
-          {
-            name: "memory.conflicts",
-            description: "List open conflicts from both databases",
-            inputSchema: {
-              type: "object",
-              properties: {
-                scope: {type: "string", enum: ["all", "global", "project"], default: "all"}
-              }
-            }
-          },
-          {
-            name: "memory.sweep_now",
-            description: "Run maintenance sweep on a database",
-            inputSchema: {
-              type: "object",
-              properties: {
-                budget_seconds: {type: "integer", default: 5},
-                scope: {type: "string", enum: ["global", "project"], default: "project"}
-              }
-            }
-          },
-          {
-            name: "memory.status",
-            description: "Get memory system status for both databases",
-            inputSchema: {
-              type: "object",
-              properties: {}
-            }
-          },
-          {
-            name: "memory.promote",
-            description: "Promote a project fact to global memory. Use when user says a preference should apply everywhere.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                fact_id: {type: "integer", description: "Project fact ID to promote to global"}
-              },
-              required: ["fact_id"]
-            }
-          },
-          {
-            name: "memory.store_extraction",
-            description: "Store extracted facts, entities, and decisions from a conversation. Call this to persist knowledge you've learned during the session.",
-            inputSchema: {
-              type: "object",
-              properties: {
-                entities: {
-                  type: "array",
-                  description: "Entities mentioned (databases, frameworks, services, etc.)",
-                  items: {
-                    type: "object",
-                    properties: {
-                      type: {type: "string", description: "Entity type: database, framework, language, platform, repo, module, person, service"},
-                      name: {type: "string", description: "Canonical name"},
-                      confidence: {type: "number", description: "0.0-1.0 extraction confidence"}
-                    },
-                    required: ["type", "name"]
-                  }
-                },
-                facts: {
-                  type: "array",
-                  description: "Facts learned during the session",
-                  items: {
-                    type: "object",
-                    properties: {
-                      subject: {type: "string", description: "Entity name or 'repo' for project-level facts"},
-                      predicate: {type: "string", description: "Relationship type: uses_database, uses_framework, convention, decision, auth_method, deployment_platform"},
-                      object: {type: "string", description: "The value or target entity"},
-                      confidence: {type: "number", description: "0.0-1.0 how confident"},
-                      quote: {type: "string", description: "Source text excerpt (max 200 chars)"},
-                      strength: {type: "string", enum: ["stated", "inferred"], description: "Was this explicitly stated or inferred?"},
-                      scope_hint: {type: "string", enum: ["project", "global"], description: "Should this apply to just this project or globally?"}
-                    },
-                    required: ["subject", "predicate", "object"]
-                  }
-                },
-                decisions: {
-                  type: "array",
-                  description: "Decisions made during the session",
-                  items: {
-                    type: "object",
-                    properties: {
-                      title: {type: "string", description: "Short summary (max 100 chars)"},
-                      summary: {type: "string", description: "Full description"},
-                      status_hint: {type: "string", enum: ["accepted", "proposed", "rejected"]}
-                    },
-                    required: ["title", "summary"]
-                  }
-                },
-                scope: {type: "string", enum: ["global", "project"], description: "Default scope for facts", default: "project"}
-              },
-              required: ["facts"]
-            }
-          },
-          {
-            name: "memory.decisions",
-            description: "Quick access to architectural decisions, constraints, and rules",
-            inputSchema: {
-              type: "object",
-              properties: {
-                limit: {type: "integer", default: 10, description: "Maximum results to return"}
-              }
-            }
-          },
-          {
-            name: "memory.conventions",
-            description: "Quick access to coding conventions and style preferences (global scope)",
-            inputSchema: {
-              type: "object",
-              properties: {
-                limit: {type: "integer", default: 20, description: "Maximum results to return"}
-              }
-            }
-          },
-          {
-            name: "memory.architecture",
-            description: "Quick access to framework choices and architectural patterns",
-            inputSchema: {
-              type: "object",
-              properties: {
-                limit: {type: "integer", default: 10, description: "Maximum results to return"}
-              }
-            }
-          }
-        ]
+        ToolDefinitions.all
       end
 
       def call(name, arguments)
@@ -225,6 +44,8 @@ module ClaudeMemory
           sweep_now(arguments)
         when "memory.status"
           status
+        when "memory.stats"
+          stats(arguments)
         when "memory.promote"
           promote(arguments)
         when "memory.store_extraction"
@@ -235,6 +56,16 @@ module ClaudeMemory
           conventions(arguments)
         when "memory.architecture"
           architecture(arguments)
+        when "memory.facts_by_tool"
+          facts_by_tool(arguments)
+        when "memory.facts_by_context"
+          facts_by_context(arguments)
+        when "memory.recall_semantic"
+          recall_semantic(arguments)
+        when "memory.search_concepts"
+          search_concepts(arguments)
+        when "memory.check_setup"
+          check_setup
         else
           {error: "Unknown tool: #{name}"}
         end
@@ -243,48 +74,22 @@ module ClaudeMemory
       private
 
       def recall(args)
-        scope = args["scope"] || "all"
-        results = @recall.query(args["query"], limit: args["limit"] || 10, scope: scope)
-        {
-          facts: results.map do |r|
-            {
-              id: r[:fact][:id],
-              subject: r[:fact][:subject_name],
-              predicate: r[:fact][:predicate],
-              object: r[:fact][:object_literal],
-              status: r[:fact][:status],
-              source: r[:source],
-              receipts: r[:receipts].map { |p| {quote: p[:quote], strength: p[:strength]} }
-            }
-          end
-        }
+        # Check if databases exist before querying
+        return database_not_found_error(StandardError.new("Database not initialized")) unless databases_exist?
+
+        scope = extract_scope(args)
+        limit = extract_limit(args)
+        results = @recall.query(args["query"], limit: limit, scope: scope)
+        ResponseFormatter.format_recall_results(results)
+      rescue Sequel::DatabaseError, Sequel::DatabaseConnectionError, SQLite3::CantOpenException, Errno::ENOENT => e
+        database_not_found_error(e)
       end
 
       def recall_index(args)
-        scope = args["scope"] || "all"
-        results = @recall.query_index(args["query"], limit: args["limit"] || 20, scope: scope)
-
-        total_tokens = results.sum { |r| r[:token_estimate] }
-
-        {
-          query: args["query"],
-          scope: scope,
-          result_count: results.size,
-          total_estimated_tokens: total_tokens,
-          facts: results.map do |r|
-            {
-              id: r[:id],
-              subject: r[:subject],
-              predicate: r[:predicate],
-              object_preview: r[:object_preview],
-              status: r[:status],
-              scope: r[:scope],
-              confidence: r[:confidence],
-              tokens: r[:token_estimate],
-              source: r[:source]
-            }
-          end
-        }
+        scope = extract_scope(args)
+        limit = extract_limit(args, default: 20)
+        results = @recall.query_index(args["query"], limit: limit, scope: scope)
+        ResponseFormatter.format_index_results(args["query"], scope, results)
       end
 
       def recall_details(args)
@@ -296,32 +101,7 @@ module ClaudeMemory
           explanation = @recall.explain(fact_id, scope: scope)
           next nil if explanation.is_a?(Core::NullExplanation)
 
-          {
-            fact: {
-              id: explanation[:fact][:id],
-              subject: explanation[:fact][:subject_name],
-              predicate: explanation[:fact][:predicate],
-              object: explanation[:fact][:object_literal],
-              status: explanation[:fact][:status],
-              confidence: explanation[:fact][:confidence],
-              scope: explanation[:fact][:scope],
-              valid_from: explanation[:fact][:valid_from],
-              valid_to: explanation[:fact][:valid_to]
-            },
-            receipts: explanation[:receipts].map { |r|
-              {
-                quote: r[:quote],
-                strength: r[:strength],
-                session_id: r[:session_id],
-                occurred_at: r[:occurred_at]
-              }
-            },
-            relationships: {
-              supersedes: explanation[:supersedes],
-              superseded_by: explanation[:superseded_by],
-              conflicts: explanation[:conflicts].map { |c| {id: c[:id], status: c[:status]} }
-            }
-          }
+          ResponseFormatter.format_detailed_explanation(explanation)
         end.compact
 
         {
@@ -335,58 +115,20 @@ module ClaudeMemory
         explanation = @recall.explain(args["fact_id"], scope: scope)
         return {error: "Fact not found in #{scope} database"} if explanation.is_a?(Core::NullExplanation)
 
-        {
-          fact: {
-            id: explanation[:fact][:id],
-            subject: explanation[:fact][:subject_name],
-            predicate: explanation[:fact][:predicate],
-            object: explanation[:fact][:object_literal],
-            status: explanation[:fact][:status],
-            valid_from: explanation[:fact][:valid_from],
-            valid_to: explanation[:fact][:valid_to]
-          },
-          source: scope,
-          receipts: explanation[:receipts].map { |p| {quote: p[:quote], strength: p[:strength]} },
-          supersedes: explanation[:supersedes],
-          superseded_by: explanation[:superseded_by],
-          conflicts: explanation[:conflicts].map { |c| c[:id] }
-        }
+        ResponseFormatter.format_explanation(explanation, scope)
       end
 
       def changes(args)
         since = args["since"] || (Time.now - 86400 * 7).utc.iso8601
         scope = args["scope"] || "all"
         list = @recall.changes(since: since, limit: args["limit"] || 20, scope: scope)
-        {
-          since: since,
-          changes: list.map do |c|
-            {
-              id: c[:id],
-              predicate: c[:predicate],
-              object: c[:object_literal],
-              status: c[:status],
-              created_at: c[:created_at],
-              source: c[:source]
-            }
-          end
-        }
+        ResponseFormatter.format_changes(since, list)
       end
 
       def conflicts(args)
         scope = args["scope"] || "all"
         list = @recall.conflicts(scope: scope)
-        {
-          count: list.size,
-          conflicts: list.map do |c|
-            {
-              id: c[:id],
-              fact_a: c[:fact_a_id],
-              fact_b: c[:fact_b_id],
-              status: c[:status],
-              source: c[:source]
-            }
-          end
-        }
+        ResponseFormatter.format_conflicts(list)
       end
 
       def sweep_now(args)
@@ -396,14 +138,7 @@ module ClaudeMemory
 
         sweeper = Sweep::Sweeper.new(store)
         stats = sweeper.run!(budget_seconds: args["budget_seconds"] || 5)
-        {
-          scope: scope,
-          proposed_expired: stats[:proposed_facts_expired],
-          disputed_expired: stats[:disputed_facts_expired],
-          orphaned_deleted: stats[:orphaned_provenance_deleted],
-          content_pruned: stats[:old_content_pruned],
-          elapsed_seconds: stats[:elapsed_seconds].round(3)
-        }
+        ResponseFormatter.format_sweep_stats(scope, stats)
       end
 
       def status
@@ -430,6 +165,35 @@ module ClaudeMemory
         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
+
       def promote(args)
         return {error: "Promote requires StoreManager"} unless @manager
 
@@ -457,7 +221,8 @@ module ClaudeMemory
         facts = (args["facts"] || []).map { |f| symbolize_keys(f) }
         decisions = (args["decisions"] || []).map { |d| symbolize_keys(d) }
 
-        project_path = ENV["CLAUDE_PROJECT_DIR"] || Dir.pwd
+        config = Configuration.new
+        project_path = config.project_dir
         occurred_at = Time.now.utc.iso8601
 
         searchable_text = build_searchable_text(entities, facts, decisions)
@@ -491,11 +256,7 @@ module ClaudeMemory
       end
 
       def build_searchable_text(entities, facts, decisions)
-        parts = []
-        entities.each { |e| parts << "#{e[:type]}: #{e[:name]}" }
-        facts.each { |f| parts << "#{f[:subject]} #{f[:predicate]} #{f[:object]} #{f[:quote]}" }
-        decisions.each { |d| parts << "#{d[:title]} #{d[:summary]}" }
-        parts.join(" ").strip
+        Core::TextBuilder.build_searchable_text(entities, facts, decisions)
       end
 
       def create_synthetic_content_item(store, text, project_path, occurred_at)
@@ -518,7 +279,7 @@ module ClaudeMemory
       end
 
       def symbolize_keys(hash)
-        hash.transform_keys(&:to_sym)
+        Core::TextBuilder.symbolize_keys(hash)
       end
 
       def get_store_for_scope(scope)
@@ -551,19 +312,174 @@ module ClaudeMemory
       end
 
       def format_shortcut_results(results, category)
+        ResponseFormatter.format_shortcut_results(category, results)
+      end
+
+      def facts_by_tool(args)
+        tool_name = args["tool_name"]
+        scope = extract_scope(args)
+        limit = extract_limit(args, default: 20)
+
+        results = @recall.facts_by_tool(tool_name, limit: limit, scope: scope)
+        ResponseFormatter.format_tool_facts(tool_name, scope, results)
+      end
+
+      def facts_by_context(args)
+        scope = extract_scope(args)
+        limit = extract_limit(args, default: 20)
+
+        if args["git_branch"]
+          results = @recall.facts_by_branch(args["git_branch"], limit: limit, scope: scope)
+          context_type = "git_branch"
+          context_value = args["git_branch"]
+        elsif args["cwd"]
+          results = @recall.facts_by_directory(args["cwd"], limit: limit, scope: scope)
+          context_type = "cwd"
+          context_value = args["cwd"]
+        else
+          return {error: "Must provide either git_branch or cwd parameter"}
+        end
+
+        ResponseFormatter.format_context_facts(context_type, context_value, scope, results)
+      end
+
+      def recall_semantic(args)
+        query = args["query"]
+        mode = (args["mode"] || "both").to_sym
+        scope = extract_scope(args)
+        limit = extract_limit(args)
+
+        results = @recall.query_semantic(query, limit: limit, scope: scope, mode: mode)
+        ResponseFormatter.format_semantic_results(query, mode.to_s, scope, results)
+      end
+
+      def search_concepts(args)
+        concepts = args["concepts"]
+        scope = extract_scope(args)
+        limit = extract_limit(args)
+
+        return {error: "Must provide 2-5 concepts"} unless (2..5).cover?(concepts.size)
+
+        results = @recall.query_concepts(concepts, limit: limit, scope: scope)
+        ResponseFormatter.format_concept_results(concepts, scope, results)
+      end
+
+      def databases_exist?
+        if @manager
+          # For dual-database mode, at least global database should exist
+          config = Configuration.new
+          File.exist?(config.global_db_path)
+        elsif @legacy_store
+          # For legacy mode, check if the database file exists
+          # Extract the database path from the store's connection
+          db_path = @legacy_store.db.opts[:database]
+          db_path && File.exist?(db_path)
+        else
+          false
+        end
+      end
+
+      def database_not_found_error(error)
         {
-          category: category,
-          count: results.size,
-          facts: results.map do |r|
-            {
-              id: r[:fact][:id],
-              subject: r[:fact][:subject_name],
-              predicate: r[:fact][:predicate],
-              object: r[:fact][:object_literal],
-              scope: r[:fact][:scope],
-              source: r[:source]
-            }
+          error: "Database not found or not accessible",
+          message: "ClaudeMemory may not be initialized. Run memory.check_setup for detailed status.",
+          details: error.message,
+          recommendations: [
+            "Run memory.check_setup to diagnose the issue",
+            "If not initialized, run: claude-memory init",
+            "For help: claude-memory doctor"
+          ]
+        }
+      end
+
+      def check_setup
+        issues = []
+        warnings = []
+        config = Configuration.new
+
+        # Check global database
+        global_db_exists = File.exist?(config.global_db_path)
+        unless global_db_exists
+          issues << "Global database not found at #{config.global_db_path}"
+        end
+
+        # Check project database
+        project_db_exists = File.exist?(config.project_db_path)
+        unless project_db_exists
+          warnings << "Project database not found at #{config.project_db_path}"
+        end
+
+        # Check for CLAUDE.md and version
+        claude_md_path = ".claude/CLAUDE.md"
+        claude_md_exists = File.exist?(claude_md_path)
+        current_version = nil
+        version_status = nil
+
+        if claude_md_exists
+          content = File.read(claude_md_path)
+          if content.include?("ClaudeMemory")
+            current_version = SetupStatusAnalyzer.extract_version(content)
+            if current_version
+              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
+            else
+              version_status = "no_version_marker"
+              warnings << "CLAUDE.md has ClaudeMemory section but no version marker"
+            end
+          else
+            warnings << "CLAUDE.md exists but no ClaudeMemory configuration found"
+          end
+        else
+          warnings << "No .claude/CLAUDE.md found"
+        end
+
+        # Check hooks configuration
+        hooks_configured = false
+        settings_paths = [".claude/settings.json", ".claude/settings.local.json"]
+        settings_paths.each do |path|
+          if File.exist?(path)
+            begin
+              config_data = JSON.parse(File.read(path))
+              if config_data["hooks"]&.any?
+                hooks_configured = true
+                break
+              end
+            rescue JSON::ParserError
+              warnings << "Invalid JSON in #{path}"
+            end
           end
+        end
+
+        unless hooks_configured
+          warnings << "No hooks configured for automatic ingestion"
+        end
+
+        # Determine overall status using analyzer
+        initialized = global_db_exists && claude_md_exists
+        status = SetupStatusAnalyzer.determine_status(global_db_exists, claude_md_exists, version_status)
+
+        # Generate recommendations using analyzer
+        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
 
@@ -577,6 +493,100 @@ module ClaudeMemory
           schema_version: store.schema_version
         }
       end
+
+      def detailed_stats(store)
+        result = {exists: true}
+
+        # Facts statistics
+        total_facts = store.facts.count
+        active_facts = store.facts.where(status: "active").count
+        superseded_facts = store.facts.where(status: "superseded").count
+
+        result[:facts] = {
+          total: total_facts,
+          active: active_facts,
+          superseded: superseded_facts
+        }
+
+        # Top predicates
+        if active_facts > 0
+          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]} }
+
+          result[:facts][:top_predicates] = top_predicates
+        end
+
+        # Entities by type
+        entity_counts = store.db[:entities]
+          .group_and_count(:type)
+          .order(Sequel.desc(:count))
+          .all
+          .map { |row| {type: row[:type], count: row[:count]} }
+
+        result[:entities] = {
+          total: store.entities.count,
+          by_type: entity_counts
+        }
+
+        # Content items
+        content_count = store.content_items.count
+        result[:content_items] = {
+          total: content_count
+        }
+
+        if content_count > 0
+          first_date = store.content_items.min(:occurred_at)
+          last_date = store.content_items.max(:occurred_at)
+          result[:content_items][:date_range] = {
+            first: first_date,
+            last: last_date
+          }
+        end
+
+        # Provenance coverage
+        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
+
+          coverage_percentage = (facts_with_provenance * 100.0 / active_facts).round(1)
+
+          result[:provenance] = {
+            facts_with_sources: facts_with_provenance,
+            total_active_facts: active_facts,
+            coverage_percentage: coverage_percentage
+          }
+        else
+          result[:provenance] = {
+            facts_with_sources: 0,
+            total_active_facts: 0,
+            coverage_percentage: 0
+          }
+        end
+
+        # Conflicts
+        open_conflicts = store.conflicts.where(status: "open").count
+        resolved_conflicts = store.conflicts.where(status: "resolved").count
+
+        result[:conflicts] = {
+          open: open_conflicts,
+          resolved: resolved_conflicts,
+          total: open_conflicts + resolved_conflicts
+        }
+
+        # Schema version
+        result[:schema_version] = store.schema_version
+
+        result
+      end
     end
   end
 end