claude_memory 0.12.0 → 0.13.0

data/lib/claude_memory/domain/observation.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Domain
+    # Domain model representing an episodic observation — "what happened",
+    # as opposed to a Fact's "what is true". Instances are immutable (frozen).
+    #
+    # Priority follows Mastra's traffic-light scheme and is an internal signal
+    # for the Observer/Reflector pipeline: 1 = important (🔴), 2 = maybe (🟡),
+    # 3 = info only (🟢). Only 🔴 is meant to survive into the actor's prompt.
+    class Observation
+      KINDS = %w[user_statement agent_action tool_result preference decision event].freeze
+      IMPORTANT = 1
+      MAYBE = 2
+      INFO = 3
+
+      # Minimum corroboration (repeated sightings) before an observation may be
+      # promoted to a structured fact. The anti-hallucination gate: a one-off
+      # mention never becomes a committed fact.
+      PROMOTION_THRESHOLD = 2
+
+      attr_reader :id, :body, :kind, :priority, :scope, :project_path,
+        :source_content_item_id, :consolidated_into, :token_count,
+        :status, :session_id, :observed_at, :created_at, :reflected_at,
+        :corroboration_count, :promoted_at, :promoted_fact_id
+
+      # @param attributes [Hash] observation attributes (see column list)
+      # @raise [ArgumentError] if body is blank or priority is out of range
+      def initialize(attributes)
+        @id = attributes[:id]
+        @body = attributes[:body]
+        @kind = attributes[:kind] || "event"
+        @priority = attributes[:priority] || INFO
+        @scope = attributes[:scope] || "project"
+        @project_path = attributes[:project_path]
+        @source_content_item_id = attributes[:source_content_item_id]
+        @consolidated_into = attributes[:consolidated_into]
+        @token_count = attributes[:token_count]
+        @status = attributes[:status] || "active"
+        @session_id = attributes[:session_id]
+        @observed_at = attributes[:observed_at]
+        @created_at = attributes[:created_at]
+        @reflected_at = attributes[:reflected_at]
+        @corroboration_count = attributes[:corroboration_count] || 1
+        @promoted_at = attributes[:promoted_at]
+        @promoted_fact_id = attributes[:promoted_fact_id]
+
+        validate!
+        freeze
+      end
+
+      # @return [Boolean] true when the observation has not been consolidated away
+      def active?
+        status == "active"
+      end
+
+      # @return [Boolean] true when the Reflector has merged this into another
+      def consolidated?
+        status == "consolidated"
+      end
+
+      # @return [Boolean] true when the Reflector retired this on TTL
+      def expired?
+        status == "expired"
+      end
+
+      # @return [Boolean] true once promoted into a structured fact
+      def promoted?
+        !promoted_at.nil?
+      end
+
+      # @return [Boolean] true when corroborated enough to be promotion-eligible
+      def corroborated?(threshold)
+        corroboration_count >= threshold
+      end
+
+      # @return [Boolean] true for 🔴 — the only priority shown to the actor
+      def important?
+        priority == IMPORTANT
+      end
+
+      # @return [Boolean] true when scope is "global"
+      def global?
+        scope == "global"
+      end
+
+      # @return [Hash] all attributes as a plain hash
+      def to_h
+        {
+          id: id,
+          body: body,
+          kind: kind,
+          priority: priority,
+          scope: scope,
+          project_path: project_path,
+          source_content_item_id: source_content_item_id,
+          consolidated_into: consolidated_into,
+          token_count: token_count,
+          status: status,
+          session_id: session_id,
+          observed_at: observed_at,
+          created_at: created_at,
+          reflected_at: reflected_at,
+          corroboration_count: corroboration_count,
+          promoted_at: promoted_at,
+          promoted_fact_id: promoted_fact_id
+        }
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "body required" if body.nil? || body.empty?
+        raise ArgumentError, "priority must be 1, 2, or 3" unless (IMPORTANT..INFO).cover?(priority)
+      end
+    end
+  end
+end

data/lib/claude_memory/embeddings/generator.rb

@@ -65,7 +65,7 @@ module ClaudeMemory
         return zero_vector if tokens.empty?
 
         # Build term frequency map
-        tf_map = tokens.each_with_object(Hash.new(0)) { |token, h| h[token] += 1 }
+        tf_map = tokens.tally
 
         # Normalize term frequencies
         max_tf = tf_map.values.max.to_f

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,10 +63,21 @@ 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?
 
+          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?
             sections << format_auto_memory_mirror(mirror_candidates)
@@ -74,6 +90,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 +153,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
@@ -157,7 +247,15 @@ module ClaudeMemory
           "in the object (e.g., \"… because …\", \"… so that …\", \"caused by …\",",
           "\"breaks when …\"). A fact with a reason is recoverable once stale; a",
           "bare conclusion is dead weight. Prefer one fact-with-reason over two",
-          "facts-without."
+          "facts-without.",
+          "",
+          "**Also log what happened (episodic layer):** in the same",
+          "`memory.store_extraction` call, populate `observations` — one per",
+          "discrete event (a decision made, a preference stated, a notable action",
+          "or outcome). Each: a concise `body` of what happened, a `kind`",
+          "(decision/preference/event/…), and a reason for decisions/preferences.",
+          "Observations record \"what happened\"; facts record \"what is true\". They",
+          "accumulate, and a corroborated observation can later graduate into a fact."
         ]
 
         items.each do |item|

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