claude_memory 0.7.1 → 0.9.0

data/lib/claude_memory/store/store_manager.rb

@@ -4,9 +4,25 @@ require "fileutils"
 
 module ClaudeMemory
   module Store
+    # Dual-database connection manager for global and project stores.
+    # Lazily opens SQLiteStore connections to the global database
+    # (~/.claude/memory.sqlite3) and the project database
+    # (.claude/memory.sqlite3 under the project root). Commands query
+    # both databases by default, with project facts taking precedence.
     class StoreManager
-      attr_reader :global_store, :project_store, :project_path
+      # @return [SQLiteStore, nil] global store (nil until {#ensure_global!} is called)
+      attr_reader :global_store
 
+      # @return [SQLiteStore, nil] project store (nil until {#ensure_project!} is called)
+      attr_reader :project_store
+
+      # @return [String] project directory path
+      attr_reader :project_path
+
+      # @param global_db_path [String, nil] override path to the global database
+      # @param project_db_path [String, nil] override path to the project database
+      # @param project_path [String, nil] project directory (defaults to Configuration)
+      # @param env [Hash] environment variable hash (default: ENV)
       def initialize(global_db_path: nil, project_db_path: nil, project_path: nil, env: ENV)
         config = Configuration.new(env)
         @project_path = project_path || config.project_dir
@@ -17,14 +33,23 @@ module ClaudeMemory
         @project_store = nil
       end
 
+      # Default global database path from Configuration.
+      # @param env [Hash] environment variable hash
+      # @return [String]
       def self.default_global_db_path(env = ENV)
         Configuration.new(env).global_db_path
       end
 
+      # Default project database path for a given project directory.
+      # @param project_path [String] project directory (default: current working directory)
+      # @return [String]
       def self.default_project_db_path(project_path = Dir.pwd)
         Configuration.new.project_db_path(project_path)
       end
 
+      # Open the global store, creating the directory and database if needed.
+      # No-op if already open.
+      # @return [SQLiteStore] the global store
       def ensure_global!
         return @global_store if @global_store
 
@@ -32,6 +57,9 @@ module ClaudeMemory
         @global_store = SQLiteStore.new(@global_db_path)
       end
 
+      # Open the project store, creating the directory and database if needed.
+      # No-op if already open.
+      # @return [SQLiteStore] the project store
       def ensure_project!
         return @project_store if @project_store
 
@@ -39,23 +67,33 @@ module ClaudeMemory
         @project_store = SQLiteStore.new(@project_db_path)
       end
 
+      # Open both global and project stores.
+      # @return [void]
       def ensure_both!
         ensure_global!
         ensure_project!
       end
 
+      # @return [String] filesystem path to the global database
       attr_reader :global_db_path
 
+      # @return [String] filesystem path to the project database
       attr_reader :project_db_path
 
+      # Check whether the global database file exists on disk.
+      # @return [Boolean]
       def global_exists?
         File.exist?(@global_db_path)
       end
 
+      # Check whether the project database file exists on disk.
+      # @return [Boolean]
       def project_exists?
         File.exist?(@project_db_path)
       end
 
+      # Close both database connections and reset store references.
+      # @return [void]
       def close
         @global_store&.close
         @project_store&.close
@@ -63,6 +101,10 @@ module ClaudeMemory
         @project_store = nil
       end
 
+      # Return the appropriate store for a given scope string.
+      # @param scope [String] "global" or "project"
+      # @return [SQLiteStore]
+      # @raise [ArgumentError] if scope is not "global" or "project"
       def store_for_scope(scope)
         case scope
         when "global"
@@ -76,6 +118,13 @@ module ClaudeMemory
         end
       end
 
+      # Copy a project-scoped fact (with its entities and provenance) into the
+      # global store, making it available across all projects. Runs the global
+      # writes in a single transaction for atomicity.
+      #
+      # @param fact_id [Integer] project fact row id to promote
+      # @return [Integer, nil] the new global fact id, or nil if the fact/subject
+      #   was not found in the project store
       def promote_fact(fact_id)
         ensure_both!
 

data/lib/claude_memory/sweep/maintenance.rb

@@ -8,10 +8,16 @@ module ClaudeMemory
     #
     # Source: QMD v2.0.1 Maintenance class pattern
     class Maintenance
