claude_memory 0.8.0 → 0.9.1

data/lib/claude_memory/commands/embeddings_command.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Shows embedding configuration, lists available models, and validates setup.
+    #
+    # Subcommands:
+    #   claude-memory embeddings          # Show current config
+    #   claude-memory embeddings list     # List available models
+    #   claude-memory embeddings check    # Validate current setup
+    #
+    class EmbeddingsCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory embeddings [list|check]"
+          end
+        end
+        return 1 if opts.nil?
+
+        subcommand = args.first
+
+        case subcommand
+        when "list" then list_models
+        when "check" then check_setup
+        when nil then show_config
+        else
+          failure("Unknown subcommand: #{subcommand}. Use: list, check")
+        end
+      end
+
+      private
+
+      def inspector
+        @inspector ||= Embeddings::Inspector.new
+      end
+
+      def show_config
+        provider = ENV["CLAUDE_MEMORY_EMBEDDING_PROVIDER"] || "tfidf"
+        model = ENV["CLAUDE_MEMORY_EMBEDDING_MODEL"]
+        api_url = ENV["CLAUDE_MEMORY_EMBEDDING_API_URL"]
+
+        stdout.puts "Embedding Configuration"
+        stdout.puts "======================"
+        stdout.puts "Provider:  #{provider}"
+        stdout.puts "Model:     #{model || "(default)"}"
+
+        if model
+          info = Embeddings::ModelRegistry.find(model)
+          if info
+            stdout.puts "Dimensions: #{info.dimensions}"
+            stdout.puts "Description: #{info.description}"
+          else
+            stdout.puts "Dimensions: (unknown - will be discovered at runtime)"
+          end
+        else
+          info = Embeddings::ModelRegistry.default_for_provider(provider)
+          if info
+            stdout.puts "Default model: #{info.name}"
+            stdout.puts "Dimensions: #{info.dimensions}"
+          end
+        end
+
+        stdout.puts "API URL:   #{api_url}" if api_url && provider == "api"
+
+        inspector.database_states.each do |state|
+          stdout.puts ""
+          stdout.puts "#{state.label.capitalize} DB: provider=#{state.provider || "unknown"}, dimensions=#{state.dimensions || "unknown"}"
+        end
+
+        stdout.puts ""
+        stdout.puts "ENV variables:"
+        stdout.puts "  CLAUDE_MEMORY_EMBEDDING_PROVIDER  Provider (tfidf, fastembed, api)"
+        stdout.puts "  CLAUDE_MEMORY_EMBEDDING_MODEL     Model name"
+        stdout.puts "  CLAUDE_MEMORY_EMBEDDING_API_KEY   API key (for api provider)"
+        stdout.puts "  CLAUDE_MEMORY_EMBEDDING_API_URL   API endpoint (for api provider)"
+        0
+      end
+
+      def list_models
+        Embeddings::ModelRegistry.providers.each do |provider|
+          stdout.puts ""
+          stdout.puts "#{provider_label(provider)}:"
+          stdout.puts "-" * 40
+
+          Embeddings::ModelRegistry.models_for_provider(provider).each do |model|
+            size = model.size_mb ? "#{model.size_mb}MB" : "cloud"
+            tokens = model.max_tokens ? "#{model.max_tokens} tokens" : ""
+            stdout.puts "  #{model.name}"
+            stdout.puts "    #{model.dimensions}-dim | #{size} | #{tokens}"
+            stdout.puts "    #{model.description}"
+          end
+        end
+
+        stdout.puts ""
+        stdout.puts "Custom models: Set CLAUDE_MEMORY_EMBEDDING_MODEL to any model"
+        stdout.puts "supported by your provider. Dimensions are auto-detected."
+        0
+      end
+
+      def check_setup
+        provider_name = ENV["CLAUDE_MEMORY_EMBEDDING_PROVIDER"] || "tfidf"
+        model_name = ENV["CLAUDE_MEMORY_EMBEDDING_MODEL"]
+
+        stdout.puts "Checking embedding setup..."
+        stdout.puts ""
+
+        ok = true
+        ok &= check_provider(provider_name)
+        ok &= check_model(provider_name, model_name) if model_name
+        ok &= render_dimension_checks(provider_name, model_name)
+
+        stdout.puts ""
+        stdout.puts ok ? "All checks passed." : "Some checks failed. See above."
+        ok ? 0 : 1
+      end
+
+      def check_provider(name)
+        case name
+        when "fastembed"
+          check_fastembed
+        when "api"
+          check_api_config
+        when "tfidf"
+          stdout.puts "  [OK] tfidf provider (built-in, always available)"
+          true
+        else
+          stdout.puts "  [FAIL] Unknown provider: #{name}"
+          false
+        end
+      end
+
+      def check_model(provider_name, model_name)
+        info = Embeddings::ModelRegistry.find(model_name)
+        if info
+          if info.provider != provider_name
+            stdout.puts "  [WARN] Model '#{model_name}' is for '#{info.provider}' provider, but '#{provider_name}' is selected"
+            stdout.puts "         Set CLAUDE_MEMORY_EMBEDDING_PROVIDER=#{info.provider}"
+          else
+            stdout.puts "  [OK] Model '#{model_name}' (#{info.dimensions}-dim)"
+          end
+        else
+          stdout.puts "  [INFO] Model '#{model_name}' not in registry (dimensions will be auto-detected)"
+        end
+        true
+      end
+
+      def render_dimension_checks(provider_name, model_name)
+        ok = true
+
+        inspector.dimension_checks(provider_name, model_name).each do |check|
+          case check.status
+          when :mismatch
+            stdout.puts "  [WARN] #{check.label}: Dimension mismatch (stored: #{check.stored_dims}, current: #{check.current_dims})"
+            stdout.puts "         Re-index with: claude-memory index --force --scope #{check.label}"
+            ok = false
+          when :match
+            stdout.puts "  [OK] #{check.label}: #{check.stored_dims}-dim (provider: #{check.stored_provider || "unknown"})"
+          when :fresh
+            stdout.puts "  [INFO] #{check.label}: No embeddings indexed yet"
+          end
+        end
+
+        ok
+      end
+
+      def check_fastembed
+        require "fastembed"
+        stdout.puts "  [OK] fastembed gem available"
+        true
+      rescue LoadError
+        stdout.puts "  [FAIL] fastembed gem not installed"
+        stdout.puts "         Add `gem 'fastembed'` to your Gemfile"
+        false
+      end
+
+      def check_api_config
+        key = ENV["CLAUDE_MEMORY_EMBEDDING_API_KEY"] || ENV["OPENAI_API_KEY"]
+        if key
+          stdout.puts "  [OK] API key configured"
+          true
+        else
+          stdout.puts "  [FAIL] No API key found"
+          stdout.puts "         Set CLAUDE_MEMORY_EMBEDDING_API_KEY or OPENAI_API_KEY"
+          false
+        end
+      end
+
+      def provider_label(provider)
+        case provider
+        when "fastembed" then "fastembed (local ONNX, no API key)"
+        when "api" then "api (OpenAI-compatible endpoints, requires API key)"
+        when "tfidf" then "tfidf (built-in, no dependencies)"
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/help_command.rb

