claude_memory 0.9.0 → 0.10.0

data/lib/claude_memory/hook/auto_memory_mirror.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "json"
+
+module ClaudeMemory
+  module Hook
+    # Mirrors Claude Code auto-memory (~/.claude/projects/<slug>/memory/*.md)
+    # into extraction candidates surfaced alongside the SessionStart distillation
+    # prompt. Diffs files against a per-project state file (mtime+md5) so only
+    # new or changed entries are emitted. Idempotent — unchanged files are
+    # skipped on re-run.
+    #
+    # The emission is a *hint* to Claude that auto-memory has content worth
+    # mirroring into claude_memory via `memory.store_extraction`. The mirror
+    # never writes facts itself; the normal extraction review flow still applies.
+    class AutoMemoryMirror
+      MAX_CANDIDATES = 5
+      MAX_TEXT_PER_ITEM = 1500
+      STATE_FILENAME = "auto_memory_mirror.json"
+
+      # Derive auto-memory directory from a project path using Claude Code's
+      # slug convention (path separators → hyphens). E.g.
+      # `/Users/me/src/app` → `~/.claude/projects/-Users-me-src-app/memory`.
+      def self.default_dir(project_path, claude_config_dir)
+        slug = project_path.to_s.tr("/", "-")
+        File.join(claude_config_dir, "projects", slug, "memory")
+      end
+
+      def self.default_state_file(project_path)
+        File.join(project_path, ".claude", STATE_FILENAME)
+      end
+
+      def initialize(auto_memory_dir:, state_file:)
+        @auto_memory_dir = auto_memory_dir
+        @state_file = state_file
+      end
+
+      # @return [Array<Hash>] candidate entries — each {name:, path:, content:, signature:}
+      def pending_candidates(limit: MAX_CANDIDATES)
+        return [] unless Dir.exist?(@auto_memory_dir)
+
+        state = load_state
+        files = Dir.glob(File.join(@auto_memory_dir, "*.md")).sort_by { |p| -File.mtime(p).to_i }
+
+        files.each_with_object([]) do |path, candidates|
+          break candidates if candidates.size >= limit
+          name = File.basename(path)
+          signature = file_signature(path)
+          prior = state[name]
+          next if prior.is_a?(Hash) && prior["md5"] == signature[:md5]
+
+          candidates << {
+            name: name,
+            path: path,
+            content: Core::TextBuilder.truncate(safe_read(path), MAX_TEXT_PER_ITEM),
+            signature: signature
+          }
+        end
+      rescue => e
+        ClaudeMemory.logger.warn("AutoMemoryMirror#pending_candidates failed: #{e.message}")
+        []
+      end
+
+      # Record the given candidates as the new baseline so they won't be
+      # re-emitted until their content changes. Call only after the candidates
+      # have actually been surfaced to the user.
+      def commit(candidates)
+        return if candidates.empty?
+
+        state = load_state
+        candidates.each do |c|
+          state[c[:name]] = {"md5" => c[:signature][:md5], "mtime" => c[:signature][:mtime]}
+        end
+        write_state(state)
+      rescue => e
+        ClaudeMemory.logger.warn("AutoMemoryMirror#commit failed: #{e.message}")
+      end
+
+      private
+
+      def file_signature(path)
+        bytes = safe_read(path)
+        {
+          md5: Digest::MD5.hexdigest(bytes),
+          mtime: File.mtime(path).to_i
+        }
+      end
+
+      def safe_read(path)
+        File.read(path)
+      rescue => e
+        ClaudeMemory.logger.debug("AutoMemoryMirror read failed for #{path}: #{e.message}")
+        ""
+      end
+
+      def load_state
+        return {} unless File.exist?(@state_file)
+        parsed = JSON.parse(File.read(@state_file))
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def write_state(state)
+        FileUtils.mkdir_p(File.dirname(@state_file))
+        File.write(@state_file, JSON.pretty_generate(state))
+      end
+    end
+  end
+end

data/lib/claude_memory/hook/context_injector.rb

@@ -11,6 +11,7 @@ module ClaudeMemory
       MAX_ARCHITECTURE = 5
       MAX_UNDISTILLED = 3
       MAX_TEXT_PER_ITEM = 1500
+      MAX_MIRROR_CANDIDATES = 5
 
       FRESH_SESSION_SOURCES = %w[startup resume clear].freeze
 