+      # Short / noise tokens dropped before Jaccard comparison.
+      # Intentionally minimal — we want conservative token extraction that
+      # still treats "Rails 8.0" and "Rails 8.1" as overlapping.
+      RESTORE_STOPWORDS = %w[for the and with via of in on to by is are].to_set.freeze
+      RESTORE_JACCARD_THRESHOLD = 0.5
       DEFAULT_CONFIG = {
         proposed_fact_ttl_days: 14,
         disputed_fact_ttl_days: 30,
-        content_retention_days: 30
+        content_retention_days: 30,
+        mcp_tool_call_retention_days: 90
       }.freeze
 
       attr_reader :store
@@ -96,6 +102,85 @@ module ClaudeMemory
         0
       end
 
+      # Restore superseded facts in a (subject, predicate) slot that were
+      # only superseded because of an obsolete single-value classification.
+      # Uses Jaccard-based token overlap to distinguish bug-superseded facts
+      # (token-disjoint siblings) from legitimate corrections (overlapping
+      # siblings).
+      #
+      # Refuses to run on predicates still classified as single-value — they
+      # should stay superseded by design.
+      #
+      # Never touches status: "rejected" facts (explicit user decisions).
+      #
+      # @return [Hash] {inspected, restored, skipped_ambiguous, skipped_rejected, decisions}
+      def restore_multi_value_supersessions(predicate:, dry_run: false)
+        if ClaudeMemory::Resolve::PredicatePolicy.single?(predicate)
+          raise ArgumentError, "Predicate '#{predicate}' is still classified single-value; refusing to restore"
+        end
+
+        result = {inspected: 0, restored: 0, skipped_ambiguous: 0, skipped_rejected: 0, decisions: []}
+
+        rows_by_subject = @store.facts
+          .where(predicate: predicate)
+          .exclude(status: "rejected")
+          .select(:id, :subject_entity_id, :object_literal, :status)
+          .all
+          .group_by { |r| r[:subject_entity_id] }
+
+        rejected_by_subject = @store.facts
+          .where(predicate: predicate, status: "rejected")
+          .select(:id, :subject_entity_id, :object_literal)
+          .all
+          .group_by { |r| r[:subject_entity_id] }
+
+        @store.db.transaction do
+          rows_by_subject.each do |subject_id, rows|
+            rejected_rows = rejected_by_subject[subject_id] || []
+            siblings = rows + rejected_rows
+
+            rows.each do |candidate|
+              next unless candidate[:status] == "superseded"
+              result[:inspected] += 1
+
+              candidate_tokens = restore_tokenize(candidate[:object_literal])
+              ambiguous_against = find_overlapping_siblings(candidate, siblings, candidate_tokens)
+
+              if ambiguous_against.empty?
+                result[:restored] += 1
+                result[:decisions] << {
+                  subject_entity_id: subject_id,
+                  fact_id: candidate[:id],
+                  object: candidate[:object_literal],
+                  action: :restore
+                }
+                restore_fact!(candidate[:id]) unless dry_run
+              else
+                result[:skipped_ambiguous] += 1
+                result[:decisions] << {
+                  subject_entity_id: subject_id,
+                  fact_id: candidate[:id],
+                  object: candidate[:object_literal],
+                  action: :skip_ambiguous,
+                  overlaps_with: ambiguous_against.map { |s| s[:object_literal] }
+                }
+              end
+            end
+          end
+        end
+
+        result
+      end
+
+      # Delete MCP tool-call telemetry rows older than retention window.
+      # Returns: Integer count of deleted rows (0 if table missing).
+      def prune_old_mcp_tool_calls
+        return 0 unless @store.db.table_exists?(:mcp_tool_calls)
+
+        cutoff = cutoff_time(@config[:mcp_tool_call_retention_days])
+        @store.mcp_tool_calls.where { called_at < cutoff }.delete
+      end
+
       # Checkpoint the SQLite WAL file for compaction.
       # Returns: true
       def checkpoint_wal
@@ -112,6 +197,35 @@ module ClaudeMemory
 
       private
 
+      def restore_tokenize(text)
+        return Set.new if text.nil?
+        text.downcase
+          .scan(/[a-z0-9]+/)
+          .reject { |t| t.length <= 2 || RESTORE_STOPWORDS.include?(t) }
+          .to_set
+      end
+
+      def restore_jaccard(a, b)
+        return 0.0 if a.empty? && b.empty?
+        intersection = (a & b).size
+        union = (a | b).size
+        return 0.0 if union.zero?
+        intersection.to_f / union
+      end
+
+      def find_overlapping_siblings(candidate, siblings, candidate_tokens)
+        siblings.select do |other|
+          next false if other[:id] == candidate[:id]
+          other_tokens = restore_tokenize(other[:object_literal])
+          restore_jaccard(candidate_tokens, other_tokens) >= RESTORE_JACCARD_THRESHOLD
+        end
+      end
+
+      def restore_fact!(fact_id)
+        @store.facts.where(id: fact_id).update(status: "active", valid_to: nil)
+        @store.fact_links.where(to_fact_id: fact_id, link_type: "supersedes").delete
+      end
+
       def cutoff_time(days)
         (Time.now - days * 86400).utc.iso8601
       end

