claude_memory 0.11.0 → 0.12.1

data/lib/claude_memory/commands/setup_vectors_command.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Guides the user through opting into vector recall with fastembed
+    # (or another provider). fastembed stays a dev/test gem dependency by
+    # design; this command is the documented opt-in path for end users.
+    #
+    # Steps:
+    #   1. Verify the chosen provider is loadable. For fastembed, surface
+    #      a clear install command if the gem isn't on $LOAD_PATH.
+    #   2. Persist CLAUDE_MEMORY_EMBEDDING_PROVIDER (and optional model)
+    #      into the project's .claude/settings.json env block, the same
+    #      mechanism Claude Code uses for OTel env (see OTel::SettingsWriter).
+    #   3. Re-embed existing facts under the new provider (unless --no-reindex).
+    #   4. Report the final state — provider, dimensions, stored alignment.
+    class SetupVectorsCommand < BaseCommand
+      OWNED_KEYS = %w[
+        CLAUDE_MEMORY_EMBEDDING_PROVIDER
+        CLAUDE_MEMORY_EMBEDDING_MODEL
+      ].freeze
+
+      FASTEMBED_INSTALL_HINT = <<~HINT
+        fastembed is not installed. claude-memory keeps fastembed as a
+        dev/test dependency so the default gem install stays light. To
+        enable it, install the gem and re-run setup-vectors:
+
+          gem install fastembed
+          claude-memory setup-vectors
+
+        Or if you bundle, add to your Gemfile:
+
+          gem "fastembed"
+
+        Then `bundle install` and re-run setup-vectors. The first run
+        downloads the BAAI/bge-small-en-v1.5 ONNX model (~75MB).
+      HINT
+
+      def call(args)
+        opts = parse_opts(args)
+        return 1 if opts.nil?
+
+        return print_status if opts[:status]
+
+        provider_name = opts[:provider]
+        unless verify_provider_loadable(provider_name)
+          return 1
+        end
+
+        if opts[:dry_run]
+          stdout.puts "Would write to #{settings_path}:"
+          stdout.puts "  CLAUDE_MEMORY_EMBEDDING_PROVIDER=#{provider_name}"
+          stdout.puts "  CLAUDE_MEMORY_EMBEDDING_MODEL=#{opts[:model]}" if opts[:model]
+          stdout.puts(opts[:reindex] ? "Would re-index facts under the new provider" : "Would skip re-index (--no-reindex)")
+          return 0
+        end
+
+        write_settings(provider_name, opts[:model])
+
+        if opts[:reindex]
+          reindex_result = reindex(provider_name)
+          return 1 if reindex_result != 0
+        else
+          stdout.puts "Skipped re-index (--no-reindex). Run 'claude-memory index --force --provider=#{provider_name}' when ready."
+        end
+
+        report_final_state(provider_name)
+        0
+      end
+
+      private
+
+      def parse_opts(args)
+        options = {provider: "fastembed", model: nil, reindex: true, dry_run: false, status: false}
+        parser = OptionParser.new do |o|
+          o.banner = "Usage: claude-memory setup-vectors [--provider=fastembed|api|tfidf] [--model=NAME] [--no-reindex] [--dry-run] [--status]"
+          o.on("--provider NAME", "Embedding provider (default: fastembed)") { |v| options[:provider] = v }
+          o.on("--model NAME", "Optional model name (e.g. BAAI/bge-small-en-v1.5)") { |v| options[:model] = v }
+          o.on("--no-reindex", "Skip re-embedding existing facts under the new provider") { options[:reindex] = false }
+          o.on("--dry-run", "Print what would change without writing or re-indexing") { options[:dry_run] = true }
+          o.on("--status", "Show the current provider config + stored alignment, then exit") { options[:status] = true }
+        end
+        parser.parse!(args.dup)
+        options
+      rescue OptionParser::InvalidOption => e
+        stderr.puts e.message
+        nil
+      end
+
+      def verify_provider_loadable(provider_name)
+        case provider_name
+        when "tfidf"
+          true # always available
+        when "fastembed"
+          require "fastembed"
+          true
+        when "api"
+          # api provider needs network + key but no gem; defer to runtime
+          true
+        else
+          stderr.puts "Unknown provider: #{provider_name}. Valid: tfidf, fastembed, api."
+          false
+        end
+      rescue LoadError
+        stderr.puts FASTEMBED_INSTALL_HINT
+        false
+      end
+
+      def settings_path
+        File.join(claude_dir, "settings.json")
+      end
+
+      def claude_dir
+        File.join(Configuration.new.project_dir, ".claude")
+      end
+
+      def write_settings(provider_name, model)
+        FileUtils.mkdir_p(claude_dir)
+        settings = load_settings
+        settings["env"] ||= {}
+        settings["env"]["CLAUDE_MEMORY_EMBEDDING_PROVIDER"] = provider_name
+        if model
+          settings["env"]["CLAUDE_MEMORY_EMBEDDING_MODEL"] = model
+        else
+          settings["env"].delete("CLAUDE_MEMORY_EMBEDDING_MODEL")
+        end
+        File.write(settings_path, JSON.pretty_generate(settings) + "\n")
+        stdout.puts "✓ Wrote CLAUDE_MEMORY_EMBEDDING_PROVIDER=#{provider_name} to #{settings_path}"
+        stdout.puts "✓ Wrote CLAUDE_MEMORY_EMBEDDING_MODEL=#{model}" if model
+      end
+
+      def load_settings
+        return {} unless File.exist?(settings_path)
+        raw = File.read(settings_path)
+        return {} if raw.strip.empty?
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError => e
+        stderr.puts "settings.json parse error: #{e.message} — refusing to overwrite"
+        {}
+      end
+
+      def reindex(provider_name)
+        stdout.puts "→ Re-embedding facts under provider=#{provider_name}…"
+        IndexCommand.new(stdout: stdout, stderr: stderr).call(["--force", "--provider", provider_name])
+      end
+
+      def report_final_state(provider_name)
+        # The settings.json write only affects future sessions (Claude Code
+        # reads the env block at session start). For the current process
+        # the ENV var isn't set, so report what Embeddings.resolve would
+        # produce under the new env.
+        env_override = ENV.to_h.merge("CLAUDE_MEMORY_EMBEDDING_PROVIDER" => provider_name)
+        provider = Embeddings.resolve(provider_name, env: env_override)
+        stdout.puts
+        stdout.puts "Provider: #{provider.name}, dimensions: #{provider.dimensions}"
+        stdout.puts "Next session will use this provider. Run 'claude-memory doctor' to verify."
+      end
+
+      def print_status
+        # Resolve under current ENV to show what the next session will use
+        provider = Embeddings.resolve
+        stdout.puts "Current provider:   #{provider.name}"
+        stdout.puts "Current dimensions: #{provider.dimensions}"
+        stdout.puts "Settings file:      #{settings_path}"
+        env = load_settings.fetch("env", {})
+        relevant = env.slice(*OWNED_KEYS)
+        if relevant.any?
+          stdout.puts "Configured env:"
+          relevant.each { |k, v| stdout.puts "  #{k}=#{v}" }
+        else
+          stdout.puts "Configured env:     (none — using default tfidf)"
+        end
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/configuration.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require "json"
 
 module ClaudeMemory
   # Centralized configuration and ENV access
