claude_memory 0.12.0 → 0.13.0

data/lib/claude_memory/commands/skills/reflect.md

@@ -0,0 +1,68 @@
+# Reflect
+
+Consolidate the episodic observation log and promote corroborated observations into
+durable facts. This is the manual, on-demand counterpart to the automatic Reflector
+that runs during sweep — use it for a deeper pass.
+
+## Usage
+
+```
+/reflect
+/reflect --scope project
+```
+
+## Instructions
+
+You are the Reflector for ClaudeMemory's episodic observation layer. Observations are
+the "what happened" log; facts are the "what is true" store. Your job is to look across
+the recent observations, find what has become a stable truth, and promote it — while
+leaving one-off noise alone.
+
+Work in three passes:
+
+### 1. Survey
+
+Call `memory.observations` (use `important_only: true` first for the 🔴 entries, then a
+broader pass). Read the log as a narrative of what has happened in this project.
+
+### 2. Consolidate related observations
+
+Where several observations describe the **same thing in different words** (regex dedup only
+catches exact matches), merge them with `memory.consolidate_observations(from_ids: […],
+body: "<synthesis>")`. The synthesized observation inherits the **combined** corroboration of
+its sources — which often tips it over the promotion threshold — and the originals are
+tombstoned (preserved and linked, not deleted). Use the `#id` shown for each observation.
+
+### 3. Promote corroborated observations → facts
+
+The promotion bridge is gated: an observation must have been **corroborated** (sighted
+repeatedly — `corroboration_count` ≥ the threshold) before it can become a fact. This is
+deliberate: requiring repeated sightings before commitment is an anti-hallucination gate
+against one-off doc/example text.
+
+For each observation that represents a **stable, repeated truth**:
+
+- Call `memory.promote_observation` with `observation_id`, a `predicate`
+  (`decision` / `convention` / `architecture`), and an `object` that **embeds a reason**
+  ("… because …", "… so that …", "to avoid …"). A bare conclusion is dead weight.
+- The tool refuses observations that are not yet corroborated — do not try to force them.
+  If something genuinely matters but has only been seen once, leave it; it will become
+  eligible once it recurs.
+
+Skip observations that are:
+
+- transient (debugging steps, one-off events),
+- already captured as facts (check `memory.recall` / `memory.decisions` first),
+- example/illustrative text rather than a claim about *this* project.
+
+### 4. Report
+
+Summarize what you promoted (observation → fact) and what you intentionally left as
+observations and why. Do not delete or rewrite observations — the deterministic Reflector
+handles dedup/expiry during sweep; your job is the semantic judgment the regex pass can't make.
+
+## Notes
+
+- Promotion preserves provenance: the new fact links back to the observation's source.
+- Promoted observations are marked so they are not re-suggested.
+- No extra API cost — this runs inside the existing Claude Code session.

data/lib/claude_memory/commands/stats_command.rb

@@ -13,7 +13,7 @@ module ClaudeMemory
       SCOPE_PROJECT = "project"
 
       def call(args)
