claude_memory 0.7.1 → 0.9.0

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/shortcuts.rb

@@ -5,22 +5,22 @@ module ClaudeMemory
     QUERIES = {
       decisions: {
         query: "decision constraint rule requirement",
-        scope: :all,
+        scope: "all",
         limit: 10
       },
       architecture: {
         query: "uses framework implements architecture pattern",
-        scope: :all,
+        scope: "all",
         limit: 10
       },
       conventions: {
         query: "convention style format pattern prefer",
-        scope: :global,
+        scope: "global",
         limit: 20
       },
       project_config: {
         query: "uses requires depends_on configuration",
-        scope: :project,
+        scope: "project",
         limit: 10
       }
     }.freeze

data/lib/claude_memory/store/retry_handler.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Store
+    # Retry logic for SQLite database operations.
+    # Handles busy/locked errors from concurrent access by multiple hook processes.
+    module RetryHandler
+      MAX_RETRIES = 5
+      RETRY_BASE_DELAY = 0.1 # seconds, with exponential backoff
+
+      def with_retry(operation_name = "database operation")
+        retries = 0
+        begin
+          yield
+        rescue Sequel::DatabaseError, Extralite::Error, Extralite::BusyError => e
+          if retryable_error?(e) && retries < MAX_RETRIES
+            retries += 1
+            delay = RETRY_BASE_DELAY * (2**retries)
+            sleep(delay)
+            retry
+          end
+          raise
+        end
+      end
+
+      def transaction_with_retry(&block)
+        with_retry("transaction") do
+          @db.transaction(&block)
+        end
+      end
+
+      private
+
+      def retryable_error?(error)
+        message = error.message.downcase
+        message.include?("busy") || message.include?("locked")
+      end
+
+      def connect_database(db_path)
+        retries = 0
+        begin
+          Sequel.connect(
+            "extralite:#{db_path}",
+            connect_sqls: [
+              "PRAGMA busy_timeout = 1000",
+              "PRAGMA journal_mode = WAL",
+              "PRAGMA synchronous = NORMAL"
+            ]
+          )
+        rescue Sequel::DatabaseConnectionError, Extralite::Error => e
+          retries += 1
+          if retries <= MAX_RETRIES && retryable_error?(e)
+            sleep(RETRY_BASE_DELAY * (2**retries))
+            retry
+          end
+          raise
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/store/schema_manager.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Store
+    # Schema migration and version management for SQLiteStore.
+    # Handles Sequel migrations, legacy version syncing, and initial setup.
+    module SchemaManager
+      SCHEMA_VERSION = 14
+
+      private
+
+      def ensure_schema!
+        migrations_path = File.expand_path("../../../db/migrations", __dir__)
+
+        # Handle backward compatibility: databases created with old migration system
+        sync_legacy_schema_version!
+
+        # Skip migration if the database is already ahead of this gem's version.
+        # This happens when a newer gem version migrated the DB and an older
+        # installed gem (e.g. via hooks) tries to open it.
+        current = current_schema_version
+        return if current && current > SCHEMA_VERSION
+
+        # Run Sequel migrations to bring database to target version
+        Sequel::Migrator.run(@db, migrations_path, target: SCHEMA_VERSION)
+
+        # Set created_at timestamp on first initialization
+        set_meta("created_at", Time.now.utc.iso8601) unless get_meta("created_at")
+
+        # Sync legacy schema_version meta key with Sequel's schema_info
+        # This maintains backwards compatibility with code that reads schema_version
+        sequel_version = @db[:schema_info].get(:version) if @db.table_exists?(:schema_info)
+        set_meta("schema_version", sequel_version.to_s) if sequel_version
+      end
+
+      # Sync legacy schema_version from meta table to Sequel's schema_info
+      # Handles two cases:
+      # 1. No schema_info table exists (old system, pre-Sequel migrations)
+      # 2. schema_info exists but is out of sync with meta.schema_version
+      def sync_legacy_schema_version!
+        return unless @db.table_exists?(:meta)
+
+        meta_version = get_meta("schema_version")&.to_i
+        return unless meta_version && meta_version >= 2
+
+        # Verify database actually has v2+ schema (defensive check)
+        columns = @db.schema(:content_items).map(&:first) if @db.table_exists?(:content_items)
+        return unless columns&.include?(:project_path)
+
+        # Create or update schema_info to match meta.schema_version
+        @db.create_table?(:schema_info) do
+          Integer :version, null: false, default: 0
+        end
+
+        sequel_version = @db[:schema_info].get(:version)
+        if sequel_version.nil? || sequel_version < meta_version
+          @db[:schema_info].delete
+          @db[:schema_info].insert(version: meta_version)
+        end
+      end
+
+      def current_schema_version
+        return nil unless @db.table_exists?(:schema_info)
+        @db[:schema_info].get(:version)
+      end
+    end
+  end
+end