claude_memory 0.8.0 → 0.9.0

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?
 

data/lib/claude_memory/recall.rb

@@ -1,29 +1,51 @@
 # frozen_string_literal: true
 
 module ClaudeMemory
+  # Query interface for facts across dual databases (global + project).
+  # Delegates to DualEngine or LegacyEngine depending on the store type.
   class Recall
+    # @return [String] query only project-scoped facts
     SCOPE_PROJECT = "project"
+    # @return [String] query only global-scoped facts
     SCOPE_GLOBAL = "global"
+    # @return [String] query both project and global facts (default)
     SCOPE_ALL = "all"
 
     class << self
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] recent decision facts
       def recent_decisions(manager, limit: 10)
         Shortcuts.for(:decisions, manager, limit: limit)
       end
 
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] architecture-related facts
       def architecture_choices(manager, limit: 10)
         Shortcuts.for(:architecture, manager, limit: limit)
       end
 
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] convention facts
       def conventions(manager, limit: 20)
         Shortcuts.for(:conventions, manager, limit: limit)
       end
 
+      # @param manager [Store::StoreManager] dual-database manager
+      # @param limit [Integer] max results
+      # @return [Array<Hash>] project configuration facts
       def project_config(manager, limit: 10)
         Shortcuts.for(:project_config, manager, limit: limit)
       end
     end
 
+    # @param store_or_manager [Store::SQLiteStore, Store::StoreManager] database store or dual-database manager
+    # @param fts [Index::LexicalFTS, nil] full-text search index (used only with legacy single-store)
+    # @param project_path [String, nil] project root path (defaults to Configuration#project_dir)
+    # @param env [Hash] environment variables
+    # @param embedding_generator [Object, nil] vector embedding generator for semantic search
     def initialize(store_or_manager, fts: nil, project_path: nil, env: ENV, embedding_generator: nil)
       config = Configuration.new(env)
       resolved_project_path = project_path || config.project_dir
@@ -45,46 +67,105 @@ module ClaudeMemory
       end
     end
 
+    # Search facts by text query using FTS5
+    # @param query_text [String] search terms
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @param include_raw_text [Boolean] include source content text in results
+    # @param intent [String, nil] query intent hint for ranking
+    # @return [Array<Hash>] matching facts with provenance
     def query(query_text, limit: 10, scope: SCOPE_ALL, include_raw_text: false, intent: nil)
       @engine.query(query_text, limit: limit, scope: scope, include_raw_text: include_raw_text, intent: intent)
     end
 
+    # Search content items (not facts) via FTS5 index
+    # @param query_text [String] search terms
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @param intent [String, nil] query intent hint for ranking
+    # @return [Array<Hash>] matching content items
     def query_index(query_text, limit: 20, scope: SCOPE_ALL, intent: nil)
       @engine.query_index(query_text, limit: limit, scope: scope, intent: intent)
     end
 
+    # Traverse fact relationships (supersessions, conflicts) as a graph
+    # @param fact_id [Integer] starting fact ID
+    # @param depth [Integer] traversal depth
+    # @param scope [String, nil] optional scope filter
+    # @return [Hash] graph with nodes and edges
     def fact_graph(fact_id, depth: 2, scope: nil)
       @engine.fact_graph(fact_id, depth: depth, scope: scope)
     end
 
+    # Show provenance chain for a fact
+    # @param fact_id_or_docid [Integer, String] fact ID or document ID
+    # @param scope [String, nil] optional scope filter
+    # @return [Hash] provenance details including source content
     def explain(fact_id_or_docid, scope: nil)
       @engine.explain(fact_id_or_docid, scope: scope)
     end
 
+    # List facts created or modified since a given time
+    # @param since [String] ISO 8601 timestamp
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] recently changed facts
     def changes(since:, limit: 50, scope: SCOPE_ALL)
       @engine.changes(since: since, limit: limit, scope: scope)
     end
 
+    # List open fact conflicts
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] unresolved conflicts
     def conflicts(scope: SCOPE_ALL)
       @engine.conflicts(scope: scope)
     end
 
+    # Find facts associated with a git branch
+    # @param branch_name [String] git branch name
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts from the given branch
     def facts_by_branch(branch_name, limit: 20, scope: SCOPE_ALL)
       @engine.facts_by_branch(branch_name, limit: limit, scope: scope)
     end
 
