claude_memory 0.10.0 → 0.12.0

data/lib/claude_memory/audit/runner.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Audit
+    # Orchestrates the audit: opens a StoreManager, runs every check in
+    # CHECK_METHODS, collects findings, computes an exit code.
+    #
+    # The runner itself is read-only. Suggestions in each Finding name
+    # the commands a user (or skill) would run to remediate; the audit
+    # never writes.
+    class Runner
+      CHECK_METHODS = %i[
+        open_conflicts
+        single_cardinality_multiplicity
+        single_cardinality_churn
+        distillation_backlog
+        shortcut_decision_leak
+        shortcut_convention_scope
+        duplicate_global_conventions
+        bare_conclusion_rate
+        project_starvation
+        auto_memory_unimported
+      ].freeze
+
+      Result = Data.define(:findings, :stats) do
+        def errors = findings.select(&:error?)
+        def warnings = findings.select(&:warn?)
+        def info = findings.select(&:info?)
+        def ok? = errors.empty?
+        def exit_code = ok? ? 0 : 1
+      end
+
+      def initialize(manager: nil)
+        @manager = manager || Store::StoreManager.new
+      end
+
+      def run
+        findings = CHECK_METHODS.flat_map { |method| Checks.public_send(method, @manager) }
+        Result.new(findings: findings, stats: collect_stats)
+      end
+
+      private
+
+      def collect_stats
+        global = @manager.store_if_exists("global")
+        project = @manager.store_if_exists("project")
+        {
+          checks_run: CHECK_METHODS.size,
+          global: store_stats(global),
+          project: store_stats(project)
+        }
+      end
+
+      def store_stats(store)
+        return nil unless store
+        {
+          active_facts: store.facts.where(status: "active").count,
+          predicate_counts: predicate_distribution(store)
+        }
+      end
+
+      def predicate_distribution(store)
+        store.facts
+          .where(status: "active")
+          .group_and_count(:predicate)
+          .all
+          .map { |row| [row[:predicate], row[:count]] }
+          .sort_by { |_, c| -c }
+          .to_h
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/audit_command.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Runs the memory health audit and prints findings. Exits non-zero
+    # when error-severity findings are present (unless --no-exit is
+    # given). JSON output is the stable surface — humans should not
+    # script against the text output.
+    class AuditCommand < BaseCommand
+      SEVERITY_RANK = {info: 0, warn: 1, error: 2}.freeze
+
+      def call(args)
+        opts = parse_opts(args)
+        return 1 if opts.nil?
+
+        manager = Store::StoreManager.new
+        result = Audit::Runner.new(manager: manager).run
+        filtered = filter_by_severity(result.findings, opts[:severity])
+
+        if opts[:json]
+          stdout.puts JSON.pretty_generate(payload(result, filtered))
+        else
+          render_text(result, filtered)
+        end
+
+        manager.close
+        opts[:no_exit] ? 0 : result.exit_code
+      end
+
+      def filter_by_severity(findings, threshold)
+        return findings if threshold.nil?
+        floor = SEVERITY_RANK.fetch(threshold) { return findings }
+        findings.select { |f| SEVERITY_RANK[f.severity] >= floor }
+      end
+
+      private
+
+      def parse_opts(args)
+        options = {json: false, no_exit: false, severity: nil}
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: claude-memory audit [--json] [--no-exit] [--severity=error|warn|info]"
+          o.on("--json", "Emit JSON instead of text") { options[:json] = true }
+          o.on("--no-exit", "Always exit 0 even on error-severity findings") { options[:no_exit] = true }
+          o.on("--severity LEVEL", "Only show findings at or above LEVEL (error|warn|info)") { |v| options[:severity] = v.to_sym }
+        end
+        parser.parse!(args.dup)
+        options
+      rescue OptionParser::InvalidOption => e
+        stderr.puts e.message
+        nil
+      end
+
+      def payload(result, filtered)
+        {
+          ok: result.ok?,
+          checks_run: result.stats[:checks_run],
+          counts: {
+            error: result.errors.size,
+            warn: result.warnings.size,
+            info: result.info.size
+          },
+          stats: result.stats.except(:checks_run),
+          findings: filtered.map(&:to_h)
+        }
+      end
+
+      def render_text(result, filtered)
+        stdout.puts "Memory health audit — #{Time.now.utc.iso8601}"
+        stdout.puts("=" * 60)
+        render_stats(result.stats)
+        stdout.puts ""
+        render_summary(result)
+        stdout.puts ""
+        render_findings(filtered)
+        stdout.puts ""
+        stdout.puts(result.ok? ? "OK" : "FAIL")
+      end
+
+      def render_stats(stats)
+        %i[global project].each do |scope|
+          s = stats[scope]
+          next unless s
+          preds = s[:predicate_counts].map { |k, v| "#{k}=#{v}" }.join(", ")
+          stdout.puts "#{scope.to_s.capitalize.ljust(7)} #{s[:active_facts]} active facts  #{preds}"
+        end
+      end
+
+      def render_summary(result)
+        stdout.puts "Checks run: #{result.stats[:checks_run]}"
+        stdout.puts "Errors: #{result.errors.size}   Warnings: #{result.warnings.size}   Info: #{result.info.size}"
+      end
+
+      def render_findings(findings)
+        if findings.empty?
+          stdout.puts "No findings."
+          return
+        end
+
+        findings.each do |f|
+          marker = case f.severity
+          when :error then "[ERROR]"
+          when :warn then "[WARN]"
+          when :info then "[INFO]"
+          end
+          stdout.puts "#{marker} #{f.id}  #{f.title}"
+          stdout.puts "  #{f.detail}"
+          stdout.puts "  → #{f.suggestion}"
+          stdout.puts "  fact_ids: #{f.fact_ids.first(20).inspect}#{"  (+#{f.fact_ids.size - 20} more)" if f.fact_ids.size > 20}" if f.fact_ids.any?
+          stdout.puts ""
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/dashboard_command.rb

@@ -36,7 +36,8 @@ module ClaudeMemory
         manager.ensure_global! if manager.global_exists?
         manager.ensure_project! if manager.project_exists?
 
-        stdout.puts "Starting ClaudeMemory dashboard on http://localhost:#{opts[:port]}"
+        stdout.puts "Starting ClaudeMemory dashboard on http://127.0.0.1:#{opts[:port]}"
+        stdout.puts "OTel receiver listening at http://127.0.0.1:#{opts[:port]}/v1/{metrics,logs,traces}"
         stdout.puts "Press Ctrl+C to stop."
 
         server = Dashboard::Server.new(

data/lib/claude_memory/commands/digest_command.rb

@@ -5,9 +5,11 @@ require "optparse"
 module ClaudeMemory
   module Commands
     # Weekly digest — a markdown summary of what memory did over the last N days.
-    # Rolls up moment counts, new knowledge, utilization, conflicts, and user
-    # feedback so users can see the value memory is delivering without
-    # needing to visit the dashboard.
+    # Sections (in order): Activity, Context cost, Quality, New knowledge,
+    # Utilization, Conflicts, Feedback. The Context cost and Quality
+    # sections (added 0.11.0) read from `Dashboard::Trust#token_budget` and
+    # `#quality_score` so users see the cost/pollution side-by-side with
+    # the value side without needing to visit the dashboard.
     #
     # The data it aggregates all already exists (activity_events, facts,
     # conflicts, moment_feedback); this command only shapes it into a report.
@@ -48,6 +50,10 @@ module ClaudeMemory
         lines << ""
         lines << activity_section(manager, cutoff)
         lines << ""
+        lines << context_cost_section(manager)
+        lines << ""
+        lines << quality_section(manager, cutoff)
+        lines << ""
         lines << knowledge_section(manager, cutoff)
         lines << ""
         lines << utilization_section(manager)
@@ -124,6 +130,92 @@ module ClaudeMemory
         "## New knowledge\n\n_Unavailable: #{e.message}_"
       end
 
+      # The token cost of every SessionStart context injection, measured over
+      # the last 30 days (Trust panel's window — intentionally wider than the
+      # digest's coverage window so percentiles stay statistically meaningful
+      # on quiet weeks). Reports zero state explicitly so users know whether a
+      # missing number means "no injections" vs. "telemetry didn't fire".
+      def context_cost_section(manager)
+        tb = Dashboard::Trust.new(manager).token_budget
+        out = ["## Context cost", ""]
+        if tb[:sample_size].zero?
+          out << "_No context injections in the last #{tb[:window_days]} days._"
+        else
+          out << "**Per-session injected tokens (last #{tb[:window_days]}d, n=#{tb[:sample_size]}):**"
+          out << "- p50: #{tb[:p50]} tokens"
+          out << "- p95: #{tb[:p95]} tokens"
+          out << "- avg: #{tb[:avg]} tokens"
+        end
+        out.join("\n")
+      rescue Sequel::DatabaseError => e
+        "## Context cost\n\n_Unavailable: #{e.message}_"
+      end
+
+      # Hallucination-rate proxy. Reports two numbers per the
+      # `quality_review.md` 2026-04-30 investigation:
+      #
+      #   - Live (last `window_days`, headline) — actionable signal of
+      #     ongoing extraction quality.
+      #   - Historical (all active facts, supplementary) — visible so
+      #     legacy noise isn't hidden, but the headline is the live one.
+      #
+      # The split exists because the unwindowed metric mixed pre-prompt-
+      # commit bare conclusions with live data; users read the combined
+      # number as "ongoing quality" and that's misleading.
+      def quality_section(manager, cutoff)
+        out = ["## Quality", ""]
+        qs = Dashboard::Trust.new(manager).quality_score
+
+        if qs[:total_active].zero?
+          if qs[:historical][:total_active].zero?
+            out << "_No active facts to score yet._"
+          else
+            out << "_No facts extracted in the last #{qs[:window_days]} days._"
+            out << "- Historical (all active): score #{qs[:historical][:score]}/100, " \
+              "#{qs[:historical][:total_active]} facts, " \
+              "#{qs[:historical][:bare_conclusion_count]} bare, " \
+              "#{qs[:historical][:suspect_count]} suspect"
+          end
+        else
+          out << "**Live score (last #{qs[:window_days]}d):** #{qs[:score]}/100 _(higher is cleaner)_"
+          out << "- Suspect (reference material): #{qs[:suspect_count]} (#{qs[:suspect_pct]}%)"
+          out << "- Bare conclusions (decision/convention without reason): #{qs[:bare_conclusion_count]} (#{qs[:bare_pct]}%)"
+          if qs[:historical][:total_active] > qs[:total_active]
+            out << ""
+            out << "_Historical (all active): score #{qs[:historical][:score]}/100, " \
+              "#{qs[:historical][:total_active]} facts, " \
+              "#{qs[:historical][:bare_conclusion_count]} bare, " \
+              "#{qs[:historical][:suspect_count]} suspect_"
+          end
+        end
+
+        rate = rejection_rate_in_window(manager, cutoff)
+        out << ""
+        out << "**Rejection rate (in window):** #{rate[:rejected]} of #{rate[:created]} extracted facts rejected (#{rate[:pct]}%)"
+
+        out.join("\n")
+      rescue Sequel::DatabaseError => e
+        "## Quality\n\n_Unavailable: #{e.message}_"
+      end
+
+      # How many facts created in the digest window have since been
+      # rejected? Counts across both stores.
+      def rejection_rate_in_window(manager, cutoff)
+        created = 0
+        rejected = 0
+
+        %w[project global].each do |scope|
+          store = manager.store_if_exists(scope)
+          next unless store
+          dataset = store.facts.where { created_at >= cutoff }
+          created += dataset.count
+          rejected += dataset.where(status: "rejected").count
+        end
+
+        pct = created.zero? ? 0.0 : (rejected * 100.0 / created).round(1)
+        {created: created, rejected: rejected, pct: pct}
+      end
+
       def utilization_section(manager)
         util = Dashboard::Trust.new(manager).utilization
         pct = util[:ratio_pct]

data/lib/claude_memory/commands/hook_command.rb

@@ -19,9 +19,9 @@ module ClaudeMemory
           return Hook::ExitCodes::ERROR
         end
 
-        unless %w[ingest sweep publish context].include?(subcommand)
+        unless %w[ingest sweep publish context nudge].include?(subcommand)
           stderr.puts "Unknown hook command: #{subcommand}"
-          stderr.puts "Available: ingest, sweep, publish, context"
+          stderr.puts "Available: ingest, sweep, publish, context, nudge"
           return Hook::ExitCodes::ERROR
         end
 
@@ -63,6 +63,8 @@ module ClaudeMemory
           hook_publish(handler, payload)
         when "context"
           hook_context(payload, opts[:db])
+        when "nudge"
+          hook_nudge(payload, opts[:db])
         end
 
         store.close
@@ -169,6 +171,28 @@ module ClaudeMemory
         Hook::ExitCodes::SUCCESS
       end
 
+      def hook_nudge(payload, db_path)
+        # Nudge needs to count past nudge events across both stores,
+        # so prefer the manager-aware path. db_path overrides only
+        # the project store (useful for tests).
+        project_path = payload["project_path"] || payload["cwd"]
+        manager = ClaudeMemory::Store::StoreManager.new(
+          project_db_path: db_path, project_path: project_path
+        )
+        manager.ensure_both!
+        store = manager.project_store || manager.global_store
+
+        handler = ClaudeMemory::Hook::Handler.new(store, manager: manager)
+        result = handler.nudge(payload)
+
+        stdout.puts result[:message] if result[:status] == :emitted
+
+        manager.close
+        Hook::ExitCodes::SUCCESS
+      rescue => e
+        classify_error(e)
+      end
+
       def hook_context(payload, db_path)
         project_path = payload["project_path"] || payload["cwd"]
         source = payload["source"]
@@ -213,6 +237,7 @@ module ClaudeMemory
         details = {
           source: source,
           context_length: context_text&.length,
+          context_tokens: ClaudeMemory::Core::TokenEstimator.estimate(context_text),
           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),

data/lib/claude_memory/commands/import_auto_memory_command.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "digest"
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Imports Claude Code auto-memory files (~/.claude/projects/<slug>/memory/*.md)
+    # into the project database as durable facts. Before this command, those
+    # markdown files were only surfaced transiently via `Hook::AutoMemoryMirror`
+    # at SessionStart — they were invisible to `memory.recall` and the
+    # shortcut tools. Importing them as facts (predicate=convention for
+    # gotcha/feedback/project files, predicate=reference for reference
+    # type) makes that knowledge first-class queryable knowledge.
+    #
+    # Idempotent on object_literal prefix: re-running skips files whose
+    # body text is already present.
+    class ImportAutoMemoryCommand < BaseCommand
+      def call(args)
+        opts = parse_opts(args)
+        return 1 if opts.nil?
+
+        auto_dir = resolve_auto_dir
+        files = list_files(auto_dir)
+        if files.empty?
+          stdout.puts "No auto-memory files found in #{auto_dir}"
+          return 0
+        end
+
+        manager = Store::StoreManager.new
+        manager.ensure_project!
+        store = manager.project_store
+
+        imported = 0
+        skipped = 0
+        files.each do |path|
+          fact_data = parse_file(path)
+          next if fact_data.nil?
+
+          if already_imported?(store, fact_data[:object_literal])
+            skipped += 1
+            next
+          end
+
+          if opts[:dry_run]
+            stdout.puts "[DRY] #{File.basename(path)} → #{fact_data[:predicate]}"
+          else
+            insert(store, fact_data, path)
+            stdout.puts "Imported: #{File.basename(path)} → #{fact_data[:predicate]}"
+          end
+          imported += 1
+        end
+
+        stdout.puts ""
+        verb = opts[:dry_run] ? "Would import" : "Imported"
+        stdout.puts "#{verb}: #{imported}  Skipped (already present): #{skipped}"
+        manager.close
+        0
+      end
+
+      private
+
+      def parse_opts(args)
+        options = {dry_run: false}
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: claude-memory import-auto-memory [--dry-run]"
+          o.on("--dry-run", "Show what would be imported without writing") { options[:dry_run] = true }
+        end
+        parser.parse!(args.dup)
+        options
+      rescue OptionParser::InvalidOption => e
+        stderr.puts e.message
+        nil
+      end
+
+      def resolve_auto_dir
+        config = Configuration.new
+        Hook::AutoMemoryMirror.default_dir(config.project_dir, config.claude_config_dir)
+      end
+
+      def list_files(dir)
+        return [] unless Dir.exist?(dir)
+        Dir.glob(File.join(dir, "*.md")).reject { |f| File.basename(f) == "MEMORY.md" }.sort
+      end
+
+      def parse_file(path)
+        text = File.read(path)
+        return nil unless (match = text.match(/\A---\n(.*?)\n---\n(.*)\z/m))
+
+        frontmatter = match[1]
+        body = match[2].strip
+
+        name = frontmatter[/^name:\s*(.+)/, 1]&.strip
+        type = frontmatter[/^type:\s*(.+)/, 1]&.strip
+        description = frontmatter[/^description:\s*(.+)/, 1]&.strip
+        return nil if name.nil? || type.nil?
+
+        predicate, subject, scope = map_type(type)
+        object = build_object(name, description, body)
+
+        {
+          subject: subject,
+          predicate: predicate,
+          object_literal: object,
+          scope: scope
+        }
+      end
+
+      def map_type(type)
+        case type
+        when "feedback", "user"
+          ["convention", "user", "global"]
+        when "reference"
+          ["reference", "repo", "project"]
+        else
+          # gotcha, project, anything else
+          ["convention", "repo", "project"]
+        end
+      end
+
+      # Build an object string that carries a reason clause so
+      # BareConclusionDetector does not flag the fact as bare. Auto-memory
+      # files conventionally include a **Why:** section; we surface the first
+      # 400 chars of the body alongside the name as the object text.
+      def build_object(name, description, body)
+        first_para = body.split("\n\n").first.to_s.strip
+        first_para = first_para[0..400] + "..." if first_para.length > 400
+
+        parts = [name]
+        parts << description if description && !description.empty? && description != name
+        parts << first_para unless first_para.empty?
+        text = parts.join(" — ").gsub(/\s+/, " ").strip
+
+        # If no reason clause is present, attach a stable suffix so the fact
+        # is structurally distinguishable from bare conclusions.
+        text += " (imported from project auto-memory; see source file for full reasoning)" unless reason_present?(text)
+        text
+      end
+
+      def reason_present?(text)
+        text.match?(/\b(because|so that|so the|so we|in order to|to avoid|to ensure|to prevent|prevents|otherwise|caused by|breaks when)\b/i)
+      end
+
+      def already_imported?(store, object_text)
+        needle = object_text[0..80].gsub(/[%_]/) { |c| "\\#{c}" }
+        !store.facts.where(Sequel.like(:object_literal, "#{needle}%")).limit(1).all.empty?
+      end
+
+      def insert(store, fact_data, path)
+        store.db.transaction do
+          subject_type = (fact_data[:subject] == "user") ? "person" : "repo"
+          subject_id = store.find_or_create_entity(type: subject_type, name: fact_data[:subject])
+
+          fact_id = store.insert_fact(
+            subject_entity_id: subject_id,
+            predicate: fact_data[:predicate],
+            object_literal: fact_data[:object_literal],
+            scope: fact_data[:scope],
+            project_path: (fact_data[:scope] == "global") ? nil : Configuration.new.project_dir
+          )
+
+          content_id = store.upsert_content_item(
+            source: "auto_memory_import",
+            session_id: nil,
+            text_hash: Digest::SHA256.hexdigest(path + fact_data[:object_literal]),
+            byte_len: fact_data[:object_literal].bytesize,
+            raw_text: fact_data[:object_literal]
+          )
+
+          store.insert_provenance(
+            fact_id: fact_id,
+            content_item_id: content_id,
+            quote: fact_data[:object_literal][0..200],
+            strength: "stated"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/initializers/hooks_configurator.rb

@@ -19,8 +19,9 @@ module ClaudeMemory
           db_path = ClaudeMemory.project_db_path
           ingest_cmd = "claude-memory hook ingest --db #{db_path}"
           sweep_cmd = "claude-memory hook sweep --db #{db_path}"
+          nudge_cmd = "claude-memory hook nudge --db #{db_path}"
 
-          hooks_config = build_hooks_config(ingest_cmd, sweep_cmd)
+          hooks_config = build_hooks_config(ingest_cmd, sweep_cmd, nudge_cmd)
 
           existing = load_json_file(settings_path)
           existing["hooks"] ||= {}
@@ -37,8 +38,9 @@ module ClaudeMemory
           db_path = ClaudeMemory.global_db_path
           ingest_cmd = "claude-memory hook ingest --db #{db_path}"
           sweep_cmd = "claude-memory hook sweep --db #{db_path}"
+          nudge_cmd = "claude-memory hook nudge --db #{db_path}"
 
-          hooks_config = build_hooks_config(ingest_cmd, sweep_cmd)
+          hooks_config = build_hooks_config(ingest_cmd, sweep_cmd, nudge_cmd)
 
           existing = load_json_file(settings_path)
           existing["hooks"] ||= {}
@@ -96,7 +98,7 @@ module ClaudeMemory
 
         private
 
-        def build_hooks_config(ingest_cmd, sweep_cmd)
+        def build_hooks_config(ingest_cmd, sweep_cmd, nudge_cmd = "claude-memory hook nudge")
           context_cmd = "claude-memory hook context"
 
           {
@@ -132,7 +134,8 @@ module ClaudeMemory
                   {"type" => "command", "command" => ingest_cmd, "timeout" => 30,
                    "statusMessage" => "Saving memory..."},
                   {"type" => "command", "command" => sweep_cmd, "timeout" => 30,
-                   "statusMessage" => "Sweeping memory..."}
+                   "statusMessage" => "Sweeping memory..."},
+                  {"type" => "command", "command" => nudge_cmd, "timeout" => 5}
                 ]
               }],
               "TaskCompleted" => [{