claude_memory 0.12.1 → 0.13.1

data/lib/claude_memory/hook/context_injector.rb

@@ -9,6 +9,8 @@ module ClaudeMemory
       MAX_DECISIONS = 5
       MAX_CONVENTIONS = 5
       MAX_ARCHITECTURE = 5
+      MAX_OBSERVATIONS = 10
+      MAX_PROMOTION_CANDIDATES = 5
       MAX_UNDISTILLED = 3
       MAX_TEXT_PER_ITEM = 1500
       MAX_MIRROR_CANDIDATES = 5
@@ -30,7 +32,8 @@ module ClaudeMemory
       # ({"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
+      attr_reader :emitted_fact_ids, :emitted_subjects, :emitted_facts_by_scope,
+        :emitted_observation_count
 
       def initialize(manager, source: nil, auto_memory_mirror: nil, stale_threshold_days: nil)
         @manager = manager
@@ -41,12 +44,14 @@ module ClaudeMemory
         @emitted_fact_ids = []
         @emitted_subjects = []
         @emitted_facts_by_scope = Hash.new { |h, k| h[k] = [] }
+        @emitted_observation_count = 0
       end
 
       def generate_context
         @emitted_fact_ids = []
         @emitted_subjects = []
         @emitted_facts_by_scope = Hash.new { |h, k| h[k] = [] }
+        @emitted_observation_count = 0
         sections = []
 
         decisions = fetch(:decisions, MAX_DECISIONS)
@@ -58,9 +63,25 @@ module ClaudeMemory
         architecture = fetch(:architecture, MAX_ARCHITECTURE)
         sections << format_section("Architecture", architecture) if architecture.any?
 
+        # Block 1 of the two-block context: the episodic observation log. Sits
+        # ahead of the (fresh-session) undistilled "Pending Knowledge Extraction"
+        # tail (Block 2). Newest-first; only 🔴 carries a marker for the actor.
+        observations = fetch_observations(MAX_OBSERVATIONS)
+        @emitted_observation_count = observations.size
+        obs_section = Observe::ObservationsRenderer.render(observations)
+        sections << obs_section if obs_section
+
         if fresh_session?
           undistilled = fetch_undistilled(MAX_UNDISTILLED)
-          sections << format_distillation_prompt(undistilled) if undistilled.any?
+          if undistilled.any?
+            sections << format_distillation_prompt(undistilled)
+            # The episodic-capture ask is its own prominent section (#72), not a
+            # buried paragraph inside the deep-distill prompt.
+            sections << format_observation_capture_prompt
+          end
+
+          promotion = fetch_promotion_candidates(MAX_PROMOTION_CANDIDATES)
+          sections << format_observation_reflection(promotion) if promotion.any?
 
           mirror_candidates = fetch_mirror_candidates(MAX_MIRROR_CANDIDATES)
           if mirror_candidates.any?
@@ -74,6 +95,19 @@ module ClaudeMemory
         sections.join("\n")
       end
 
+      # Reflection-only context for PreCompact (context pressure) — just the
+      # promote/consolidate instructions for corroborated/related observations.
+      # PreCompact is the analog of Mastra's token-threshold reflection trigger;
+      # at compaction we nudge the Claude-as-reflector pass rather than
+      # re-inject the full snapshot (which would add tokens as the window fills).
+      # @return [String, nil]
+      def reflection_context
+        candidates = fetch_promotion_candidates(MAX_PROMOTION_CANDIDATES)
+        return nil if candidates.empty?
+
+        format_observation_reflection(candidates)
+      end
+
       private
 
       def fresh_session?
@@ -124,6 +158,67 @@ module ClaudeMemory
         @stale_threshold_days ||= Configuration.new.injection_stale_days
       end
 