@@ -19,20 +19,27 @@ module ClaudeMemory
             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)
+            hook       Run hook entrypoints (ingest|sweep|publish|context)
             init       Initialize ClaudeMemory in a project
             ingest     Ingest transcript delta
             promote    Promote a project fact to global memory
             publish    Publish snapshot to Claude Code memory
             recall     Recall facts matching a query
+            recover    Recover stuck operations
+            reject     Mark a fact as rejected (e.g. hallucination)
+            restore    Restore superseded facts from reclassified predicates
             search     Search indexed content
             serve-mcp  Start MCP server
+            stats      Show statistics (--tools for MCP telemetry)
             sweep      Run maintenance/pruning
             uninstall  Remove ClaudeMemory configuration
             version    Show version number
 
           Utilities:
             completion     Generate shell completions (bash/zsh)
+            embeddings     Inspect embedding backend
+            git-lfs        Git LFS integration for memory DB
+            index          Build or rebuild content indexes
             install-skill  Install agent skills to ~/.claude/commands/
 
           Run 'claude-memory <command> --help' for more information on a command.

data/lib/claude_memory/commands/registry.rb

@@ -3,48 +3,48 @@
 module ClaudeMemory
   module Commands
     # Registry for CLI command lookup and dispatch
-    # Maps command names to command classes for dynamic dispatch
+    # Maps command names to command classes and short descriptions.
+    # Descriptions are authoritative for shell completion and help output;
+    # keep them current when adding commands.
     class Registry
