claude_memory 0.9.1 → 0.11.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,117 @@ 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
+
+      # First-week ROI nudge. Computes per-session metrics (facts
+      # contributed via Stop-hook ingest, percentage of those Claude
+      # actually used in recall/context-injection) and decides whether
+      # to print to the user. Quiets after MAX_NUDGES successful runs
+      # or when CLAUDE_MEMORY_NO_NUDGE=1.
+      #
+      # The "first ~10 sessions" gate is enforced by counting prior
+      # `roi_nudge` activity events with status=success across both
+      # stores. Once the user has seen the nudge enough times, memory
+      # gets out of the way; trust is established or it isn't.
+      MAX_NUDGES = 10
+      ENV_NUDGE_OPT_OUT = "CLAUDE_MEMORY_NO_NUDGE"
+
+      def nudge(payload)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        session_id = payload["session_id"] || @config.session_id
+
+        # Cleanly silent on opt-out — no activity event, no record of
+        # having tried. Users who set the env var don't want a paper
+        # trail of suppressed nudges.
+        return {status: :silent, reason: "opt_out"} if @env[ENV_NUDGE_OPT_OUT] == "1"
+        return {status: :silent, reason: "no_session_id"} if session_id.nil? || session_id.empty?
+
+        prior = prior_nudge_count
+        if prior >= MAX_NUDGES
+          return {status: :silent, reason: "first_week_complete", prior_count: prior}
+        end
+
+        contributed_ids = session_contributed_facts(session_id)
+        n = contributed_ids.size
+
+        if n.zero?
+          # Don't burn one of the user's 10 nudge slots on an empty
+          # session. Memory contributed nothing → no trust signal to
+          # surface; come back next session with real data.
+          return {status: :silent, reason: "no_contributions", prior_count: prior}
+        end
+
+        used = session_used_facts(session_id, contributed_ids)
+        pct = (used * 100.0 / n).round
+        message = "memory contributed #{n} fact#{"s" unless n == 1} this session, %used = #{pct}%"
+
+        log_activity("roi_nudge", status: "success", session_id: session_id, t0: t0,
+          details: {n: n, used: used, pct: pct, prior_count: prior})
+
+        {
+          status: :emitted,
+          message: message,
+          n: n, used: used, pct: pct,
+          remaining: MAX_NUDGES - prior - 1
+        }
       end
 
       def context(payload)
+        t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
         manager = @manager || build_manager(payload)
         manager.ensure_both!
 
@@ -68,17 +156,117 @@ 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,
+            context_tokens: Core::TokenEstimator.estimate(context_text),
+            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)
       end
+
+      # Cross-scope nudge counter. Counts both stores so a user with
+      # global facts only doesn't bypass the first-week limit.
+      def prior_nudge_count
+        manager_or_self.then do |m|
+          %w[project global].sum do |scope|
+            store = m.respond_to?(:store_if_exists) ? m.store_if_exists(scope) : nil
+            next 0 unless store
+            store.activity_events.where(event_type: "roi_nudge", status: "success").count
+          end
+        end
+      rescue Sequel::DatabaseError
+        # If we can't read the count, err on the side of "still in
+        # first week" so users keep getting feedback while we figure
+        # out what's wrong with the DB.
+        0
+      end
+
+      # Facts whose provenance points to content_items captured in
+      # this session. Active facts only — superseded/rejected ones
+      # don't count as memory contributing.
+      def session_contributed_facts(session_id)
+        return [] unless @store
+        @store.facts
+          .join(:provenance, fact_id: :id)
+          .join(:content_items, id: Sequel[:provenance][:content_item_id])
+          .where(Sequel[:content_items][:session_id] => session_id)
+          .where(Sequel[:facts][:status] => "active")
+          .select(Sequel[:facts][:id])
+          .distinct
+          .map { |row| row[:id] }
+      rescue Sequel::DatabaseError => e
+        ClaudeMemory.logger.debug("session_contributed_facts failed: #{e.message}")
+        []
+      end
+
+      # Of the given fact ids, how many appear in top_fact_ids of any
+      # recall or hook_context activity event tagged with this
+      # session_id?
+      def session_used_facts(session_id, fact_ids)
+        return 0 if fact_ids.empty?
+        return 0 unless @store
+        target = fact_ids.to_set
+        used = Set.new
+
+        @store.activity_events
+          .where(event_type: %w[recall hook_context], status: "success")
+          .where(session_id: session_id)
+          .select(:detail_json)
+          .all
+          .each do |row|
+            details = row[:detail_json] ? JSON.parse(row[:detail_json]) : {}
+            (details["top_fact_ids"] || []).each { |id| used << id if target.include?(id) }
+          end
+
+        used.size
+      rescue Sequel::DatabaseError, JSON::ParserError => e
+        ClaudeMemory.logger.debug("session_used_facts failed: #{e.message}")
+        0
+      end
+
+      def manager_or_self
+        return @manager if @manager
+        # When the Handler was given only a single store (no manager),
+        # we still want to count nudges; treat the store like a single-
+        # scope manager via a tiny wrapper.
+        @_handler_store_facade ||= SingleStoreFacade.new(@store)
+      end
+
+      class SingleStoreFacade
+        def initialize(store)
+          @store = store
+        end
+
+        def store_if_exists(scope)
+          # The manager's store_if_exists returns nil for the absent
+          # scope; we don't know which scope this single store
+          # represents, so return it for "project" and nil for
+          # "global". Counts undercount global-only setups, which is
+          # acceptable — global-only users would normally pass a
+          # manager.
+          (scope == "project") ? @store : nil
+        end
+      end
     end
   end
 end

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/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