claude_memory 0.8.0 → 0.9.1

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

@@ -129,13 +129,16 @@ module ClaudeMemory
           }
 
           if active_facts > 0
-            stats[:top_predicates] = store.db[:facts]
+            all_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]} }
+
+            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

data/lib/claude_memory/mcp/instructions_builder.rb

@@ -108,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/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?
 
@@ -46,15 +59,22 @@ module ClaudeMemory
         rescue JSON::ParserError => e
           send_error(-32700, "Parse error: #{e.message}", 0)
         rescue => e
-          request_id = request&.fetch("id", nil) || 0
-          send_error(-32603, "Internal error: #{e.message}", request_id)
+          # Per JSON-RPC 2.0: never respond to notifications, even on error
+          request_id = request&.fetch("id", nil)
+          send_error(-32603, "Internal error: #{e.message}", request_id) unless request_id.nil?
         end
       end
 
+      # @return [Hash, nil] JSON-RPC response hash, or nil for notifications
       def process_request(request)
         id = request["id"]
         method = request["method"]
 
+        # Per JSON-RPC 2.0: a request without an id is a notification and
+        # MUST NOT receive a response. MCP relies on this for
+        # `notifications/initialized` after the initialize handshake.
+        return nil if id.nil?
+
         case method
         when "initialize"
           handle_initialize(id, request["params"])
@@ -74,6 +94,7 @@ module ClaudeMemory
         end
       end
 
+      # @return [Hash] initialize response with capabilities and server info
       def handle_initialize(id, _params)
         {
           jsonrpc: "2.0",
@@ -93,6 +114,7 @@ module ClaudeMemory
         }
       end
 
+      # @return [Hash] list of available tool definitions
       def handle_tools_list(id)
         {
           jsonrpc: "2.0",
@@ -103,11 +125,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 +153,7 @@ module ClaudeMemory
         }
       end
 
+      # @return [Hash] list of available prompt definitions
       def handle_prompts_list(id)
         {
           jsonrpc: "2.0",
@@ -138,6 +164,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/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
@@ -123,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
           },
           {
@@ -144,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.",
@@ -156,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"}
                     },
@@ -170,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)"},

data/lib/claude_memory/mcp/tools.rb

@@ -16,6 +16,9 @@ require_relative "handlers/setup_handlers"
 
 module ClaudeMemory
   module MCP
+    # Dispatcher that routes MCP tool calls to handler modules.
+    # Each handler module (QueryHandlers, ShortcutHandlers, etc.) provides
+    # the implementation for a group of related tools.
     class Tools
       include ToolHelpers
       include Handlers::QueryHandlers
@@ -25,6 +28,7 @@ module ClaudeMemory
       include Handlers::StatsHandlers
       include Handlers::SetupHandlers
 
+      # @param store_or_manager [Store::SQLiteStore, Store::StoreManager] database backend
       def initialize(store_or_manager)
         @recall = Recall.new(store_or_manager)
 
@@ -35,10 +39,15 @@ module ClaudeMemory
         end
       end
 
+      # @return [Array<Hash>] MCP tool definition hashes for tools/list
       def definitions
         ToolDefinitions.all
       end
 
+      # Dispatch a tool call to the appropriate handler method.
+      # @param name [String] fully-qualified tool name (e.g. "memory.recall")
+      # @param arguments [Hash] tool arguments from the MCP request
+      # @return [Hash] structured result hash for the tool response
       def call(name, arguments)
         case name
         when "memory.recall" then recall(arguments)
@@ -51,6 +60,7 @@ module ClaudeMemory
         when "memory.status" then status
         when "memory.stats" then stats(arguments)
         when "memory.promote" then promote(arguments)
+        when "memory.reject_fact" then reject_fact(arguments)
         when "memory.store_extraction" then store_extraction(arguments)
         when "memory.decisions" then decisions(arguments)
         when "memory.conventions" then conventions(arguments)

data/lib/claude_memory/publish.rb

@@ -4,15 +4,22 @@ require "digest"
 require "fileutils"
 
 module ClaudeMemory
+  # Generates Markdown snapshots from active facts for use as project memory.
+  # Publishes to .claude/rules/ (shared), a local file, or the home directory.
   class Publish
     RULES_DIR = ".claude/rules"
     GENERATED_FILE = "claude_memory.generated.md"
 
