claude_memory 0.5.0 → 0.6.0

data/lib/claude_memory/recall.rb

@@ -499,7 +499,8 @@ module ClaudeMemory
       results = template.execute(scope: scope, limit: limit) do |store, source|
         query_semantic_single(store, text, limit: limit * 3, mode: mode, source: source)
       end
-      dedupe_and_sort(results, limit)
+      # Use similarity-preserving dedupe (not source/time sort) to keep RRF ordering
+      Core::FactRanker.dedupe_by_fact_id(results, limit)
     end
 
     def query_semantic_legacy(text, limit:, scope:, mode:)
@@ -529,6 +530,33 @@ module ClaudeMemory
       # Generate query embedding
       query_embedding = @embedding_generator.generate(query_text)
 
+      # Fast path: use sqlite-vec KNN when available
+      vec_index = store.vector_index
+      if vec_index.available?
+        return search_by_vector_native(store, vec_index, query_embedding, limit, source)
+      end
+
+      # Fallback: JSON + Ruby cosine similarity
+      search_by_vector_fallback(store, query_embedding, limit, source)
+    end
+
+    def search_by_vector_native(store, vec_index, query_embedding, limit, source)
+      matches = vec_index.search(query_embedding, k: limit)
+      return [] if matches.empty?
+
+      fact_ids = matches.map { |m| m[:fact_id] }
+      facts_by_id = batch_find_facts(store, fact_ids)
+      receipts_by_fact_id = batch_find_receipts(store, fact_ids)
+
+      Core::ResultBuilder.build_results_with_scores(
+        matches,
+        facts_by_id: facts_by_id,
+        receipts_by_fact_id: receipts_by_fact_id,
+        source: source
+      )
+    end
+
+    def search_by_vector_fallback(store, query_embedding, limit, source)
       # Load facts with embeddings
       facts_data = store.facts_with_embeddings(limit: 5000)
       return [] if facts_data.empty?
@@ -556,33 +584,59 @@ module ClaudeMemory
     end
 
     def search_by_fts(store, query_text, limit, source)
-      # Use existing FTS search infrastructure
       fts = Index::LexicalFTS.new(store)
-      content_ids = fts.search(query_text, limit: limit * 2)
+      ranked_results = fts.search_with_ranks(query_text, limit: limit * 2)
 
-      return [] if content_ids.empty?
+      return [] if ranked_results.empty?
 
-      # Find facts from content items
-      fact_ids = store.provenance
+      content_ids = ranked_results.map { |r| r[:content_item_id] }
+
+      # Map content_item_ids to fact_ids, preserving FTS rank order
+      provenance_rows = store.provenance
         .where(content_item_id: content_ids)
-        .select(:fact_id)
-        .distinct
-        .map { |row| row[:fact_id] }
+        .select(:fact_id, :content_item_id)
+        .all
 
-      return [] if fact_ids.empty?
+      content_to_facts = provenance_rows.group_by { |r| r[:content_item_id] }
+
+      # Build ordered fact list with normalized BM25 scores
+      # FTS5 rank values are negative (more negative = better match)
+      ranks = ranked_results.map { |r| r[:rank] }
+      min_rank = ranks.min # Most negative = best
+      max_rank = ranks.max # Least negative = worst
+      range = (max_rank - min_rank).abs
+
+      seen_fact_ids = Set.new
+      scored_matches = []
+
+      ranked_results.each do |r|
+        similarity = if range > 0
+          # Normalize: best rank → 1.0, worst rank → 0.1
+          0.1 + 0.9 * ((max_rank - r[:rank]).abs / range)
+        else
+          0.8 # Single result gets a reasonable score
+        end
 
-      # Batch fetch facts
+        fact_ids = content_to_facts[r[:content_item_id]]&.map { |p| p[:fact_id] } || []
+        fact_ids.each do |fid|
+          next if seen_fact_ids.include?(fid)
+          seen_fact_ids.add(fid)
+          scored_matches << {fact_id: fid, similarity: similarity}
+        end
+      end
+
+      return [] if scored_matches.empty?
+
+      fact_ids = scored_matches.map { |m| m[:fact_id] }
       facts_by_id = batch_find_facts(store, fact_ids)
       receipts_by_fact_id = batch_find_receipts(store, fact_ids)
 
-      results = Core::ResultBuilder.build_results(
-        fact_ids,
+      Core::ResultBuilder.build_results_with_scores(
+        scored_matches,
         facts_by_id: facts_by_id,
         receipts_by_fact_id: receipts_by_fact_id,
-        source: source,
-        similarity: 0.5  # Default score for FTS results
-      )
-      results.take(limit)
+        source: source
+      ).take(limit)
     end
 
     def merge_search_results(vector_results, text_results, limit)