data/lib/claude_memory/sweep/sweeper.rb

@@ -7,6 +7,7 @@ module ClaudeMemory
         proposed_fact_ttl_days: 14,
         disputed_fact_ttl_days: 30,
         content_retention_days: 30,
+        mcp_tool_call_retention_days: 90,
         default_budget_seconds: 5
       }.freeze
 
@@ -29,6 +30,7 @@ module ClaudeMemory
           disputed_facts_expired: 0,
           orphaned_provenance_deleted: 0,
           old_content_pruned: 0,
+          mcp_tool_calls_pruned: 0,
           escalation_level: :normal
         }
 
@@ -38,6 +40,7 @@ module ClaudeMemory
         run_if_within_budget { @stats[:disputed_facts_expired] = maintenance.expire_disputed_facts }
         run_if_within_budget { @stats[:orphaned_provenance_deleted] = maintenance.prune_orphaned_provenance }
         run_if_within_budget { @stats[:old_content_pruned] = maintenance.prune_old_content }
+        run_if_within_budget { @stats[:mcp_tool_calls_pruned] = maintenance.prune_old_mcp_tool_calls }
         run_if_within_budget { @stats[:vec_backfilled] = maintenance.backfill_vec_index }
         run_if_within_budget { @stats[:vec_cleaned] = maintenance.cleanup_vec_expired }
         run_if_within_budget { @stats[:wal_checkpointed] = maintenance.checkpoint_wal }

data/lib/claude_memory/templates/hooks.example.json

@@ -6,7 +6,20 @@
           {
             "type": "command",
             "command": "claude-memory hook ingest",
-            "timeout": 10
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest",
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
           }
         ]
       }
@@ -17,7 +30,8 @@
           {
             "type": "command",
             "command": "claude-memory hook ingest",
-            "timeout": 10
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
           }
         ]
       }
@@ -28,12 +42,14 @@
           {
             "type": "command",
             "command": "claude-memory hook ingest",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "claude-memory hook sweep",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }
@@ -44,12 +60,14 @@
           {
             "type": "command",
             "command": "claude-memory hook ingest",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "claude-memory hook sweep",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }
@@ -61,7 +79,8 @@
           {
             "type": "command",
             "command": "claude-memory hook sweep",
-            "timeout": 10
+            "timeout": 10,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }

data/lib/claude_memory/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeMemory
-  VERSION = "0.7.1"
+  VERSION = "0.9.0"
 end

data/lib/claude_memory.rb

@@ -38,6 +38,7 @@ require_relative "claude_memory/commands/checks/claude_md_check"
 require_relative "claude_memory/commands/checks/hooks_check"
 require_relative "claude_memory/commands/checks/reporter"
 require_relative "claude_memory/commands/checks/vec_check"
+require_relative "claude_memory/commands/checks/distill_check"
 require_relative "claude_memory/commands/help_command"
 require_relative "claude_memory/commands/version_command"
 require_relative "claude_memory/commands/doctor_command"
@@ -67,6 +68,11 @@ require_relative "claude_memory/commands/recover_command"
 require_relative "claude_memory/commands/compact_command"
 require_relative "claude_memory/commands/export_command"
 require_relative "claude_memory/commands/git_lfs_command"
+require_relative "claude_memory/commands/install_skill_command"
+require_relative "claude_memory/commands/completion_command"
+require_relative "claude_memory/commands/embeddings_command"
+require_relative "claude_memory/commands/reject_command"
+require_relative "claude_memory/commands/restore_command"
 require_relative "claude_memory/commands/registry"
 require_relative "claude_memory/cli"
 require_relative "claude_memory/configuration"
@@ -77,9 +83,16 @@ require_relative "claude_memory/domain/fact"
 require_relative "claude_memory/domain/entity"
 require_relative "claude_memory/domain/provenance"
 require_relative "claude_memory/domain/conflict"
+require_relative "claude_memory/embeddings/model_registry"
+require_relative "claude_memory/embeddings/inspector"
 require_relative "claude_memory/embeddings/generator"
