claude_memory 0.11.0 → 0.12.0

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

data/lib/claude_memory/dashboard/telemetry.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Cost & Tokens dashboard panel. Aggregates Claude Code's OTel metric
+    # exports — server-side via Sequel datasets so the API returns
+    # final-rendered bins and the JS does no reduce.
+    #
+    # Returns the empty shape ({status:, cost_over_time: [], ...}) when no
+    # store or no rows exist so the dashboard renders before the first
+    # ingest.
+    class Telemetry
+      LOOKBACK_DAYS = 7
+      TOP_TOOLS_LIMIT = 10
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      def snapshot
+        store = @manager.default_store(prefer: :global)
+        return empty_snapshot(store) unless store&.db&.table_exists?(:otel_metrics)
+
+        cutoff = (Time.now - LOOKBACK_DAYS * 86_400).utc.iso8601
+        metrics = store.otel_metrics.where { recorded_at >= cutoff }
+        events = events_dataset(store, cutoff)
+
+        {
+          status: status_payload(store),
+          cost_over_time: cost_over_time(metrics),
+          tokens_by_model: tokens_by_model(metrics),
+          top_tools_by_latency: top_tools(events),
+          error_rate: error_rate(events),
+          recent_metrics: recent_metrics(metrics),
+          contains_prompt_content: contains_prompt_content?(events)
+        }
+      end
+
+      private
+
+      def empty_snapshot(store)
+        {
+          status: status_payload(store),
+          cost_over_time: [],
+          tokens_by_model: [],
+          top_tools_by_latency: [],
+          error_rate: {total: 0, errors: 0, ratio: 0.0},
+          recent_metrics: [],
+          contains_prompt_content: false
+        }
+      end
+
+      def status_payload(store)
+        OTel::Status.new(store, configuration: ClaudeMemory::Configuration.new).snapshot
+      end
+
+      def cost_over_time(metrics)
+        rows = metrics
+          .where(name: OTel::MetricName::COST_USAGE)
+          .select_group(Sequel.lit("substr(recorded_at, 1, 13)").as(:hour))
+          .select_append { sum(value_float).as(:cost_usd) }
+          .select_append { count(id).as(:requests) }
+          .order(:hour)
+          .all
+        rows.map { |r|
+          {
+            hour: r[:hour],
+            cost_usd: (r[:cost_usd] || 0.0).to_f.round(6),
+            requests: r[:requests].to_i
+          }
+        }
+      end
+
+      # SQLite's json_extract was added in 3.38.0 (2022-02). Sequel runs it
+      # via Sequel.lit so we group by (model, type) at the DB layer instead
+      # of materializing the whole window into Ruby.
+      def tokens_by_model(metrics)
+        model_expr = Sequel.lit("json_extract(attributes_json, '$.model')")
+        type_expr = Sequel.lit("json_extract(attributes_json, '$.type')")
+        rows = metrics
+          .where(name: OTel::MetricName::TOKEN_USAGE)
+          .select_group(model_expr.as(:model), type_expr.as(:type))
+          .select_append { sum(Sequel.function(:coalesce, :value_int, :value_float)).as(:tokens) }
+          .order(Sequel.desc(:tokens))
+          .all
+        rows.map { |r|
+          {model: r[:model] || "unknown", type: r[:type] || "unknown", tokens: r[:tokens].to_i}
+        }
+      end
+
+      def top_tools(events)
+        return [] if events.nil?
+        tool_expr = Sequel.lit("json_extract(attributes_json, '$.tool_name')")
+        duration_expr = Sequel.lit("json_extract(attributes_json, '$.duration_ms')")
+        rows = events
+          .where(event_name: OTel::EventName::TOOL_RESULT)
+          .select_group(tool_expr.as(:tool))
+          .select_append { count(id).as(:count) }
+          .select_append { avg(duration_expr).as(:avg_duration_ms) }
+          .order(Sequel.desc(:avg_duration_ms))
+          .limit(TOP_TOOLS_LIMIT)
+          .all
+        rows.map { |r|
+          {tool: r[:tool] || "unknown", count: r[:count].to_i, avg_duration_ms: r[:avg_duration_ms].to_i}
+        }
+      end
+
+      def error_rate(events)
+        return {total: 0, errors: 0, ratio: 0.0} if events.nil?
+        total = events.where(event_name: OTel::EventName::API_PAIR).count
+        errors = events.where(event_name: OTel::EventName::API_ERROR).count
+        ratio = total.zero? ? 0.0 : (errors.to_f / total).round(4)
+        {total: total, errors: errors, ratio: ratio}
+      end
+
+      def recent_metrics(metrics)
+        rows = metrics
+          .where(name: OTel::MetricName::TOKEN_USAGE)
+          .order(Sequel.desc(:recorded_at))
+          .limit(100)
+          .all
+        rows.map { |row|
+          attrs = OTel::Attributes.from_json(row[:attributes_json])
+          {
+            recorded_at: row[:recorded_at],
+            model: attrs.model,
+            type: attrs.token_type,
+            tokens: OTel::Attributes.token_count(row),
+            session_id: attrs.session_id,
+            prompt_id: attrs.prompt_id
+          }.compact
+        }
+      end
+
+      def events_dataset(store, cutoff)
+        return nil unless store.db.table_exists?(:otel_events)
+        store.otel_events.where { occurred_at >= cutoff }
+      end
+
+      # SQL pre-filter via LIKE on each prompt-content key, short-circuited
+      # by .any?. JSON encodes object keys as `"key":` (compact), so the
+      # patterns can't false-match longer keys (e.g. "prompt_length").
+      def contains_prompt_content?(events)
+        return false if events.nil?
+        clauses = OTel::Attributes::PROMPT_CONTENT_KEYS.map { |key|
+          Sequel.lit("attributes_json LIKE ?", %("#{key}":))
+        }
+        events
+          .where(event_name: OTel::EventName::PROMPT_BODY_FAMILY)
+          .where(Sequel.|(*clauses))
+          .limit(1)
+          .any?
+      end
+    end
+  end
+end