@@ -20,13 +21,31 @@ module ClaudeMemory
         architecture: {query: "uses framework implements architecture pattern", scope: "all"}
       }.freeze
 
-      def initialize(manager, source: nil)
+      # Fact IDs and subjects that `generate_context` injected on the most recent
+      # call. Both are empty until `generate_context` has been invoked. Populated
+      # in call order (decisions → conventions → architecture) so benchmark
+      # harnesses can attribute sections if they care.
+      #
+      # emitted_facts_by_scope groups the IDs by the DB they came from
+      # ({"project" => [...], "global" => [...]}) so telemetry can resolve
+      # each fact from the correct store. Fact IDs autoincrement per-DB,
+      # so a bare ID without scope is ambiguous.
+      attr_reader :emitted_fact_ids, :emitted_subjects, :emitted_facts_by_scope
+
+      def initialize(manager, source: nil, auto_memory_mirror: nil)
         @manager = manager
         @source = source
         @recall = Recall.new(manager)
+        @auto_memory_mirror = auto_memory_mirror
+        @emitted_fact_ids = []
+        @emitted_subjects = []
+        @emitted_facts_by_scope = Hash.new { |h, k| h[k] = [] }
       end
 
       def generate_context
+        @emitted_fact_ids = []
+        @emitted_subjects = []
+        @emitted_facts_by_scope = Hash.new { |h, k| h[k] = [] }
         sections = []
 
         decisions = fetch(:decisions, MAX_DECISIONS)
@@ -41,6 +60,12 @@ module ClaudeMemory
         if fresh_session?
           undistilled = fetch_undistilled(MAX_UNDISTILLED)
           sections << format_distillation_prompt(undistilled) if undistilled.any?
+
+          mirror_candidates = fetch_mirror_candidates(MAX_MIRROR_CANDIDATES)
+          if mirror_candidates.any?
+            sections << format_auto_memory_mirror(mirror_candidates)
+            auto_memory_mirror.commit(mirror_candidates)
+          end
         end
 
         return nil if sections.empty?
@@ -57,7 +82,20 @@ module ClaudeMemory
       def fetch(category, limit)
         config = QUERIES.fetch(category)
         results = @recall.query(config[:query], limit: limit, scope: config[:scope])
-        results.map { |r| format_fact(r[:fact]) }
+        results.filter_map do |r|
+          fact = r[:fact]
+          next unless fact
+          formatted = format_fact(fact)
+          next unless formatted
+          if fact[:id]
+            @emitted_fact_ids << fact[:id]
+            scope_key = (r[:source] || fact[:scope] || "project").to_s
+            @emitted_facts_by_scope[scope_key] << fact[:id]
+          end
+          subject = fact[:subject_name] || fact[:subject_entity_id]
+          @emitted_subjects << subject.to_s if subject
+          formatted
+        end
       rescue => e
         ClaudeMemory.logger.debug("ContextInjector#fetch(#{category}) failed: #{e.message}")
         []
@@ -104,7 +142,13 @@ module ClaudeMemory
           "followed by `memory.mark_distilled` for each item.",
           "",
           "**What to extract:** technology decisions, conventions, preferences, architecture",
-          "**What to skip:** debugging steps, code output, transient errors"
+          "**What to skip:** debugging steps, code output, transient errors",
+          "",
+          "**Reasoning requirement:** decisions and conventions MUST embed a reason",
+          "in the object (e.g., \"… because …\", \"… so that …\", \"caused by …\",",
+          "\"breaks when …\"). A fact with a reason is recoverable once stale; a",
+          "bare conclusion is dead weight. Prefer one fact-with-reason over two",
+          "facts-without."
         ]
 
         items.each do |item|
@@ -126,6 +170,56 @@ module ClaudeMemory
         items.each { |item| lines << "- #{item}" }
         lines.join("\n")
       end