+require_relative "claude_memory/embeddings/fastembed_adapter"
+require_relative "claude_memory/embeddings/api_adapter"
+require_relative "claude_memory/embeddings/dimension_check"
+require_relative "claude_memory/embeddings/resolver"
 require_relative "claude_memory/embeddings/similarity"
 require_relative "claude_memory/hook/context_injector"
+require_relative "claude_memory/hook/distillation_runner"
 require_relative "claude_memory/hook/exit_codes"
 require_relative "claude_memory/hook/handler"
 require_relative "claude_memory/hook/error_classifier"
@@ -110,6 +123,9 @@ require_relative "claude_memory/mcp/tools"
 require_relative "claude_memory/publish"
 require_relative "claude_memory/recall/dual_query_template"
 require_relative "claude_memory/recall/expansion_detector"
+require_relative "claude_memory/recall/query_core"
+require_relative "claude_memory/recall/legacy_engine"
+require_relative "claude_memory/recall/dual_engine"
 require_relative "claude_memory/recall"
 require_relative "claude_memory/shortcuts"
 require_relative "claude_memory/resolve/predicate_policy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_memory
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Valentino Stoll
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.102'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.102'
 - !ruby/object:Gem::Dependency
   name: extralite
   requirement: !ruby/object:Gem::Requirement
@@ -44,6 +44,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.9
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -51,8 +54,13 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.1'
-description: Turn-key Ruby gem providing Claude Code with instant, high-quality, long-term,
-  self-managed memory using Claude Code Hooks + MCP + Output Style.
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.9
+description: Gives Claude Code persistent memory across sessions. Claude recalls your
+  codebase architecture without file traversal, enforces project conventions during
+  code generation, tracks decisions with rationale, and remembers your preferences
+  across all projects. Zero-config via Hooks + MCP.
 email:
 - v@codenamev.com
 executables:
@@ -60,13 +68,15 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude-plugin/commands/distill-transcripts.md"
+- ".claude-plugin/commands/memory-recall.md"
 - ".claude-plugin/marketplace.json"
 - ".claude-plugin/plugin.json"
+- ".claude-plugin/scripts/hook-runner.sh"
+- ".claude-plugin/scripts/serve-mcp.sh"
 - ".claude.json"
 - ".claude/CLAUDE.md"
 - ".claude/memory.sqlite3"
-- ".claude/memory.sqlite3-shm"
-- ".claude/memory.sqlite3-wal"
 - ".claude/output-styles/memory-aware.md"
 - ".claude/rules/claude_memory.generated.md"
 - ".claude/settings.json"
@@ -86,6 +96,7 @@ files:
 - ".claude/skills/study-repo/SKILL.md"
 - ".claude/skills/study-repo/analysis-template.md"
 - ".claude/skills/study-repo/focus-examples.md"
+- ".claude/skills/upgrade-dependencies/SKILL.md"
 - ".gitattributes"
 - ".lefthook/map_specs.rb"
 - ".mcp.json"
@@ -112,6 +123,8 @@ files:
 - db/migrations/010_add_llm_cache.rb
 - db/migrations/011_add_tool_call_summaries.rb
 - db/migrations/012_add_vec_indexing_support.rb
+- db/migrations/013_add_mcp_tool_calls.rb
+- db/migrations/014_canonicalize_predicates.rb
 - docs/EXAMPLES.md
 - docs/GETTING_STARTED.md
 - docs/RELEASE_NOTES_v0.2.0.md
@@ -151,14 +164,17 @@ files:
 - lib/claude_memory/commands/changes_command.rb
 - lib/claude_memory/commands/checks/claude_md_check.rb
 - lib/claude_memory/commands/checks/database_check.rb
+- lib/claude_memory/commands/checks/distill_check.rb
 - lib/claude_memory/commands/checks/hooks_check.rb
 - lib/claude_memory/commands/checks/reporter.rb
 - lib/claude_memory/commands/checks/snapshot_check.rb
 - lib/claude_memory/commands/checks/vec_check.rb
 - lib/claude_memory/commands/compact_command.rb
+- lib/claude_memory/commands/completion_command.rb
 - lib/claude_memory/commands/conflicts_command.rb
 - lib/claude_memory/commands/db_init_command.rb
 - lib/claude_memory/commands/doctor_command.rb
+- lib/claude_memory/commands/embeddings_command.rb
 - lib/claude_memory/commands/explain_command.rb
 - lib/claude_memory/commands/export_command.rb
 - lib/claude_memory/commands/git_lfs_command.rb
