claude_memory 0.7.1 → 0.9.0

data/lib/claude_memory/mcp/tool_definitions.rb

@@ -14,6 +14,59 @@ module ClaudeMemory
       # Annotations for idempotent writes (safe to retry)
       WRITE_IDEMPOTENT = {readOnlyHint: false, idempotentHint: true, destructiveHint: false}.freeze
 
+      # Schema for {predicate, count} entries
+      PREDICATE_COUNT_SCHEMA = {
+        type: "object",
+        properties: {
+          predicate: {type: "string"},
+          count: {type: "integer"}
+        },
+        required: ["predicate", "count"]
+      }.freeze
+
+      # Schema for per-database stats block returned by memory.stats
+      DATABASE_STATS_SCHEMA = {
+        type: "object",
+        properties: {
+          exists: {type: "boolean"},
+          schema_version: {type: "integer"},
+          facts: {
+            type: "object",
+            properties: {
+              total: {type: "integer"},
+              active: {type: "integer"},
+              superseded: {type: "integer"},
+              top_predicates: {
+                type: "array",
+                description: "Top 10 predicates by count (known + novel combined)",
+                items: PREDICATE_COUNT_SCHEMA
+              },
+              predicates_known: {
+                type: "array",
+                description: "Predicates with explicit cardinality policies in PredicatePolicy::POLICIES, sorted by count desc",
+                items: PREDICATE_COUNT_SCHEMA
+              },
+              predicates_novel: {
+                type: "array",
+                description: "Predicates not in PredicatePolicy::POLICIES, sorted by count desc. Novel predicates with high counts are candidates for promotion to known status with explicit cardinality policies (canonicalization signal).",
+                items: PREDICATE_COUNT_SCHEMA
+              }
+            }
+          },
+          entities: {
+            type: "object",
+            properties: {
+              total: {type: "integer"},
+              by_type: {type: "array", items: {type: "object"}}
+            }
+          },
+          content_items: {type: "object"},
+          provenance: {type: "object"},
+          conflicts: {type: "object"},
+          vec: {type: "object"}
+        }
+      }.freeze
+
       # Returns array of tool definitions for MCP protocol
       # @return [Array<Hash>] Tool definitions with name, description, and inputSchema
       def self.all
@@ -25,6 +78,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 +94,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"}
               },
@@ -121,13 +176,29 @@ module ClaudeMemory
           },
           {
             name: "memory.stats",
-            description: "Get detailed statistics about the memory system (facts by predicate, entities by type, provenance coverage, conflicts, database sizes)",
+            description: "Get detailed statistics about the memory system (facts by predicate, entities by type, provenance coverage, conflicts, database sizes).",
             inputSchema: {
               type: "object",
               properties: {
                 scope: {type: "string", enum: ["all", "global", "project"], description: "Show stats for: all (default), global, or project", default: "all"}
               }
             },
+            outputSchema: {
+              type: "object",
+              properties: {
+                scope: {type: "string", enum: ["all", "global", "project"]},
+                databases: {
+                  type: "object",
+                  description: "Per-database stats. Keys are 'global', 'project', or 'legacy' depending on connection mode.",
+                  properties: {
+                    global: DATABASE_STATS_SCHEMA,
+                    project: DATABASE_STATS_SCHEMA,
+                    legacy: DATABASE_STATS_SCHEMA
+                  }
+                }
+              },
+              required: ["scope", "databases"]
+            },
             annotations: READ_ONLY
           },
           {
@@ -142,6 +213,20 @@ module ClaudeMemory
             },
             annotations: WRITE_IDEMPOTENT
           },
+          {
+            name: "memory.reject_fact",
+            description: "Mark a fact as rejected (e.g. a distiller hallucination). Sets status to 'rejected' and closes any open conflicts involving the fact. Use when the user confirms a fact is wrong.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                fact_id: {type: "integer", description: "Fact ID to reject"},
+                docid: {type: "string", description: "8-char docid (alternative to fact_id)"},
+                reason: {type: "string", description: "Why the fact is wrong (recorded in conflict notes)"},
+                scope: {type: "string", enum: ["project", "global"], description: "Database scope", default: "project"}
+              }
+            },
+            annotations: WRITE_IDEMPOTENT
+          },
           {
             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.",
@@ -154,7 +239,7 @@ module ClaudeMemory
                   items: {
                     type: "object",
                     properties: {
-                      type: {type: "string", description: "Entity type: database, framework, language, platform, repo, module, person, service"},
+                      type: {type: "string", description: "Entity type. Common types: database, framework, language, platform, repo, module, person, service, tool, library, concept. You may use other types if needed."},
                       name: {type: "string", description: "Canonical name"},
                       confidence: {type: "number", description: "0.0-1.0 extraction confidence"}
                     },
@@ -168,7 +253,7 @@ module ClaudeMemory
                     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"},
+                      predicate: {type: "string", description: "Relationship type. Known predicates: #{ClaudeMemory::Resolve::PredicatePolicy.known_predicates.join(", ")}. You may use other snake_case predicates for relations that don't fit these — be specific and reuse existing predicates when possible."},
                       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)"},
@@ -265,10 +350,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 +396,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