claude_memory 0.4.0 → 0.5.0

data/lib/claude_memory/mcp/response_formatter.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "../core/relative_time"
+require_relative "../core/snippet_extractor"
+
 module ClaudeMemory
   module MCP
     # Pure logic for formatting domain objects into MCP tool responses
@@ -7,26 +10,32 @@ module ClaudeMemory
     class ResponseFormatter
       # Format recall query results into MCP response
       # @param results [Array<Hash>] Recall results with :fact and :receipts
+      # @param compact [Boolean] Omit receipts for smaller responses
+      # @param query [String, nil] Original query for snippet extraction
       # @return [Hash] MCP response with facts array
-      def self.format_recall_results(results)
+      def self.format_recall_results(results, compact: false, query: nil)
         {
-          facts: results.map { |r| format_recall_fact(r) }
+          facts: results.map { |r| format_recall_fact(r, compact: compact, query: query) }
         }
       end
 
       # Format single recall fact result
       # @param result [Hash] Single result with :fact, :receipts, :source
+      # @param compact [Boolean] Omit receipts
+      # @param query [String, nil] Original query for snippet extraction
       # @return [Hash] Formatted fact for MCP response
-      def self.format_recall_fact(result)
-        {
+      def self.format_recall_fact(result, compact: false, query: nil)
+        fact = {
           id: result[:fact][:id],
+          docid: result[:fact][:docid],
           subject: result[:fact][:subject_name],
           predicate: result[:fact][:predicate],
           object: result[:fact][:object_literal],
           status: result[:fact][:status],
-          source: result[:source],
-          receipts: result[:receipts].map { |p| format_receipt(p) }
+          source: result[:source]
         }
+        fact[:receipts] = result[:receipts].map { |p| format_receipt(p, query: query) } unless compact
+        fact
       end
 
       # Format index query results with token estimates
@@ -52,6 +61,7 @@ module ClaudeMemory
       def self.format_index_fact(result)
         {
           id: result[:id],
+          docid: result[:docid],
           subject: result[:subject],
           predicate: result[:predicate],
           object_preview: result[:object_preview],
@@ -71,11 +81,13 @@ module ClaudeMemory
         {
           fact: {
             id: explanation[:fact][:id],
+            docid: explanation[:fact][:docid],
             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_from_ago: Core::RelativeTime.format(explanation[:fact][:valid_from]),
             valid_to: explanation[:fact][:valid_to]
           },
           source: scope,
@@ -93,6 +105,7 @@ module ClaudeMemory
         {
           fact: {
             id: explanation[:fact][:id],
+            docid: explanation[:fact][:docid],
             subject: explanation[:fact][:subject_name],
             predicate: explanation[:fact][:predicate],
             object: explanation[:fact][:object_literal],
@@ -100,6 +113,7 @@ module ClaudeMemory
             confidence: explanation[:fact][:confidence],
             scope: explanation[:fact][:scope],
             valid_from: explanation[:fact][:valid_from],
+            valid_from_ago: Core::RelativeTime.format(explanation[:fact][:valid_from]),
             valid_to: explanation[:fact][:valid_to]
           },
           receipts: explanation[:receipts].map { |r| format_detailed_receipt(r) },
@@ -113,21 +127,55 @@ module ClaudeMemory
 
       # Format receipt (provenance) with minimal fields
       # @param receipt [Hash] Receipt with :quote and :strength
+      # @param query [String, nil] Optional query for snippet extraction
       # @return [Hash] Formatted receipt
-      def self.format_receipt(receipt)
-        {quote: receipt[:quote], strength: receipt[:strength]}
+      def self.format_receipt(receipt, query: nil)
+        result = {quote: receipt[:quote], strength: receipt[:strength]}
+        append_line_range(result, receipt)
+        append_snippet(result, receipt, query)
+        result
       end
 
       # Format detailed receipt with session and timestamp
       # @param receipt [Hash] Receipt with full fields
+      # @param query [String, nil] Optional query for snippet extraction
       # @return [Hash] Formatted detailed receipt
-      def self.format_detailed_receipt(receipt)
-        {
+      def self.format_detailed_receipt(receipt, query: nil)
+        result = {
           quote: receipt[:quote],
           strength: receipt[:strength],
           session_id: receipt[:session_id],
-          occurred_at: receipt[:occurred_at]
+          occurred_at: receipt[:occurred_at],
+          occurred_ago: Core::RelativeTime.format(receipt[:occurred_at])
         }
+        append_line_range(result, receipt)
+        append_snippet(result, receipt, query)
+        result
+      end
+
+      # Append stored line range from provenance if available
+      # @param result [Hash] Result hash to append to
+      # @param receipt [Hash] Receipt with optional :line_start, :line_end
+      def self.append_line_range(result, receipt)
+        return unless receipt[:line_start]
+
+        result[:line_start] = receipt[:line_start]
+        result[:line_end] = receipt[:line_end]
+      end
+
+      # Extract and append snippet from raw_text if available
+      # @param result [Hash] Result hash to append to
+      # @param receipt [Hash] Receipt with optional :raw_text
+      # @param query [String, nil] Query for snippet extraction
+      def self.append_snippet(result, receipt, query)
+        return unless query && receipt[:raw_text]
+
+        extracted = Core::SnippetExtractor.extract_with_lines(receipt[:raw_text], query)
+        return unless extracted
+
+        result[:snippet] = extracted[:snippet]
+        result[:line_start] = extracted[:line_start]
+        result[:line_end] = extracted[:line_end]
       end
 
       # Format changes list into MCP response
@@ -147,10 +195,12 @@ module ClaudeMemory
       def self.format_change(change)
         {
           id: change[:id],
+          docid: change[:docid],
           predicate: change[:predicate],
           object: change[:object_literal],
           status: change[:status],
           created_at: change[:created_at],
+          created_ago: Core::RelativeTime.format(change[:created_at]),
           source: change[:source]
         }
       end
@@ -198,62 +248,73 @@ module ClaudeMemory
       # @param mode [String] Search mode (vector, text, both)
       # @param scope [String] Scope
       # @param results [Array<Hash>] Results with similarity scores
+      # @param compact [Boolean] Omit receipts for smaller responses
       # @return [Hash] Formatted semantic search response
-      def self.format_semantic_results(query, mode, scope, results)
+      def self.format_semantic_results(query, mode, scope, results, compact: false)
         {
           query: query,
           mode: mode,
           scope: scope,
           count: results.size,
-          facts: results.map { |r| format_semantic_fact(r) }
+          facts: results.map { |r| format_semantic_fact(r, compact: compact, query: query) }
         }
       end
 
       # Format single semantic search fact with similarity
       # @param result [Hash] Result with fact, receipts, and similarity
+      # @param compact [Boolean] Omit receipts
+      # @param query [String, nil] Original query for snippet extraction
       # @return [Hash] Formatted fact with similarity
-      def self.format_semantic_fact(result)
-        {
+      def self.format_semantic_fact(result, compact: false, query: nil)
+        fact = {
           id: result[:fact][:id],
+          docid: result[:fact][:docid],
           subject: result[:fact][:subject_name],
           predicate: result[:fact][:predicate],
           object: result[:fact][:object_literal],
           scope: result[:fact][:scope],
           source: result[:source],
-          similarity: result[:similarity],
-          receipts: result[:receipts].map { |r| format_receipt(r) }
+          similarity: result[:similarity]
         }
+        fact[:receipts] = result[:receipts].map { |r| format_receipt(r, query: query) } unless compact
+        fact
       end
 
       # Format concept search results
       # @param concepts [Array<String>] Concepts searched
       # @param scope [String] Scope
       # @param results [Array<Hash>] Results with similarity scores
+      # @param compact [Boolean] Omit receipts for smaller responses
       # @return [Hash] Formatted concept search response
-      def self.format_concept_results(concepts, scope, results)
+      def self.format_concept_results(concepts, scope, results, compact: false)
+        query = concepts.join(" ")
         {
           concepts: concepts,
           scope: scope,
           count: results.size,
-          facts: results.map { |r| format_concept_fact(r) }
+          facts: results.map { |r| format_concept_fact(r, compact: compact, query: query) }
         }
       end
 
       # Format single concept search fact with multi-concept similarity
       # @param result [Hash] Result with average and per-concept similarities
+      # @param compact [Boolean] Omit receipts
+      # @param query [String, nil] Original query for snippet extraction
       # @return [Hash] Formatted fact with concept similarities
-      def self.format_concept_fact(result)
-        {
+      def self.format_concept_fact(result, compact: false, query: nil)
+        fact = {
           id: result[:fact][:id],
+          docid: result[:fact][:docid],
           subject: result[:fact][:subject_name],
           predicate: result[:fact][:predicate],
           object: result[:fact][:object_literal],
           scope: result[:fact][:scope],
           source: result[:source],
           average_similarity: result[:similarity],
-          concept_similarities: result[:concept_similarities],
-          receipts: result[:receipts].map { |r| format_receipt(r) }
+          concept_similarities: result[:concept_similarities]
         }
+        fact[:receipts] = result[:receipts].map { |r| format_receipt(r, query: query) } unless compact
+        fact
       end
 
       # Format shortcut query results (decisions, architecture, etc.)
@@ -274,6 +335,7 @@ module ClaudeMemory
       def self.format_shortcut_fact(result)
         {
           id: result[:fact][:id],
+          docid: result[:fact][:docid],
           subject: result[:fact][:subject_name],
           predicate: result[:fact][:predicate],
           object: result[:fact][:object_literal],
@@ -318,6 +380,7 @@ module ClaudeMemory
       def self.format_generic_fact(result)
         {
           id: result[:fact][:id],
+          docid: result[:fact][:docid],
           subject: result[:fact][:subject_name],
           predicate: result[:fact][:predicate],
           object: result[:fact][:object_literal],

data/lib/claude_memory/mcp/server.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "query_guide"
+require_relative "text_summary"
 
 module ClaudeMemory
   module MCP
@@ -58,6 +60,10 @@ module ClaudeMemory
           handle_tools_list(id)
         when "tools/call"
           handle_tools_call(id, request["params"])
+        when "prompts/list"
+          handle_prompts_list(id)
+        when "prompts/get"
+          handle_prompts_get(id, request["params"])
         when "shutdown"
           @running = false
           {jsonrpc: "2.0", id: id, result: nil}
@@ -73,7 +79,8 @@ module ClaudeMemory
           result: {
             protocolVersion: PROTOCOL_VERSION,
             capabilities: {
-              tools: {}
+              tools: {},
+              prompts: {}
             },
             serverInfo: {
               name: "claude-memory",
@@ -104,17 +111,40 @@ module ClaudeMemory
         # Connections are automatically reopened on next use
         release_connections
 
+        text_summary = TextSummary.for_tool(name, result)
+
         {
           jsonrpc: "2.0",
           id: id,
           result: {
             content: [
-              {type: "text", text: JSON.generate(result)}
-            ]
+              {type: "text", text: text_summary}
+            ],
+            structuredContent: result
+          }
+        }
+      end
+
+      def handle_prompts_list(id)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          result: {
+            prompts: [QueryGuide.definition]
           }
         }
       end
 
+      def handle_prompts_get(id, params)
+        name = params&.dig("name")
+
+        if name == QueryGuide::PROMPT_NAME
+          {jsonrpc: "2.0", id: id, result: QueryGuide.content}
+        else
+          {jsonrpc: "2.0", id: id, error: {code: -32602, message: "Unknown prompt: #{name}"}}
+        end
+      end
+
       def release_connections
         if @store_or_manager.is_a?(Store::StoreManager)
           # Release both global and project store connections
@@ -124,7 +154,7 @@ module ClaudeMemory
           # Release single store connection (legacy)
           @store_or_manager.db.disconnect
         end
-      rescue
+      rescue Sequel::DatabaseError, Extralite::Error
         # Silently ignore disconnect errors
         # Connection will be reopened automatically on next use
       end

data/lib/claude_memory/mcp/text_summary.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module MCP
+    # Generates human-readable text summaries from MCP tool results.
+    # Used alongside structuredContent for dual content/structuredContent pattern.
+    module TextSummary
+      def self.for_tool(name, result)
+        return result[:error] if result[:error]
+
+        case name
+        when "memory.recall" then summarize_recall(result)
+        when "memory.recall_index" then summarize_recall_index(result)
+        when "memory.recall_details" then summarize_recall_details(result)
+        when "memory.explain" then summarize_explain(result)
+        when "memory.changes" then summarize_changes(result)
+        when "memory.conflicts" then summarize_conflicts(result)
+        when "memory.sweep_now" then summarize_sweep(result)
+        when "memory.status" then summarize_status(result)
+        when "memory.stats" then summarize_stats(result)
+        when "memory.promote" then summarize_promote(result)
+        when "memory.store_extraction" then summarize_extraction(result)
+        when "memory.decisions" then summarize_shortcut(result)
+        when "memory.conventions" then summarize_shortcut(result)
+        when "memory.architecture" then summarize_shortcut(result)
+        when "memory.facts_by_tool" then summarize_tool_facts(result)
+        when "memory.facts_by_context" then summarize_context_facts(result)
+        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.check_setup" then summarize_check_setup(result)
+        else JSON.generate(result)
+        end
+      end
+
+      def self.summarize_recall(result)
+        facts = result[:facts] || []
+        return "No facts found." if facts.empty?
+
+        lines = ["Found #{facts.size} fact(s):"]
+        facts.each do |f|
+          lines << "- [#{fact_label(f)}] #{f[:subject]}.#{f[:predicate]} = #{f[:object]}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_recall_index(result)
+        facts = result[:facts] || []
+        return "No matching facts for '#{result[:query]}'." if facts.empty?
+
+        lines = ["#{result[:result_count]} fact(s) matching '#{result[:query]}' (~#{result[:total_estimated_tokens]} tokens):"]
+        facts.each do |f|
+          lines << "- [#{fact_label(f)}] #{f[:subject]}.#{f[:predicate]}: #{f[:object_preview]} (#{f[:tokens]}t)"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_recall_details(result)
+        facts = result[:facts] || []
+        return "No facts found for given IDs." if facts.empty?
+
+        lines = ["#{result[:fact_count]} fact(s):"]
+        facts.each do |f|
+          fact = f[:fact]
+          lines << "- [#{fact_label(fact)}] #{fact[:subject]}.#{fact[:predicate]} = #{fact[:object]} (#{fact[:status]}, #{fact[:scope]})"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_explain(result)
+        f = result[:fact]
+        lines = ["Fact [#{fact_label(f)}]: #{f[:subject]}.#{f[:predicate]} = #{f[:object]}"]
+        lines << "Status: #{f[:status]}, valid from: #{f[:valid_from_ago] || f[:valid_from] || "unknown"}"
+        lines << "Source: #{result[:source]}"
+
+        receipts = result[:receipts] || []
+        if receipts.any?
+          lines << "Evidence: #{receipts.map { |r| r[:quote] }.join("; ")}"
+        end
+
+        lines.join("\n")
+      end
+
+      def self.summarize_changes(result)
+        changes = result[:changes] || []
+        return "No changes since #{result[:since]}." if changes.empty?
+
+        lines = ["#{changes.size} change(s) since #{result[:since]}:"]
+        changes.each do |c|
+          ago = c[:created_ago] ? " (#{c[:created_ago]})" : ""
+          lines << "- [#{fact_label(c)}] #{c[:predicate]}: #{c[:object]} [#{c[:status]}]#{ago}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_conflicts(result)
+        return "No open conflicts." if result[:count] == 0
+
+        lines = ["#{result[:count]} conflict(s):"]
+        (result[:conflicts] || []).each do |c|
+          lines << "- Conflict ##{c[:id]}: fact #{c[:fact_a]} vs fact #{c[:fact_b]} (#{c[:status]})"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_sweep(result)
+        "Sweep (#{result[:scope]}): #{result[:proposed_expired]} proposed expired, " \
+          "#{result[:disputed_expired]} disputed expired, " \
+          "#{result[:orphaned_deleted]} orphaned deleted, " \
+          "#{result[:content_pruned]} content pruned " \
+          "(#{result[:elapsed_seconds]}s)"
+      end
+
+      def self.summarize_status(result)
+        dbs = result[:databases] || {}
+        lines = ["Memory status:"]
+        dbs.each do |name, info|
+          lines << if info[:exists] == false
+            "- #{name}: not initialized"
+          else
+            "- #{name}: #{info[:facts_active]} active facts, #{info[:open_conflicts]} conflicts (schema v#{info[:schema_version]})"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_stats(result)
+        dbs = result[:databases] || {}
+        lines = ["Stats (scope: #{result[:scope]}):"]
+        dbs.each do |name, info|
+          if info[:exists] == false
+            lines << "- #{name}: not initialized"
+          else
+            facts = info[:facts] || {}
+            lines << "- #{name}: #{facts[:active]}/#{facts[:total]} active facts, #{info[:entities]&.dig(:total) || 0} entities"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_promote(result)
+        if result[:success]
+          "Fact #{result[:project_fact_id]} promoted to global (new ID: #{result[:global_fact_id]})"
+        else
+          result[:error]
+        end
+      end
+
+      def self.summarize_extraction(result)
+        if result[:success]
+          "Stored: #{result[:facts_created]} facts, #{result[:entities_created]} entities, " \
+            "#{result[:facts_superseded]} superseded, #{result[:conflicts_created]} conflicts"
+        else
+          result[:error]
+        end
+      end
+
+      def self.summarize_shortcut(result)
+        facts = result[:facts] || []
+        return "No #{result[:category]} found." if facts.empty?
+
+        lines = ["#{result[:count]} #{result[:category]}:"]
+        facts.each do |f|
+          lines << "- [#{fact_label(f)}] #{f[:object]}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_tool_facts(result)
+        facts = result[:facts] || []
+        return "No facts discovered via #{result[:tool_name]}." if facts.empty?
+
+        lines = ["#{result[:count]} fact(s) from #{result[:tool_name]}:"]
+        facts.each do |f|
+          lines << "- [#{fact_label(f)}] #{f[:subject]}.#{f[:predicate]} = #{f[:object]}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_context_facts(result)
+        facts = result[:facts] || []
+        return "No facts for #{result[:context_type]}=#{result[:context_value]}." if facts.empty?
+
+        lines = ["#{result[:count]} fact(s) for #{result[:context_type]}=#{result[:context_value]}:"]
+        facts.each do |f|
+          lines << "- [#{fact_label(f)}] #{f[:subject]}.#{f[:predicate]} = #{f[:object]}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_semantic(result)
+        facts = result[:facts] || []
+        return "No semantic matches for '#{result[:query]}'." if facts.empty?
+
+        lines = ["#{result[:count]} match(es) for '#{result[:query]}' (#{result[:mode]}):"]
+        facts.each do |f|
+          sim = f[:similarity] ? " (#{(f[:similarity] * 100).round}%)" : ""
+          lines << "- [#{fact_label(f)}] #{f[:subject]}.#{f[:predicate]} = #{f[:object]}#{sim}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_concepts(result)
+        facts = result[:facts] || []
+        concepts_str = (result[:concepts] || []).join(" + ")
+        return "No facts matching all concepts: #{concepts_str}." if facts.empty?
+
+        lines = ["#{result[:count]} fact(s) matching #{concepts_str}:"]
+        facts.each do |f|
+          sim = f[:average_similarity] ? " (#{(f[:average_similarity] * 100).round}%)" : ""
+          lines << "- [#{fact_label(f)}] #{f[:subject]}.#{f[:predicate]} = #{f[:object]}#{sim}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_fact_graph(result)
+        nodes = result[:nodes] || []
+        edges = result[:edges] || []
+        return "Fact #{result[:root_fact_id]} not found." if nodes.empty?
+
+        lines = ["Graph for fact ##{result[:root_fact_id]} (depth #{result[:depth]}): #{result[:node_count]} nodes, #{result[:edge_count]} edges"]
+        nodes.each do |n|
+          label = n[:docid] || n[:id]
+          lines << "- [#{label}] #{n[:subject]}.#{n[:predicate]} = #{n[:object]} (#{n[:status]})"
+        end
+        if edges.any?
+          lines << "Edges:"
+          edges.each do |e|
+            lines << "  #{e[:from]} --#{e[:type]}--> #{e[:to]}"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_check_setup(result)
+        lines = ["Setup status: #{result[:status]}"]
+        lines << "Version: #{result[:version][:current]} (latest: #{result[:version][:latest]})"
+
+        components = result[:components] || {}
+        lines << "Components: global_db=#{components[:global_database]}, project_db=#{components[:project_database]}, hooks=#{components[:hooks_configured]}"
+
+        issues = result[:issues] || []
+        issues.each { |i| lines << "Issue: #{i}" }
+
+        warnings = result[:warnings] || []
+        warnings.each { |w| lines << "Warning: #{w}" }
+
+        lines.join("\n")
+      end
+
+      # Format fact identifier: prefer docid if available, fall back to integer id
+      def self.fact_label(fact)
+        fact[:docid] || fact[:id]
+      end
+    end
+  end
+end

data/lib/claude_memory/mcp/tool_definitions.rb

@@ -17,7 +17,8 @@ module ClaudeMemory
               properties: {
                 query: {type: "string", description: "Search query for existing knowledge (e.g., 'authentication flow', 'error handling', 'database setup')"},
                 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"}
+                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", default: false}
               },
               required: ["query"]
             }
@@ -53,7 +54,7 @@ module ClaudeMemory
             inputSchema: {
               type: "object",
               properties: {
-                fact_id: {type: "integer", description: "Fact ID to explain"},
+                fact_id: {description: "Fact ID (integer) or docid (8-char hex string) to explain"},
                 scope: {type: "string", enum: ["global", "project"], description: "Which database to look in", default: "project"}
               },
               required: ["fact_id"]
@@ -240,7 +241,8 @@ module ClaudeMemory
                 query: {type: "string", description: "Search query"},
                 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"}
+                scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"},
+                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses", default: false}
               },
               required: ["query"]
             }
@@ -259,11 +261,25 @@ module ClaudeMemory
                   description: "2-5 concepts that must all be present"
                 },
                 limit: {type: "integer", default: 10, description: "Maximum results to return"},
-                scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"}
+                scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"},
+                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses", default: false}
               },
               required: ["concepts"]
             }
           },
+          {
+            name: "memory.fact_graph",
+            description: "Build a dependency graph showing how facts relate through supersession and conflict links. Returns nodes (facts) and edges (supersedes/conflicts).",
+            inputSchema: {
+              type: "object",
+              properties: {
+                fact_id: {type: "integer", description: "Root fact ID to start traversal from"},
+                depth: {type: "integer", description: "Maximum BFS traversal depth (1-5)", default: 2},
+                scope: {type: "string", enum: ["global", "project"], description: "Which database to search", default: "project"}
+              },
+              required: ["fact_id"]
+            }
+          },
           {
             name: "memory.check_setup",
             description: "Check ClaudeMemory initialization status. Returns version info, issues found, and recommendations.",