+
+      def fetch_mirror_candidates(limit)
+        mirror = auto_memory_mirror
+        return [] unless mirror
+        mirror.pending_candidates(limit: limit)
+      rescue => e
+        ClaudeMemory.logger.warn("ContextInjector#fetch_mirror_candidates failed: #{e.message}")
+        []
+      end
+
+      def auto_memory_mirror
+        @auto_memory_mirror ||= build_default_mirror
+      end
+
+      def build_default_mirror
+        project_path = @manager.respond_to?(:project_path) ? @manager.project_path : nil
+        return nil unless project_path
+
+        config = Configuration.new
+        AutoMemoryMirror.new(
+          auto_memory_dir: AutoMemoryMirror.default_dir(project_path, config.claude_config_dir),
+          state_file: AutoMemoryMirror.default_state_file(project_path)
+        )
+      rescue => e
+        ClaudeMemory.logger.debug("ContextInjector#build_default_mirror failed: #{e.message}")
+        nil
+      end
+
+      def format_auto_memory_mirror(candidates)
+        lines = [
+          "## Auto-Memory Mirror Candidates",
+          "",
+          "The following auto-memory entries (from `~/.claude/projects/<slug>/memory/`)",
+          "are new or changed since the last mirror. Consider extracting them into",
+          "claude_memory via `memory.store_extraction` so future sessions can recall",
+          "them via `memory.conventions` / `memory.recall_semantic`.",
+          "",
+          "**Review discipline applies:** only extract high-signal entries (gotchas,",
+          "feedback, references). Skip transient project state. Preserve the `**Why:**`",
+          "and `**How to apply:**` reasoning when present."
+        ]
+
+        candidates.each do |candidate|
+          lines << ""
+          lines << "### #{candidate[:name]}"
+          lines << candidate[:content]
+        end
+
+        lines.join("\n")
+      end
     end
   end
 end

data/lib/claude_memory/hook/handler.rb

@@ -22,6 +22,8 @@ module ClaudeMemory
         raise PayloadError, "Missing required field: session_id" if session_id.nil? || session_id.empty?
         raise PayloadError, "Missing required field: transcript_path" if transcript_path.nil? || transcript_path.empty?
 
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         ingester = Ingest::Ingester.new(@store, env: @env)
         result = ingester.ingest(
           source: "claude_code",
@@ -36,31 +38,64 @@ module ClaudeMemory
           )
         end
 
+        log_activity("hook_ingest",
+          status: (result[:status] == :ingested) ? "success" : "skipped",
+          session_id: session_id, t0: t0,
+          details: {bytes_read: result[:bytes_read], content_id: result[:content_id],
+                    reason: result[:reason]}.compact)
+
         result
       rescue Ingest::TranscriptReader::FileNotFoundError => e
-        # Transcript file doesn't exist (e.g., headless Claude session)
-        # This is expected, not an error - return success with no-op status
+        log_activity("hook_ingest", status: "skipped", session_id: session_id, t0: t0,
+          details: {reason: "transcript_not_found"})
         {status: :skipped, reason: "transcript_not_found", message: e.message}
       end
 
       def sweep(payload)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         budget = payload.fetch("budget", DEFAULT_SWEEP_BUDGET).to_i
         sweeper = Sweep::Sweeper.new(@store)
         stats = sweeper.run!(budget_seconds: budget)
+        stats[:recall_timestamps_refreshed] = refresh_recall_timestamps
+
+        log_activity("hook_sweep", status: "success", t0: t0,
+          details: {elapsed_seconds: stats[:elapsed_seconds],
+                    budget_honored: stats[:budget_honored]})
 
         {stats: stats}
       end
 
+      # Sweep-derived staleness data. Skips silently if the sweep was given a
+      # store-only handler (no manager); the cross-DB refresher requires the
+      # manager because project events can touch global facts and vice versa.
+      def refresh_recall_timestamps
+        return {project: 0, global: 0} unless @manager
+        Sweep::RecallTimestampRefresher.new(@manager).refresh!
+      rescue Sequel::DatabaseError => e
+        ClaudeMemory.logger.debug("recall timestamp refresh failed: #{e.message}")
+        {project: 0, global: 0, error: e.message}
+      end
+
       def publish(payload)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         mode = payload.fetch("mode", "shared").to_sym
         since = payload["since"]
         rules_dir = payload["rules_dir"]
 
         publisher = Publish.new(@store)
-        publisher.publish!(mode: mode, since: since, rules_dir: rules_dir)
+        result = publisher.publish!(mode: mode, since: since, rules_dir: rules_dir)
+
+        log_activity("hook_publish", status: "success", t0: t0,
+          details: {mode: mode.to_s, publish_status: result[:status].to_s})
+
+        result
       end
 
       def context(payload)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         manager = @manager || build_manager(payload)
         manager.ensure_both!
 
