claude_memory 0.9.0 → 0.10.0

data/lib/claude_memory/commands/hook_command.rb

@@ -172,14 +172,17 @@ module ClaudeMemory
       def hook_context(payload, db_path)
         project_path = payload["project_path"] || payload["cwd"]
         source = payload["source"]
+        session_id = payload["session_id"]
         manager = ClaudeMemory::Store::StoreManager.new(
           project_db_path: db_path,
           project_path: project_path
         )
         manager.ensure_both!
 
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         injector = ClaudeMemory::Hook::ContextInjector.new(manager, source: source)
         context_text = injector.generate_context
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
 
         if context_text
           response = {
@@ -191,12 +194,43 @@ module ClaudeMemory
           stdout.puts JSON.generate(response)
         end
 
+        record_context_activity(manager, context_text, injector,
+          session_id: session_id, source: source, duration_ms: duration_ms)
+
         manager.close
         Hook::ExitCodes::SUCCESS
       rescue => e
         classify_error(e)
       end
 
+      CONTEXT_PREVIEW_BYTES = 400
+
+      def record_context_activity(manager, context_text, injector, session_id:, source:, duration_ms:)
+        store = manager.project_store || manager.global_store
+        return unless store
+
+        by_scope = injector.emitted_facts_by_scope.transform_values { |ids| ids.first(10) }
+        details = {
+          source: source,
+          context_length: context_text&.length,
+          preview: context_text&.byteslice(0, CONTEXT_PREVIEW_BYTES),
+          truncated: context_text ? context_text.bytesize > CONTEXT_PREVIEW_BYTES : false,
+          top_fact_ids: injector.emitted_fact_ids.first(10),
+          top_facts_by_scope: (by_scope if by_scope.any?),
+          top_subjects: injector.emitted_subjects.uniq.first(10),
+          fact_count: injector.emitted_fact_ids.size
+        }.compact
+
+        ClaudeMemory::ActivityLog.record(store,
+          event_type: "hook_context",
+          status: context_text ? "success" : "skipped",
+          session_id: session_id,
+          duration_ms: duration_ms,
+          details: details)
+      rescue => e
+        ClaudeMemory.logger.debug("record_context_activity failed: #{e.message}")
+      end
+
       def classify_error(error)
         exit_code = Hook::ErrorClassifier.exit_code_for(error)
 

data/lib/claude_memory/commands/reclassify_references_command.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # One-time cleanup for historical convention facts that are actually
+    # descriptions of external projects (LOC counts, star counts, author
+    # attributions, "X is a plugin…" templates). The Distill::ReferenceMaterialDetector
+    # now guards new writes in ManagementHandlers#store_extraction; this
+    # command walks existing rows and retags them to predicate=reference.
+    class ReclassifyReferencesCommand < BaseCommand
+      def call(args)
+        opts = parse_options(args, {scope: "project", dry_run: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory reclassify-references [options]"
+            parser.on("--scope SCOPE", %w[project global], "Database scope (default: project)") { |v| o[:scope] = v }
+            parser.on("--dry-run", "Show what would be reclassified without writing") { o[:dry_run] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+
+        begin
+          result = Sweep::Maintenance.new(store).reclassify_references(dry_run: opts[:dry_run])
+        ensure
+          manager.close
+        end
+
+        print_result(opts, result)
+        0
+      end
+
+      private
+
+      def print_result(opts, result)
+        mode = opts[:dry_run] ? "DRY RUN" : "RECLASSIFY"
+        stdout.puts "#{mode}: scope=#{opts[:scope]}"
+        stdout.puts "=" * 50
+        stdout.puts "Active conventions inspected: #{result[:inspected]}"
+        stdout.puts "Reclassified as reference:    #{result[:reclassified]}"
+
+        return if result[:decisions].empty?
+
+        stdout.puts
+        stdout.puts "Decisions:"
+        result[:decisions].each do |d|
+          preview = d[:object].to_s[0, 100]
+          stdout.puts "  fact ##{d[:fact_id]}  #{preview}#{"…" if d[:object].to_s.length > 100}"
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/registry.rb

@@ -37,7 +37,12 @@ module ClaudeMemory
         "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"}
+        "restore" => {class: RestoreCommand, description: "Restore superseded facts from obsolete single-value classification"},
+        "dedupe-conflicts" => {class: DedupeConflictsCommand, description: "Deduplicate historical open conflict rows that describe the same pair"},
+        "reclassify-references" => {class: ReclassifyReferencesCommand, description: "Retag existing convention facts that match reference-material heuristics"},
+        "census" => {class: CensusCommand, description: "Aggregate predicate usage across project databases"},
+        "dashboard" => {class: DashboardCommand, description: "Open debugging dashboard"},
+        "digest" => {class: DigestCommand, description: "Render a weekly markdown digest of memory activity"}
       }.freeze
 
       # Find a command class by name

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

@@ -35,12 +35,23 @@ For each content item, carefully read the raw_text and extract:
   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
+- object: The value. For **decision** and **convention** predicates, the object
+  MUST embed the reason — append a compact "— because ..." / "so that ..." /
+  "to avoid ..." clause, or include the trigger ("caused by X", "breaks when Y").
+  Bare conclusions without rationale are dead weight once they become stale:
+  a fact with a reason is recoverable, a fact without one is not. Architecture
+  facts should note the design *trade-off* if non-obvious.
 - confidence: 0.0-1.0
 - quote: Source excerpt (max 200 chars)
 - strength: "stated" (explicitly said) or "inferred" (implied)
 - scope_hint: "project" (this project only) or "global" (all projects)
 
+Examples of the reasoning requirement:
+- ❌ Bare: "Configuration class has instance methods only"
+- ✅ With why: "Configuration class has instance methods only — stub with instance_double + allow(Configuration).to receive(:new) because class-level stubbing breaks isolation"
+- ❌ Bare: "MCP tools return dual content + structuredContent"
+- ✅ With why: "MCP tools return dual content + structuredContent so human-readable summaries and machine-parseable JSON ship in the same response; compact mode omits receipts for ~60% smaller payloads"
+
 **Decisions** — Choices made:
 - title: Short summary (max 100 chars)
 - summary: Full description
@@ -100,3 +111,4 @@ Return a summary:
 - Prefer "stated" strength over "inferred" unless clearly implied
 - Do NOT fabricate facts — only extract what's actually in the text
 - If text is mostly code/tool output with no conversational knowledge, mark as distilled with 0 facts
+- Prefer one fact-with-reason over two facts-without. Length cost is worth it — stale facts with reasoning are recoverable, stale facts without are dead weight

data/lib/claude_memory/commands/stats_command.rb

@@ -13,13 +13,15 @@ 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, 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("--stale", "Show facts not recalled in CLAUDE_MEMORY_STALE_DAYS (default 14)") { o[:stale] = true }
             parser.on("--since DAYS", Integer, "Limit --tools 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 +30,10 @@ module ClaudeMemory
           return print_mcp_tool_call_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 +54,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

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