data/lib/claude_memory/deprecations.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  # Soft-rename / soft-removal mechanism for public-API surfaces.
+  # Used to mark an old name (CLI flag, MCP tool, Ruby method, hook
+  # field, predicate) as deprecated in `N.x.0` releases while keeping it
+  # functional for at least one minor cycle, with explicit removal no
+  # earlier than `(N+1).0.0`. This deprecation policy is documented in
+  # `docs/api_stability.md`.
+  #
+  # @example Deprecate a renamed CLI flag
+  #   ClaudeMemory::Deprecations.warn(
+  #     name: "claude-memory recall --legacy-mode",
+  #     replacement: "--mode=legacy",
+  #     removed_in: "1.0.0"
+  #   )
+  #
+  # @example Deprecate a soft-renamed Ruby method
+  #   ClaudeMemory::Deprecations.warn(
+  #     name: "ClaudeMemory::Recall#legacy_query",
+  #     replacement: "Recall#query",
+  #     removed_in: "1.0.0",
+  #     message: "Pass `mode: :legacy` to #query instead."
+  #   )
+  #
+  # Two suppression mechanisms keep deprecation noise manageable:
+  #
+  # - **Per-call-site dedupe**: same (name, caller_file:line) pair only
+  #   emits once per process. Prevents tight loops or repeated callers
+  #   from drowning the terminal.
+  # - **Env var opt-out**: `CLAUDE_MEMORY_NO_DEPRECATIONS=1` silences
+  #   everything. Recommended for test fixtures and CI runs that
+  #   knowingly exercise legacy paths.
+  module Deprecations
+    ENV_OPT_OUT = "CLAUDE_MEMORY_NO_DEPRECATIONS"
+
+    # Tracks already-emitted (name, caller-location) pairs for dedupe.
+    # Bounded — this is a long-lived process state but the cardinality
+    # is at most "every deprecated surface × every call site that
+    # touches it", which stays small in practice.
+    @emitted = {}
+    @mutex = Mutex.new
+
+    class << self
+      # Emit a deprecation warning to `output` (stderr by default).
+      #
+      # @param name [String] the deprecated identifier (CLI flag, method,
+      #   tool name, etc.). Be specific: "ClaudeMemory::Recall#query(:legacy)"
+      #   beats "Recall#query".
+      # @param replacement [String, nil] what users should switch to.
+      #   Optional but strongly recommended — a deprecation without a
+      #   migration path is annoying.
+      # @param removed_in [String, nil] target removal version, semver
+      #   string. Conventionally the next major (`(N+1).0.0`).
+      # @param message [String, nil] free-form extra context. Use for
+      #   subtle migration nuance the replacement string can't capture.
+      # @param caller_location [String, nil] override for testing.
+      # @param output [IO] override for testing. Default: $stderr.
+      # @return [Boolean] true if a warning was emitted, false if
+      #   suppressed (env opt-out or already-emitted dedupe).
+      def warn(name:, replacement: nil, removed_in: nil, message: nil,
+        caller_location: nil, output: $stderr)
+        return false if suppressed?
+
+        location = caller_location || derive_caller_location
+        key = "#{name}@#{location}"
+
+        @mutex.synchronize do
+          return false if @emitted[key]
+          @emitted[key] = true
+        end
+
+        output.puts(format_warning(name: name, replacement: replacement,
+          removed_in: removed_in, message: message, location: location))
+        true
+      end
+
+      # Wipe the per-call-site dedupe state. Test-only — production
+      # callers should rely on the per-process behavior.
+      def reset!
+        @mutex.synchronize { @emitted.clear }
+      end
+
+      private
+
+      def suppressed?
+        ENV[ENV_OPT_OUT] == "1"
+      end
+
+      def derive_caller_location
+        # Skip: 0=this method, 1=warn, 2=actual caller
+        loc = caller_locations(3, 1)&.first
+        loc ? "#{loc.path}:#{loc.lineno}" : "unknown"
+      end
+
+      def format_warning(name:, replacement:, removed_in:, message:, location:)
+        parts = ["[ClaudeMemory] DEPRECATION: #{name} is deprecated"]
+        parts << "scheduled for removal in #{removed_in}" if removed_in
+        parts << "use #{replacement} instead" if replacement
+        head = parts.join(", ") + "."
+        head += " #{message}" if message
+        "#{head} (called from #{location})"
+      end
+    end
+  end
+end