+      # Automatic semantic reflection (Phase 4): surface observations that have
+      # been corroborated past the promotion threshold so Claude can promote
+      # them to facts inline, this session, at no extra API cost.
+      # Project store only: the reflection nudge renders bare `[obs #<id>]` and
+      # `memory.promote_observation`/`consolidate_observations` default to the
+      # project scope. Observation ids autoincrement *per-DB*, so mixing in
+      # global-store candidates would route a promote call to the wrong DB.
+      # Observations are written project-scoped on the ingest path today; if a
+      # global observation writer is ever added, scope-tag the nudge line
+      # (mirror @emitted_facts_by_scope) before broadening this.
+      def fetch_promotion_candidates(limit)
+        store = @manager.project_store
+        return [] unless store
+
+        store
+          .promotion_candidates(min_corroboration: Domain::Observation::PROMOTION_THRESHOLD, limit: limit)
+          .sort_by { |o| -(o[:corroboration_count] || 0) }
+          .first(limit)
+      rescue => e
+        ClaudeMemory.logger.warn("ContextInjector#fetch_promotion_candidates failed: #{e.message}")
+        []
+      end
+
+      def format_observation_reflection(candidates)
+        lines = [
+          "## Observation Reflection",
+          "",
+          "**Promote:** these observations have recurred enough to be worth committing",
+          "as facts (corroboration gate passed). For each that represents a stable truth,",
+          "call `memory.promote_observation(observation_id, predicate, object)` — embed a",
+          "reason in the object (\"… because …\", \"… so that …\"). Skip noise / already-captured.",
+          "",
+          "**Consolidate:** if several observations in the log above (by `#id`) describe the",
+          "same thing in different words, merge them with",
+          "`memory.consolidate_observations(from_ids: […], body: \"<synthesis>\")`. Their",
+          "corroboration combines, which can tip the merged observation past the promotion gate."
+        ]
+
+        candidates.each do |obs|
+          lines << ""
+          lines << "- [obs ##{obs[:id]} ×#{obs[:corroboration_count]}] #{obs[:body]}"
+        end
+
+        lines.join("\n")
+      end
+
+      def fetch_observations(limit)
+        stores = []
+        stores << @manager.project_store if @manager.project_store
+        stores << @manager.global_store if @manager.global_store
+
+        stores
+          .flat_map { |s| s.recent_observations(limit: limit) }
+          .sort_by { |o| o[:observed_at] || "" }
+          .reverse
+          .first(limit)
+      rescue => e
+        ClaudeMemory.logger.warn("ContextInjector#fetch_observations failed: #{e.message}")
+        []
+      end
+
       def fetch_undistilled(limit)
         stores = []
         stores << @manager.project_store if @manager.project_store
@@ -171,6 +266,34 @@ module ClaudeMemory
         lines.join("\n")
       end
 
+      # First-class, standalone ask for the episodic layer (#72). Authoring
+      # observations was previously a paragraph buried inside the optional
+      # deep-distill flow above, and that flow fires almost never — so the
+      # episodic log was 100% Layer-1 scrapes. This decouples it: a prominent,
+      # lightweight instruction to log "what happened" directly, the same way
+      # the fact context rides the session. Effectiveness is measurable via the
+      # `mcp_extraction` content-item source (Layer-2) vs `claude_code` (Layer-1).
+      def format_observation_capture_prompt
+        <<~PROMPT.strip
+          ## Log What Happened (episodic memory)
+
+          Record the recent narrative as **observations** — "what happened",
+          complementing the facts above ("what is true"). For each discrete
+          event in the recent work above (a decision made, a preference stated,
+          a notable fix or outcome), call `memory.store_extraction` with an
+          `observations` array — one entry per event:
+
+          - `body`: one concise sentence of what happened (embed a reason for
+            decisions/preferences — "… because …", "… so that …")
+          - `kind`: `decision`, `preference`, or `event`
+          - `priority`: 1 important, 2 maybe, 3 info
+
+          Keep it to genuine events worth remembering — skip routine steps and
+          code output. Observations accumulate and a corroborated one graduates
+          into a fact. Send them with the facts in the same call, or on their own.
+        PROMPT
+      end
+
       def format_section(title, items)
         items = items.compact.uniq
         return nil if items.empty?

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

@@ -13,6 +13,10 @@ module ClaudeMemory
           entities = (args["entities"] || []).map { |e| symbolize_keys(e) }
           facts = (args["facts"] || []).map { |f| symbolize_keys(f) }
           decisions = (args["decisions"] || []).map { |d| symbolize_keys(d) }