-      # Map of command names to class names
-      # As more commands are extracted, add them here
+      # Map of command names to {class:, description:} entries.
+      # As more commands are extracted, add them here.
       COMMANDS = {
-        "help" => "HelpCommand",
-        "version" => "VersionCommand",
-        "doctor" => "DoctorCommand",
-        "stats" => "StatsCommand",
-        "promote" => "PromoteCommand",
-        "search" => "SearchCommand",
-        "explain" => "ExplainCommand",
-        "conflicts" => "ConflictsCommand",
-        "changes" => "ChangesCommand",
-        "recall" => "RecallCommand",
-        "sweep" => "SweepCommand",
-        "ingest" => "IngestCommand",
-        "publish" => "PublishCommand",
-        "db:init" => "DbInitCommand",
-        "init" => "InitCommand",
-        "uninstall" => "UninstallCommand",
-        "serve-mcp" => "ServeMcpCommand",
-        "hook" => "HookCommand",
-        "index" => "IndexCommand",
-        "recover" => "RecoverCommand",
-        "compact" => "CompactCommand",
-        "export" => "ExportCommand",
-        "git-lfs" => "GitLfsCommand",
-        "install-skill" => "InstallSkillCommand",
-        "completion" => "CompletionCommand"
+        "help" => {class: HelpCommand, description: "Show help message"},
+        "version" => {class: VersionCommand, description: "Show version"},
+        "doctor" => {class: DoctorCommand, description: "Check system health"},
+        "stats" => {class: StatsCommand, description: "Show statistics"},
+        "promote" => {class: PromoteCommand, description: "Promote fact to global"},
+        "search" => {class: SearchCommand, description: "Search indexed content"},
+        "explain" => {class: ExplainCommand, description: "Explain a fact with receipts"},
+        "conflicts" => {class: ConflictsCommand, description: "Show open conflicts"},
+        "changes" => {class: ChangesCommand, description: "Show recent fact changes"},
+        "recall" => {class: RecallCommand, description: "Recall facts matching query"},
+        "sweep" => {class: SweepCommand, description: "Run maintenance"},
+        "ingest" => {class: IngestCommand, description: "Ingest transcript delta"},
+        "publish" => {class: PublishCommand, description: "Publish snapshot"},
+        "db:init" => {class: DbInitCommand, description: "Initialize database"},
+        "init" => {class: InitCommand, description: "Initialize ClaudeMemory"},
+        "uninstall" => {class: UninstallCommand, description: "Remove configuration"},
+        "serve-mcp" => {class: ServeMcpCommand, description: "Start MCP server"},
+        "hook" => {class: HookCommand, description: "Run hook entrypoints"},
+        "index" => {class: IndexCommand, description: "Index content"},
+        "recover" => {class: RecoverCommand, description: "Recover database"},
+        "compact" => {class: CompactCommand, description: "Compact databases"},
+        "export" => {class: ExportCommand, description: "Export facts to JSON"},
+        "git-lfs" => {class: GitLfsCommand, description: "Git LFS integration"},
+        "install-skill" => {class: InstallSkillCommand, description: "Install agent skills"},
+        "completion" => {class: CompletionCommand, description: "Generate shell completions"},
+        "embeddings" => {class: EmbeddingsCommand, description: "Inspect embedding backend"},
+        "reject" => {class: RejectCommand, description: "Mark a fact as rejected"},
+        "restore" => {class: RestoreCommand, description: "Restore superseded facts from obsolete single-value classification"}
       }.freeze
 
       # Find a command class by name
       # @param command_name [String] the command name (e.g., "help", "version")
       # @return [Class, nil] the command class, or nil if not found
       def self.find(command_name)
-        return nil if command_name.nil?
-
-        class_name = COMMANDS[command_name]
-        return nil unless class_name
-
-        Commands.const_get(class_name)
+        COMMANDS.dig(command_name, :class)
       end
 
       # Get all registered command names
