claude_memory 0.8.0 → 0.9.0

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

data/lib/claude_memory/distill/json_schema.md

@@ -66,13 +66,17 @@ This document defines the schema for extracted knowledge from transcripts.
 - **conflict**: `{kind: "conflict", value: true}` - indicates contradictory information detected
 - **time_boundary**: `{kind: "time_boundary", value: "2024-01-15"}` - temporal boundary marker
 
-## Predicate Types (MVP)
+## Predicate Types
+
+Canonical vocabulary defined in `lib/claude_memory/resolve/predicate_policy.rb`.
 
 | Predicate | Cardinality | Exclusive |
 |-----------|-------------|-----------|
 | convention | multi | no |
-| decision | multi (by scope) | no |
-| auth_method | single | yes |
+| decision | multi | no |
+| architecture | multi | no |
+| uses_framework | multi | no |
+| uses_language | multi | no |
 | uses_database | single | yes |
-| uses_framework | single | yes |
 | deployment_platform | single | yes |
+| auth_method | single | yes |

data/lib/claude_memory/distill/null_distiller.rb

@@ -73,6 +73,8 @@ module ClaudeMemory
             facts << build_fact("uses_framework", entity[:name], text, scope_hint)
           when "platform"
             facts << build_fact("deployment_platform", entity[:name], text, scope_hint)
+          when "language"
+            facts << build_fact("uses_language", entity[:name], text, scope_hint)
           end
         end
 

data/lib/claude_memory/domain/entity.rb

@@ -2,10 +2,18 @@
 
 module ClaudeMemory
   module Domain
-    # Domain model representing an entity (database, framework, person, etc.)
+    # Domain model representing an entity (database, framework, person, etc.).
+    # Instances are immutable (frozen).
     class Entity
       attr_reader :id, :type, :canonical_name, :slug, :created_at
 
+      # @param attributes [Hash] entity attributes
+      # @option attributes [Integer] :id database primary key
+      # @option attributes [String] :type entity category (required, e.g. "database", "framework", "person")
+      # @option attributes [String] :canonical_name display name (required)
+      # @option attributes [String] :slug URL-safe identifier (required)
+      # @option attributes [String] :created_at ISO 8601 creation timestamp
+      # @raise [ArgumentError] if type, canonical_name, or slug is blank
       def initialize(attributes)
         @id = attributes[:id]
         @type = attributes[:type]
@@ -17,18 +25,22 @@ module ClaudeMemory
         freeze
       end
 
+      # @return [Boolean] true when type is "database"
       def database?
         type == "database"
       end
 
+      # @return [Boolean] true when type is "framework"
       def framework?
         type == "framework"
       end
 
+      # @return [Boolean] true when type is "person"
       def person?
         type == "person"
       end
 
+      # @return [Hash] all attributes as a plain hash
       def to_h
         {
           id: id,

data/lib/claude_memory/domain/fact.rb

@@ -2,13 +2,27 @@
 
 module ClaudeMemory
   module Domain
-    # Domain model representing a fact in the memory system
-    # Encapsulates business logic and validation
+    # Domain model representing a fact in the memory system.
+    # Encapsulates business logic and validation. Instances are immutable (frozen).
     class Fact
       attr_reader :id, :docid, :subject_name, :predicate, :object_literal,
         :status, :confidence, :scope, :project_path,
         :valid_from, :valid_to, :created_at
 
+      # @param attributes [Hash] fact attributes
+      # @option attributes [Integer] :id database primary key
+      # @option attributes [Integer] :docid FTS document id
+      # @option attributes [String] :subject_name entity name of the subject
+      # @option attributes [String] :predicate relationship type (required)
+      # @option attributes [String] :object_literal literal value (required)
+      # @option attributes [String] :status one of "active", "superseded", "rejected", "disputed"
+      # @option attributes [Float] :confidence score between 0 and 1 (default: 1.0)
+      # @option attributes [String] :scope "project" or "global" (default: "project")
+      # @option attributes [String] :project_path path for project-scoped facts
+      # @option attributes [String] :valid_from ISO 8601 start of validity
+      # @option attributes [String] :valid_to ISO 8601 end of validity (nil if current)
+      # @option attributes [String] :created_at ISO 8601 creation timestamp
+      # @raise [ArgumentError] if predicate, object_literal, or confidence is invalid
       def initialize(attributes)
         @id = attributes[:id]
         @docid = attributes[:docid]
@@ -27,22 +41,32 @@ module ClaudeMemory
         freeze
       end
 
+      # @return [Boolean] true when status is "active"
       def active?
         status == "active"
       end
 
+      # @return [Boolean] true when status is "superseded"
       def superseded?
         status == "superseded"
       end
 
+      # @return [Boolean] true when status is "rejected"
+      def rejected?
+        status == "rejected"
+      end
+
+      # @return [Boolean] true when scope is "global"
       def global?
         scope == "global"
       end
 
+      # @return [Boolean] true when scope is "project"
       def project?
         scope == "project"
       end
 
+      # @return [Hash] all attributes as a plain hash
       def to_h
         {
           id: id,

data/lib/claude_memory/embeddings/api_adapter.rb

@@ -22,19 +22,20 @@ module ClaudeMemory
       DEFAULT_API_URL = "https://api.openai.com/v1/embeddings"
       DEFAULT_MODEL = "text-embedding-3-small"
 
-      def initialize(env: ENV)
+      def initialize(model: nil, env: ENV)
         @api_key = env["CLAUDE_MEMORY_EMBEDDING_API_KEY"] || env["OPENAI_API_KEY"]
         @api_url = env["CLAUDE_MEMORY_EMBEDDING_API_URL"] || DEFAULT_API_URL
-        @model = env["CLAUDE_MEMORY_EMBEDDING_MODEL"] || DEFAULT_MODEL
+        @model = model || env["CLAUDE_MEMORY_EMBEDDING_MODEL"] || DEFAULT_MODEL
+        @known_dimensions = ModelRegistry.dimensions_for(@model)
 
         raise ArgumentError, "Set CLAUDE_MEMORY_EMBEDDING_API_KEY or OPENAI_API_KEY" unless @api_key
       end
 
       def name = "api"
 
-      # Dimensions are lazy — derived from the first API response and cached.
+      # Dimensions resolved from registry if known, otherwise lazy from first API response.
       def dimensions
-        @dimensions ||= fetch_dimensions
+        @dimensions ||= @known_dimensions || fetch_dimensions
       end
 
       # Generate embedding for a query text.