+          # Layer-2 episodic observations. Claude's output is semi-trusted, so
+          # each is coerced and validated at this boundary; invalid rows are
+          # dropped rather than aborting the batch.
+          observations = (args["observations"] || []).filter_map { |o| coerce_observation(o) }
 
           config = Configuration.new
           project_path = config.project_dir
@@ -26,7 +30,8 @@ module ClaudeMemory
             entities: entities,
             facts: facts,
             decisions: decisions,
-            signals: []
+            signals: [],
+            observations: observations
           )
 
           # Guard against the LLM distiller labeling descriptions of external
@@ -52,7 +57,113 @@ module ClaudeMemory
             entities_created: result[:entities_created],
             facts_created: result[:facts_created],
             facts_superseded: result[:facts_superseded],
-            conflicts_created: result[:conflicts_created]
+            conflicts_created: result[:conflicts_created],
+            observations_created: result[:observations_created]
+          }
+        end
+
+        # Coerce one Claude-supplied observation into a clean candidate, or nil
+        # when it can't be a usable episodic row. Defaults live here so the
+        # rest of the pipeline never sees a blank body or an out-of-range
+        # priority. Returns a symbol-keyed hash for Resolver#persist_observations.
+        def coerce_observation(raw)
+          obs = symbolize_keys(raw)
+          body = obs[:body].to_s.strip
+          return nil if body.empty?
+
+          kind = Domain::Observation::KINDS.include?(obs[:kind]) ? obs[:kind] : "event"
+          priority = obs[:priority].to_i
+          priority = Domain::Observation::INFO unless (Domain::Observation::IMPORTANT..Domain::Observation::INFO).cover?(priority)
+
+          {body: body, kind: kind, priority: priority}
+        end
+
+        # Promotion bridge: turn a corroborated observation into a structured
+        # fact. Server-side anti-hallucination gate — refuses to promote an
+        # observation that has not been sighted at least PROMOTION_THRESHOLD
+        # times. Creates the fact through the resolver (so supersession/conflict
+        # handling applies) and marks the observation promoted so it is not
+        # re-suggested.
+        def promote_observation(args)
+          scope = args["scope"] || "project"
+          store = get_store_for_scope(scope)
+          return {error: "Database not available"} unless store
+
+          observation_id = args["observation_id"]
+          return {error: "observation_id required"} if observation_id.nil?
+
+          obs = store.observations.where(id: observation_id).first
+          return {error: "Observation #{observation_id} not found in #{scope} database"} unless obs
+          return {error: "Observation #{observation_id} already promoted (fact #{obs[:promoted_fact_id]})"} unless obs[:promoted_at].nil?
+
+          threshold = Domain::Observation::PROMOTION_THRESHOLD
+          if obs[:corroboration_count].to_i < threshold
+            return {error: "Not yet corroborated: observation #{observation_id} has #{obs[:corroboration_count]} sighting(s), need #{threshold}. Promotion requires repeated corroboration (anti-hallucination gate)."}
+          end
+
+          predicate = args["predicate"]
+          object = args["object"]
+          return {error: "predicate and object are required"} if predicate.nil? || object.to_s.strip.empty?
+          subject = args["subject"] || "repo"
+
+          config = Configuration.new
+          project_path = config.project_dir
+          occurred_at = Time.now.utc.iso8601
+
+          extraction = Distill::Extraction.new(
+            facts: [{subject: subject, predicate: predicate, object: object, strength: "derived"}]
+          )
+          result = Resolve::Resolver.new(store).apply(
+            extraction, content_item_id: obs[:source_content_item_id],
+            occurred_at: occurred_at, project_path: project_path, scope: scope
+          )
+
+          # The resolver reports the id of the fact it actually touched
+          # (inserted, reinforced, or disputed) — no need to re-query for it.
+          fact_id = result[:fact_ids].compact.first
+          return {error: "Promotion failed: the fact for observation #{observation_id} could not be resolved after creation"} unless fact_id
+
+          store.mark_observation_promoted(observation_id, fact_id: fact_id)
+
+          {
+            success: true,
+            observation_id: observation_id,
+            fact_id: fact_id,
+            predicate: Resolve::PredicatePolicy.canonicalize(predicate),
+            object: object,
+            corroboration_count: obs[:corroboration_count],
+            facts_created: result[:facts_created]
+          }
+        end
+
+        # Semantic reflection: merge several related observations into one
+        # synthesized observation (the Claude-as-reflector pass). Validates the
+        # synthesized body at the border via coerce_observation, then delegates
+        # the atomic merge to the store.
+        def consolidate_observations(args)
+          scope = args["scope"] || "project"
+          store = get_store_for_scope(scope)
+          return {error: "Database not available"} unless store
+
+          from_ids = Array(args["from_ids"]).map(&:to_i).reject(&:zero?).uniq
+          return {error: "from_ids must list at least 2 observation ids"} if from_ids.size < 2
+
+          synthesized = coerce_observation(args)
+          return {error: "body is required"} unless synthesized
+
+          project_path = (scope == "global") ? nil : Configuration.new.project_dir
+          result = store.consolidate_observations(
+            from_ids, body: synthesized[:body], kind: synthesized[:kind],
+            priority: synthesized[:priority], scope: scope, project_path: project_path
+          )
+          return {error: "Need at least 2 active #{scope} observations from that set to consolidate"} unless result
+
+          {
+            success: true,
+            scope: scope,
+            consolidated_into: result[:id],
+            merged: result[:merged],
+            corroboration_count: result[:corroboration_count]
           }
         end
 

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