@@ -173,13 +189,18 @@ files:
 - lib/claude_memory/commands/initializers/mcp_configurator.rb
 - lib/claude_memory/commands/initializers/memory_instructions_writer.rb
 - lib/claude_memory/commands/initializers/project_initializer.rb
+- lib/claude_memory/commands/install_skill_command.rb
 - lib/claude_memory/commands/promote_command.rb
 - lib/claude_memory/commands/publish_command.rb
 - lib/claude_memory/commands/recall_command.rb
 - lib/claude_memory/commands/recover_command.rb
 - lib/claude_memory/commands/registry.rb
+- lib/claude_memory/commands/reject_command.rb
+- lib/claude_memory/commands/restore_command.rb
 - lib/claude_memory/commands/search_command.rb
 - lib/claude_memory/commands/serve_mcp_command.rb
+- lib/claude_memory/commands/skills/distill-transcripts.md
+- lib/claude_memory/commands/skills/memory-recall.md
 - lib/claude_memory/commands/stats_command.rb
 - lib/claude_memory/commands/sweep_command.rb
 - lib/claude_memory/commands/uninstall_command.rb
@@ -214,10 +235,16 @@ files:
 - lib/claude_memory/domain/entity.rb
 - lib/claude_memory/domain/fact.rb
 - lib/claude_memory/domain/provenance.rb
+- lib/claude_memory/embeddings/api_adapter.rb
+- lib/claude_memory/embeddings/dimension_check.rb
 - lib/claude_memory/embeddings/fastembed_adapter.rb
 - lib/claude_memory/embeddings/generator.rb
+- lib/claude_memory/embeddings/inspector.rb
+- lib/claude_memory/embeddings/model_registry.rb
+- lib/claude_memory/embeddings/resolver.rb
 - lib/claude_memory/embeddings/similarity.rb
 - lib/claude_memory/hook/context_injector.rb
+- lib/claude_memory/hook/distillation_runner.rb
 - lib/claude_memory/hook/error_classifier.rb
 - lib/claude_memory/hook/exit_codes.rb
 - lib/claude_memory/hook/handler.rb
@@ -240,22 +267,34 @@ files:
 - lib/claude_memory/ingest/transcript_reader.rb
 - lib/claude_memory/logging/logger.rb
 - lib/claude_memory/mcp/error_classifier.rb
+- lib/claude_memory/mcp/handlers/context_handlers.rb
+- lib/claude_memory/mcp/handlers/management_handlers.rb
+- lib/claude_memory/mcp/handlers/query_handlers.rb
+- lib/claude_memory/mcp/handlers/setup_handlers.rb
+- lib/claude_memory/mcp/handlers/shortcut_handlers.rb
+- lib/claude_memory/mcp/handlers/stats_handlers.rb
 - lib/claude_memory/mcp/instructions_builder.rb
 - lib/claude_memory/mcp/query_guide.rb
 - lib/claude_memory/mcp/response_formatter.rb
 - lib/claude_memory/mcp/server.rb
 - lib/claude_memory/mcp/setup_status_analyzer.rb
+- lib/claude_memory/mcp/telemetry.rb
 - lib/claude_memory/mcp/text_summary.rb
 - lib/claude_memory/mcp/tool_definitions.rb
 - lib/claude_memory/mcp/tool_helpers.rb
 - lib/claude_memory/mcp/tools.rb
 - lib/claude_memory/publish.rb
 - lib/claude_memory/recall.rb
+- lib/claude_memory/recall/dual_engine.rb
 - lib/claude_memory/recall/dual_query_template.rb
 - lib/claude_memory/recall/expansion_detector.rb
+- lib/claude_memory/recall/legacy_engine.rb
+- lib/claude_memory/recall/query_core.rb
 - lib/claude_memory/resolve/predicate_policy.rb
 - lib/claude_memory/resolve/resolver.rb
 - lib/claude_memory/shortcuts.rb
+- lib/claude_memory/store/retry_handler.rb
+- lib/claude_memory/store/schema_manager.rb
 - lib/claude_memory/store/sqlite_store.rb
 - lib/claude_memory/store/store_manager.rb
 - lib/claude_memory/sweep/maintenance.rb
@@ -296,5 +335,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: Long-term, self-managed memory for Claude Code
+summary: Long-term memory for Claude Code — architecture recall, convention enforcement,
+  decision tracking
 test_files: []