@@ -59,6 +59,19 @@ module ClaudeMemory
       def self.registered?(command_name)
         COMMANDS.key?(command_name)
       end
+
+      # Get the short description for a command
+      # @param command_name [String] the command name
+      # @return [String, nil] the description, or nil if not registered
+      def self.description(command_name)
+        COMMANDS.dig(command_name, :description)
+      end
+
+      # Get all command descriptions as a hash
+      # @return [Hash{String => String}] command name → description
+      def self.descriptions
+        COMMANDS.transform_values { |entry| entry[:description] }
+      end
     end
   end
 end

data/lib/claude_memory/commands/reject_command.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Mark a fact as rejected (e.g. a distiller hallucination).
+    # Closes any open conflicts involving the fact.
+    class RejectCommand < BaseCommand
+      # @param args [Array<String>] command line arguments (fact_id_or_docid, --scope, --reason)
+      # @return [Integer] exit code (0 for success, 1 for failure)
+      def call(args)
+        opts = parse_options(args, {scope: "project", reason: nil}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory reject <fact_id_or_docid> [options]"
+            parser.on("--scope SCOPE", %w[project global], "Database scope (default: project)") { |v| o[:scope] = v }
+            parser.on("--reason TEXT", "Why this fact is wrong (recorded in conflict notes)") { |v| o[:reason] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        identifier = args.first
+        return failure("Usage: claude-memory reject <fact_id_or_docid> [options]") if identifier.nil? || identifier.empty?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+
+        fact_id = resolve_fact_id(store, identifier)
+        unless fact_id
+          stderr.puts "Fact '#{identifier}' not found in #{opts[:scope]} database."
+          manager.close
+          return 1
+        end
+
+        result = store.reject_fact(fact_id, reason: opts[:reason])
+        manager.close
+
+        if result.nil?
+          stderr.puts "Fact ##{fact_id} not found."
+          return 1
+        end
+
+        stdout.puts "Rejected fact ##{fact_id} in #{opts[:scope]} database."
+        stdout.puts "Resolved #{result[:conflicts_resolved]} open conflict(s)." if result[:conflicts_resolved] > 0
+        0
+      end
+
+      private
+
+      # Accept either a numeric fact id or an 8-char docid hex string.
+      # @param store [Store::SQLiteStore] database to look up the fact in
+      # @param identifier [String] numeric fact id or hex docid
+      # @return [Integer, nil] resolved fact id, or nil if not found
+      def resolve_fact_id(store, identifier)
+        return identifier.to_i if identifier.match?(/\A\d+\z/)
+
+        row = store.find_fact_by_docid(identifier)
+        row ? row[:id] : nil
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/restore_command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # One-time recovery for facts that were superseded because of an
+    # obsolete single-value predicate classification. See
+    # Sweep::Maintenance#restore_multi_value_supersessions for the algorithm
+    # and Jaccard heuristic.
+    class RestoreCommand < BaseCommand
+      # @param args [Array<String>] command line arguments (--predicate, --scope, --dry-run)
+      # @return [Integer] exit code (0 for success, 1 for failure)
+      def call(args)
+        opts = parse_options(args, {predicate: nil, scope: "project", dry_run: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory restore --predicate NAME [options]"
+            parser.on("--predicate NAME", "Predicate to restore (e.g. uses_framework)") { |v| o[:predicate] = v }
+            parser.on("--scope SCOPE", %w[project global], "Database scope (default: project)") { |v| o[:scope] = v }
+            parser.on("--dry-run", "Show what would be restored without writing") { o[:dry_run] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        return failure("--predicate required (e.g. --predicate uses_framework)") if opts[:predicate].nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+
+        begin
+          result = Sweep::Maintenance.new(store).restore_multi_value_supersessions(
+            predicate: opts[:predicate],
+            dry_run: opts[:dry_run]
+          )
+        rescue ArgumentError => e
+          stderr.puts e.message
+          manager.close
+          return 1
+        ensure
+          manager.close
+        end
+
+        print_result(opts, result)
+        0
+      end
+
+      private
+
+      # Print a summary of restored and skipped facts.
+      # @param opts [Hash] parsed options including :predicate, :scope, :dry_run
+      # @param result [Hash] result from Sweep::Maintenance#restore_multi_value_supersessions
+      # @return [void]
+      def print_result(opts, result)
+        mode = opts[:dry_run] ? "DRY RUN" : "RESTORE"
+        stdout.puts "#{mode}: predicate=#{opts[:predicate]} scope=#{opts[:scope]}"
+        stdout.puts "=" * 50
+        stdout.puts "Inspected:         #{result[:inspected]}"
+        stdout.puts "Restored:          #{result[:restored]}"
+        stdout.puts "Skipped ambiguous: #{result[:skipped_ambiguous]}"
+
+        return if result[:decisions].empty?
+
+        stdout.puts
+        stdout.puts "Decisions:"
+        result[:decisions].each do |d|
+          case d[:action]
+          when :restore
+            stdout.puts "  [restore] ##{d[:fact_id]}  #{d[:object]}"
+          when :skip_ambiguous
+            overlaps = d[:overlaps_with].map { |o| "'#{o}'" }.join(", ")
+            stdout.puts "  [skip]    ##{d[:fact_id]}  #{d[:object]}  (overlaps: #{overlaps})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/skills/distill-transcripts.md

@@ -30,7 +30,11 @@ For each content item, carefully read the raw_text and extract:
 
 **Facts** — Knowledge learned:
 - subject: Entity name or "repo" for project-level facts
-- predicate: uses_database, uses_framework, convention, decision, auth_method, deployment_platform, depends_on, testing_strategy
+- predicate: prefer a predicate from the canonical vocabulary defined in
+  `lib/claude_memory/resolve/predicate_policy.rb` (convention, decision,
+  architecture, uses_framework, uses_language, uses_database,
+  deployment_platform, auth_method). Other snake_case predicates are
+  accepted but fall through to the default multi-value policy.
 - object: The value
 - confidence: 0.0-1.0
 - quote: Source excerpt (max 200 chars)

data/lib/claude_memory/commands/stats_command.rb

@@ -13,15 +13,21 @@ module ClaudeMemory
       SCOPE_PROJECT = "project"
 
       def call(args)
-        opts = parse_options(args, {scope: SCOPE_ALL}) do |o|
+        opts = parse_options(args, {scope: SCOPE_ALL, tools: false, since_days: nil}) do |o|
           OptionParser.new do |parser|
             parser.banner = "Usage: claude-memory stats [options]"
             parser.on("--scope SCOPE", ["all", "global", "project"],
               "Show stats for: all (default), global, or project") { |v| o[:scope] = v }
+            parser.on("--tools", "Show MCP tool-call usage stats") { o[:tools] = true }
+            parser.on("--since DAYS", Integer, "Limit --tools to last N days") { |v| o[:since_days] = v }
           end
         end
         return 1 if opts.nil?
 
+        if opts[:tools]
+          return print_mcp_tool_call_stats(opts[:since_days])
+        end
+
         manager = ClaudeMemory::Store::StoreManager.new
 
         stdout.puts "ClaudeMemory Statistics"
@@ -42,6 +48,10 @@ module ClaudeMemory
 
       private
 
+      def open_readonly(db_path)
+        Sequel.connect("extralite://#{db_path}")
+      end
+
       def print_database_stats(label, db_path)
         stdout.puts "## #{label} DATABASE"
         stdout.puts
@@ -53,7 +63,7 @@ module ClaudeMemory
         end
 
         begin
-          db = Sequel.sqlite(db_path, readonly: true)
+          db = open_readonly(db_path)
 
           # Facts statistics
           print_fact_stats(db)
@@ -245,6 +255,92 @@ module ClaudeMemory
         # Format number with comma separators (e.g., 1234567 => "1,234,567")
         num.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
       end
+
+      def print_mcp_tool_call_stats(since_days)
+        manager = ClaudeMemory::Store::StoreManager.new
+        db_path = manager.project_db_path
+
+        stdout.puts "MCP Tool Call Statistics"
+        stdout.puts "=" * 50
+
+        unless File.exist?(db_path)
+          stdout.puts "Project database does not exist: #{db_path}"
+          manager.close
+          return 0
+        end
+
+        db = open_readonly(db_path)
+
+        unless db.table_exists?(:mcp_tool_calls)
+          stdout.puts "No telemetry recorded yet (run MCP server first)."
+          db.disconnect
+          manager.close
+          return 0
+        end
+
+        dataset = db[:mcp_tool_calls]
+        if since_days
+          cutoff = (Time.now - since_days * 86400).utc.iso8601
+          dataset = dataset.where { called_at >= cutoff }
+          stdout.puts "Window: last #{since_days} day#{"s" unless since_days == 1}"
+        else
+          stdout.puts "Window: all time"
+        end
+        stdout.puts
+
+        total = dataset.count
+        if total.zero?
+          stdout.puts "No tool calls recorded in window."
+          db.disconnect
+          manager.close
+          return 0
+        end
+
+        errors = dataset.exclude(error_class: nil).count
+        error_rate = (errors * 100.0 / total).round(1)
+        stdout.puts "Total calls: #{format_number(total)}"
+        stdout.puts "Errors: #{format_number(errors)} (#{error_rate}%)"
+        stdout.puts
+
+        print_per_tool_breakdown(dataset)
+
+        db.disconnect
+        manager.close
+        0
+      rescue Sequel::DatabaseError, Extralite::Error => e
+        stderr.puts "Error reading telemetry: #{e.message}"
+        1
+      end
+
+      def print_per_tool_breakdown(dataset)
+        stdout.puts "Per-tool breakdown:"
+        stdout.puts "  #{"Tool".ljust(28)} #{"Calls".rjust(7)}  #{"Avg ms".rjust(8)}  #{"P95 ms".rjust(8)}  #{"Err %".rjust(6)}"
+
+        rows = dataset
+          .group_and_count(:tool_name)
+          .order(Sequel.desc(:count))
+          .all
+
+        rows.each do |row|
+          tool = row[:tool_name]
+          calls = row[:count]
+          durations = dataset.where(tool_name: tool).select_map(:duration_ms).sort
+          avg = (durations.sum.to_f / calls).round(1)
+          p95 = percentile(durations, 0.95)
+          tool_errors = dataset.where(tool_name: tool).exclude(error_class: nil).count
+          tool_err_rate = (tool_errors * 100.0 / calls).round(1)
+
+          stdout.puts "  #{tool.to_s.ljust(28)} #{calls.to_s.rjust(7)}  #{avg.to_s.rjust(8)}  #{p95.to_s.rjust(8)}  #{tool_err_rate.to_s.rjust(6)}"
+        end
+      end
+
+      def percentile(sorted, pct)
+        return 0 if sorted.empty?
+        idx = (sorted.size * pct).ceil - 1
+        idx = 0 if idx < 0
+        idx = sorted.size - 1 if idx >= sorted.size
+        sorted[idx]
+      end
     end
   end
 end

data/lib/claude_memory/configuration.rb

@@ -8,31 +8,44 @@ module ClaudeMemory
   class Configuration
     attr_reader :env
 
+    # @param env [Hash] environment variables (default: ENV)
     def initialize(env = ENV)
       @env = env
     end
 
+    # @return [String] user home directory
     def home_dir
       env["HOME"] || File.expand_path("~")
     end
 
+    # @return [String] project root directory (resolves git worktrees)
     def project_dir
       env["CLAUDE_PROJECT_DIR"] || resolve_project_dir
     end
 
+    # @return [String] Claude config directory (default: ~/.claude)
+    def claude_config_dir
+      env["CLAUDE_CONFIG_DIR"] || File.join(home_dir, ".claude")
+    end
+
+    # @return [String] path to global memory database
     def global_db_path
-      File.join(home_dir, ".claude", "memory.sqlite3")
+      File.join(claude_config_dir, "memory.sqlite3")
     end
 
+    # @param project_path [String, nil] override project root (defaults to project_dir)
+    # @return [String] path to project memory database
     def project_db_path(project_path = nil)
       path = project_path || project_dir
       File.join(path, ".claude", "memory.sqlite3")
     end
 
+    # @return [String, nil] current Claude session ID from CLAUDE_SESSION_ID
     def session_id
       env["CLAUDE_SESSION_ID"]
     end
 
+    # @return [String, nil] path to current transcript from CLAUDE_TRANSCRIPT_PATH
     def transcript_path
       env["CLAUDE_TRANSCRIPT_PATH"]
     end