@@ -49,7 +49,15 @@ module ClaudeMemory
           explanation = @recall.explain(args["fact_id"], scope: scope)
           return {error: "Fact not found in #{scope} database"} if explanation.is_a?(Core::NullExplanation)
 
-          ResponseFormatter.format_explanation(explanation, scope)
+          result = ResponseFormatter.format_explanation(explanation, scope)
+
+          # Episodic provenance: if this fact was promoted from observations,
+          # show the lineage back to them (reverse of observations.promoted_fact_id).
+          store = get_store_for_scope(scope)
+          promoted_from = store ? store.observations_for_fact(args["fact_id"]) : []
+          result[:promoted_from_observations] = promoted_from if result.is_a?(Hash) && promoted_from.any?
+
+          result
         end
 
         def recall_semantic(args)
@@ -109,6 +117,45 @@ module ClaudeMemory
             }
           }
         end
+
+        # List recent episodic observations (the "what happened" log). Read-only.
+        # Phase 1 queries one scope's store (default project); cross-scope merge
+        # comes with the stable-prefix injection phase.
+        def observations(args)
+          return database_not_found_error unless databases_exist?
+
+          scope = args["scope"] || "project"
+          limit = extract_limit(args, default: 20)
+          min_priority = (args["important_only"] == true) ? Domain::Observation::IMPORTANT : nil
+
+          store = get_store_for_scope(scope)
+          return {error: "Database not available"} unless store
+
+          rows = store.recent_observations(scope: scope, limit: limit, min_priority: min_priority)
+
+          {
+            observation_count: rows.size,
+            observations: rows.map { |row|
+              obs = Domain::Observation.new(row)
+              {
+                id: obs.id,
+                kind: obs.kind,
+                priority: obs.priority,
+                body: obs.body,
+                scope: obs.scope,
+                status: obs.status,
+                corroboration_count: obs.corroboration_count,
+                promoted_fact_id: obs.promoted_fact_id,
+                consolidated_into: obs.consolidated_into,
+                source_content_item_id: obs.source_content_item_id,
+                observed_at: obs.observed_at,
+                observed_ago: Core::RelativeTime.format(obs.observed_at)
+              }
+            }
+          }
+        rescue Sequel::DatabaseError, Sequel::DatabaseConnectionError, Errno::ENOENT => e
+          classified_error(e, tool_name: "memory.observations")
+        end
       end
     end
   end

data/lib/claude_memory/mcp/instructions_builder.rb