+    # @param store [Store::SQLiteStore] database store for reading facts
+    # @param file_system [Infrastructure::FileSystem] filesystem abstraction for I/O
     def initialize(store, file_system: Infrastructure::FileSystem.new)
       @store = store
       @fs = file_system
     end
 
+    # Generate a complete Markdown snapshot with header and body
+    # @param since [String, nil] ISO 8601 timestamp to include recent supersessions
+    # @return [String] full Markdown document
     def generate_snapshot(since: nil)
       header = <<~HEADER
         <!--
@@ -28,6 +35,12 @@ module ClaudeMemory
       header + generate_body(since: since)
     end
 
+    # Write snapshot to disk if content has changed
+    # @param mode [Symbol] output target (:shared, :local, or :home)
+    # @param granularity [Symbol] snapshot granularity (currently only :repo)
+    # @param since [String, nil] ISO 8601 timestamp for recent supersessions
+    # @param rules_dir [String, nil] override rules directory path
+    # @return [Hash] result with :status (:updated or :unchanged) and :path
     def publish!(mode: :shared, granularity: :repo, since: nil, rules_dir: nil)
       path = output_path(mode, rules_dir: rules_dir)
       body = generate_body(since: since)
@@ -97,8 +110,9 @@ module ClaudeMemory
         .all
     end
 
+    # @return [String] Markdown section for decision facts
     def generate_decisions_section(facts)
-      decisions = facts.select { |f| f[:predicate] == "decision" || f[:predicate]&.start_with?("decided_") }
+      decisions = facts.select { |f| Resolve::PredicatePolicy.section_for(f[:predicate]) == :decisions }
       return "" if decisions.empty?
 
       lines = ["## Current Decisions\n"]
@@ -108,8 +122,9 @@ module ClaudeMemory
       lines.join("\n") + "\n"
     end
 
+    # @return [String] Markdown section for convention facts
     def generate_conventions_section(facts)
-      conventions = facts.select { |f| f[:predicate] == "convention" || f[:predicate]&.include?("_convention") }
+      conventions = facts.select { |f| Resolve::PredicatePolicy.section_for(f[:predicate]) == :conventions }
       return "" if conventions.empty?
 
       lines = ["## Conventions\n"]
@@ -119,10 +134,9 @@ module ClaudeMemory
       lines.join("\n") + "\n"
     end
 
+    # @return [String] Markdown section for technical constraint facts
     def generate_constraints_section(facts)
-      constraints = facts.select do |f|
-        %w[uses_database uses_framework deployment_platform auth_method].include?(f[:predicate])
-      end
+      constraints = facts.select { |f| Resolve::PredicatePolicy.section_for(f[:predicate]) == :constraints }
       return "" if constraints.empty?
 
       lines = ["## Technical Constraints\n"]
@@ -132,6 +146,25 @@ module ClaudeMemory
       lines.join("\n") + "\n"
     end
 
+    # @return [String] Markdown section for additional knowledge grouped by predicate
+    def generate_additional_section(facts)
+      additional = facts.select { |f| Resolve::PredicatePolicy.section_for(f[:predicate]) == :additional }
+      return "" if additional.empty?
+
+      grouped = additional.group_by { |f| f[:predicate] }
+      lines = ["## Additional Knowledge\n"]
+      grouped.each do |predicate, group_facts|
+        lines << "### #{humanize(predicate)}\n"
+        group_facts.each do |f|
+          subject = f[:subject_name] || "repo"
+          lines << "- #{subject}: #{f[:object_literal]}"
+        end
+        lines << ""
+      end
+      lines.join("\n") + "\n"
+    end
+
+    # @return [String] Markdown section for open conflicts
     def generate_conflicts_section(conflicts)
       return "" if conflicts.empty?
 
@@ -143,6 +176,7 @@ module ClaudeMemory
       lines.join("\n") + "\n"
     end
 
+    # @return [String] Markdown section for recently superseded facts
     def generate_supersessions_section(supersessions)
       return "" if supersessions.empty?
 
@@ -162,6 +196,7 @@ module ClaudeMemory
       sections << generate_decisions_section(facts)
       sections << generate_conventions_section(facts)
       sections << generate_constraints_section(facts)
+      sections << generate_additional_section(facts)
       sections << generate_conflicts_section(conflicts) if conflicts.any?
       sections << generate_supersessions_section(recent_supersessions) if recent_supersessions.any?