@@ -68,13 +103,25 @@ module ClaudeMemory
         injector = ContextInjector.new(manager, source: source)
         context_text = injector.generate_context
 
+        log_activity("hook_context",
+          status: context_text ? "success" : "skipped", t0: t0,
+          details: {context_length: context_text&.length, source: source})
+
         {status: :ok, context: context_text}
       rescue => e
+        log_activity("hook_context", status: "error", t0: t0,
+          details: {error: e.message})
         {status: :error, context: nil, message: e.message}
       end
 
       private
 
+      def log_activity(event_type, status:, session_id: nil, t0: nil, details: nil)
+        duration_ms = t0 ? ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round : nil
+        ActivityLog.record(@store, event_type: event_type, status: status,
+          session_id: session_id, duration_ms: duration_ms, details: details)
+      end
+
       def build_manager(payload)
         project_path = payload["project_path"] || @config.project_dir
         Store::StoreManager.new(project_path: project_path, env: @env)

data/lib/claude_memory/mcp/handlers/management_handlers.rb

@@ -29,6 +29,13 @@ module ClaudeMemory
             signals: []
           )
 
+          # Guard against the LLM distiller labeling descriptions of external
+          # projects (LOC counts, star counts, "X is a plugin by …") as
+          # `convention`. Retag those as `reference` before resolution so
+          # they don't pollute the Knowledge-base conventions list or get
+          # returned by `memory.conventions`.
+          extraction = Distill::ReferenceMaterialDetector.new.reclassify(extraction)
+
           resolver = Resolve::Resolver.new(store)
           result = resolver.apply(
             extraction,
@@ -41,6 +48,7 @@ module ClaudeMemory
           {
             success: true,
             scope: scope,
+            content_item_id: content_item_id,
             entities_created: result[:entities_created],
             facts_created: result[:facts_created],
             facts_superseded: result[:facts_superseded],

data/lib/claude_memory/mcp/query_guide.rb

@@ -11,6 +11,17 @@ module ClaudeMemory
       PROMPT_TEXT = <<~GUIDE
         # ClaudeMemory Search Strategy Guide
 
+        ## Mental Model — V = R/C
+
+        Memory's value per interaction is governed by one relation:
+
+        - **R** — judgment retained from prior interactions (decisions, corrections, reasons, why-lines)
+        - **C** — context that must be rebuilt from scratch each session
+
+        **Goal**: raise R, lower C. Recall relevant facts (↑R) using the cheapest tool that answers the question (↓C). Repeat-corrections and re-derivations are the clearest failure signals — both mean R didn't propagate.
+
+        Every tool below is an instrument for one of those two levers. Pick accordingly.
+
         ## Tool Escalation — Cheap to Expensive
 
         Start with fast, cheap tools. Escalate only when you need more detail.

data/lib/claude_memory/mcp/server.rb

@@ -59,8 +59,9 @@ module ClaudeMemory
         rescue JSON::ParserError => e
           send_error(-32700, "Parse error: #{e.message}", 0)
         rescue => e
-          request_id = request&.fetch("id", nil) || 0
-          send_error(-32603, "Internal error: #{e.message}", request_id)
+          # Per JSON-RPC 2.0: never respond to notifications, even on error
+          request_id = request&.fetch("id", nil)
+          send_error(-32603, "Internal error: #{e.message}", request_id) unless request_id.nil?
         end
       end
 
@@ -69,6 +70,11 @@ module ClaudeMemory
         id = request["id"]
         method = request["method"]
 
+        # Per JSON-RPC 2.0: a request without an id is a notification and
+        # MUST NOT receive a response. MCP relies on this for
+        # `notifications/initialized` after the initialize handshake.
+        return nil if id.nil?
+
         case method
         when "initialize"
           handle_initialize(id, request["params"])

data/lib/claude_memory/mcp/text_summary.rb

@@ -31,6 +31,8 @@ module ClaudeMemory
         when "memory.undistilled" then summarize_undistilled(result)
         when "memory.mark_distilled" then summarize_mark_distilled(result)
         when "memory.check_setup" then summarize_check_setup(result)
+        when "memory.activity" then summarize_activity(result)
+        when "memory.list_projects" then summarize_list_projects(result)
         else JSON.generate(result)
         end
       end
@@ -275,6 +277,33 @@ module ClaudeMemory
         lines.join("\n")
       end
 
+      def self.summarize_activity(result)
+        events = result[:events] || []
+        return "No activity events recorded." if events.empty?
+
+        summary = result[:summary] || {}
+        lines = ["#{result[:event_count]} event(s):"]
+        summary.each do |type, counts|
+          parts = counts.map { |status, count| "#{count} #{status}" }
+          lines << "  #{type}: #{parts.join(", ")}"
+        end
+        lines.join("\n")
+      end
+
+      def self.summarize_list_projects(result)
+        lines = ["Projects:"]
+        if result[:global]
+          lines << "- Global: #{result[:global][:facts_active] || 0} active facts"
+        end
+        if result[:current_project]
+          lines << "- Current: #{result[:current_project][:facts_active] || 0} active facts"
+        end
+        (result[:other_projects] || []).each do |p|
+          lines << "- #{p[:path]}: #{p[:facts_active] || 0} active facts"
+        end
+        lines.join("\n")
+      end
+
       # Format fact identifier: prefer docid if available, fall back to integer id
       def self.fact_label(fact)
         fact[:docid] || fact[:id]

data/lib/claude_memory/mcp/tool_definitions.rb

@@ -438,6 +438,19 @@ module ClaudeMemory
               properties: {}
             },
             annotations: READ_ONLY
+          },
+          {
+            name: "memory.activity",
+            description: "View recent activity events (hook executions, recalls, context injections). Shows what happened behind the scenes for debugging and observability.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                limit: {type: "integer", default: 50, description: "Maximum events to return"},
+                event_type: {type: "string", enum: %w[hook_ingest hook_context hook_sweep hook_publish recall store_extraction], description: "Filter by event type"},
+                since: {type: "string", description: "ISO 8601 timestamp lower bound"}
+              }
+            },
+            annotations: READ_ONLY
           }
         ]
       end