-        opts = parse_options(args, {scope: SCOPE_ALL, tools: false, tokens: false, stale: false, since_days: nil, stale_days: nil}) do |o|
+        opts = parse_options(args, {scope: SCOPE_ALL, tools: false, tokens: false, stale: false, observations: false, since_days: nil, stale_days: nil}) do |o|
           OptionParser.new do |parser|
             parser.banner = "Usage: claude-memory stats [options]"
             parser.on("--scope SCOPE", ["all", "global", "project"],
@@ -21,6 +21,7 @@ module ClaudeMemory
             parser.on("--tools", "Show MCP tool-call usage stats") { o[:tools] = true }
             parser.on("--tokens", "Show SessionStart context-injection token budget") { o[:tokens] = true }
             parser.on("--stale", "Show facts not recalled in CLAUDE_MEMORY_STALE_DAYS (default 14)") { o[:stale] = true }
+            parser.on("--observations", "Show episodic observation counts (status, kind, promotable)") { o[:observations] = true }
             parser.on("--since DAYS", Integer, "Limit --tools/--tokens to last N days") { |v| o[:since_days] = v }
             parser.on("--stale-days N", Integer, "Override staleness threshold for --stale") { |v| o[:stale_days] = v }
           end
@@ -31,6 +32,10 @@ module ClaudeMemory
           return print_mcp_tool_call_stats(opts[:since_days])
         end
 
+        if opts[:observations]
+          return print_observation_stats
+        end
+
         if opts[:tokens]
           return print_token_budget_stats(opts[:since_days])
         end
@@ -90,6 +95,60 @@ module ClaudeMemory
         0
       end
 
+      def print_observation_stats
+        manager = ClaudeMemory::Store::StoreManager.new
+        stores = %w[project global]
+          .filter_map { |scope| manager.store_if_exists(scope) }
+          .select { |store| store.db.table_exists?(:observations) }
+
+        stdout.puts "Observation Statistics (episodic layer)"
+        stdout.puts "=" * 50
+
+        threshold = ClaudeMemory::Domain::Observation::PROMOTION_THRESHOLD
+
+        total = stores.sum { |s| s.observations.count }
+        if total.zero?
+          stdout.puts "No observations recorded yet."
+          manager.close
+          return 0
+        end
+
+        active = stores.sum { |s| s.observations.where(status: "active").count }
+        consolidated = stores.sum { |s| s.observations.where(status: "consolidated").count }
+        expired = stores.sum { |s| s.observations.where(status: "expired").count }
+        promoted = stores.sum { |s| s.observations.exclude(promoted_at: nil).count }
+        promotable = stores.sum do |s|
+          s.observations.where(status: "active", promoted_at: nil)
+            .where { corroboration_count >= threshold }.count
+        end
+
+        stdout.puts "Active: #{active}"
+        stdout.puts "Consolidated: #{consolidated}"
+        stdout.puts "Expired: #{expired}"
+        stdout.puts "Promoted: #{promoted}"
+        stdout.puts "Promotable (>= #{threshold} sightings): #{promotable}"
+        stdout.puts
+
+        kinds = Hash.new(0)
+        stores.each do |store|
+          store.observations.where(status: "active").group_and_count(:kind).each do |row|
+            kinds[row[:kind]] += row[:count]
+          end
+        end
+
+        stdout.puts "By kind (active):"
+        if kinds.empty?
+          stdout.puts "  (none)"
+        else
+          kinds.sort_by { |_k, v| -v }.each do |kind, count|
+            stdout.puts "  #{count.to_s.rjust(4)} - #{kind}"
+          end
+        end
+
+        manager.close
+        0
+      end
+
       def open_readonly(db_path)
         Sequel.connect("extralite://#{db_path}")
       end

data/lib/claude_memory/dashboard/api.rb

@@ -456,6 +456,10 @@ module ClaudeMemory
         Efficacy::Reporter.report(events, timeframe: {since: since, session_id: session_id})
       end
 
+      def observations
+        Observations.new(@manager).report
+      end
+
       def timeline
         Timeline.new(@manager).days
       end

data/lib/claude_memory/dashboard/index.html

@@ -163,6 +163,39 @@
   .delta.flat { color: var(--text-dim); }
   .moments-sub { font-size: 12px; color: var(--text-dim); margin-top: 6px; }
 
+  /* Observations sidebar panel */
+  .obs-headline {
+    display: flex;
+    gap: 14px;
+    align-items: baseline;
+    margin-bottom: 6px;
+  }
+  .obs-headline .n {
+    font-size: 32px;
+    font-weight: 600;
+    letter-spacing: -0.02em;
+    line-height: 1;
+  }
+  .obs-headline .obs-stat { display: flex; flex-direction: column; gap: 2px; }
+  .obs-headline .obs-stat-n { font-size: 18px; font-weight: 600; color: var(--text); line-height: 1; }
+  .obs-headline .obs-stat-label { font-size: 10px; color: var(--text-faint); text-transform: uppercase; letter-spacing: 0.06em; }
+  .obs-sub { font-size: 12px; color: var(--text-dim); margin: 8px 0; }
+  .obs-breakdowns { display: flex; flex-direction: column; gap: 8px; margin-top: 10px; }
+  .obs-breakdown-label { font-size: 10px; text-transform: uppercase; letter-spacing: 0.06em; color: var(--text-faint); margin-bottom: 4px; }
+  .obs-badges { display: flex; flex-wrap: wrap; gap: 6px; }
+  .obs-badge {
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    padding: 2px 8px;
+    border-radius: 999px;
+    border: 1px solid var(--border);
+    background: var(--surface2);
+    font-size: 11px;
+    color: var(--text-dim);
+  }
+  .obs-badge .obs-badge-n { font-weight: 600; color: var(--text); font-variant-numeric: tabular-nums; }
+
   /* Knowledge-base sidebar panel */
   .kb-totals {
     display: flex;
@@ -1157,6 +1190,13 @@
       <div class="moments-sub" id="moments-sub"></div>
     </div>
 
+    <div class="panel" id="panel-observations">
+      <div class="panel-label">Episodic observations
+        <span class="panel-hint" title="The 'what happened' log that complements facts ('what is true'). Observations accrue as the Observer runs, and become facts once corroborated ≥2×.">ⓘ</span>
+      </div>
+      <div id="obs-panel-body"></div>
+    </div>
+
     <div class="panel" id="panel-review">
       <div class="panel-label">Needs review</div>
       <div class="review-rows" id="review-rows"></div>
@@ -1234,6 +1274,7 @@
   </div>
   <div class="drawer-tabs">
     <div class="drawer-tab active" data-adv="knowledge">Knowledge</div>
+    <div class="drawer-tab" data-adv="observations">Observations</div>
     <div class="drawer-tab" data-adv="overview">Overview</div>
     <div class="drawer-tab" data-adv="facts">Facts</div>
     <div class="drawer-tab" data-adv="explore">Explore</div>
@@ -1253,6 +1294,13 @@
     <div class="knowledge-body" id="knowledge-body"></div>
   </div>
 
+  <div class="drawer-panel" id="adv-observations">
+    <div id="obs-summary" class="adv-card"></div>
+    <div class="adv-card" style="padding: 0;">
+      <div id="obs-recent"></div>
+    </div>
+  </div>
+
   <div class="drawer-panel" id="adv-overview">
     <div id="overview-rows"></div>
     <div class="adv-card">
@@ -1444,7 +1492,77 @@ async function api(path, params = {}) {
 
 // ==================== Load cycle ====================
 async function loadAll() {
-  await Promise.all([loadHealth(), loadTrust(), loadMoments(), loadKnowledgePanel(), loadReusePanel()]);
+  await Promise.all([loadHealth(), loadTrust(), loadMoments(), loadKnowledgePanel(), loadReusePanel(), loadObservationsPanel()]);
+}
+
+// Sidebar "Episodic observations" panel — headline numbers + breakdowns.
+// The richer recent timeline lives in the Advanced drawer (loadObservations).
+async function loadObservationsPanel() {
+  const data = await api('observations');
+  const t = data.totals || {}, c = data.compression || {}, corr = data.corroboration || {};
+  const body = document.getElementById('obs-panel-body');
+  if (!body) return;
+
+  const active = t.active || 0;
+  if (!active) {
+    body.innerHTML = `
+      <div class="feed-empty" style="padding: 24px 16px; text-align: left;">
+        <h3>No observations yet</h3>
+        <p>The episodic log — "what happened" — accrues as the Observer runs over your sessions. Once an observation is corroborated ≥2×, it becomes a fact.</p>
+      </div>`;
+    return;
+  }
+
+  const promotable = corr.promotable || 0;
+  body.innerHTML = `
+    <div class="obs-headline">
+      <div class="obs-stat">
+        <span class="n">${active.toLocaleString()}</span>
+        <span class="obs-stat-label">active</span>
+      </div>
+      <div class="obs-stat">
+        <span class="obs-stat-n">${promotable.toLocaleString()}</span>
+        <span class="obs-stat-label">ready to promote</span>
+      </div>
+      <div class="obs-stat">
+        <span class="obs-stat-n">${c.ratio ? c.ratio + '×' : '—'}</span>
+        <span class="obs-stat-label">compression</span>
+      </div>
+    </div>
+    <div class="obs-sub">${promotable
+      ? `${promotable.toLocaleString()} ready to promote — observations corroborated ≥2× become facts (max seen ×${corr.max || 0}).`
+      : `None ready yet — observations corroborated ≥2× become facts (max seen ×${corr.max || 0}).`}</div>
+    <div class="obs-breakdowns">
+      ${renderObsBreakdown('By priority', priorityBadges(data.by_priority || {}))}
+      ${renderObsBreakdown('By kind', kindBadges(data.by_kind || {}))}
+    </div>`;
+}
+
+const PRIORITY_MARKERS = {1: '🔴', 2: '🟡', 3: '🟢'};
+const PRIORITY_LABELS = {1: 'important', 2: 'maybe', 3: 'info'};
+
+function priorityBadges(byPriority) {
+  return [1, 2, 3]
+    .filter(p => byPriority[p] || byPriority[String(p)])
+    .map(p => {
+      const n = byPriority[p] || byPriority[String(p)] || 0;
+      return `<span class="obs-badge">${PRIORITY_MARKERS[p]} ${PRIORITY_LABELS[p]} <span class="obs-badge-n">${n}</span></span>`;
+    }).join('');
+}
+
+function kindBadges(byKind) {
+  return Object.entries(byKind)
+    .sort((a, b) => b[1] - a[1])
+    .map(([kind, n]) => `<span class="obs-badge">${esc(kind)} <span class="obs-badge-n">${n}</span></span>`)
+    .join('');
+}
+
+function renderObsBreakdown(label, badgesHtml) {
+  if (!badgesHtml) return '';
+  return `<div>
+    <div class="obs-breakdown-label">${label}</div>
+    <div class="obs-badges">${badgesHtml}</div>
+  </div>`;
 }
 
 async function loadKnowledgePanel() {
@@ -2180,7 +2298,41 @@ function switchAdvTab(name) {
 
 // ==================== Advanced drawer loaders ====================
 async function loadAdvanced() {
-  await Promise.all([loadKnowledge(), loadOverview(), loadFacts(), loadEfficacy(), loadConflicts(), loadActivityLog(), loadTelemetry()]);
+  await Promise.all([loadKnowledge(), loadObservations(), loadOverview(), loadFacts(), loadEfficacy(), loadConflicts(), loadActivityLog(), loadTelemetry()]);
+}
+
+async function loadObservations() {
+  const data = await api('observations');
+  const t = data.totals || {}, c = data.compression || {}, corr = data.corroboration || {};
+  const promotable = corr.promotable || 0;
+  const summary = document.getElementById('obs-summary');
+  if (summary) {
+    summary.innerHTML = `
+      <h3>Episodic observations <span style="color: var(--text-faint); font-weight: normal;">— what happened</span></h3>
+      <div style="display: flex; flex-wrap: wrap; gap: 16px; color: var(--text-dim); font-size: 13px;">
+        <span><span class="big">${(t.active || 0).toLocaleString()}</span> active</span>
+        <span>${t.consolidated || 0} consolidated · ${t.expired || 0} expired · ${t.promoted || 0} promoted</span>
+        <span>${promotable} ready to promote (max ×${corr.max || 0}) — observations corroborated ≥2× become facts</span>
+        <span>compression ${c.ratio ? c.ratio + '×' : '—'} <span style="color: var(--text-faint);">(${(c.source_tokens || 0).toLocaleString()} → ${(c.observation_tokens || 0).toLocaleString()} tok)</span></span>
+      </div>
+      <div class="obs-breakdowns" style="margin-top: 12px;">
+        ${renderObsBreakdown('By priority', priorityBadges(data.by_priority || {}))}
+        ${renderObsBreakdown('By kind', kindBadges(data.by_kind || {}))}
+      </div>`;
+  }
+  const recentEl = document.getElementById('obs-recent');
+  const recent = data.recent || [];
+  if (recentEl) {
+    recentEl.innerHTML = recent.length ? recent.map(o => `
+      <div style="padding: 8px 12px; border-bottom: 1px solid var(--border);">
+        <span style="color: var(--text-faint); font-size: 11px;">#${o.id} · ${esc(o.kind)} · p${o.priority}${o.corroboration_count > 1 ? ' · ×' + o.corroboration_count : ''} · ${esc(o.observed_ago || '')}</span>
+        <div style="color: var(--text); font-size: 13px;">${PRIORITY_MARKERS[o.priority] ? PRIORITY_MARKERS[o.priority] + ' ' : ''}${esc(o.body || '')}</div>
+      </div>`).join('') : `
+      <div class="feed-empty" style="text-align: left;">
+        <h3>No observations yet</h3>
+        <p>The episodic log — "what happened" — accrues from your sessions as the Observer runs. Once an observation is corroborated ≥2×, it gets promoted into a fact.</p>
+      </div>`;
+  }
 }
 
 async function loadTelemetry() {

data/lib/claude_memory/dashboard/observations.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Dashboard
+    # Observability for the episodic observation layer. Surfaces counts by
+    # status/kind/priority, corroboration + promotion readiness, a Mastra-style
+    # compression ratio (source content tokens ÷ observation tokens), and a
+    # recent timeline. Aggregated across the project and global stores.
+    #
+    # Pulled out of Dashboard::API so the queries live next to the data.
+    class Observations
+      RECENT_LIMIT = 20
+
+      def initialize(manager)
+        @manager = manager
+      end
+
+      def report
+        stores = observation_stores
+        return empty_report if stores.empty?
+
+        {
+          totals: totals(stores),
+          by_kind: by_field(stores, :kind),
+          by_priority: by_field(stores, :priority),
+          corroboration: corroboration(stores),
+          compression: compression(stores),
+          recent: recent(stores)
+        }
+      end
+
+      private
+
+      def observation_stores
+        [@manager.project_store, @manager.global_store].compact.select { |s| s.db.table_exists?(:observations) }
+      end
+
+      def empty_report
+        {
+          totals: {active: 0, consolidated: 0, expired: 0, promoted: 0},
+          by_kind: {}, by_priority: {},
+          corroboration: {max: 0, promotable: 0},
+          compression: {observation_tokens: 0, source_tokens: 0, ratio: nil},
+          recent: []
+        }
+      end
+
+      def totals(stores)
+        {
+          active: count_where(stores, status: "active"),
+          consolidated: count_where(stores, status: "consolidated"),
+          expired: count_where(stores, status: "expired"),
+          promoted: stores.sum { |s| s.observations.exclude(promoted_at: nil).count }
+        }
+      end
+
+      def count_where(stores, **filter)
+        stores.sum { |s| s.observations.where(**filter).count }
+      end
+
+      def by_field(stores, field)
+        merged = Hash.new(0)
+        stores.each do |store|
+          store.observations.where(status: "active").group_and_count(field).each do |row|
+            merged[row[field]] += row[:count]
+          end
+        end
+        merged
+      end
+
+      def corroboration(stores)
+        threshold = Domain::Observation::PROMOTION_THRESHOLD
+        {
+          max: stores.map { |s| s.observations.where(status: "active").max(:corroboration_count) || 0 }.max,
+          promotable: stores.sum { |s|
+            s.observations.where(status: "active", promoted_at: nil).where { corroboration_count >= threshold }.count
+          }
+        }
+      end
+
+      # Source content tokens vs the tokens the observations distilled them into.
+      # ratio > 1 means the episodic log is a compression of its source.
+      def compression(stores)
+        obs_tokens = stores.sum { |s| s.observations.where(status: "active").sum(:token_count) || 0 }
+        source_tokens = stores.sum { |s| source_tokens_for(s) }
+        ratio = obs_tokens.zero? ? nil : (source_tokens.to_f / obs_tokens).round(1)
+        {observation_tokens: obs_tokens, source_tokens: source_tokens, ratio: ratio}
+      end
+
+      def source_tokens_for(store)
+        ids = store.observations
+          .where(status: "active").exclude(source_content_item_id: nil)
+          .distinct.select(:source_content_item_id)
+          .map { |r| r[:source_content_item_id] }
+        return 0 if ids.empty?
+
+        bytes = store.content_items.where(id: ids).sum(:byte_len) || 0
+        (bytes / 4.0).round
+      end
+
+      def recent(stores)
+        stores
+          .flat_map { |s| s.recent_observations(limit: RECENT_LIMIT) }
+          .sort_by { |o| o[:observed_at].to_s }.reverse.first(RECENT_LIMIT)
+          .map do |o|
+            {
+              id: o[:id], kind: o[:kind], priority: o[:priority],
+              corroboration_count: o[:corroboration_count], body: o[:body],
+              observed_ago: Core::RelativeTime.format(o[:observed_at])
+            }
+          end
+      end
+    end
+  end
+end

data/lib/claude_memory/dashboard/server.rb

@@ -62,6 +62,7 @@ module ClaudeMemory
           }
         }
         @server.mount_proc("/api/timeline") { |_req, res| with_fresh_connections { json_response(res, api.timeline) } }
+        @server.mount_proc("/api/observations") { |_req, res| with_fresh_connections { json_response(res, api.observations) } }
         @server.mount_proc("/api/recall") { |req, res| with_fresh_connections { json_response(res, api.recall(req.query)) } }
         @server.mount_proc("/api/conflicts") { |req, res| with_fresh_connections { handle_conflicts(api, req, res) } }
         @server.mount_proc("/api/moments") { |req, res| with_fresh_connections { handle_moments(api, req, res) } }

data/lib/claude_memory/distill/extraction.rb

@@ -3,17 +3,18 @@
 module ClaudeMemory
   module Distill
     class Extraction
-      attr_reader :entities, :facts, :decisions, :signals
+      attr_reader :entities, :facts, :decisions, :signals, :observations
 
-      def initialize(entities: [], facts: [], decisions: [], signals: [])
+      def initialize(entities: [], facts: [], decisions: [], signals: [], observations: [])
         @entities = entities
         @facts = facts
         @decisions = decisions
         @signals = signals
+        @observations = observations
       end
 
       def empty?
-        entities.empty? && facts.empty? && decisions.empty? && signals.empty?
+        entities.empty? && facts.empty? && decisions.empty? && signals.empty? && observations.empty?
       end
 
       def to_h
@@ -21,7 +22,8 @@ module ClaudeMemory
           entities: entities,
           facts: facts,
           decisions: decisions,
-          signals: signals
+          signals: signals,
+          observations: observations
         }
       end
     end

data/lib/claude_memory/distill/null_distiller.rb

@@ -21,7 +21,10 @@ module ClaudeMemory
       ENTITY_PATTERNS = {
         "database" => /\b(postgresql|postgres|mysql|sqlite|mongodb|redis)\b/i,
         "framework" => /\b(rails|sinatra|django|express|next\.?js|react|vue)\b/i,
-        "language" => /\b(ruby|python|javascript|typescript|go|rust)\b/i,
+        # `Go` is matched case-sensitively (via the inline (?-i:) flag) so the
+        # English verb "go" / "go-to" doesn't masquerade as the language; the
+        # other languages stay case-insensitive. `golang` normalizes to `go`.
+        "language" => /\b(ruby|python|javascript|typescript|rust|(?-i:Go)|golang)\b/i,
         "platform" => /\b(aws|gcp|azure|heroku|vercel|netlify|docker|kubernetes)\b/i
       }.freeze
 
@@ -35,17 +38,33 @@ module ClaudeMemory
         /\buniversally\b/i
       ].freeze
 
+      # Observation-specific convention patterns: stricter than the shared
+      # CONVENTION_PATTERNS. Bare `always (.+)` / `never (.+)` / `we use (.+)`
+      # match code, prose, and instruction text ("never answer from memory",
+      # "never nil. def …"), so observations require explicit convention
+      # framing or a first-person "we always/never".
+      OBSERVATION_CONVENTION_PATTERNS = [
+        /\bconvention[:\s]+(.+)/i,
+        /\bstandard[:\s]+(.+)/i,
+        /\bwe\s+(?:should\s+)?(?:always|never)\s+(.+)/i
+      ].freeze
+
+      # Bodies that look like code / JSON / shell rather than a statement.
+      NOISE_BODY_SIGNATURE = /\bdef\s|\bclass\s|\bmodule\s|=>|::|","|":\s*"|[{}]|\$\(|&&|\|\|/
+
       def distill(text, content_item_id: nil)
         entities = extract_entities(text)
         facts = extract_facts(text, entities)
         decisions = extract_decisions(text)
         signals = extract_signals(text)
+        observations = extract_observations(text)
 
         Extraction.new(
           entities: entities,
           facts: facts,
           decisions: decisions,
-          signals: signals
+          signals: signals,
+          observations: observations
         )
       end
 
@@ -55,7 +74,9 @@ module ClaudeMemory
         found = []
         ENTITY_PATTERNS.each do |type, pattern|
           text.scan(pattern).flatten.uniq.each do |name|
-            found << {type: type, name: name.downcase, confidence: 0.7}
+            normalized = name.downcase
+            normalized = "go" if normalized == "golang"
+            found << {type: type, name: normalized, confidence: 0.7}
           end
         end
         found.uniq { |e| [e[:type], e[:name]] }
@@ -103,6 +124,68 @@ module ClaudeMemory
         signals
       end
 
+      # Layer-1 Observer: emit episodic observations for the same signals the
+      # distiller can detect by regex. A decision being made and a convention
+      # being stated are both "things that happened" worth logging in the
+      # episodic layer, independent of the semantic facts they also produce.
+      # Decisions are 🔴 (important), conventions 🟡 (maybe) — the priority is
+      # an internal Observer/Reflector signal. Richer observations come from
+      # the Layer-2 Claude-as-observer pass (a later phase).
+      def extract_observations(text)
+        observations = []
+        scope_hint = global_scope_signal?(text) ? "global" : "project"
+
+        DECISION_PATTERNS.each do |pattern|
+          text.scan(pattern).flatten.each do |match|
+            observations << build_observation("decision", Domain::Observation::IMPORTANT, "decided to #{match.strip}", scope_hint)
+          end
+        end
+
+        OBSERVATION_CONVENTION_PATTERNS.each do |pattern|
+          text.scan(pattern).flatten.each do |match|
+            observations << build_observation("preference", Domain::Observation::MAYBE, match.strip, scope_hint)
+          end
+        end
+
+        observations.compact.uniq { |o| [o[:kind], o[:body]] }.first(10)
+      end
+
+      # Returns nil for content that isn't a usable statement: code/JSON noise,
+      # or fewer than three words after trimming to the first sentence.
+      def build_observation(kind, priority, body, scope_hint)
+        cleaned = trim_to_statement(clean_observation_body(body))
+        return nil if cleaned.empty? || noise_body?(cleaned) || cleaned.split.size < 3
+
+        {kind: kind, priority: priority, body: cleaned.slice(0, 500), scope_hint: scope_hint}
+      end
+
+      # Cap a captured span to its first sentence (and a hard length limit) so a
+      # greedy `.+` match can't swallow a whole code block or JSON line.
+      def trim_to_statement(text)
+        s = text.to_s.strip
+        (s[/\A.{0,240}?[.!?](?=\s|\z)/m] || s[0, 240]).to_s.strip
+      end
+
+      def noise_body?(body)
+        body.match?(NOISE_BODY_SIGNATURE)
+      end
+
+      # The distiller scans raw transcript text, which is JSONL — so a captured
+      # body can carry JSON/escaping artifacts (`\n`, `\"`, a trailing `"}`,
+      # a leading `= `/`### ` from injected memory/markdown). Normalize them out:
+      # cleaner bodies read better in the injected log AND normalize more
+      # consistently, which is what the Reflector's dedup/corroboration keys off.
+      def clean_observation_body(body)
+        body.to_s
+          .gsub(/\\+[ntr]/, " ")   # literal \n \t \r (even multiply-escaped) -> space
+          .gsub(/\\+"/, '"')       # escaped quote -> quote
+          .gsub(/\\+/, "")         # residual backslashes
+          .gsub(/\s+/, " ")        # collapse whitespace
+          .sub(/\A[\s"'`,:=#*>\-\]}]+/, "")  # leading JSON/markdown artifacts
+          .sub(/[\s"'`,:\-\]}]+\z/, "")       # trailing JSON artifacts
+          .strip
+      end
+
       def global_scope_signal?(text)
         GLOBAL_SCOPE_PATTERNS.any? { |pattern| text.match?(pattern) }
       end

data/lib/claude_memory/distill/reference_material_detector.rb

@@ -76,11 +76,14 @@ module ClaudeMemory
           end
         end
 
+        # Only facts are transformed; every other field must pass through
+        # unchanged (an earlier version silently dropped observations).
         Distill::Extraction.new(
           entities: extraction.entities,
           facts: new_facts,
           decisions: extraction.decisions,
-          signals: extraction.signals
+          signals: extraction.signals,
+          observations: extraction.observations
         )
       end