@@ -125,6 +125,7 @@ module ClaudeMemory
           - Before refactoring: call memory.decisions to understand why past choices were made
           - When asked about preferences: global facts store user environment and style preferences across all projects
           - When adding to the codebase: recall which files and patterns to follow (memory knows correct paths and relationships)
+          - When reviewing what happened or curating memory: call memory.observations to read the episodic log and surface corroborated patterns worth promoting to facts
         GUIDANCE
       end
 

data/lib/claude_memory/mcp/query_guide.rb

@@ -87,6 +87,34 @@ module ClaudeMemory
         - Use after: performing LLM-based fact extraction on undistilled content
         - Cost: ~100 tokens per call
 
+        ### Tier 6: Episodic Observation Management
+
+        Observations are the episodic "what happened" log that complements facts
+        ("what is true"). They accrue automatically; these tools let you inspect
+        and curate them. The `/reflect` skill wraps the full survey→consolidate→
+        promote workflow if you want it guided.
+
+        **memory.observations** — Read the episodic observation log
+        - Use for: surveying recent narrative ("what happened"), spotting patterns
+          that recur enough to become facts, checking promotion readiness
+        - Returns: observations with status/kind/priority, corroboration_count,
+          and promoted_fact_id where promoted
+        - Cost: ~200-500 tokens per call
+
+        **memory.promote_observation** — Promote a corroborated observation to a fact
+        - Use when: an observation has been corroborated (seen ≥ 2 times) and
+          represents a stable truth worth committing as a structured fact
+        - Gate: refuses uncorroborated or already-promoted observations — this is
+          the anti-hallucination defense against one-off doc/example text
+        - Embed a reason in the object ("… because …", "… so that …")
+        - Cost: ~200 tokens per call
+
+        **memory.consolidate_observations** — Merge related observations into one
+        - Use when: several observations describe the same thing in different words
+        - Effect: corroboration counts combine (which can tip the merged row past
+          the promotion gate); sources are tombstoned (preserved, not deleted)
+        - Cost: ~200 tokens per call
+
         ## Recommended Workflow
 
         1. **Start broad**: `memory.recall` or shortcut tools (decisions/conventions/architecture)

data/lib/claude_memory/mcp/tool_definitions.rb

@@ -276,6 +276,19 @@ module ClaudeMemory
                     required: ["title", "summary"]
                   }
                 },
+                observations: {
+                  type: "array",
+                  description: "Episodic observations — what happened this session (experimental, observational layer). Complements facts ('what is true') with 'what happened': decisions made, preferences stated, notable actions/outcomes. One per discrete event; embed a reason for decisions/preferences.",
+                  items: {
+                    type: "object",
+                    properties: {
+                      body: {type: "string", description: "Concise statement of what happened"},
+                      kind: {type: "string", enum: %w[user_statement agent_action tool_result preference decision event], description: "What kind of event (default: event)"},
+                      priority: {type: "integer", enum: [1, 2, 3], description: "Internal signal: 1=important, 2=maybe, 3=info (default: 3)"}
+                    },
+                    required: ["body"]
+                  }
+                },
                 scope: {type: "string", enum: ["global", "project"], description: "Default scope for facts", default: "project"}
               },
               required: ["facts"]
@@ -451,6 +464,51 @@ module ClaudeMemory
               }
             },
             annotations: READ_ONLY