data/lib/claude_memory/mcp/tools.rb

@@ -44,11 +44,34 @@ module ClaudeMemory
         ToolDefinitions.all
       end
 
+      # Tools that represent recall/query usage - tracked for efficacy
+      RECALL_TOOLS = %w[
+        memory.recall memory.recall_index memory.recall_semantic
+        memory.search_concepts memory.decisions memory.conventions memory.architecture
+      ].freeze
+
+      # Write tools worth tracking
+      WRITE_TOOLS = %w[memory.store_extraction].freeze
+
+      TRACKED_TOOLS = (RECALL_TOOLS + WRITE_TOOLS).freeze
+
       # Dispatch a tool call to the appropriate handler method.
       # @param name [String] fully-qualified tool name (e.g. "memory.recall")
       # @param arguments [Hash] tool arguments from the MCP request
       # @return [Hash] structured result hash for the tool response
       def call(name, arguments)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        result = dispatch(name, arguments)
+
+        log_tool_activity(name, arguments, result, t0) if TRACKED_TOOLS.include?(name)
+
+        result
+      end
+
+      private
+
+      def dispatch(name, arguments)
         case name
         when "memory.recall" then recall(arguments)
         when "memory.recall_index" then recall_index(arguments)
@@ -74,6 +97,7 @@ module ClaudeMemory
         when "memory.mark_distilled" then mark_distilled(arguments)
         when "memory.check_setup" then check_setup
         when "memory.list_projects" then list_projects
+        when "memory.activity" then activity(arguments)
         else {error: "Unknown tool: #{name}"}
         end
       end
@@ -111,6 +135,130 @@ module ClaudeMemory
           @legacy_store
         end
       end
