claude_memory 0.12.1 → 0.13.0

data/lib/claude_memory/audit/checks.rb

@@ -226,6 +226,155 @@ module ClaudeMemory
         end
       end
 
+      # Scopes whose stores carry an observations table. Observation checks
+      # iterate both DBs because observations may be project- or global-scoped.
+      OBSERVATION_SCOPES = %i[project global].freeze
+
+      # Valid observation lifecycle states. Anything else means a writer or
+      # migration stamped a status the resolver/reflector never produce.
+      OBSERVATION_STATUSES = %w[active consolidated expired].freeze
+
+      def observation_stores(manager)
+        OBSERVATION_SCOPES
+          .map { |scope| [scope, manager.store_if_exists(scope.to_s)] }
+          .reject { |_, store| store.nil? }
+      end
+
+      # C011 — Orphaned observations (provenance points at a missing content item).
+      def orphaned_observations(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          content_ids = store.content_items.select(:id)
+          orphans = store.observations
+            .exclude(source_content_item_id: nil)
+            .exclude(source_content_item_id: content_ids)
+            .select(:id)
+            .all
+          next [] if orphans.empty?
+
+          [Finding.new(
+            id: "C011",
+            severity: :warn,
+            title: "#{orphans.size} observation(s) in #{scope} DB reference a missing content item",
+            detail: "An observation's source_content_item_id should point at the content_items row it was distilled from. A dangling pointer means the source row was pruned or never existed, so the observation's provenance can no longer be explained.",
+            suggestion: "Inspect with memory.observations. These rows are append-only; if the provenance is unrecoverable, consolidate or expire them via the Reflector (PreCompact/SessionEnd) rather than deleting.",
+            fact_ids: orphans.map { |r| r[:id] }
+          )]
+        end
+      end
+
+      # C012 — Promotion consistency (promoted_at ⇔ promoted_fact_id, fact must exist + be active).
+      def observation_promotion_consistency(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          active_fact_ids = store.facts.where(status: "active").select(:id)
+
+          missing_fact_id = store.observations
+            .exclude(promoted_at: nil)
+            .where(promoted_fact_id: nil)
+            .select(:id).all
+          dangling_fact = store.observations
+            .exclude(promoted_fact_id: nil)
+            .exclude(promoted_fact_id: store.facts.select(:id))
+            .select(:id, :promoted_fact_id).all
+          inactive_fact = store.observations
+            .exclude(promoted_fact_id: nil)
+            .exclude(promoted_fact_id: active_fact_ids)
+            .exclude(promoted_fact_id: dangling_fact.map { |r| r[:promoted_fact_id] })
+            .select(:id, :promoted_fact_id).all
+          missing_timestamp = store.observations
+            .exclude(promoted_fact_id: nil)
+            .where(promoted_at: nil)
+            .select(:id).all
+
+          obs_ids = (missing_fact_id + dangling_fact + inactive_fact + missing_timestamp).map { |r| r[:id] }.uniq
+          next [] if obs_ids.empty?
+
+          problems = []
+          problems << "#{missing_fact_id.size} promoted but missing promoted_fact_id" unless missing_fact_id.empty?
+          problems << "#{dangling_fact.size} promoted_fact_id pointing at a non-existent fact" unless dangling_fact.empty?
+          problems << "#{inactive_fact.size} promoted into a non-active fact" unless inactive_fact.empty?
+          problems << "#{missing_timestamp.size} have promoted_fact_id but no promoted_at" unless missing_timestamp.empty?
+
+          [Finding.new(
+            id: "C012",
+            severity: :error,
+            title: "#{obs_ids.size} observation(s) in #{scope} DB have inconsistent promotion state",
+            detail: "Promotion must be atomic: a promoted observation has both promoted_at set and promoted_fact_id pointing at an existing, active fact. Violations (#{problems.join("; ")}) mean mark_observation_promoted ran partially or the target fact was later rejected/superseded, leaving the observation pointing at nothing usable.",
+            suggestion: "Inspect the fact with claude-memory explain <fact_id>. If the fact was intentionally rejected, the observation should be re-opened for re-promotion via memory.promote_observation; if mark_observation_promoted half-ran, re-run promotion.",
+            fact_ids: obs_ids
+          )]
+        end
+      end
+
+      # C013 — Tombstone-chain validity (consolidated_into must point to a real,
+      # non-self row and a consolidated observation must not stay active).
+      def observation_tombstone_chain(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          obs_ids = store.observations.select(:id)
+
+          dangling = store.observations
+            .exclude(consolidated_into: nil)
+            .exclude(consolidated_into: obs_ids)
+            .select(:id, :consolidated_into).all
+          self_link = store.observations
+            .exclude(consolidated_into: nil)
+            .where(Sequel[:consolidated_into] => Sequel[:id])
+            .select(:id).all
+          active_but_tombstoned = store.observations
+            .exclude(consolidated_into: nil)
+            .where(status: "active")
+            .select(:id).all
+          consolidated_without_link = store.observations
+            .where(status: "consolidated", consolidated_into: nil)
+            .select(:id).all
+
+          flagged = (dangling + self_link + active_but_tombstoned + consolidated_without_link).map { |r| r[:id] }.uniq
+          next [] if flagged.empty?
+
+          problems = []
+          problems << "#{dangling.size} consolidated_into → missing observation" unless dangling.empty?
+          problems << "#{self_link.size} consolidated_into self-link" unless self_link.empty?
+          problems << "#{active_but_tombstoned.size} active yet have a consolidated_into target" unless active_but_tombstoned.empty?
+          problems << "#{consolidated_without_link.size} status=consolidated with no consolidated_into keeper" unless consolidated_without_link.empty?
+
+          [Finding.new(
+            id: "C013",
+            severity: :error,
+            title: "#{flagged.size} observation(s) in #{scope} DB have a broken tombstone chain",
+            detail: "Tombstoning is append-only: a superseded observation gets status=consolidated and consolidated_into pointing at the surviving keeper. Violations (#{problems.join("; ")}) corrupt the lineage — recall could surface a tombstoned row, or a consolidated row could orphan its history.",
+            suggestion: "Inspect with memory.observations. Re-run the deterministic Reflector (fires on PreCompact/SessionEnd) to re-derive consolidation; a self-link or active+tombstoned row indicates a Reflector bug — file it rather than hand-editing the append-only table.",
+            fact_ids: flagged
+          )]
+        end
+      end
+
+      # C014 — Status / corroboration sanity (known status set, corroboration ≥ 1).
+      def observation_status_corroboration(manager)
+        observation_stores(manager).flat_map do |scope, store|
+          bad_status = store.observations
+            .exclude(status: OBSERVATION_STATUSES)
+            .select(:id).all
+          bad_corroboration = store.observations
+            .where { corroboration_count < 1 }
+            .select(:id).all
+
+          flagged = (bad_status + bad_corroboration).map { |r| r[:id] }.uniq
+          next [] if flagged.empty?
+
+          problems = []
+          problems << "#{bad_status.size} with status outside #{OBSERVATION_STATUSES.inspect}" unless bad_status.empty?
+          problems << "#{bad_corroboration.size} with corroboration_count < 1" unless bad_corroboration.empty?
+
+          [Finding.new(
+            id: "C014",
+            severity: :warn,
+            title: "#{flagged.size} observation(s) in #{scope} DB have invalid status/corroboration",
+            detail: "Every observation should carry a known lifecycle status (#{OBSERVATION_STATUSES.join("/")}) and at least one sighting (corroboration_count ≥ 1; a fresh insert counts as 1). Violations (#{problems.join("; ")}) break the promotion gate (which keys off corroboration) and the recall filters (which key off status).",
+            suggestion: "Inspect with memory.observations. A corroboration_count < 1 means increment_corroboration math went negative; an unknown status means a migration or external writer bypassed insert_observation. Re-derive via the Reflector if possible.",
+            fact_ids: flagged
+          )]
+        end
+      end
+
       def normalize_convention(text)
         text.to_s
           .downcase

data/lib/claude_memory/audit/runner.rb

@@ -20,6 +20,10 @@ module ClaudeMemory
         bare_conclusion_rate
         project_starvation
         auto_memory_unimported
+        orphaned_observations
+        observation_promotion_consistency
+        observation_tombstone_chain
+        observation_status_corroboration
       ].freeze
 
       Result = Data.define(:findings, :stats) do

data/lib/claude_memory/commands/census_command.rb

@@ -138,7 +138,7 @@ module ClaudeMemory
 
         predicates = db[:facts].select(:predicate, :status).group_and_count(:predicate, :status).all
           .each_with_object(Hash.new { |h, k| h[k] = Hash.new(0) }) do |row, acc|
-            acc[row[:predicate].to_s][row[:status].to_s] += row[:count].to_i
+          acc[row[:predicate].to_s][row[:status].to_s] += row[:count].to_i
         end
 
         entity_types = db[:entities].group_and_count(:type).all.each_with_object(Hash.new(0)) do |row, acc|

data/lib/claude_memory/commands/hook_command.rb

@@ -205,14 +205,26 @@ module ClaudeMemory
 
         t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         injector = ClaudeMemory::Hook::ContextInjector.new(manager, source: source)
-        context_text = injector.generate_context
+        # On PreCompact (context pressure) inject only the reflection nudge, not
+        # the full snapshot; everywhere else inject the full SessionStart context.
+        context_text = if payload["hook_event_name"] == "PreCompact"
+          injector.reflection_context
+        else
+          injector.generate_context
+        end
         duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
 
         if context_text
           response = {
             hookSpecificOutput: {
               hookEventName: "SessionStart",
-              additionalContext: context_text
+              # Wrap in <claude-memory-context> so a later ingest strips our own
+              # injected snapshot back out (ContentSanitizer lists this tag in
+              # SYSTEM_TAGS). Without the wrapper, memory's injected facts and
+              # observation log leak into the transcript and get re-distilled —
+              # a self-ingestion feedback loop. Claude still reads the content;
+              # only the re-ingestion path treats it as strippable.
+              additionalContext: "<claude-memory-context>\n#{context_text}\n</claude-memory-context>"
             }
           }
           stdout.puts JSON.generate(response)
@@ -243,7 +255,8 @@ module ClaudeMemory
           top_fact_ids: injector.emitted_fact_ids.first(10),
           top_facts_by_scope: (by_scope if by_scope.any?),
           top_subjects: injector.emitted_subjects.uniq.first(10),
-          fact_count: injector.emitted_fact_ids.size
+          fact_count: injector.emitted_fact_ids.size,
+          observation_count: injector.emitted_observation_count
         }.compact
 
         ClaudeMemory::ActivityLog.record(store,

data/lib/claude_memory/commands/initializers/hooks_configurator.rb

@@ -126,7 +126,9 @@ module ClaudeMemory
                   {"type" => "command", "command" => ingest_cmd, "timeout" => 30,
                    "statusMessage" => "Saving memory..."},
                   {"type" => "command", "command" => sweep_cmd, "timeout" => 30,
-                   "statusMessage" => "Sweeping memory..."}
+                   "statusMessage" => "Sweeping memory..."},
+                  {"type" => "command", "command" => context_cmd, "timeout" => 5,
+                   "statusMessage" => "Reflecting on memory..."}
                 ]
               }],
               "SessionEnd" => [{

data/lib/claude_memory/commands/install_skill_command.rb

@@ -15,6 +15,10 @@ module ClaudeMemory
         "distill-transcripts" => {
           file: "distill-transcripts.md",
           description: "Distill transcripts — extract facts/entities/decisions from undistilled content"
+        },
+        "reflect" => {
+          file: "reflect.md",
+          description: "Reflect on observations — consolidate the episodic log and promote corroborated observations to facts"
         }
       }.freeze
 

data/lib/claude_memory/commands/observations_command.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+
+module ClaudeMemory
+  module Commands
+    # CLI parity for the episodic observation layer — the "what happened" log
+    # that complements the semantic fact store ("what is true").
+    #
+    # Subcommands:
+    #   observations [list]   Summary: counts by status/kind/priority,
+    #                         corroboration + promotion readiness, compression
+    #                         ratio, and a recent timeline.
+    #   observations promote <id> --predicate P --object O [--subject S] [--scope ...]
+    #   observations consolidate <id1,id2,...> --body "<synthesis>" [--scope ...]
+    #
+    # The promote subcommand reuses the same corroboration gate and Resolver
+    # path as the memory.promote_observation MCP tool, so the anti-hallucination
+    # threshold is enforced identically across surfaces.
+    class ObservationsCommand < BaseCommand
+      def call(args)
+        subcommand = args.first
+        case subcommand
+        when "promote"
+          promote(args.drop(1))
+        when "consolidate"
+          consolidate(args.drop(1))
+        when "list", nil
+          list(args.drop(subcommand ? 1 : 0))
+        else
+          # Treat unknown first token as options to `list` (e.g. --json).
+          list(args)
+        end
+      end
+
+      private
+
+      # --- list (default) -----------------------------------------------------
+
+      def list(args)
+        opts = parse_options(args, {limit: 20, kind: nil, status: "active", scope: nil, json: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory observations [list] [options]"
+            parser.on("--limit N", Integer, "Max rows in the recent timeline (default: 20)") { |v| o[:limit] = v }
+            parser.on("--kind K", "Filter timeline by kind (e.g. decision, preference, event)") { |v| o[:kind] = v }
+            parser.on("--status S", "Filter timeline by status (active, consolidated, expired)") { |v| o[:status] = v }
+            parser.on("--scope SCOPE", %w[project global], "Limit to a single scope") { |v| o[:scope] = v }
+            parser.on("--json", "Emit machine-readable JSON") { o[:json] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        stores = observation_stores(manager, opts[:scope])
+
+        report = build_report(stores, opts)
+        manager.close
+
+        if opts[:json]
+          stdout.puts(JSON.pretty_generate(report))
+        else
+          render_report(report)
+        end
+        0
+      end
+
+      def build_report(stores, opts)
+        {
+          totals: totals(stores),
+          by_kind: by_field(stores, :kind),
+          by_priority: by_field(stores, :priority),
+          corroboration: corroboration(stores),
+          compression: compression(stores),
+          recent: recent(stores, opts)
+        }
+      end
+
+      def render_report(report)
+        stdout.puts "Observations (episodic 'what happened' log)"
+        stdout.puts "=" * 50
+        stdout.puts
+
+        render_totals(report[:totals])
+        stdout.puts
+        render_breakdown("By kind (active)", report[:by_kind])
+        stdout.puts
+        render_priority(report[:by_priority])
+        stdout.puts
+        render_corroboration(report[:corroboration])
+        stdout.puts
+        render_compression(report[:compression])
+        stdout.puts
+        render_recent(report[:recent])
+      end
+
+      def render_totals(totals)
+        stdout.puts "Totals:"
+        stdout.puts "  Active: #{totals[:active]}"
+        stdout.puts "  Consolidated: #{totals[:consolidated]}"
+        stdout.puts "  Expired: #{totals[:expired]}"
+        stdout.puts "  Promoted: #{totals[:promoted]}"
+      end
+
+      def render_breakdown(title, counts)
+        stdout.puts "#{title}:"
+        if counts.empty?
+          stdout.puts "  (none)"
+          return
+        end
+        counts.sort_by { |_k, v| -v }.each do |key, count|
+          stdout.puts "  #{count.to_s.rjust(4)} - #{key}"
+        end
+      end
+
+      def render_priority(counts)
+        stdout.puts "By priority (active):"
+        if counts.empty?
+          stdout.puts "  (none)"
+          return
+        end
+        counts.sort_by { |priority, _v| priority }.each do |priority, count|
+          stdout.puts "  #{count.to_s.rjust(4)} - #{priority} (#{priority_label(priority)})"
+        end
+      end
+
+      def priority_label(priority)
+        case priority
+        when Domain::Observation::IMPORTANT then "important"
+        when Domain::Observation::MAYBE then "maybe"
+        else "info"
+        end
+      end
+
+      def render_corroboration(corroboration)
+        threshold = Domain::Observation::PROMOTION_THRESHOLD
+        stdout.puts "Corroboration:"
+        stdout.puts "  Max sightings: #{corroboration[:max]}"
+        stdout.puts "  Promotable (>= #{threshold} sightings, not yet promoted): #{corroboration[:promotable]}"
+      end
+
+      def render_compression(compression)
+        ratio = compression[:ratio]
+        stdout.puts "Compression:"
+        stdout.puts "  Observation tokens: #{compression[:observation_tokens]}"
+        stdout.puts "  Source tokens: #{compression[:source_tokens]}"
+        if ratio
+          stdout.puts "  Ratio (source / observation): #{ratio}x"
+        else
+          stdout.puts "  Ratio (source / observation): n/a"
+        end
+      end
+
+      def render_recent(recent)
+        stdout.puts "Recent timeline:"
+        if recent.empty?
+          stdout.puts "  (no observations)"
+          return
+        end
+        recent.each do |obs|
+          marker = priority_marker(obs[:priority])
+          stdout.puts "  ##{obs[:id]} #{marker} [#{obs[:kind]}] x#{obs[:corroboration_count]} (#{obs[:observed_ago]})"
+          stdout.puts "    #{obs[:body]}"
+        end
+      end
+
+      def priority_marker(priority)
+        case priority
+        when Domain::Observation::IMPORTANT then "[!]"
+        when Domain::Observation::MAYBE then "[~]"
+        else "[ ]"
+        end
+      end
+
+      # --- read aggregation (mirrors Dashboard::Observations) -----------------
+
+      def observation_stores(manager, scope)
+        scopes = scope ? [scope] : %w[project global]
+        scopes.filter_map { |s| manager.store_if_exists(s) }
+          .select { |store| store.db.table_exists?(:observations) }
+      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 || 0,
+          promotable: stores.sum do |s|
+            s.observations.where(status: "active", promoted_at: nil)
+              .where { corroboration_count >= threshold }.count
+          end
+        }
+      end
+
+      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, opts)
+        rows = stores.flat_map do |store|
+          dataset = store.observations
+          dataset = dataset.where(status: opts[:status]) if opts[:status]
+          dataset = dataset.where(kind: opts[:kind]) if opts[:kind]
+          dataset.order(Sequel.desc(:observed_at), Sequel.desc(:id)).limit(opts[:limit]).all
+        end
+
+        rows.sort_by { |o| o[:observed_at].to_s }.reverse.first(opts[: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
+
+      # --- promote ------------------------------------------------------------
+
+      def promote(args)
+        opts = parse_options(args, {predicate: nil, object: nil, subject: "repo", scope: "project"}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory observations promote <id> --predicate P --object O [options]"
+            parser.on("--predicate P", "Fact predicate (e.g. decision, convention)") { |v| o[:predicate] = v }
+            parser.on("--object O", "Fact object (the claim text)") { |v| o[:object] = v }
+            parser.on("--subject S", "Fact subject (default: repo)") { |v| o[:subject] = v }
+            parser.on("--scope SCOPE", %w[project global], "Database scope (default: project)") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        observation_id = parse_id(args.first)
+        return failure("Usage: claude-memory observations promote <id> --predicate P --object O") if observation_id.nil?
+        return failure("--predicate and --object are required") if opts[:predicate].nil? || opts[:object].to_s.strip.empty?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+
+        result = promote_observation(store, observation_id, opts)
+        manager.close
+
+        return failure(result[:error]) if result[:error]
+
+        stdout.puts "Promoted observation ##{observation_id} -> fact ##{result[:fact_id]}"
+        stdout.puts "  #{result[:predicate]}: #{result[:object]}"
+        stdout.puts "  Corroboration: #{result[:corroboration_count]} sighting(s)"
+        0
+      end
+
+      # Server-side corroboration gate + Resolver path — the same logic the
+      # memory.promote_observation MCP handler uses. Returns {error:} on refusal
+      # or {fact_id:, predicate:, object:, corroboration_count:} on success.
+      def promote_observation(store, observation_id, opts)
+        obs = store.observations.where(id: observation_id).first
+        return {error: "Observation #{observation_id} not found in #{opts[: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} (anti-hallucination gate)."}
+        end
+
+        occurred_at = Time.now.utc.iso8601
+        project_path = (opts[:scope] == "global") ? nil : Configuration.new.project_dir
+        extraction = Distill::Extraction.new(
+          facts: [{subject: opts[:subject], predicate: opts[:predicate], object: opts[: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: opts[:scope]
+        )
+
+        fact_id = result[:fact_ids].compact.first
+        return {error: "Promotion failed: the fact for observation #{observation_id} could not be resolved."} unless fact_id
+
+        store.mark_observation_promoted(observation_id, fact_id: fact_id)
+
+        {
+          fact_id: fact_id,
+          predicate: Resolve::PredicatePolicy.canonicalize(opts[:predicate]),
+          object: opts[:object],
+          corroboration_count: obs[:corroboration_count]
+        }
+      end
+
+      # --- consolidate --------------------------------------------------------
+
+      def consolidate(args)
+        opts = parse_options(args, {body: nil, kind: "event", priority: Domain::Observation::INFO, scope: "project"}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory observations consolidate <id1,id2,...> --body \"<synthesis>\" [options]"
+            parser.on("--body TEXT", "The synthesized observation text") { |v| o[:body] = v }
+            parser.on("--kind K", "Kind for the merged observation (default: event)") { |v| o[:kind] = v }
+            parser.on("--scope SCOPE", %w[project global], "Database scope (default: project)") { |v| o[:scope] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        from_ids = parse_id_list(args.first)
+        return failure("Usage: claude-memory observations consolidate <id1,id2,...> --body \"<synthesis>\"") if from_ids.size < 2
+        return failure("--body is required") if opts[:body].to_s.strip.empty?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+        project_path = (opts[:scope] == "global") ? nil : Configuration.new.project_dir
+
+        result = store.consolidate_observations(
+          from_ids, body: opts[:body].strip, kind: opts[:kind],
+          priority: opts[:priority], scope: opts[:scope], project_path: project_path
+        )
+        manager.close
+
+        return failure("Need at least 2 active #{opts[:scope]} observations from that set to consolidate.") if result.nil?
+
+        stdout.puts "Consolidated #{result[:merged]} observations -> ##{result[:id]}"
+        stdout.puts "  Combined corroboration: #{result[:corroboration_count]} sighting(s)"
+        0
+      end
+
+      # --- parsing helpers ----------------------------------------------------
+
+      def parse_id(token)
+        return nil if token.nil? || !token.match?(/\A\d+\z/)
+        token.to_i
+      end
+
+      def parse_id_list(token)
+        return [] if token.nil?
+        token.split(",").map(&:strip).select { |t| t.match?(/\A\d+\z/) }.map(&:to_i).uniq
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/registry.rb

@@ -37,6 +37,7 @@ module ClaudeMemory
         "completion" => {class: CompletionCommand, description: "Generate shell completions"},
         "embeddings" => {class: EmbeddingsCommand, description: "Inspect embedding backend"},
         "reject" => {class: RejectCommand, description: "Mark a fact as rejected"},
+        "observations" => {class: ObservationsCommand, description: "Inspect, promote, or consolidate episodic observations"},
         "restore" => {class: RestoreCommand, description: "Restore superseded facts from obsolete single-value classification"},
         "dedupe-conflicts" => {class: DedupeConflictsCommand, description: "Deduplicate historical open conflict rows that describe the same pair"},
         "reclassify-references" => {class: ReclassifyReferencesCommand, description: "Retag existing convention facts that match reference-material heuristics"},