+          },
+          {
+            name: "memory.observations",
+            description: "List recent episodic observations — the 'what happened' log that complements facts ('what is true'). Append-only, newest first. Priority is an internal signal (1=important, 2=maybe, 3=info).",
+            inputSchema: {
+              type: "object",
+              properties: {
+                scope: {type: "string", enum: %w[project global], description: "Filter by scope; omit for any"},
+                limit: {type: "integer", default: 20, description: "Maximum observations to return"},
+                important_only: {type: "boolean", default: false, description: "Return only priority-1 (🔴) observations"}
+              }
+            },
+            annotations: READ_ONLY
+          },
+          {
+            name: "memory.promote_observation",
+            description: "Promote a corroborated observation into a structured fact (the observation→fact bridge). Refuses observations sighted fewer than the corroboration threshold (anti-hallucination gate). Embed a reason in the object (because…/so that…). Surfaced by the SessionStart 'Observation Reflection' section.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                observation_id: {type: "integer", description: "The corroborated observation to promote"},
+                predicate: {type: "string", description: "Fact predicate (e.g. decision, convention, architecture)"},
+                object: {type: "string", description: "Fact object — include a reason clause"},
+                subject: {type: "string", default: "repo", description: "Fact subject (default: repo)"},
+                scope: {type: "string", enum: %w[project global], default: "project"}
+              },
+              required: ["observation_id", "predicate", "object"]
+            },
+            annotations: WRITE
+          },
+          {
+            name: "memory.consolidate_observations",
+            description: "Semantic reflection: merge several related observations (that say the same thing in different words) into one synthesized observation. Corroboration combines, which can tip the result over the promotion threshold. The originals are tombstoned (preserved, linked), not deleted.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                from_ids: {type: "array", items: {type: "integer"}, minItems: 2, description: "Observation ids to merge (>= 2, same scope)"},
+                body: {type: "string", description: "The synthesized observation text"},
+                kind: {type: "string", enum: %w[user_statement agent_action tool_result preference decision event], description: "Kind of the merged observation (default: event)"},
+                priority: {type: "integer", enum: [1, 2, 3], description: "1=important, 2=maybe, 3=info (default: 3)"},
+                scope: {type: "string", enum: %w[project global], default: "project"}
+              },
+              required: ["from_ids", "body"]
+            },
+            annotations: WRITE
           }
         ]
       end

data/lib/claude_memory/mcp/tools.rb

@@ -98,6 +98,9 @@ module ClaudeMemory
         when "memory.check_setup" then check_setup
         when "memory.list_projects" then list_projects
         when "memory.activity" then activity(arguments)
+        when "memory.observations" then observations(arguments)
+        when "memory.promote_observation" then promote_observation(arguments)
+        when "memory.consolidate_observations" then consolidate_observations(arguments)
         else {error: "Unknown tool: #{name}"}
         end
       end

data/lib/claude_memory/observe/observations_renderer.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Observe
+    # Renders episodic observation rows into the actor-facing markdown block —
+    # the front-loaded "what happened" log that complements the fact snapshot
+    # ("what is true").
+    #
+    # Priority is an internal Observer/Reflector signal. Following Mastra, only
+    # 🔴 (important) survives as a marker when shown to the actor; 🟡/🟢 are
+    # stripped as visual noise. The observation bodies themselves are always
+    # shown — the emoji is the only thing filtered.
+    module ObservationsRenderer
+      IMPORTANT_MARKER = "🔴"
+
+      module_function
+
+      # @param observations [Array<Hash>] rows with :body, :priority, :observed_at
+      # @param title [String] section heading
+      # @param intro [Boolean] include the one-line explainer (true for injection)
+      # @return [String, nil] markdown block, or nil when there is nothing to show
+      def render(observations, title: "Observations (what happened)", intro: true)
+        rows = Array(observations).reject { |o| o[:body].to_s.strip.empty? }
+        return nil if rows.empty?
+
+        lines = ["## #{title}"]
+        if intro
+          lines << ""
+          lines << "Episodic log of what happened in this project — complements the facts above (what is true). Newest first."
+        end
+        lines << ""
+        rows.each { |obs| lines << format_line(obs) }
+        lines.join("\n")
+      end
+
+      # @return [String] a single "- [#id] [🔴 ]body (time ago)" log line. The
+      # id tag lets the reflection step reference an observation for
+      # promote/consolidate; it's omitted when the row carries no id.
+      def format_line(obs)
+        body = obs[:body].to_s.strip
+        id_tag = obs[:id] ? "[##{obs[:id]}] " : ""
+        marker = (obs[:priority] == Domain::Observation::IMPORTANT) ? "#{IMPORTANT_MARKER} " : ""
+        ago = Core::RelativeTime.format(obs[:observed_at])
+        suffix = ago ? " (#{ago})" : ""
+        "- #{id_tag}#{marker}#{body}#{suffix}"
+      end
+    end
+  end
+end