+
+      def log_tool_activity(name, arguments, result, t0)
+        store = default_store
+        return unless store
+
+        duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
+        event_type = WRITE_TOOLS.include?(name) ? "store_extraction" : "recall"
+        status = result[:error] ? "error" : "success"
+        session_id = extract_session_id(arguments)
+
+        details = {tool: name}
+        if event_type == "recall"
+          details[:query] = arguments["query"] || arguments["concepts"]&.join(", ")
+          details[:scope] = arguments["scope"]
+          details[:result_count] = extract_result_count(result)
+          # top_fact_ids is a flat list of the first 5 IDs; top_facts_by_scope
+          # groups the same IDs by source so dashboard readers can resolve
+          # each ID from the DB it actually came from. Fact IDs autoincrement
+          # per-DB, so a bare ID without scope is ambiguous.
+          scoped = extract_top_facts_scoped(result)
+          details[:top_fact_ids] = scoped.values.flatten.first(5)
+          details[:top_facts_by_scope] = scoped if scoped.any?
+          details[:results_by_scope] = extract_scope_breakdown(result)
+        else
+          details[:facts_created] = result[:facts_created]
+          details[:entities_created] = result[:entities_created]
+          details[:content_item_id] = result[:content_item_id]
+        end
+
+        ActivityLog.record(store, event_type: event_type, status: status,
+          session_id: session_id, duration_ms: duration_ms, details: details.compact)
+      end
+
+      # Probe a recall result for a count of returned items. Falls back to
+      # counting the first array-valued key among the shapes emitted by the
+      # various recall handlers (facts, results, items, concepts).
+      def extract_result_count(result)
+        return 0 unless result.is_a?(Hash)
+        [:fact_count, :count, :results_count].each do |key|
+          val = result[key]
+          return val if val.is_a?(Integer)
+        end
+        [:facts, :results, :items, :concepts, :conflicts].each do |key|
+          val = result[key]
+          return val.size if val.is_a?(Array)
+        end
+        0
+      end
+
+      # Capture up to 5 fact ids from a recall result, grouped by source scope.
+      # Fact IDs autoincrement per-DB, so without scope a bare ID is ambiguous
+      # (project fact #1 and global fact #1 are different facts). Recall rows
+      # carry either a :source or :scope field identifying which DB the fact
+      # came from; we use that to group.
+      #
+      # @return [Hash{String => Array<Integer>}] e.g. {"project" => [5, 8], "global" => [1]}
+      def extract_top_facts_scoped(result, limit: 5)
+        return {} unless result.is_a?(Hash)
+        collection = [:facts, :results, :items].map { |k| result[k] }.find { |v| v.is_a?(Array) }
+        return {} unless collection
+
+        grouped = Hash.new { |h, k| h[k] = [] }
+        collection.first(limit).each do |row|
+          next unless row.is_a?(Hash)
+          fact = row[:fact] || row["fact"] || row
+          id = fact.is_a?(Hash) ? (fact[:id] || fact["id"]) : nil
+          next unless id
+          scope = row[:source] || row["source"] || fact[:scope] || fact["scope"] || "project"
+          grouped[scope.to_s] << id
+        end
+        grouped
+      end
+
+      def extract_session_id(arguments)
+        (arguments.is_a?(Hash) && arguments["session_id"]) || Configuration.new.session_id
+      end
+
+      # Count returned items grouped by their :scope field so the dashboard
+      # can show whether a recall's hits came from global preferences, project
+      # facts, or both. Returns nil when the result shape doesn't carry facts.
+      # @return [Hash{String => Integer}, nil]
+      def extract_scope_breakdown(result)
+        return nil unless result.is_a?(Hash)
+        collection = [:facts, :results, :items].map { |k| result[k] }.find { |v| v.is_a?(Array) }
+        return nil unless collection
+
+        breakdown = Hash.new(0)
+        collection.each { |row|
+          next unless row.is_a?(Hash)
+          scope = row[:scope] || row["scope"] || row[:source] || row["source"] || "unknown"
+          breakdown[scope.to_s] += 1
+        }
+        breakdown.empty? ? nil : breakdown
+      end
+
+      # Return whichever store is available for activity logging. Delegates
+      # to StoreManager#default_store which prefers the project store and
+      # falls back to global — preventing silent drops of activity events
+      # when the project DB hasn't been initialized yet.
+      def default_store
+        return @legacy_store unless @manager
+        @manager.default_store(prefer: :project)
+      end
+
+      def activity(args)
+        store = default_store
+        return {error: "No database available"} unless store
+
+        limit = args["limit"] || 50
+        event_type = args["event_type"]
+        since = args["since"]
+
+        events = ActivityLog.recent(store, limit: limit, event_type: event_type, since: since)
+        summary = ActivityLog.summary(store, since: since)
+
+        {
+          event_count: events.size,
+          summary: summary,
+          events: events.map { |e|
+            e[:occurred_ago] = Core::RelativeTime.format(e[:occurred_at])
+            e
+          }
+        }
+      end
     end
   end
 end