data/lib/claude_memory/distill/reference_material_detector.rb

@@ -43,11 +43,28 @@ module ClaudeMemory
         /\bby\s+[[:upper:]][[:alpha:]'-]+\s+[[:upper:]][[:alpha:]'-]+/
       ].freeze
 
-      # Predicates we inspect. Decisions stay decisions even when they cite
-      # external projects ("From QMD restudy: adopt X"); the guard targets
-      # only `convention`, where misclassification is most common.
+      # Predicates inspected for object-text reference signals. Decisions
+      # stay decisions even when they cite external projects ("From QMD
+      # restudy: adopt X"); the object-text guard targets only
+      # `convention`, where misclassification is most common.
       GUARDED_PREDICATES = %w[convention].freeze
 
+      # Stack-shaping single-value predicates that historically attract
+      # hallucinations from CLAUDE.md-style example text ("e.g., this app
+      # uses PostgreSQL"). For these predicates we additionally inspect the
+      # source quote for example markers — if the LLM extracted a stack
+      # fact from documentation example text, it's not a real project
+      # commitment. Added 2026-05-21 after the audit found 10 open
+      # conflicts driven by recurring example-text extraction.
+      QUOTE_GUARDED_PREDICATES = %w[uses_database uses_framework uses_language deployment_platform auth_method].freeze
+
+      # Example markers that signal the source text is documentation
+      # exemplifying a scope/predicate concept, not a real stack claim.
+      EXAMPLE_QUOTE_PATTERNS = [
+        /\b(?:e\.?g\.?|i\.?e\.?|for example|for instance|such as)[,:]?\s/i,
+        /\(\s*(?:e\.?g\.?|i\.?e\.?)[,.]/i
+      ].freeze
+
       def reclassify(extraction)
         return extraction if extraction.facts.nil? || extraction.facts.empty?
 
@@ -68,11 +85,27 @@ module ClaudeMemory
       end
 
       def reference_material?(fact)
-        return false unless GUARDED_PREDICATES.include?(fact[:predicate].to_s)
+        predicate = fact[:predicate].to_s
+        return true if convention_with_reference_object?(fact, predicate)
+        return true if stack_predicate_from_example_text?(fact, predicate)
+        false
+      end
+
+      private
+
+      def convention_with_reference_object?(fact, predicate)
+        return false unless GUARDED_PREDICATES.include?(predicate)
         object = fact[:object].to_s
         return false if object.empty?
         STRONG_PATTERNS.any? { |re| object.match?(re) }
       end
+
+      def stack_predicate_from_example_text?(fact, predicate)
+        return false unless QUOTE_GUARDED_PREDICATES.include?(predicate)
+        quote = fact[:quote].to_s
+        return false if quote.empty?
+        EXAMPLE_QUOTE_PATTERNS.any? { |re| quote.match?(re) }
+      end
     end
   end
 end

data/lib/claude_memory/hook/auto_memory_mirror.rb

@@ -21,10 +21,14 @@ module ClaudeMemory
       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`.
+      # slug convention. Both path separators and underscores are converted
+      # to hyphens — e.g. `/Users/me/src/my_app` →
+      # `~/.claude/projects/-Users-me-src-my-app/memory`. Before the
+      # underscore conversion was added (2026-05-21 audit), this method
+      # silently missed auto-memory for any project name containing `_`,
+      # including claude_memory itself.
       def self.default_dir(project_path, claude_config_dir)
-        slug = project_path.to_s.tr("/", "-")
+        slug = project_path.to_s.tr("/_", "-")
         File.join(claude_config_dir, "projects", slug, "memory")
       end