data/lib/claude_memory/observe/reflector.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Observe
+    # Deterministic, free (no LLM) Reflector for the episodic observation log.
+    #
+    # Runs inside Sweep, which fires on PreCompact and SessionEnd — Claude
+    # Code's context-pressure lifecycle events. That is the analog of Mastra's
+    # token-threshold-triggered reflection: "reflect when memory gets big" maps
+    # onto "reflect when the session is about to compact", without a wall-clock
+    # timer (Claude Code has no cron hook) and without extra API cost.
+    #
+    # Two passes, both provenance-preserving (tombstone, never hard-delete):
+    #   - dedupe: collapse near-duplicate active observations (same scope) into
+    #     the newest, linking losers via consolidated_into. Similarity is decided
+    #     by an injected matcher (default: lexical token-overlap, #73) so the
+    #     promotion gate can actually accumulate corroboration — exact-string
+    #     matching never folded varied wording, leaving every observation at
+    #     corroboration 1 (the 2026-06-23 audit finding).
+    #   - expire_stale_info: retire info-level (🟢 / priority 3) observations
+    #     older than the TTL to bound context size. Important (🔴) and maybe
+    #     (🟡) are never expired — only the lowest-signal tier ages out.
+    #
+    # Semantic consolidation ("combine related items, surface patterns") is
+    # deliberately NOT here — it needs the LLM and lands in the Phase-4
+    # Claude-as-reflector pass. This pass is pure Ruby so it can run shell-side
+    # in the sweep hook for free.
+    class Reflector
+      DEFAULT_INFO_TTL_DAYS = 30
+
+      # @return [Struct] counts from one reflection pass
+      Result = Struct.new(:deduped, :expired) do
+        def total
+          deduped + expired
+        end
+      end
+
+      def initialize(store, info_ttl_days: DEFAULT_INFO_TTL_DAYS, matcher: TokenOverlapMatcher.new)
+        @store = store
+        @info_ttl_days = info_ttl_days
+        @matcher = matcher
+      end
+
+      # @return [Result] number of observations deduped and expired
+      def reflect!
+        deduped = 0
+        expired = 0
+        @store.db.transaction do
+          deduped = dedupe
+          expired = expire_stale_info
+        end
+        Result.new(deduped: deduped, expired: expired)
+      end
+
+      private
+
+      def dedupe
+        active = @store.observations.where(status: "active").order(:id).all
+        active.group_by { |o| o[:scope] }.sum { |_scope, rows| dedupe_scope(rows) }
+      end
+
+      # Greedy clustering within one scope: the newest observation in a cluster
+      # is the keeper; older near-duplicates fold into it. O(n²) matcher calls,
+      # but n is bounded (#74 cut the inflow; expire_stale_info bounds the tail).
+      def dedupe_scope(rows)
+        return 0 if rows.size < 2
+
+        ordered = rows.sort_by { |r| [r[:observed_at].to_s, r[:id]] }.reverse
+        folded = {}
+        merged = 0
+
+        ordered.each do |keeper|
+          next if folded[keeper[:id]]
+
+          ordered.each do |other|
+            next if other[:id] == keeper[:id] || folded[other[:id]]
+            next unless @matcher.similar?(keeper[:body], other[:body])
+
+            # Fold the duplicate's sightings into the keeper before tombstoning
+            # so corroboration survives consolidation and can cross the promotion
+            # threshold. A duplicate IS a repeated sighting.
+            @store.increment_corroboration(keeper[:id], by: other[:corroboration_count] || 1)
+            @store.tombstone_observation(other[:id], into_id: keeper[:id])
+            folded[other[:id]] = true
+            merged += 1
+          end
+
+          folded[keeper[:id]] = true
+        end
+
+        merged
+      end
+
+      def expire_stale_info
+        cutoff = (Time.now - @info_ttl_days * 86400).utc.iso8601
+        ids = @store.observations
+          .where(status: "active", priority: Domain::Observation::INFO)
+          .where { observed_at < cutoff }
+          .select(:id)
+          .map { |r| r[:id] }
+
+        ids.each { |id| @store.expire_observation(id) }
+        ids.size
+      end
+    end
+  end
+end