claude_memory 0.8.0 → 0.9.1

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])

data/lib/claude_memory/store/schema_manager.rb

@@ -5,7 +5,7 @@ module ClaudeMemory
     # Schema migration and version management for SQLiteStore.
     # Handles Sequel migrations, legacy version syncing, and initial setup.
     module SchemaManager
-      SCHEMA_VERSION = 12
+      SCHEMA_VERSION = 14
 
       private