data/lib/claude_memory/store/sqlite_store.rb

@@ -10,7 +10,7 @@ require "sequel/adapters/extralite"
 module ClaudeMemory
   module Store
     class SQLiteStore
-      SCHEMA_VERSION = 10
+      SCHEMA_VERSION = 12
 
       attr_reader :db
 
@@ -21,17 +21,65 @@ module ClaudeMemory
         ensure_schema!
       end
 
+      # Retry configuration for database operations
+      # SQLite's busy_timeout doesn't reliably detect lock release, so we use
+      # shorter timeouts with application-level retry for better responsiveness
+      MAX_RETRIES = 5
+      RETRY_BASE_DELAY = 0.1 # seconds, with exponential backoff
+
+      # Execute a block with retry logic for busy/locked errors
+      # This handles concurrent access from multiple hook processes
+      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) # Exponential backoff
+            sleep(delay)
+            retry
+          end
+          raise
+        end
+      end
+
+      # Execute a transaction with retry logic for concurrent access
+      # Use this instead of @db.transaction when concurrent writes are expected
+      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)
-        Sequel.connect(
-          "extralite:#{db_path}",
-          connect_sqls: [
-            "PRAGMA journal_mode = WAL",
-            "PRAGMA synchronous = NORMAL",
-            "PRAGMA busy_timeout = 30000"
-          ]
-        )
+        retries = 0
+        begin
+          Sequel.connect(
+            "extralite:#{db_path}",
+            # Use shorter busy_timeout since we handle retry at app level
+            # This allows faster detection of lock release between retries
+            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
 
       public
@@ -40,6 +88,10 @@ module ClaudeMemory
         @db.disconnect
       end
 
+      def vector_index
+        @vector_index ||= Index::VectorIndex.new(self)
+      end
+
       # Checkpoint the WAL file to prevent unlimited growth
       # This truncates the WAL after checkpointing
       # Should be called periodically during maintenance/sweep operations
@@ -106,27 +158,29 @@ module ClaudeMemory
       def upsert_content_item(source:, text_hash:, byte_len:, session_id: nil, transcript_path: nil,
         project_path: nil, occurred_at: nil, raw_text: nil, metadata: nil,
         git_branch: nil, cwd: nil, claude_version: nil, thinking_level: nil, source_mtime: nil)
-        existing = content_items.where(text_hash: text_hash, session_id: session_id).get(:id)
-        return existing if existing
+        with_retry("upsert_content_item") do
+          existing = content_items.where(text_hash: text_hash, session_id: session_id).get(:id)
+          return existing if existing
 
-        now = Time.now.utc.iso8601
-        content_items.insert(
-          source: source,
-          session_id: session_id,
-          transcript_path: transcript_path,
-          project_path: project_path,
-          occurred_at: occurred_at || now,
-          ingested_at: now,
-          text_hash: text_hash,
-          byte_len: byte_len,
-          raw_text: raw_text,
-          metadata_json: metadata&.to_json,
-          git_branch: git_branch,
-          cwd: cwd,
-          claude_version: claude_version,
-          thinking_level: thinking_level,
-          source_mtime: source_mtime
-        )
+          now = Time.now.utc.iso8601
+          content_items.insert(
+            source: source,
+            session_id: session_id,
+            transcript_path: transcript_path,
+            project_path: project_path,
+            occurred_at: occurred_at || now,
+            ingested_at: now,
+            text_hash: text_hash,
+            byte_len: byte_len,
+            raw_text: raw_text,
+            metadata_json: metadata&.to_json,
+            git_branch: git_branch,
+            cwd: cwd,
+            claude_version: claude_version,
+            thinking_level: thinking_level,
+            source_mtime: source_mtime
+          )
+        end
       end
 
       def content_item_by_transcript_and_mtime(transcript_path, mtime_iso8601)
@@ -142,6 +196,7 @@ module ClaudeMemory
             tool_name: tc[:tool_name],
             tool_input: tc[:tool_input],
             tool_result: tc[:tool_result],
+            compressed_summary: tc[:compressed_summary],
             is_error: tc[:is_error] || false,
             timestamp: tc[:timestamp]
           )
@@ -412,6 +467,12 @@ module ClaudeMemory
         # 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)
 
@@ -451,6 +512,11 @@ module ClaudeMemory
         end
       end
 
+      def current_schema_version
+        return nil unless @db.table_exists?(:schema_info)
+        @db[:schema_info].get(:version)
+      end
+
       def set_meta(key, value)
         @db[:meta].insert_conflict(target: :key, update: {value: value}).insert(key: key, value: value)
       end

data/lib/claude_memory/sweep/sweeper.rb