+    # Find facts associated with a working directory
+    # @param cwd [String] directory path
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts from the given directory
     def facts_by_directory(cwd, limit: 20, scope: SCOPE_ALL)
       @engine.facts_by_directory(cwd, limit: limit, scope: scope)
     end
 
+    # Find facts associated with a specific tool
+    # @param tool_name [String] tool name (e.g., "Read", "Bash")
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts from sessions using the given tool
     def facts_by_tool(tool_name, limit: 20, scope: SCOPE_ALL)
       @engine.facts_by_tool(tool_name, limit: limit, scope: scope)
     end
 
+    # Search facts using vector embeddings (semantic similarity)
+    # @param text [String] natural language query
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @param mode [Symbol] :vector, :lexical, or :both (hybrid RRF)
+    # @param explain [Boolean] include scoring breakdown in results
+    # @param intent [String, nil] query intent hint for ranking
+    # @return [Array<Hash>] semantically similar facts
     def query_semantic(text, limit: 10, scope: SCOPE_ALL, mode: :both, explain: false, intent: nil)
       @engine.query_semantic(text, limit: limit, scope: scope, mode: mode, explain: explain, intent: intent)
     end
 
+    # Find facts at the intersection of multiple concepts
+    # @param concepts [Array<String>] 2-5 concept terms to intersect
+    # @param limit [Integer] max results
+    # @param scope [String] one of SCOPE_ALL, SCOPE_PROJECT, SCOPE_GLOBAL
+    # @return [Array<Hash>] facts matching all given concepts
+    # @raise [ArgumentError] if concepts count is not 2-5
     def query_concepts(concepts, limit: 10, scope: SCOPE_ALL)
       raise ArgumentError, "Must provide 2-5 concepts" unless (2..5).cover?(concepts.size)
 

data/lib/claude_memory/resolve/predicate_policy.rb

@@ -3,17 +3,77 @@
 module ClaudeMemory
   module Resolve
     class PredicatePolicy
+      # Canonical predicate vocabulary. Curated after a multi-project survey
+      # of real memory databases under ~/src — predicates with zero facts
+      # across every database were pruned; predicates observed in the wild
+      # but missing from the policy (architecture, uses_language) were added.
+      #
+      # - convention / decision: workhorse multi-value predicates
+      # - uses_framework / uses_language: multi-value (projects use multiple)
+      # - uses_database / deployment_platform / auth_method: single-value,
+      #   correctly 1:1 per project in observed data
+      # - architecture: multi-value structural knowledge (was implicit)
       POLICIES = {
         "convention" => {cardinality: :multi, exclusive: false},
         "decision" => {cardinality: :multi, exclusive: false},
-        "auth_method" => {cardinality: :single, exclusive: true},
+        "architecture" => {cardinality: :multi, exclusive: false},
+        "uses_framework" => {cardinality: :multi, exclusive: false},
+        "uses_language" => {cardinality: :multi, exclusive: false},
         "uses_database" => {cardinality: :single, exclusive: true},
-        "uses_framework" => {cardinality: :single, exclusive: true},
-        "deployment_platform" => {cardinality: :single, exclusive: true}
+        "deployment_platform" => {cardinality: :single, exclusive: true},
+        "auth_method" => {cardinality: :single, exclusive: true}
       }.freeze
 
       DEFAULT_POLICY = {cardinality: :multi, exclusive: false}.freeze
 
