claude_memory 0.5.1 → 0.6.0

data/lib/claude_memory/commands/initializers/global_initializer.rb

@@ -14,17 +14,27 @@ module ClaudeMemory
         def initialize_memory
           @stdout.puts "Initializing ClaudeMemory (global only)...\n\n"
 
+          if plugin_mode?
+            @stdout.puts "(Plugin mode detected — hooks and MCP managed by plugin)\n\n"
+          end
+
           # Check for existing hooks in global settings
-          hooks_config = HooksConfigurator.new(@stdout)
-          global_settings = File.join(Dir.home, ".claude", "settings.json")
-          if hooks_config.has_claude_memory_hooks?(global_settings)
-            handle_existing_hooks(hooks_config, global_settings)
-            return 0 if @skip_initialization
+          unless plugin_mode?
+            hooks_config = HooksConfigurator.new(@stdout)
+            global_settings = File.join(Dir.home, ".claude", "settings.json")
+            if hooks_config.has_claude_memory_hooks?(global_settings)
+              handle_existing_hooks(hooks_config, global_settings)
+              return 0 if @skip_initialization
+            end
           end
 
           ensure_database
-          configure_hooks unless @skip_hooks
-          configure_mcp
+
+          unless plugin_mode?
+            configure_hooks unless @skip_hooks
+            configure_mcp
+          end
+
           configure_memory_instructions
 
           print_completion_message
@@ -74,9 +84,18 @@ module ClaudeMemory
           MemoryInstructionsWriter.new(@stdout).write_global_instructions
         end
 
+        def plugin_mode?
+          ENV.key?("CLAUDE_PLUGIN_ROOT")
+        end
+
         def print_completion_message
           @stdout.puts "\n=== Global Setup Complete ===\n"
           @stdout.puts "ClaudeMemory is now configured globally."
+
+          if plugin_mode?
+            @stdout.puts "\nPlugin mode: hooks and MCP are managed by the plugin."
+          end
+
           @stdout.puts "\nNote: Run 'claude-memory init' in each project for project-specific memory."
         end
       end

data/lib/claude_memory/commands/initializers/project_initializer.rb

@@ -16,19 +16,29 @@ module ClaudeMemory
         def initialize_memory
           @stdout.puts "Initializing ClaudeMemory (project-local)...\n\n"
 
+          if plugin_mode?
+            @stdout.puts "(Plugin mode detected — hooks, MCP, and output style managed by plugin)\n\n"
+          end
+
           # Check for existing hooks and offer options
-          hooks_config = HooksConfigurator.new(@stdout)
-          if hooks_config.has_claude_memory_hooks?(".claude/settings.json")
-            handle_existing_hooks(hooks_config)
-            return 0 if @skip_initialization
+          unless plugin_mode?
+            hooks_config = HooksConfigurator.new(@stdout)
+            if hooks_config.has_claude_memory_hooks?(".claude/settings.json")
+              handle_existing_hooks(hooks_config)
+              return 0 if @skip_initialization
+            end
           end
 
           ensure_databases
           ensure_directories
-          configure_hooks unless @skip_hooks
-          configure_mcp
+
+          unless plugin_mode?
+            configure_hooks unless @skip_hooks
+            configure_mcp
+            install_output_style
+          end
+
           configure_memory_instructions
-          install_output_style
 
           print_completion_message
           0
@@ -93,17 +103,30 @@ module ClaudeMemory
           @stdout.puts "✓ Installed output style at #{style_dest}"
         end
 
+        def plugin_mode?
+          ENV.key?("CLAUDE_PLUGIN_ROOT")
+        end
+
         def print_completion_message
           @stdout.puts "\n=== Setup Complete ===\n"
           @stdout.puts "ClaudeMemory is now configured for this project."
           @stdout.puts "\nDatabases:"
           @stdout.puts "  Global: ~/.claude/memory.sqlite3 (user-wide knowledge)"
           @stdout.puts "  Project: .claude/memory.sqlite3 (project-specific)"