@@ -66,6 +67,65 @@ module ClaudeMemory
       DEFAULT_STALE_DAYS
     end
 
+    # Threshold (in days) for the context-injection staleness marker. A
+    # single-value fact older than this and not recalled within it gets a
+    # "verify before relying" annotation when injected at SessionStart.
+    # Deliberately much longer than DEFAULT_STALE_DAYS (the dashboard's
+    # review-candidate window) — the injection marker should fire only on
+    # facts old enough to be genuinely risky, not merely unused for a
+    # couple weeks. Override via CLAUDE_MEMORY_INJECTION_STALE_DAYS.
+    DEFAULT_INJECTION_STALE_DAYS = 180
+
+    # @return [Integer] injection staleness threshold in days
+    def injection_stale_days
+      raw = env["CLAUDE_MEMORY_INJECTION_STALE_DAYS"]
+      return DEFAULT_INJECTION_STALE_DAYS if raw.nil? || raw.empty?
+      parsed = Integer(raw, 10)
+      (parsed > 0) ? parsed : DEFAULT_INJECTION_STALE_DAYS
+    rescue ArgumentError
+      DEFAULT_INJECTION_STALE_DAYS
+    end
+
+    # Whether OTel trace ingestion is opted in. Reads OTEL_TRACES_EXPORTER
+    # from .claude/settings.json's env block. Traces are off unless the
+    # value is present and non-empty and not "none". Set by
+    # `claude-memory otel --enable-traces`.
+    #
+    # @return [Boolean]
+    def otel_traces_enabled?
+      value = settings_env["OTEL_TRACES_EXPORTER"]
+      return false if value.nil?
+      stripped = value.to_s.strip
+      !stripped.empty? && stripped != "none"
+    end
+
+    # Read the env block from .claude/settings.json (project scope) so
+    # callers can inspect what Claude Code sees at session start. Returns
+    # an empty hash when the file is missing or unparseable — matches the
+    # tolerant behavior of Claude Code's settings loader.
+    #
+    # @return [Hash]
+    def settings_env
+      path = settings_json_path
+      return {} unless path
+      raw = File.read(path)
+      parsed = JSON.parse(raw)
+      env_block = parsed.is_a?(Hash) ? parsed["env"] : nil
+      env_block.is_a?(Hash) ? env_block : {}
+    rescue JSON::ParserError, Errno::ENOENT
+      {}
+    end
+
+    # Path to the project-scoped settings.json. nil when no project_dir
+    # exists (e.g. running outside any directory).
+    #
+    # @return [String, nil]
+    def settings_json_path
+      dir = project_dir
+      return nil unless dir
+      File.join(dir, ".claude", "settings.json")
+    end
+
     private
 
     def resolve_project_dir