+      # Drift canonicalization. Maps predicate names the distiller has
+      # organically coined onto the canonical form in POLICIES. Consulted
+      # at insert time by the Resolver so synonym drift never fragments
+      # the knowledge graph.
+      #
+      # Entries observed in real project DBs:
+      # - has_convention (chaos_to_the_rescue): prefix-drift of convention
+      # - primary_language (prior policy entry): supplanted by uses_language
+      #   which the distiller emits naturally and has multi-value semantics
+      SYNONYMS = {
+        "has_convention" => "convention",
+        "primary_language" => "uses_language"
+      }.freeze
+
+      # Section classification for the published snapshot. Keeps Publish
+      # from hard-coding predicate names; adding a new predicate to the
+      # policy and the section map in one place updates everything.
+      SECTION_MAP = {
+        "decision" => :decisions,
+        "convention" => :conventions,
+        "uses_database" => :constraints,
+        "uses_framework" => :constraints,
+        "uses_language" => :constraints,
+        "deployment_platform" => :constraints,
+        "auth_method" => :constraints
+        # architecture intentionally falls through to :additional for now
+      }.freeze
+
+      def self.known_predicates
+        POLICIES.keys
+      end
+
+      # Return the canonical form of a predicate name, applying known
+      # synonym mappings. Leaves unmapped predicates unchanged.
+      def self.canonicalize(predicate)
+        return predicate if predicate.nil?
+        SYNONYMS.fetch(predicate, predicate)
+      end
+
+      # Return the snapshot section a predicate belongs to.
+      # Respects legacy prefix/suffix patterns (decided_*, *_convention)
+      # that pre-date the policy.
+      def self.section_for(predicate)
+        return :decisions if predicate&.start_with?("decided_")
+        return :conventions if predicate&.include?("_convention")
+        SECTION_MAP.fetch(predicate, :additional)
+      end
+
       def self.policy_for(predicate)
         POLICIES.fetch(predicate, DEFAULT_POLICY)
       end

data/lib/claude_memory/resolve/resolver.rb

@@ -2,11 +2,32 @@
 
 module ClaudeMemory
   module Resolve
+    # Truth maintenance engine that processes distilled extractions into stored facts.
+    # Wraps entity resolution, fact insertion, supersession, and conflict detection
+    # in a single database transaction.
+    #
+    # @example
+    #   resolver = Resolver.new(store)
+    #   result = resolver.apply(extraction, content_item_id: 42, scope: "project")
+    #   result[:facts_created]   #=> 3
+    #   result[:facts_superseded] #=> 1
     class Resolver
+      # @param store [Store::SQLiteStore] backing database for reads and writes
       def initialize(store)
         @store = store
       end
 
+      # Apply a distilled extraction, resolving each fact against existing knowledge.
+      # Facts may be inserted, reinforce an existing fact, supersede old facts, or
+      # create a conflict when the resolution is ambiguous.
+      #
+      # @param extraction [#entities, #facts] distilled extraction with entities and facts
+      # @param content_item_id [Integer, nil] source content item for provenance
+      # @param occurred_at [String, nil] ISO 8601 timestamp (defaults to now)
+      # @param project_path [String, nil] project path for scoped facts
+      # @param scope [String] default scope for facts ("project" or "global")
+      # @return [Hash] counts keyed by :entities_created, :facts_created,
+      #   :facts_superseded, :conflicts_created, :provenance_created
       def apply(extraction, content_item_id: nil, occurred_at: nil, project_path: nil, scope: "project")
         occurred_at ||= Time.now.utc.iso8601
 
@@ -49,6 +70,21 @@ module ClaudeMemory
       end
 
       def resolve_fact(fact_data, entity_ids, content_item_id, occurred_at, project_path:, scope:)
+        # Canonicalize drift-prone predicate synonyms (has_convention →
+        # convention, primary_language → uses_language) before anything
+        # else looks at the predicate.
+        original_predicate = fact_data[:predicate]
+        canonical = PredicatePolicy.canonicalize(original_predicate)
+        if canonical != original_predicate
+          ClaudeMemory.logger.debug("resolve",
+            message: "Canonicalized predicate",
+            from: original_predicate,
+            to: canonical)
+          fact_data = fact_data.merge(predicate: canonical)
+        end
+
+        log_novel_predicate(canonical) unless PredicatePolicy.known_predicates.include?(canonical)
+
         subject_id = resolve_subject(fact_data, entity_ids)
         existing_facts = @store.facts_for_slot(subject_id, fact_data[:predicate])
         resolution = determine_resolution(existing_facts, fact_data, entity_ids)
@@ -57,6 +93,13 @@ module ClaudeMemory
           project_path: project_path, scope: scope)
       end
 
+      def log_novel_predicate(predicate)
+        ClaudeMemory.logger.warn("resolve",
+          message: "Novel predicate encountered",
+          predicate: predicate,
+          hint: "add to PredicatePolicy::POLICIES or PredicatePolicy::SYNONYMS to canonicalize")
+      end
+
       def resolve_subject(fact_data, entity_ids)
         entity_ids[fact_data[:subject]] ||
           @store.find_or_create_entity(type: "repo", name: fact_data[:subject])