-          @stdout.puts "\nNext steps:"
-          @stdout.puts "  1. Restart Claude Code to load the new configuration"
-          @stdout.puts "  2. Use Claude Code normally - transcripts will be ingested automatically"
-          @stdout.puts "  3. Run 'claude-memory promote <fact_id>' to move facts to global"
-          @stdout.puts "  4. Run 'claude-memory doctor' to verify setup"
+
+          if plugin_mode?
+            @stdout.puts "\nPlugin mode: hooks, MCP, and output style are managed by the plugin."
+            @stdout.puts "\nNext steps:"
+            @stdout.puts "  1. Use Claude Code normally - transcripts will be ingested automatically"
+            @stdout.puts "  2. Run 'claude-memory promote <fact_id>' to move facts to global"
+            @stdout.puts "  3. Run 'claude-memory doctor' to verify setup"
+          else
+            @stdout.puts "\nNext steps:"
+            @stdout.puts "  1. Restart Claude Code to load the new configuration"
+            @stdout.puts "  2. Use Claude Code normally - transcripts will be ingested automatically"
+            @stdout.puts "  3. Run 'claude-memory promote <fact_id>' to move facts to global"
+            @stdout.puts "  4. Run 'claude-memory doctor' to verify setup"
+          end
         end
       end
     end

data/lib/claude_memory/commands/registry.rb

@@ -27,7 +27,9 @@ module ClaudeMemory
         "serve-mcp" => "ServeMcpCommand",
         "hook" => "HookCommand",
         "index" => "IndexCommand",
-        "recover" => "RecoverCommand"
+        "recover" => "RecoverCommand",
+        "compact" => "CompactCommand",
+        "export" => "ExportCommand"
       }.freeze
 
       # Find a command class by name

data/lib/claude_memory/hook/context_injector.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Hook
+    # Generates context for SessionStart hook injection.
+    # Queries both global and project databases for key facts
+    # and formats them as concise context for Claude.
+    class ContextInjector
+      MAX_DECISIONS = 5
+      MAX_CONVENTIONS = 5
+      MAX_ARCHITECTURE = 5
+
+      QUERIES = {
+        decisions: {query: "decision constraint rule requirement", scope: "all"},
+        conventions: {query: "convention style format pattern prefer", scope: "all"},
+        architecture: {query: "uses framework implements architecture pattern", scope: "all"}
+      }.freeze
+
+      def initialize(manager)
+        @manager = manager
+        @recall = Recall.new(manager)
+      end
+
+      def generate_context
+        sections = []
+
+        decisions = fetch(:decisions, MAX_DECISIONS)
+        sections << format_section("Decisions", decisions) if decisions.any?
+
+        conventions = fetch(:conventions, MAX_CONVENTIONS)
+        sections << format_section("Conventions", conventions) if conventions.any?
+
+        architecture = fetch(:architecture, MAX_ARCHITECTURE)
+        sections << format_section("Architecture", architecture) if architecture.any?
+
+        return nil if sections.empty?
+
+        sections.join("\n")
+      end
+
+      private
+
+      def fetch(category, limit)
+        config = QUERIES.fetch(category)
+        results = @recall.query(config[:query], limit: limit, scope: config[:scope])
+        results.map { |r| format_fact(r[:fact]) }
+      rescue => _e
+        []
+      end
+
+      def format_fact(fact)
+        return nil unless fact
+
+        subject = fact[:subject_name] || fact[:subject_entity_id]
+        predicate = fact[:predicate]
+        object = fact[:object_literal]
+
+        if subject && predicate && object
+          "#{subject}.#{predicate} = #{object}"
+        elsif object
+          object.to_s
+        end
+      end
+
+      def format_section(title, items)
+        items = items.compact.uniq
+        return nil if items.empty?
+
+        lines = ["## #{title}"]
+        items.each { |item| lines << "- #{item}" }
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/claude_memory/hook/error_classifier.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Hook
+    # Classifies hook errors into transport/infrastructure failures
+    # vs client/programming bugs to determine exit code behavior.
+    #
+    # Transport errors (exit 0): Infrastructure failures that shouldn't
+    # block Claude Code sessions. Memory is optional — degrade gracefully.
+    #
+    # Client errors (exit 2): Programming bugs or invalid input that
+    # developers should see and fix.
+    #
+    # Source: claude-mem hook-command.ts:26-66
+    module ErrorClassifier
+      # Infrastructure/transport error class names — resolved lazily
+      # to avoid load-order dependency on Sequel
+      TRANSPORT_ERROR_NAMES = %w[
+        Sequel::DatabaseConnectionError
+        Sequel::DatabaseError
+      ].freeze
+
+      TRANSPORT_ERROR_CLASSES = [
+        Errno::EACCES,
+        Errno::ENOSPC,
+        Errno::EISDIR,
+        Errno::EROFS,
+        IOError
+      ].freeze
+
+      # Client/programming error classes — surface to developer
+      CLIENT_ERROR_CLASSES = [
+        Handler::PayloadError,
+        JSON::ParserError,
+        TypeError,
+        NoMethodError,
+        ArgumentError
+      ].freeze
+
+      module_function
+
+      # Returns true for infrastructure failures that should not block sessions
+      def transport_error?(error)
+        TRANSPORT_ERROR_CLASSES.any? { |klass| error.is_a?(klass) } ||
+          TRANSPORT_ERROR_NAMES.any? { |name| error.class.ancestors.any? { |a| a.name == name } }
+      end
+
+      # Returns true for programming bugs that developers should fix
+      def client_error?(error)
+        CLIENT_ERROR_CLASSES.any? { |klass| error.is_a?(klass) }
+      end
+
+      # Returns the appropriate exit code for an error
+      def exit_code_for(error)
+        if transport_error?(error)
+          ExitCodes::SUCCESS
+        elsif client_error?(error)
+          ExitCodes::ERROR
+        else
+          # Unknown errors default to graceful degradation —
+          # memory should never block Claude Code sessions
+          ExitCodes::SUCCESS
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/hook/handler.rb

