claude_memory 0.9.1 → 0.11.0

data/lib/claude_memory/commands/stats_command.rb

@@ -13,13 +13,16 @@ module ClaudeMemory
       SCOPE_PROJECT = "project"
 
       def call(args)
-        opts = parse_options(args, {scope: SCOPE_ALL, tools: false, since_days: nil}) do |o|
+        opts = parse_options(args, {scope: SCOPE_ALL, tools: false, tokens: false, stale: false, since_days: nil, stale_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 }
+            parser.on("--tokens", "Show SessionStart context-injection token budget") { o[:tokens] = true }
+            parser.on("--stale", "Show facts not recalled in CLAUDE_MEMORY_STALE_DAYS (default 14)") { o[:stale] = true }
+            parser.on("--since DAYS", Integer, "Limit --tools/--tokens to last N days") { |v| o[:since_days] = v }
+            parser.on("--stale-days N", Integer, "Override staleness threshold for --stale") { |v| o[:stale_days] = v }
           end
         end
         return 1 if opts.nil?
@@ -28,6 +31,14 @@ module ClaudeMemory
           return print_mcp_tool_call_stats(opts[:since_days])
         end
 
+        if opts[:tokens]
+          return print_token_budget_stats(opts[:since_days])
+        end
+
+        if opts[:stale]
+          return print_stale_facts(opts[:stale_days])
+        end
+
         manager = ClaudeMemory::Store::StoreManager.new
 
         stdout.puts "ClaudeMemory Statistics"
@@ -48,6 +59,37 @@ module ClaudeMemory
 
       private
 
+      def print_stale_facts(override_days)
+        threshold = override_days || ClaudeMemory::Configuration.new.stale_days
+        manager = ClaudeMemory::Store::StoreManager.new
+        result = ClaudeMemory::Recall::StaleDetector.stale_facts(manager, threshold_days: threshold)
+
+        stdout.puts "Stale facts (last_recalled_at older than #{threshold} day#{"s" unless threshold == 1})"
+        stdout.puts "=" * 60
+
+        if result[:total].zero?
+          stdout.puts "No stale facts."
+          stdout.puts ""
+          stdout.puts "Run `claude-memory sweep` to refresh last_recalled_at from activity_events."
+        else
+          stdout.puts "Total: #{result[:total]} (project=#{result[:project].size}, global=#{result[:global].size})"
+          stdout.puts ""
+          %i[project global].each do |scope|
+            rows = result[scope]
+            next if rows.empty?
+            stdout.puts "## #{scope.to_s.upcase}"
+            rows.each do |row|
+              last = row[:last_recalled_at] || "never"
+              stdout.puts "  ##{row[:id]} [#{row[:predicate]}] #{row[:object_literal]&.slice(0, 80)} (last: #{last})"
+            end
+            stdout.puts ""
+          end
+        end
+
+        manager.close
+        0
+      end
+
       def open_readonly(db_path)
         Sequel.connect("extralite://#{db_path}")
       end
@@ -312,6 +354,93 @@ module ClaudeMemory
         1
       end
 
+      TOKEN_BUCKETS = [
+        ["<500", 0, 500],
+        ["500-1000", 500, 1000],
+        ["1000-2000", 1000, 2000],
+        ["2000-5000", 2000, 5000],
+        ["5000+", 5000, Float::INFINITY]
+      ].freeze
+
+      def print_token_budget_stats(since_days)
+        manager = ClaudeMemory::Store::StoreManager.new
+        db_path = manager.project_db_path
+
+        stdout.puts "SessionStart Context Token Budget"
+        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?(:activity_events)
+          stdout.puts "No activity telemetry recorded yet."
+          db.disconnect
+          manager.close
+          return 0
+        end
+
+        dataset = db[:activity_events]
+          .where(event_type: "hook_context", status: "success")
+        if since_days
+          cutoff = (Time.now - since_days * 86400).utc.iso8601
+          dataset = dataset.where { occurred_at >= cutoff }
+          stdout.puts "Window: last #{since_days} day#{"s" unless since_days == 1}"
+        else
+          stdout.puts "Window: all time"
+        end
+        stdout.puts
+
+        tokens = dataset.select_map(:detail_json).filter_map do |json|
+          next unless json
+          value = JSON.parse(json)["context_tokens"]
+          value if value.is_a?(Integer) && value > 0
+        end
+
+        if tokens.empty?
+          stdout.puts "No context injections recorded in window."
+          stdout.puts ""
+          stdout.puts "Token telemetry is recorded automatically on SessionStart hooks."
+          stdout.puts "Run a Claude Code session in this project to populate."
+          db.disconnect
+          manager.close
+          return 0
+        end
+
+        sorted = tokens.sort
+        total = sorted.size
+        stdout.puts "Sessions: #{format_number(total)}"
+        stdout.puts "p50: #{format_number(percentile(sorted, 0.50))} tokens"
+        stdout.puts "p95: #{format_number(percentile(sorted, 0.95))} tokens"
+        stdout.puts "Avg: #{format_number((sorted.sum.to_f / total).round)} tokens"
+        stdout.puts "Min: #{format_number(sorted.first)} tokens"
+        stdout.puts "Max: #{format_number(sorted.last)} tokens"
+        stdout.puts ""
+        print_token_distribution(sorted)
+
+        db.disconnect
+        manager.close
+        0
+      rescue Sequel::DatabaseError, JSON::ParserError, Extralite::Error => e
+        stderr.puts "Error reading token telemetry: #{e.message}"
+        1
+      end
+
+      def print_token_distribution(sorted)
+        total = sorted.size
+        stdout.puts "Distribution:"
+        TOKEN_BUCKETS.each do |label, low, high|
+          count = sorted.count { |t| t >= low && t < high }
+          pct = (count * 100.0 / total).round(1)
+          bar = "█" * (pct / 5).round
+          stdout.puts "  #{label.ljust(12)} #{count.to_s.rjust(5)} (#{pct.to_s.rjust(5)}%) #{bar}"
+        end
+      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)}"