@@ -31,6 +31,8 @@ module ClaudeMemory
         expire_disputed_facts if within_budget?
         prune_orphaned_provenance if within_budget?
         prune_old_content if within_budget?
+        backfill_vec_index if within_budget?
+        cleanup_vec_expired if within_budget?
         checkpoint_wal if within_budget?
 
         @stats[:elapsed_seconds] = Time.now - @start_time
@@ -83,6 +85,34 @@ module ClaudeMemory
           .delete
       end
 
+      def with_vec_index
+        vec_index = @store.vector_index
+        return unless vec_index.available?
+        yield vec_index
+      end
+
+      def backfill_vec_index
+        with_vec_index do |vec_index|
+          @stats[:vec_backfilled] = vec_index.backfill_batch!(limit: 100)
+        end
+      end
+
+      def cleanup_vec_expired
+        with_vec_index do |vec_index|
+          # Remove vec0 entries for superseded/expired facts
+          # (remove_embedding manages vec_indexed_at)
+          stale_ids = @store.facts
+            .where(status: %w[superseded expired])
+            .where(Sequel.~(vec_indexed_at: nil))
+            .select(:id)
+            .limit(100)
+            .map { |r| r[:id] }
+
+          stale_ids.each { |fact_id| vec_index.remove_embedding(fact_id) }
+          @stats[:vec_cleaned] = stale_ids.size
+        end
+      end
+
       def checkpoint_wal
         @store.checkpoint_wal
         @stats[:wal_checkpointed] = true

data/lib/claude_memory/version.rb

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

data/lib/claude_memory.rb

@@ -31,6 +31,7 @@ require_relative "claude_memory/commands/checks/snapshot_check"
 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/help_command"
 require_relative "claude_memory/commands/version_command"
 require_relative "claude_memory/commands/doctor_command"
@@ -57,6 +58,8 @@ require_relative "claude_memory/commands/serve_mcp_command"
 require_relative "claude_memory/commands/hook_command"
 require_relative "claude_memory/commands/index_command"
 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/registry"
 require_relative "claude_memory/cli"
 require_relative "claude_memory/configuration"
@@ -69,15 +72,19 @@ require_relative "claude_memory/domain/provenance"
 require_relative "claude_memory/domain/conflict"
 require_relative "claude_memory/embeddings/generator"
 require_relative "claude_memory/embeddings/similarity"
+require_relative "claude_memory/hook/context_injector"
 require_relative "claude_memory/hook/exit_codes"
 require_relative "claude_memory/hook/handler"
+require_relative "claude_memory/hook/error_classifier"
 require_relative "claude_memory/index/query_options"
 require_relative "claude_memory/index/index_query_logic"
 require_relative "claude_memory/index/index_query"
 require_relative "claude_memory/index/lexical_fts"
+require_relative "claude_memory/index/vector_index"
 require_relative "claude_memory/ingest/privacy_tag"
 require_relative "claude_memory/ingest/content_sanitizer"
 require_relative "claude_memory/ingest/metadata_extractor"
+require_relative "claude_memory/ingest/observation_compressor"
 require_relative "claude_memory/ingest/tool_extractor"
 require_relative "claude_memory/ingest/tool_filter"
 require_relative "claude_memory/ingest/ingester"
@@ -87,6 +94,7 @@ require_relative "claude_memory/infrastructure/file_system"
 require_relative "claude_memory/infrastructure/in_memory_file_system"
 require_relative "claude_memory/infrastructure/operation_tracker"
 require_relative "claude_memory/infrastructure/schema_validator"
+require_relative "claude_memory/mcp/instructions_builder"
 require_relative "claude_memory/mcp/query_guide"
 require_relative "claude_memory/mcp/text_summary"
 require_relative "claude_memory/mcp/tool_helpers"

data/scripts/hook-runner.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Generic hook delegate for claude-memory.
+# Used by the Claude Code plugin to run hook subcommands.
+# Usage: hook-runner.sh <subcommand> [args...]
+# Exit 0 on missing binary to avoid blocking Claude Code.
+
+set -uo pipefail
+
+if command -v claude-memory > /dev/null 2>&1; then
+  exec claude-memory hook "$@"
+else
+  echo "claude-memory gem not found. Install with: gem install claude_memory" >&2
+  exit 0
+fi

data/scripts/serve-mcp.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Wrapper script for claude-memory MCP server.
+# Used by the Claude Code plugin to launch the MCP server.
+# Falls back to a JSON-RPC error if the gem is not installed.
+
+set -euo pipefail
+
+if command -v claude-memory > /dev/null 2>&1; then
+  exec claude-memory serve-mcp
+else
+  # Return a JSON-RPC error so Claude Code surfaces it to the user
+  echo '{"jsonrpc":"2.0","id":1,"error":{"code":-32603,"message":"claude-memory gem not found. Install with: gem install claude_memory"}}'
+  exit 1
+fi