@@ -7,8 +7,9 @@ module ClaudeMemory
 
       DEFAULT_SWEEP_BUDGET = 5
 
-      def initialize(store, env: ENV)
+      def initialize(store, env: ENV, manager: nil)
         @store = store
+        @manager = manager
         @config = Configuration.new(env)
         @env = env
       end
@@ -50,6 +51,25 @@ module ClaudeMemory
         publisher = Publish.new(@store)
         publisher.publish!(mode: mode, since: since, rules_dir: rules_dir)
       end
+
+      def context(payload)
+        manager = @manager || build_manager(payload)
+        manager.ensure_both!
+
+        injector = ContextInjector.new(manager)
+        context_text = injector.generate_context
+
+        {status: :ok, context: context_text}
+      rescue => e
+        {status: :error, context: nil, message: e.message}
+      end
+
+      private
+
+      def build_manager(payload)
+        project_path = payload["project_path"] || @config.project_dir
+        Store::StoreManager.new(project_path: project_path, env: @env)
+      end
     end
   end
 end

data/lib/claude_memory/index/vector_index.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Index
+    # Native sqlite-vec KNN search wrapper
+    # Follows the same lazy-init pattern as LexicalFTS:
+    # the extension and virtual table are created on first use.
+    class VectorIndex
+      EMBEDDING_DIMENSIONS = 384
+
+      def initialize(store)
+        @store = store
+        @db = store.db
+        @available = nil
+        @vec_table_ensured = false
+      end
+
+      # Is the sqlite-vec extension loadable?
+      # Caches the result after the first probe.
+      def available?
+        return @available unless @available.nil?
+
+        @available = load_extension!
+      end
+
+      # Insert (or replace) a fact's embedding into the vec0 virtual table.
+      # Also sets vec_indexed_at on the fact row.
+      # @param fact_id [Integer]
+      # @param vector [Array<Float>] 384-dimensional embedding
+      def insert_embedding(fact_id, vector)
+        return false unless available?
+
+        ensure_vec_table!
+        blob = vector.pack("f*")
+        # vec0 doesn't support INSERT OR REPLACE; delete first
+        execute_with_params("DELETE FROM facts_vec WHERE fact_id = ?", fact_id)
+        execute_with_params(
+          "INSERT INTO facts_vec(fact_id, embedding) VALUES (?, ?)",
+          fact_id, blob
+        )
+        @store.facts.where(id: fact_id).update(vec_indexed_at: Time.now.utc.iso8601)
+        true
+      end
+
+      # Remove a fact's embedding from the vec0 virtual table.
+      # Also clears vec_indexed_at on the fact row.
+      # @param fact_id [Integer]
+      def remove_embedding(fact_id)
+        return false unless available?
+
+        ensure_vec_table!
+        @db[:facts_vec].where(fact_id: fact_id).delete
+        @store.facts.where(id: fact_id).update(vec_indexed_at: nil)
+        true
+      end
+
+      # KNN search: returns fact_ids + distances, caller hydrates facts
+      # Two-step query pattern (no JOINs with vec0).
+      # @param query_vector [Array<Float>]
+      # @param k [Integer] number of nearest neighbors
+      # @return [Array<Hash>] [{fact_id:, distance:, similarity:}, ...]
+      def search(query_vector, k: 10)
+        return [] unless available?
+
+        ensure_vec_table!
+        blob = query_vector.pack("f*")
+
+        rows = @db.synchronize do |conn|
+          conn.query(
+            "SELECT fact_id, distance FROM facts_vec WHERE embedding MATCH ? AND k = ? ORDER BY distance",
+            [blob, k]
+          )
+        end
+
+        rows.map do |row|
+          {
+            fact_id: row[:fact_id],
+            distance: row[:distance],
+            similarity: (1.0 - row[:distance]).clamp(0.0, 1.0)
+          }
+        end
+      end
+
+      # Backfill facts that have embedding_json but haven't been indexed in vec0
+      # @param limit [Integer] max facts to process per call
+      # @return [Integer] number of facts backfilled
+      def backfill_batch!(limit: 100)
+        return 0 unless available?
+
+        ensure_vec_table!
+        rows = @store.facts
+          .where(vec_indexed_at: nil)
+          .where(Sequel.~(embedding_json: nil))
+          .where(status: "active")
+          .select(:id, :embedding_json)
+          .order(:id)
+          .limit(limit)
+          .all
+
+        return 0 if rows.empty?
+
+        now = Time.now.utc.iso8601
+        indexed_ids = []
+
+        rows.each do |row|
+          vector = JSON.parse(row[:embedding_json])
+          blob = vector.pack("f*")
+          # No DELETE needed: vec_indexed_at is nil so these rows can't be in vec0
+          execute_with_params(
+            "INSERT INTO facts_vec(fact_id, embedding) VALUES (?, ?)",
+            row[:id], blob
+          )
+          indexed_ids << row[:id]
+        rescue JSON::ParserError
+          next
+        end
+
+        # Batch-update timestamps
+        @store.facts.where(id: indexed_ids).update(vec_indexed_at: now) if indexed_ids.any?
+
+        indexed_ids.size
+      end
+
+      # Number of entries in the vec0 virtual table
+      def count
+        return 0 unless available?
+
+        ensure_vec_table!
+        @db[:facts_vec].count
+      end
+
+      # Coverage statistics for vec indexing
+      # @return [Hash] {with_embedding:, vec_indexed:, coverage_pct:}
+      def coverage_stats
+        with_embedding = @store.facts.where(Sequel.~(embedding_json: nil)).where(status: "active").count
+        vec_indexed = @store.facts.where(Sequel.~(vec_indexed_at: nil)).where(status: "active").count
+        coverage_pct = (with_embedding > 0) ? (vec_indexed * 100.0 / with_embedding).round(1) : 0
+
+        {with_embedding: with_embedding, vec_indexed: vec_indexed, coverage_pct: coverage_pct}
+      end
+
+      private
+
+      # Execute parameterized SQL via the raw Extralite connection
+      # Sequel's db.run doesn't support bind params with Extralite
+      def execute_with_params(sql, *params)
+        @db.synchronize { |conn| conn.execute(sql, params) }
+      end
+
+      def load_extension!
+        require "sqlite_vec"
+        @db.synchronize do |conn|
+          SqliteVec.load(conn)
+        end
+        true
+      rescue LoadError, StandardError
+        false
+      end
+
+      def ensure_vec_table!
+        return if @vec_table_ensured
+
+        @db.run(<<~SQL)
+          CREATE VIRTUAL TABLE IF NOT EXISTS facts_vec
+          USING vec0(fact_id INTEGER PRIMARY KEY, embedding float[#{EMBEDDING_DIMENSIONS}] distance_metric=cosine)
+        SQL
+        @vec_table_ensured = true
+      end
+    end
+  end
+end

data/lib/claude_memory/infrastructure/schema_validator.rb

@@ -21,6 +21,9 @@ module ClaudeMemory
         operation_progress: %i[id operation_type scope status started_at]
       }.freeze
 
+      # sqlite-vec virtual table prefix; all internal tables (chunks, rowids, etc.) share this
+      VEC_TABLE_PREFIX = "facts_vec"
+
       CRITICAL_INDEXES = %i[
         idx_facts_predicate idx_facts_subject idx_facts_status idx_facts_scope
         idx_facts_project idx_provenance_fact idx_content_items_session
@@ -184,9 +187,10 @@ module ClaudeMemory
         now = Time.now.utc.iso8601
         version = @store.schema_version
 
-        # Get table counts for snapshot
+        # Get table counts for snapshot (skip virtual tables that need extensions)
         table_counts = {}
         @store.db.tables.each do |table|
+          next if table.to_s.start_with?(VEC_TABLE_PREFIX)
           table_counts[table.to_s] = @store.db[table].count
         end
 

data/lib/claude_memory/ingest/ingester.rb

@@ -5,13 +5,14 @@ require "digest"
 module ClaudeMemory
   module Ingest
     class Ingester
-      def initialize(store, fts: nil, env: ENV, metadata_extractor: nil, tool_extractor: nil, tool_filter: nil)
+      def initialize(store, fts: nil, env: ENV, metadata_extractor: nil, tool_extractor: nil, tool_filter: nil, observation_compressor: nil)
         @store = store
         @fts = fts || Index::LexicalFTS.new(store)
         @config = Configuration.new(env)
         @metadata_extractor = metadata_extractor || MetadataExtractor.new
         @tool_extractor = tool_extractor || ToolExtractor.new
         @tool_filter = tool_filter || ToolFilter.new
+        @observation_compressor = observation_compressor || ObservationCompressor.new
       end
 
       def ingest(source:, session_id:, transcript_path:, project_path: nil)
@@ -22,6 +23,7 @@ module ClaudeMemory
 
         prepared = prepare_delta(session_id, transcript_path, project_path)
         return {status: :no_change, bytes_read: 0} if prepared.nil?
+        return {status: :skipped, bytes_read: 0, reason: "session_excluded"} if prepared == :excluded
 
         content_id = persist_content(source, session_id, transcript_path, prepared)
 
@@ -31,13 +33,25 @@ module ClaudeMemory
 
       private
 
+      # Tags that cause the entire delta to be skipped when present.
+      # Different from ContentSanitizer which strips tag content but keeps the rest.
+      EXCLUSION_TAGS = %w[no-memory private].freeze
+
       def prepare_delta(session_id, transcript_path, project_path)
         current_offset = @store.get_delta_cursor(session_id, transcript_path) || 0
         delta, new_offset = TranscriptReader.read_delta(transcript_path, current_offset)
         return nil if delta.nil?
 
+        # Skip entire delta if session exclusion markers are present
+        if session_excluded?(delta)
+          # Advance cursor so we don't re-check this content
+          @store.update_delta_cursor(session_id, transcript_path, new_offset)
+          return :excluded
+        end
+
         metadata = @metadata_extractor.extract(delta)
         tool_calls = @tool_filter.filter(@tool_extractor.extract(delta))
+        tool_calls = compress_tool_calls(tool_calls)
         delta = ContentSanitizer.strip_tags(delta)
 
         {
@@ -128,6 +142,13 @@ module ClaudeMemory
         end
       end
 
+      def compress_tool_calls(tool_calls)
+        tool_calls.map do |tc|
+          summary = @observation_compressor.compress(tc[:tool_name], tc[:tool_input])
+          tc.merge(compressed_summary: summary)
+        end
+      end
+
       def should_ingest?(transcript_path)
         return true unless File.exist?(transcript_path)
 
@@ -140,6 +161,10 @@ module ClaudeMemory
         existing.nil?
       end
 
+      def session_excluded?(text)
+        EXCLUSION_TAGS.any? { |tag| text.include?("<#{tag}>") }
+      end
+
       def detect_project_path
         @config.project_dir
       end