data/lib/claude_memory/core/fact_query_builder.rb

@@ -141,6 +141,7 @@ module ClaudeMemory
             Sequel[:facts][:valid_from],
             Sequel[:facts][:valid_to],
             Sequel[:facts][:created_at],
+            Sequel[:facts][:last_recalled_at],
             Sequel[:entities][:canonical_name].as(:subject_name),
             Sequel[:facts][:scope],
             Sequel[:facts][:project_path]

data/lib/claude_memory/dashboard/api.rb

@@ -460,6 +460,14 @@ module ClaudeMemory
         Timeline.new(@manager).days
       end
 
+      def telemetry
+        Telemetry.new(@manager).snapshot
+      end
+
+      def prompt_journey(prompt_id)
+        PromptJourney.new(@manager).for(prompt_id.to_s)
+      end
+
       private
 
       CONTENT_ITEM_PREVIEW_BYTES = 8000

data/lib/claude_memory/dashboard/index.html

@@ -1044,6 +1044,16 @@
   }
   .knowledge-card .kc-meta .src.project { background: var(--accent-dim); color: var(--accent); }
   .knowledge-card .kc-meta .src.global { background: var(--purple-dim); color: var(--purple); }
+  /* Generic .src badge used by Prompt Journey rows; knowledge-card rule above
+     wins by specificity for project/global tags inside knowledge cards. */
+  .src {
+    font-family: var(--mono);
+    font-size: 10px;
+    padding: 1px 6px;
+    border-radius: 3px;
+  }
+  .src.otel { background: var(--accent-dim); color: var(--accent); }
+  .src.activity { background: var(--purple-dim); color: var(--purple); }
   .knowledge-card.highlighted {
     border-color: var(--accent);
     box-shadow: 0 0 0 3px var(--accent-dim);
@@ -1230,6 +1240,7 @@
     <div class="drawer-tab" data-adv="efficacy">Efficacy</div>
     <div class="drawer-tab" data-adv="conflicts">Conflicts</div>
     <div class="drawer-tab" data-adv="activity">Raw log</div>
+    <div class="drawer-tab" data-adv="telemetry">Telemetry</div>
   </div>
 
   <div class="drawer-panel active" id="adv-knowledge">
@@ -1360,6 +1371,54 @@
       </table>
     </div>
   </div>
+
+  <div class="drawer-panel" id="adv-telemetry">
+    <div class="adv-card" id="telemetry-status" style="font-size: 12px; color: var(--text-dim);">
+      Loading telemetry status...
+    </div>
+    <div class="adv-card" style="font-size: 11px; color: var(--text-dim);">
+      Capturing only metrics by default. Prompts and bodies require explicit opt-in via
+      <code>claude-memory otel --capture-prompts</code>.
+    </div>
+    <div class="adv-card">
+      <h3 style="margin-top: 0;">Cost (last 7 days, hourly)</h3>
+      <table>
+        <thead><tr><th>Hour</th><th style="text-align: right;">Requests</th><th style="text-align: right;">Cost USD</th></tr></thead>
+        <tbody id="telemetry-cost-tbody"></tbody>
+      </table>
+    </div>
+    <div class="adv-card">
+      <h3 style="margin-top: 0;">Tokens by model</h3>
+      <table>
+        <thead><tr><th>Model</th><th>Type</th><th style="text-align: right;">Tokens</th></tr></thead>
+        <tbody id="telemetry-tokens-tbody"></tbody>
+      </table>
+    </div>
+    <div class="adv-card">
+      <h3 style="margin-top: 0;">Top tools by latency</h3>
+      <table>
+        <thead><tr><th>Tool</th><th style="text-align: right;">Calls</th><th style="text-align: right;">Avg duration (ms)</th></tr></thead>
+        <tbody id="telemetry-tools-tbody"></tbody>
+      </table>
+    </div>
+    <div class="adv-card">
+      <h3 style="margin-top: 0;">Recent token-usage points</h3>
+      <table>
+        <thead><tr><th>Recorded at</th><th>Model</th><th>Type</th><th style="text-align: right;">Tokens</th><th>Prompt</th></tr></thead>
+        <tbody id="telemetry-recent-tbody"></tbody>
+      </table>
+    </div>
+  </div>
+</div>
+
+<div class="modal-backdrop" id="prompt-journey-modal" role="dialog" aria-modal="true">
+  <div class="modal" role="document">
+    <div class="modal-header">
+      <h2 id="prompt-journey-title">Prompt journey</h2>
+      <button class="modal-close" aria-label="Close" onclick="closeModal('prompt-journey-modal')">&times;</button>
+    </div>
+    <div id="prompt-journey-body"></div>
+  </div>
 </div>
 
 <div id="toast" class="toast"></div>
@@ -2121,7 +2180,87 @@ function switchAdvTab(name) {
 
 // ==================== Advanced drawer loaders ====================
 async function loadAdvanced() {
-  await Promise.all([loadKnowledge(), loadOverview(), loadFacts(), loadEfficacy(), loadConflicts(), loadActivityLog()]);
+  await Promise.all([loadKnowledge(), loadOverview(), loadFacts(), loadEfficacy(), loadConflicts(), loadActivityLog(), loadTelemetry()]);
+}
+
+async function loadTelemetry() {
+  const data = await api('telemetry');
+
+  const status = data.status || {};
+  const statusEl = document.getElementById('telemetry-status');
+  const endpoint = status.endpoint ? esc(status.endpoint) : '<em>not configured</em>';
+  const banner = data.contains_prompt_content
+    ? '<div style="color: #c4863c; margin-top: 4px;">Captured payload contains prompt or body content. Disable with <code>claude-memory otel --no-capture-prompts</code>.</div>'
+    : '';
+  statusEl.innerHTML = `
+    Endpoint: ${endpoint}<br>
+    Metrics: ${status.metric_count || 0} · Events: ${status.event_count || 0} · Traces: ${status.trace_count || 0} (enabled: ${status.traces_enabled ? 'yes' : 'no'})<br>
+    Last metric: ${status.last_metric_at ? esc(status.last_metric_at) : 'never'}
+    ${banner}
+  `;
+
+  const costTbody = document.getElementById('telemetry-cost-tbody');
+  const cost = data.cost_over_time || [];
+  costTbody.innerHTML = cost.length === 0
+    ? `<tr><td colspan="3" style="color: var(--text-faint);">No cost metrics yet. Run <code>claude-memory otel --enable</code> and start a Claude session.</td></tr>`
+    : cost.map(row => `
+      <tr><td>${esc(row.hour)}</td><td style="text-align: right;">${row.requests}</td><td style="text-align: right;">$${row.cost_usd.toFixed(4)}</td></tr>
+    `).join('');
+
+  const tokensTbody = document.getElementById('telemetry-tokens-tbody');
+  const tokens = data.tokens_by_model || [];
+  tokensTbody.innerHTML = tokens.length === 0
+    ? `<tr><td colspan="3" style="color: var(--text-faint);">No token usage yet.</td></tr>`
+    : tokens.map(row => `
+      <tr><td>${esc(row.model)}</td><td>${esc(row.type)}</td><td style="text-align: right;">${row.tokens.toLocaleString()}</td></tr>
+    `).join('');
+
+  const toolsTbody = document.getElementById('telemetry-tools-tbody');
+  const tools = data.top_tools_by_latency || [];
+  toolsTbody.innerHTML = tools.length === 0
+    ? `<tr><td colspan="3" style="color: var(--text-faint);">No tool_result events yet.</td></tr>`
+    : tools.map(row => `
+      <tr><td>${esc(row.tool)}</td><td style="text-align: right;">${row.count}</td><td style="text-align: right;">${row.avg_duration_ms}</td></tr>
+    `).join('');
+
+  const recentTbody = document.getElementById('telemetry-recent-tbody');
+  const recent = data.recent_metrics || [];
+  recentTbody.innerHTML = recent.length === 0
+    ? `<tr><td colspan="5" style="color: var(--text-faint);">No recent token data points.</td></tr>`
+    : recent.map(row => {
+        const promptCell = row.prompt_id
+          ? `<a href="javascript:void(0)" onclick="openPromptJourney('${esc(row.prompt_id)}')">view</a>`
+          : '';
+        return `<tr>
+          <td>${esc(row.recorded_at || '')}</td>
+          <td>${esc(row.model || '')}</td>
+          <td>${esc(row.type || '')}</td>
+          <td style="text-align: right;">${(row.tokens || 0).toLocaleString()}</td>
+          <td>${promptCell}</td>
+        </tr>`;
+      }).join('');
+}
+
+async function openPromptJourney(promptId) {
+  const data = await api('prompt_journey', {prompt_id: promptId});
+  const body = document.getElementById('prompt-journey-body');
+  document.getElementById('prompt-journey-title').textContent = `Prompt journey · ${promptId}`;
+  const events = data.events || [];
+  body.innerHTML = events.length === 0
+    ? `<div style="padding: 12px; color: var(--text-faint);">No events recorded for prompt ${esc(promptId)} yet.</div>`
+    : `<table>
+        <thead><tr><th>Time</th><th>Source</th><th>Event</th><th>Model / Tool</th><th>Duration</th></tr></thead>
+        <tbody>${events.map(ev => `
+          <tr>
+            <td>${esc(ev.occurred_ago || ev.occurred_at || '')}</td>
+            <td><span class="src ${esc(ev.source)}">${esc(ev.source)}</span></td>
+            <td>${esc(ev.name || '')}</td>
+            <td>${esc(ev.model || ev.tool_name || '')}</td>
+            <td>${ev.duration_ms != null ? `${ev.duration_ms} ms` : ''}</td>
+          </tr>`).join('')}
+        </tbody>
+      </table>`;
+  openModal('prompt-journey-modal');
 }
 
 let knowledgeScope = 'all';

data/lib/claude_memory/dashboard/prompt_journey.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Per-prompt waterfall view. Calls Store::PromptJourneyQuery to UNION
+    # otel_events and activity_events on prompt_id, then shapes results
+    # for the frontend (relative timestamps, parsed attributes).
+    class PromptJourney
+      def initialize(manager)
+        @manager = manager
+      end
+
+      def for(prompt_id)
+        @manager.ensure_global! if @manager.respond_to?(:ensure_global!) && !@manager.global_store
+        @manager.ensure_project! if @manager.respond_to?(:ensure_project!) && !@manager.project_store
+        return empty_payload(prompt_id) unless @manager.global_store || @manager.project_store
+
+        rows = ClaudeMemory::Store::PromptJourneyQuery.new(@manager).fetch(prompt_id)
+        {
+          prompt_id: prompt_id,
+          event_count: rows.size,
+          events: rows.map { |row| present(row) }
+        }
+      end
+
+      private
+
+      def empty_payload(prompt_id)
+        {prompt_id: prompt_id, event_count: 0, events: []}
+      end
+
+      def present(row)
+        attrs = OTel::Attributes.from_json(row[:attributes_json])
+        {
+          source: row[:source],
+          name: row[:name],
+          occurred_at: row[:occurred_at],
+          occurred_ago: Core::RelativeTime.format(row[:occurred_at]),
+          session_id: row[:session_id],
+          status: row[:status],
+          duration_ms: row[:duration_ms] || attrs.duration_ms,
+          model: attrs.model,
+          tool_name: attrs.tool_name
+        }.compact
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/server.rb

@@ -18,6 +18,7 @@ module ClaudeMemory
       def start
         @server = WEBrick::HTTPServer.new(
           Port: @port,
+          BindAddress: "127.0.0.1",
           Logger: WEBrick::Log.new(File::NULL),
           AccessLog: []
         )
@@ -67,6 +68,91 @@ module ClaudeMemory
         @server.mount_proc("/api/trust") { |_req, res| with_fresh_connections { json_response(res, api.trust) } }
         @server.mount_proc("/api/knowledge") { |req, res| with_fresh_connections { json_response(res, api.knowledge(req.query)) } }
         @server.mount_proc("/api/reuse") { |req, res| with_fresh_connections { json_response(res, api.reuse(req.query)) } }
+        @server.mount_proc("/api/telemetry") { |_req, res| with_fresh_connections { json_response(res, api.telemetry) } }
+        @server.mount_proc("/api/prompt_journey") { |req, res|
+          with_fresh_connections {
+            prompt_id = req.query["prompt_id"].to_s
+            json_response(res, api.prompt_journey(prompt_id))
+          }
+        }
+
+        # OTel writer routes — high-frequency, no with_fresh_connections.
+        # Telemetry exports happen at sub-second cadence; the WAL stale-cache
+        # concern that motivates per-request connection release only affects
+        # readers.
+        @server.mount_proc("/v1/metrics") { |req, res| handle_otel(:metrics, req, res) }
+        @server.mount_proc("/v1/logs") { |req, res| handle_otel(:logs, req, res) }
+        @server.mount_proc("/v1/traces") { |req, res| handle_otel(:traces, req, res) }
+      end
+
+      # OTLP/HTTP/JSON receiver. Rejects non-JSON content with 415; returns
+      # 501 for /v1/traces unless the user opted in via
+      # `claude-memory otel --enable-traces`. On parse/persist failure
+      # returns 400 with the underlying error message — matches OTLP's
+      # tolerant retry semantics so Claude Code's exporter backs off.
+      def handle_otel(kind, req, res)
+        return otel_response(res, 415, "only application/json is accepted") unless json_content?(req)
+        if kind == :traces && !configuration.otel_traces_enabled?
+          return otel_response(res, 501, "traces ingestion disabled — run `claude-memory otel --enable-traces`")
+        end
+
+        payload = parse_json_body(req)
+        return otel_response(res, 400, "request body was not valid JSON") if payload.nil? || payload == {}
+
+        store = ensure_global_store
+        return otel_response(res, 503, "global store unavailable") unless store
+
+        rows = case kind
+        when :metrics then {metrics: ClaudeMemory::OTel::OtlpJsonEnvelope.parse_metrics(payload)}
+        when :logs then {events: ClaudeMemory::OTel::OtlpJsonEnvelope.parse_logs(payload)}
+        when :traces then {traces: ClaudeMemory::OTel::OtlpJsonEnvelope.parse_traces(payload)}
+        end
+
+        result = ClaudeMemory::OTel::Ingestor.new(store).ingest(rows)
+        if result.success?
+          back_tag_activity_events(rows[:events]) if kind == :logs
+          json_response(res, {})
+        else
+          otel_response(res, 400, result.error)
+        end
+      rescue => e
+        otel_response(res, 500, e.message)
+      end
+
+      # After OTel events with prompt.id are persisted, scan project +
+      # global activity_events and stamp prompt_id on matching rows so the
+      # Prompt Journey panel can UNION-join them. Hook events (session_id-
+      # bearing) match exactly; MCP recall/store_extraction rows (NULL
+      # session_id) fall back to time-window proximity. Best-effort —
+      # tagging failures never block the OTLP response.
+      def back_tag_activity_events(events)
+        return unless events && !events.empty?
+        @manager.ensure_project! if @manager.respond_to?(:ensure_project!) && !@manager.project_store
+        ClaudeMemory::OTel::PromptScope.new(@manager).tag(events)
+      rescue Sequel::DatabaseError, Extralite::Error
+        # never block the OTLP response on a tagging failure
+      end
+
+      def json_content?(req)
+        ct = req["content-type"].to_s.downcase
+        ct.start_with?("application/json")
+      end
+
+      def otel_response(res, status, message)
+        res.status = status
+        res["Content-Type"] = "application/json; charset=utf-8"
+        res.body = JSON.generate(error: message)
+      end
+
+      def configuration
+        @configuration ||= ClaudeMemory::Configuration.new
+      end
+
+      def ensure_global_store
+        @manager.ensure_global!
+        @manager.global_store
+      rescue Sequel::DatabaseError, Errno::ENOENT
+        nil
       end
 
       # WAL-mode SQLite caches pages on reader connections; when the MCP