data/skills/setup-memory/SKILL.md

@@ -38,12 +38,18 @@ When invoked, it will:
 ### Step 1: Check Installation Status
 
 ```bash
+gem list claude_memory
 claude-memory --version
 claude-memory doctor
 ```
 
 Analyze the output to determine current state.
 
+- If `gem list` shows no `claude_memory` entry, the gem is not installed.
+  Guide the user: `gem install claude_memory`
+- If running in plugin mode (`CLAUDE_PLUGIN_ROOT` is set), hooks and MCP
+  are managed by the plugin — only databases and memory instructions need setup.
+
 ### Step 2: Determine Action Required
 
 - **Not installed**: Databases don't exist

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_memory
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Valentino Stoll
@@ -37,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: sqlite-vec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
 email:
@@ -70,6 +84,7 @@ files:
 - ".claude/skills/study-repo/analysis-template.md"
 - ".claude/skills/study-repo/focus-examples.md"
 - ".lefthook/map_specs.rb"
+- ".mcp.json"
 - ".ruby-version"
 - CHANGELOG.md
 - CLAUDE.md
@@ -91,6 +106,8 @@ files:
 - db/migrations/008_add_provenance_line_range.rb
 - db/migrations/009_add_docid.rb
 - db/migrations/010_add_llm_cache.rb
+- db/migrations/011_add_tool_call_summaries.rb
+- db/migrations/012_add_vec_indexing_support.rb
 - docs/EXAMPLES.md
 - docs/GETTING_STARTED.md
 - docs/RELEASE_NOTES_v0.2.0.md
@@ -106,8 +123,11 @@ files:
 - docs/expert_review.md
 - docs/improvements.md
 - docs/influence/.gitkeep
+- docs/influence/claude-mem.md
 - docs/influence/claude-supermemory.md
+- docs/influence/episodic-memory.md
 - docs/influence/grepai.md
+- docs/influence/kbs.md
 - docs/influence/qmd.md
 - docs/organizational_memory_playbook.md
 - docs/plans/feature_adoption_plan.md
@@ -129,10 +149,13 @@ files:
 - 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/conflicts_command.rb
 - lib/claude_memory/commands/db_init_command.rb
 - lib/claude_memory/commands/doctor_command.rb
 - lib/claude_memory/commands/explain_command.rb
+- lib/claude_memory/commands/export_command.rb
 - lib/claude_memory/commands/help_command.rb
 - lib/claude_memory/commands/hook_command.rb
 - lib/claude_memory/commands/index_command.rb
@@ -188,12 +211,15 @@ files:
 - lib/claude_memory/embeddings/fastembed_adapter.rb
 - lib/claude_memory/embeddings/generator.rb
 - lib/claude_memory/embeddings/similarity.rb
+- lib/claude_memory/hook/context_injector.rb
+- lib/claude_memory/hook/error_classifier.rb
 - lib/claude_memory/hook/exit_codes.rb
 - lib/claude_memory/hook/handler.rb
 - lib/claude_memory/index/index_query.rb
 - lib/claude_memory/index/index_query_logic.rb
 - lib/claude_memory/index/lexical_fts.rb
 - lib/claude_memory/index/query_options.rb
+- lib/claude_memory/index/vector_index.rb
 - lib/claude_memory/infrastructure/file_system.rb
 - lib/claude_memory/infrastructure/in_memory_file_system.rb
 - lib/claude_memory/infrastructure/operation_tracker.rb
@@ -201,11 +227,13 @@ files:
 - lib/claude_memory/ingest/content_sanitizer.rb
 - lib/claude_memory/ingest/ingester.rb
 - lib/claude_memory/ingest/metadata_extractor.rb
+- lib/claude_memory/ingest/observation_compressor.rb
 - lib/claude_memory/ingest/privacy_tag.rb
 - lib/claude_memory/ingest/tool_extractor.rb
 - lib/claude_memory/ingest/tool_filter.rb
 - lib/claude_memory/ingest/transcript_reader.rb
 - lib/claude_memory/logging/logger.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
@@ -228,6 +256,8 @@ files:
 - lib/claude_memory/templates/output-styles/memory-aware.md
 - lib/claude_memory/version.rb
 - output-styles/memory-aware.md
+- scripts/hook-runner.sh
+- scripts/serve-mcp.sh
 - sig/claude_memory.rbs
 - skills/analyze/SKILL.md
 - skills/debug-memory/SKILL.md
@@ -255,7 +285,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.4
+rubygems_version: 4.0.6
 specification_version: 4
 summary: Long-term, self-managed memory for Claude Code
 test_files: []