data/lib/claude_memory/commands/sweep_command.rb

@@ -19,12 +19,14 @@ module ClaudeMemory
 
         stdout.puts "Running sweep on #{opts[:scope]} database with #{opts[:budget]}s budget..."
         stats = sweeper.run!(budget_seconds: opts[:budget])
+        refresh_counts = ClaudeMemory::Sweep::RecallTimestampRefresher.new(manager).refresh!
 
         stdout.puts "Sweep complete:"
         stdout.puts "  Proposed facts expired: #{stats[:proposed_facts_expired]}"
         stdout.puts "  Disputed facts expired: #{stats[:disputed_facts_expired]}"
         stdout.puts "  Orphaned provenance deleted: #{stats[:orphaned_provenance_deleted]}"
         stdout.puts "  Old content pruned: #{stats[:old_content_pruned]}"
+        stdout.puts "  Recall timestamps refreshed: project=#{refresh_counts[:project]}, global=#{refresh_counts[:global]}"
         stdout.puts "  Elapsed: #{stats[:elapsed_seconds].round(2)}s"
         stdout.puts "  Budget honored: #{stats[:budget_honored]}"
 

data/lib/claude_memory/configuration.rb

@@ -50,6 +50,22 @@ module ClaudeMemory
       env["CLAUDE_TRANSCRIPT_PATH"]
     end
 
+    # Default staleness threshold (in days) for #35 access-based staleness.
+    # Active facts whose last_recalled_at is older than this — or never set,
+    # for facts created earlier than the same window — are flagged as
+    # candidates for review. Override via CLAUDE_MEMORY_STALE_DAYS.
+    DEFAULT_STALE_DAYS = 14
+
+    # @return [Integer] staleness threshold in days
+    def stale_days
+      raw = env["CLAUDE_MEMORY_STALE_DAYS"]
+      return DEFAULT_STALE_DAYS if raw.nil? || raw.empty?
+      parsed = Integer(raw, 10)
+      (parsed > 0) ? parsed : DEFAULT_STALE_DAYS
+    rescue ArgumentError
+      DEFAULT_STALE_DAYS
+    end
+
     private
 
     def resolve_project_dir

data/lib/claude_memory/core/relative_time.rb

@@ -37,6 +37,15 @@ module ClaudeMemory
         nil
       end
 
+      # Parse a timestamp value into a Unix epoch integer; returns 0 when the
+      # value is unparseable. Used by sort comparators that need a stable
+      # numeric key without an exception path.
+      def self.to_epoch(value)
+        Time.parse(value.to_s).to_i
+      rescue ArgumentError, TypeError
+        0
+      end
+
       def self.format_absolute(time)
         time.strftime("%Y-%m-%d")
       end