claude_memory 0.5.1 → 0.6.0

data/hooks/hooks.json

@@ -5,7 +5,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest"
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
+            "timeout": 10
           }
         ]
       }
@@ -15,7 +16,13 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest"
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh context",
+            "timeout": 5
           }
         ]
       }
@@ -25,32 +32,29 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest"
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
+            "timeout": 30
           },
           {
             "type": "command",
-            "command": "claude-memory hook publish"
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh sweep",
+            "timeout": 30
           }
         ]
       }
     ],
-    "Notification": [
+    "SessionEnd": [
       {
-        "matcher": "idle_prompt",
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook sweep"
-          }
-        ]
-      }
-    ],
-    "SessionEnd": [
-      {
-        "hooks": [
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh ingest",
+            "timeout": 30
+          },
           {
             "type": "command",
-            "command": "claude-memory hook publish"
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-runner.sh sweep",
+            "timeout": 30
           }
         ]
       }

data/lefthook.yml

@@ -17,6 +17,10 @@ pre-commit:
         fi
     quality-review:
       run: |
+        if [ -n "$CLAUDECODE" ]; then
+          echo "Inside Claude Code session, skipping quality-review hook (run /review-commit manually)"
+          exit 0
+        fi
         staged_ruby=$(git diff --cached --name-only --diff-filter=ACM | grep '\.rb$' || true)
         if [ -n "$staged_ruby" ]; then
           echo "Running quality review on staged changes..."

data/lib/claude_memory/commands/checks/vec_check.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    module Checks
+      # Checks sqlite-vec extension availability and index coverage
+      class VecCheck
+        def call
+          vec_available = check_vec_availability
+          coverage = check_vec_coverage
+
+          warnings = []
+          unless vec_available
+            warnings << "sqlite-vec extension not available (vector search uses slower JSON fallback)"
+          end
+
+          if vec_available && coverage && coverage[:coverage_pct] < 100 && coverage[:with_embedding] > 0
+            warnings << "Vec index coverage: #{coverage[:coverage_pct]}% (#{coverage[:vec_indexed]}/#{coverage[:with_embedding]} facts). Run 'claude-memory index --vec' to backfill."
+          end
+
+          {
+            status: warnings.any? ? :warning : :ok,
+            label: "sqlite-vec",
+            message: vec_available ? "sqlite-vec available" : "sqlite-vec not available",
+            details: {
+              available: vec_available,
+              coverage: coverage
+            },
+            warnings: warnings
+          }
+        end
+
+        private
+
+        def check_vec_availability
+          require "sqlite_vec"
+          true
+        rescue LoadError
+          false
+        end
+
+        def check_vec_coverage
+          config = Configuration.new
+          totals = {vec_indexed: 0, with_embedding: 0, coverage_pct: 0}
+
+          [config.global_db_path, config.project_db_path].each do |db_path|
+            next unless File.exist?(db_path)
+
+            store = nil
+            begin
+              store = Store::SQLiteStore.new(db_path)
+              stats = store.vector_index.coverage_stats
+              totals[:with_embedding] += stats[:with_embedding]
+              totals[:vec_indexed] += stats[:vec_indexed]
+            rescue => _e
+              next
+            ensure
+              store&.close
+            end
+          end
+
+          totals[:coverage_pct] = if totals[:with_embedding] > 0
+            (totals[:vec_indexed] * 100.0 / totals[:with_embedding]).round(1)
+          else
+            0
+          end
+
+          totals
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/compact_command.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Runs SQLite VACUUM and optional integrity check on memory databases.
+    # Reclaims space from deleted/superseded facts and defragments storage.
+    class CompactCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {scope: "all", check: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory compact [options]"
+            parser.on("--scope SCOPE", %w[all global project],
+              "Scope: all (default), global, or project") { |v| o[:scope] = v }
+            parser.on("--check", "Run integrity check before compacting") { o[:check] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+
+        if opts[:scope] == "all" || opts[:scope] == "global"
+          compact_database("global", manager.global_db_path, check: opts[:check])
+        end
+
+        if opts[:scope] == "all" || opts[:scope] == "project"
+          compact_database("project", manager.project_db_path, check: opts[:check])
+        end
+
+        manager.close
+        0
+      end
+
+      private
+
+      def compact_database(label, db_path, check: false)
+        unless File.exist?(db_path)
+          stdout.puts "#{label}: database not found at #{db_path}"
+          return
+        end
+
+        size_before = File.size(db_path)
+
+        if check
+          stdout.puts "#{label}: running integrity check..."
+          result = run_integrity_check(db_path)
+          unless result == "ok"
+            stderr.puts "#{label}: integrity check failed: #{result}"
+            return
+          end
+          stdout.puts "#{label}: integrity check passed"
+        end
+
+        stdout.puts "#{label}: compacting..."
+        run_vacuum(db_path)
+
+        size_after = File.size(db_path)
+        saved = size_before - size_after
+
+        stdout.puts "#{label}: #{format_size(size_before)} -> #{format_size(size_after)} (#{format_saved(saved)})"
+      end
+
+      def run_vacuum(db_path)
+        store = ClaudeMemory::Store::SQLiteStore.new(db_path)
+        store.db.run("VACUUM")
+        store.close
+      end
+
+      def run_integrity_check(db_path)
+        store = ClaudeMemory::Store::SQLiteStore.new(db_path)
+        result = store.db.fetch("PRAGMA integrity_check").first[:integrity_check]
+        store.close
+        result
+      end
+
+      def format_size(bytes)
+        if bytes >= 1024 * 1024
+          "#{(bytes / (1024.0 * 1024.0)).round(2)} MB"
+        else
+          "#{(bytes / 1024.0).round(1)} KB"
+        end
+      end
+
+      def format_saved(bytes)
+        if bytes > 0
+          "saved #{format_size(bytes)}"
+        elsif bytes == 0
+          "no change"
+        else
+          "grew #{format_size(bytes.abs)}"
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/doctor_command.rb

@@ -20,6 +20,7 @@ module ClaudeMemory
         checks = [
           Checks::DatabaseCheck.new(manager.global_db_path, "global"),
           Checks::DatabaseCheck.new(manager.project_db_path, "project"),
+          Checks::VecCheck.new,
           Checks::SnapshotCheck.new,
           Checks::ClaudeMdCheck.new,
           Checks::HooksCheck.new

data/lib/claude_memory/commands/export_command.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module Commands
+    # Exports facts, entities, and provenance to JSON for backup or migration.
+    # Output goes to stdout (default) or a file via --output.
+    class ExportCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {scope: "project", status: "active", output: nil, pretty: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory export [options]"
+            parser.on("--scope SCOPE", %w[all global project],
+              "Scope: project (default), global, or all") { |v| o[:scope] = v }
+            parser.on("--status STATUS", %w[active all],
+              "Fact status: active (default) or all") { |v| o[:status] = v }
+            parser.on("--output FILE", "Write to file instead of stdout") { |v| o[:output] = v }
+            parser.on("--pretty", "Pretty-print JSON output") { o[:pretty] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        data = build_export(manager, opts[:scope], opts[:status])
+        manager.close
+
+        json = opts[:pretty] ? JSON.pretty_generate(data) : JSON.generate(data)
+
+        if opts[:output]
+          File.write(opts[:output], json)
+          stderr.puts "Exported #{data[:facts].size} facts to #{opts[:output]}"
+        else
+          stdout.puts json
+        end
+
+        0
+      end
+
+      private
+
+      def build_export(manager, scope, status_filter)
+        export = {
+          version: ClaudeMemory::VERSION,
+          exported_at: Time.now.utc.iso8601,
+          scope: scope,
+          entities: [],
+          facts: []
+        }
+
+        if scope == "all" || scope == "global"
+          if manager.global_exists?
+            manager.ensure_global!
+            collect_from_store(manager.global_store, "global", status_filter, export)
+          end
+        end
+
+        if scope == "all" || scope == "project"
+          if manager.project_exists?
+            manager.ensure_project!
+            collect_from_store(manager.project_store, "project", status_filter, export)
+          end
+        end
+
+        export
+      end
+
+      def collect_from_store(store, source_label, status_filter, export)
+        # Collect entities
+        store.entities.each do |entity|
+          export[:entities] << {
+            id: entity[:id],
+            type: entity[:type],
+            name: entity[:canonical_name],
+            source: source_label
+          }
+        end
+
+        # Collect facts with provenance
+        facts_ds = store.facts
+        facts_ds = facts_ds.where(status: "active") if status_filter == "active"
+
+        facts_ds.each do |fact|
+          subject = store.entities.where(id: fact[:subject_entity_id]).first
+          receipts = store.provenance.where(fact_id: fact[:id]).all
+
+          export[:facts] << {
+            id: fact[:id],
+            docid: fact[:docid],
+            subject: subject&.[](:canonical_name),
+            predicate: fact[:predicate],
+            object: fact[:object_literal],
+            status: fact[:status],
+            confidence: fact[:confidence],
+            scope: fact[:scope],
+            valid_from: fact[:valid_from],
+            valid_to: fact[:valid_to],
+            created_at: fact[:created_at],
+            source: source_label,
+            receipts: receipts.map { |r|
+              {quote: r[:quote], strength: r[:strength]}
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/help_command.rb

@@ -12,10 +12,12 @@ module ClaudeMemory
 
           Commands:
             changes    Show recent fact changes
+            compact    Compact databases (VACUUM + integrity check)
             conflicts  Show open conflicts
             db:init    Initialize the SQLite database
             doctor     Check system health
             explain    Explain a fact with receipts
+            export     Export facts to JSON for backup
             help       Show this help message
             hook       Run hook entrypoints (ingest|sweep|publish)
             init       Initialize ClaudeMemory in a project

data/lib/claude_memory/commands/hook_command.rb

@@ -5,25 +5,30 @@ require "json"
 module ClaudeMemory
   module Commands
     # Handles hook entrypoints (ingest, sweep, publish)
+    # Supports --async flag to fork and run in background
     class HookCommand < BaseCommand
+      ASYNC_SUBCOMMANDS = %w[ingest sweep publish].freeze
+
       def call(args)
         subcommand = args.first
 
         unless subcommand
-          stderr.puts "Usage: claude-memory hook <ingest|sweep|publish> [options]"
+          stderr.puts "Usage: claude-memory hook <ingest|sweep|publish|context> [options]"
           stderr.puts "\nReads hook payload JSON from stdin."
+          stderr.puts "Options: --async  Run in background (ingest, sweep, publish only)"
           return Hook::ExitCodes::ERROR
         end
 
-        unless %w[ingest sweep publish].include?(subcommand)
+        unless %w[ingest sweep publish context].include?(subcommand)
           stderr.puts "Unknown hook command: #{subcommand}"
-          stderr.puts "Available: ingest, sweep, publish"
+          stderr.puts "Available: ingest, sweep, publish, context"
           return Hook::ExitCodes::ERROR
         end
 
-        opts = parse_options(args[1..] || [], {db: ClaudeMemory.project_db_path}) do |o|
+        opts = parse_options(args[1..] || [], {db: ClaudeMemory.project_db_path, async: false}) do |o|
           OptionParser.new do |parser|
             parser.on("--db PATH", "Database path") { |v| o[:db] = v }
+            parser.on("--async", "Run in background (non-blocking)") { o[:async] = true }
           end
         end
         return Hook::ExitCodes::ERROR if opts.nil?
@@ -31,6 +36,21 @@ module ClaudeMemory
         payload = parse_hook_payload
         return Hook::ExitCodes::ERROR unless payload
 
+        if opts[:async] && ASYNC_SUBCOMMANDS.include?(subcommand)
+          return run_async(subcommand, payload, opts)
+        end
+
+        execute_sync(subcommand, payload, opts)
+      rescue ClaudeMemory::Hook::Handler::PayloadError => e
+        stderr.puts "Payload error: #{e.message}"
+        Hook::ExitCodes::ERROR
+      rescue => e
+        classify_error(e)
+      end
+
+      private
+
+      def execute_sync(subcommand, payload, opts)
         store = ClaudeMemory::Store::SQLiteStore.new(opts[:db])
         handler = ClaudeMemory::Hook::Handler.new(store)
 
@@ -41,16 +61,52 @@ module ClaudeMemory
           hook_sweep(handler, payload)
         when "publish"
           hook_publish(handler, payload)
+        when "context"
+          hook_context(payload, opts[:db])
         end
 
         store.close
         exit_code
-      rescue ClaudeMemory::Hook::Handler::PayloadError => e
-        stderr.puts "Payload error: #{e.message}"
-        Hook::ExitCodes::ERROR
       end
 
-      private
+      def run_async(subcommand, payload, opts)
+        pid = fork_background(subcommand, payload, opts)
+
+        if pid
+          Process.detach(pid)
+          stdout.puts "Running #{subcommand} in background (pid: #{pid})"
+          Hook::ExitCodes::SUCCESS
+        else
+          stderr.puts "Fork not available, falling back to synchronous execution"
+          execute_sync(subcommand, payload, opts)
+        end
+      end
+
+      def fork_background(subcommand, payload, opts)
+        Process.fork do
+          # Detach from parent I/O
+          $stdin.reopen(File::NULL, "r")
+          $stdout.reopen(File::NULL, "w")
+          $stderr.reopen(File::NULL, "w")
+
+          store = ClaudeMemory::Store::SQLiteStore.new(opts[:db])
+          handler = ClaudeMemory::Hook::Handler.new(store)
+
+          case subcommand
+          when "ingest" then handler.ingest(payload)
+          when "sweep" then handler.sweep(payload)
+          when "publish" then handler.publish(payload)
+          end
+
+          store.close
+        rescue
+          # Background process must not propagate errors
+          nil
+        end
+      rescue NotImplementedError
+        # Process.fork not available (e.g., JRuby)
+        nil
+      end
 
       def parse_hook_payload
         input = stdin.read
@@ -72,9 +128,13 @@ module ClaudeMemory
           Hook::ExitCodes::SUCCESS
         when :skipped
           # Different reasons for skipping have different severity
-          if result[:reason] == "unchanged"
+          case result[:reason]
+          when "unchanged"
             stdout.puts "No new content to ingest"
             Hook::ExitCodes::SUCCESS
+          when "session_excluded"
+            stdout.puts "Session excluded by privacy marker"
+            Hook::ExitCodes::SUCCESS
           else
             # transcript_not_found or other skipped reasons
             stdout.puts "Skipped ingestion: #{result[:reason]}"
@@ -108,6 +168,47 @@ module ClaudeMemory
 
         Hook::ExitCodes::SUCCESS
       end
+
+      def hook_context(payload, db_path)
+        project_path = payload["project_path"] || payload["cwd"]
+        manager = ClaudeMemory::Store::StoreManager.new(
+          project_db_path: db_path,
+          project_path: project_path
+        )
+        manager.ensure_both!
+
+        injector = ClaudeMemory::Hook::ContextInjector.new(manager)
+        context_text = injector.generate_context
+
+        if context_text
+          response = {
+            hookSpecificOutput: {
+              hookEventName: "SessionStart",
+              additionalContext: context_text
+            }
+          }
+          stdout.puts JSON.generate(response)
+        end
+
+        manager.close
+        Hook::ExitCodes::SUCCESS
+      rescue => e
+        classify_error(e)
+      end
+
+      def classify_error(error)
+        exit_code = Hook::ErrorClassifier.exit_code_for(error)
+
+        if exit_code == Hook::ExitCodes::SUCCESS
+          # Transport/infrastructure error — degrade gracefully
+          stderr.puts "Hook degraded gracefully: #{error.class} - #{error.message}"
+        else
+          # Client/programming error — surface to developer
+          stderr.puts "Hook error: #{error.class} - #{error.message}"
+        end
+
+        exit_code
+      end
     end
   end
 end

data/lib/claude_memory/commands/index_command.rb

@@ -9,12 +9,13 @@ module ClaudeMemory
       SCOPE_PROJECT = "project"
 
       def call(args)
-        opts = parse_options(args, {scope: SCOPE_ALL, batch_size: 100, force: false}) do |o|
+        opts = parse_options(args, {scope: SCOPE_ALL, batch_size: 100, force: false, vec: false}) do |o|
           OptionParser.new do |parser|
             parser.banner = "Usage: claude-memory index [options]"
             parser.on("--scope SCOPE", "Scope: global, project, or all (default: all)") { |v| o[:scope] = v }
             parser.on("--batch-size SIZE", Integer, "Batch size (default: 100)") { |v| o[:batch_size] = v }
             parser.on("--force", "Re-index facts that already have embeddings") { o[:force] = true }
+            parser.on("--vec", "Backfill vec0 index from existing embeddings (no regeneration)") { o[:vec] = true }
           end
         end
         return 1 if opts.nil?
@@ -25,14 +26,14 @@ module ClaudeMemory
           return 1
         end
 
-        generator = Embeddings::Generator.new
-
-        if opts[:scope] == SCOPE_ALL || opts[:scope] == SCOPE_GLOBAL
-          index_database("global", Configuration.global_db_path, generator, opts)
+        if opts[:vec]
+          return vec_backfill(opts)
         end
 
-        if opts[:scope] == SCOPE_ALL || opts[:scope] == SCOPE_PROJECT
-          index_database("project", Configuration.project_db_path, generator, opts)
+        generator = Embeddings::Generator.new
+
+        scopes_for(opts[:scope]).each do |label, db_path|
+          index_database(label, db_path, generator, opts)
         end
 
         0
@@ -40,6 +41,13 @@ module ClaudeMemory
 
       private
 
+      def scopes_for(scope)
+        pairs = []
+        pairs << ["global", Configuration.global_db_path] if scope == SCOPE_ALL || scope == SCOPE_GLOBAL
+        pairs << ["project", Configuration.project_db_path] if scope == SCOPE_ALL || scope == SCOPE_PROJECT
+        pairs
+      end
+
       def index_database(label, db_path, generator, opts)
         unless File.exist?(db_path)
           stdout.puts "#{label.capitalize} database not found, skipping..."
@@ -94,6 +102,11 @@ module ClaudeMemory
 
         stdout.puts "#{label.capitalize} database: Indexing #{facts.size} facts..."
 
+        vec_index = store.vector_index
+        if vec_index.available?
+          stdout.puts "  sqlite-vec available, dual-writing to vec0 index"
+        end
+
         processed = checkpoint ? checkpoint[:processed_items] : 0
         begin
           facts.each_slice(opts[:batch_size]) do |batch|
@@ -106,9 +119,12 @@ module ClaudeMemory
                 # Generate embedding
                 embedding = generator.generate(text)
 
-                # Store embedding
+                # Store embedding (JSON column)
                 store.update_fact_embedding(fact[:id], embedding)
 
+                # Dual-write to vec0 if available (insert_embedding manages vec_indexed_at)
+                vec_index.insert_embedding(fact[:id], embedding) if vec_index.available?
+
                 processed += 1
               end
 
@@ -137,6 +153,45 @@ module ClaudeMemory
         end
       end
 
+      def vec_backfill(opts)
+        scopes_for(opts[:scope]).each do |label, db_path|
+          unless File.exist?(db_path)
+            stdout.puts "#{label.capitalize} database not found, skipping..."
+            next
+          end
+
+          store = Store::SQLiteStore.new(db_path)
+          begin
+            vec_index = store.vector_index
+
+            unless vec_index.available?
+              stderr.puts "#{label.capitalize}: sqlite-vec not available, cannot backfill"
+              next
+            end
+
+            total = store.facts.where(vec_indexed_at: nil).where(Sequel.~(embedding_json: nil)).where(status: "active").count
+            if total == 0
+              stdout.puts "#{label.capitalize} database: All embeddings already in vec0 index"
+              next
+            end
+
+            stdout.puts "#{label.capitalize} database: Backfilling #{total} facts to vec0..."
+            backfilled = 0
+            loop do
+              count = vec_index.backfill_batch!(limit: opts[:batch_size])
+              break if count == 0
+              backfilled += count
+              stdout.puts "  Backfilled #{backfilled}/#{total}..."
+            end
+            stdout.puts "  Done! #{backfilled} facts indexed in vec0"
+          ensure
+            store.close
+          end
+        end
+
+        0
+      end
+
       def build_fact_text(fact, store)
         # Build rich text representation for embedding
         parts = []