claude_memory 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cec498c9aec388d1decdcb7ae05616fb414d7f026401248b6a051d051d238e39
-  data.tar.gz: 9a8b44aa97db10ead04a074f2619f08cdb74976dd22ce7843a5968bbbbda410e
+  metadata.gz: 93e553fc87bd36ebe27b8709a28dea9bd206a669491327fc8b6340e6078a8f67
+  data.tar.gz: c19722c5028ed5746f58792bb34e57939600deaa0a59b6ff00a421b3ed829bdc
 SHA512:
-  metadata.gz: 22c84d179c6af89f06909604674794741739237edc5cdb11c18bd9ba06ae4f9334bf20a4d8e8057181d25a206419cf50b35fec392ec3cd7d5fb093ea0046ef0c
-  data.tar.gz: a138ae2049416a7ec21ecef3545115a8415a2d64618d8f3334a50e2b6d552b61a7056824f5ef968b78907cfbc6515e38f60a1feed75a4db8b94793736bf0826d
+  metadata.gz: 7bd3a98c636c525e2bfc579e9e265ecef3a07311d4ba543d692abc092ddc0822df86832b9e5b53d802597a6dbe7495aa192210d6d4e5961c21383daac22cef09
+  data.tar.gz: b587239c11c342551f35937ecdbb108254269306fa98fbaac6680d23f8e427a32f26cbb1524c8f19a08da1773e292b6d75df92e101cb724d59fd65017f275832

data/.claude/rules/claude_memory.generated.md

@@ -1,13 +1,18 @@
 <!--
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-06-03T13:21:02Z
+  Generated: 2026-06-16T18:31:16Z
 -->
 
 # Project Memory
 
 ## Current Decisions
 
+- From Mastra Observational Memory study: add an episodic observation layer that augments (not replaces) the dynamic-recall semantic fact store — because facts answer 'what is true' and observations answer 'what happened', and claude_memory currently lacks the episodic half; recall stays for targeted lookups.
+- From Mastra Observational Memory study: make observation reflection automatic via the PreCompact and SessionEnd hooks rather than a manual-only skill — because Claude Code exposes no timer/cron hook, but PreCompact fires on context pressure (the analog of Mastra's token threshold) and rides the existing session at no extra API cost.
+- From Mastra Observational Memory study: run the Reflector's deterministic GC shell-side in Ruby and its semantic consolidation via PreCompact additionalContext (Claude-as-reflector inline) — to keep automatic reflection within the no-extra-API-cost convention, explicitly rejecting Claude Code Routines and subagents because each incurs a separate token budget.
+- From Mastra Observational Memory study: tombstone superseded observations via a consolidated_into link rather than hard-deleting them (unlike Mastra's lossy drop) — to preserve claude_memory's provenance guarantee while still bounding context size.
+- From Mastra Observational Memory study: promote an observation to a structured fact only after corroboration across multiple observations — because requiring repeated sightings before commitment doubles as an anti-hallucination gate against reject-churn from one-off doc/example text.
 - MCP tool-call telemetry stores minimal columns (tool_name, duration_ms, result_count, scope, error_class) — deliberately no query_text or query_hash. YAGNI: hashes are write-only without the raw text, and raw text adds privacy concerns without clear value beyond existing shortcut tools (memory.decisions, memory.conventions). — to avoid storing query hashes that are write-only without the raw text.
 - From QMD 2026-02-02 restudy: adopt Claude Code plugin format, MCP structured content pattern, MCP query guide prompt, inline status checks. Carry forward sqlite-vec, RRF, docids, smart expansion from 2026-01-26. Reject custom fine-tuned models, LLM reranking, YAML collections. — to align with our pure-Ruby/SQLite constraints (no GGUF, no LLM-side fine-tuning).
 - From claude-supermemory study: adopt SessionStart hook context injection (hookSpecificOutput.additionalContext), tool-specific observation compression, and relative time formatting. Reject cloud storage dependency and no-test approach. — to avoid cloud-storage lock-in and no-test fragility identified in the study.

data/.claude/settings.local.json

@@ -53,6 +53,7 @@
       "mcp__memory__memory_conflicts"
     ]
   },
-  "enableAllProjectMcpServers": true,
+  "enableAllProjectMcpServers": false,
+  "disabledMcpjsonServers": ["memory"],
   "outputStyle": "memory-aware"
 }

data/.claude-plugin/marketplace.json

@@ -7,9 +7,9 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.12.1",
+      "version": "0.13.0",
       "source": "./",
-      "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
+      "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions, plus an episodic observation log of what happened — so Claude explains your codebase without file traversal, follows your patterns, learns from corrections, and never re-asks what it already learned.",
       "repository": "https://github.com/codenamev/claude_memory"
     }
   ]

data/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-memory",
-  "version": "0.12.1",
-  "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
+  "version": "0.13.0",
+  "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions, plus an episodic observation log of what happened — so Claude explains your codebase without file traversal, follows your patterns, learns from corrections, and never re-asks what it already learned.",
   "author": {
     "name": "Valentino Stoll",
     "email": "v@codenamev.com"

data/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-06-18
+
+Theme: **Episodic memory — a second kind of memory.** ClaudeMemory gains an append-only *observation* layer ("what happened") that complements the semantic fact store ("what is true"), modeled on [Mastra's Observational Memory](docs/influence/mastra-observational-memory.md). Observations accrue automatically, are deduplicated/consolidated by reflection, and are promoted to facts only after corroboration — making repeated sighting an anti-hallucination gate built into the memory model. Schema advances to v20 (additive; no breaking changes to existing facts/queries).
+
+### Added
+
+**Episodic Observation Layer**
+
+- **`observations` table** (schema v19–v20) — append-only episodic rows complementing facts. Columns include `body`, `kind`, `priority` (1=🔴/2=🟡/3=🟢), `scope`, `source_content_item_id` (provenance), `consolidated_into` (tombstone lineage — superseded observations are preserved, never deleted), `corroboration_count`, `promoted_at`/`promoted_fact_id`, `status`.
+- **Observer** — Layer-1 `NullDistiller` (regex) plus Layer-2 Claude-as-observer (SessionStart context hook, zero extra API cost) emit observations alongside facts; persisted by the `Resolver` inside the existing extraction transaction.
+- **Reflector** (`Observe::Reflector`) — deterministic dedup + TTL-expiry of info-level observations runs shell-side on `PreCompact`/`SessionEnd`; semantic consolidation (Claude-as-reflector) rides the next turn's `PreCompact` `additionalContext`. No separate API spend.
+- **Two-block SessionStart injection** — Block 1 is the stable observation log (🔴-marked); Block 2 is the undistilled "pending knowledge" tail. Wrapped in `<claude-memory-context>` so the injected log isn't re-ingested as new observations.
+- **Observation→fact promotion bridge** — facts are created from observations only after corroboration (≥2 sightings, `Domain::Observation::PROMOTION_THRESHOLD`); refuses uncorroborated or already-promoted rows.
+- **MCP tools** (28 total): `memory.observations` (read the episodic log), `memory.promote_observation` (corroboration-gated promotion), `memory.consolidate_observations` (semantic merge; corroboration combines, sources tombstoned).
+- **`/reflect` skill** — guided survey → consolidate → promote → report pass over the observation log.
+- **`claude-memory observations`** command — list/inspect the log (counts by status/kind/priority, promotion readiness, compression), plus `promote` and `consolidate` subcommands; `claude-memory stats --observations` summarizes counts.
+- **Dashboard Observations panel** (first-class, main sidebar + Advanced tab) — counts by kind/priority, corroboration + promotion readiness, source→observation compression ratio, recent timeline.
+- **`claude-memory audit` observation health checks** — orphaned observations, promotion consistency, and tombstone-chain validity, documented in `docs/audit_runbook.md`.
+
+### Changed
+
+- **Dependencies updated** to current within constraints — `sequel` 5.105, `standard` 1.55, `rubocop` 1.87, `json`, `psych`, `parallel` 2.x, among others. No runtime-gem major bumps required.
+
+### Fixed
+
+- **`consolidate_observations` read-modify-write race** — the source read and corroboration sum now run inside the transaction, with `status='active'` re-asserted on the tombstone update, so concurrent `PreCompact`/`SessionEnd` reflectors can't double-count or double-tombstone.
+- **`go` language false positive** — the distiller no longer extracts the English word "go" as the Go language (case-sensitive match + `golang` normalization).
+
 ## [0.12.1] - 2026-06-05
 
 Theme: **Upgrade-experience patches surfaced by the 0.12.0 soak.** Four small but high-impact fixes — all uncovered by one user upgrading a single project — closing visibility gaps in the doctor and the plugin manifest. No schema changes, no breaking changes.

data/CLAUDE.md

@@ -113,7 +113,7 @@ bin/run-evals --comparative --setup-competitors  # Install + run in one step
 
 NullDistiller (regex, Layer 1):
   - Concept Recall: 0.952 (regex-detectable entities/facts)
-  - Fact Precision: 1.000, Fact Recall: 1.000 (on 31 test cases)
+  - Fact Precision: 0.935, Fact Recall: 1.000 (on 31 test cases) — deliberately high-recall ("extract every mention, filter downstream"); see improvements.md #70
   - Pipeline latency: P95 < 5ms (medium text)
 
 Claude Code (LLM, Layers 2+3):
@@ -150,7 +150,7 @@ Transcripts → Ingest → Index (FTS5)
 The distillation pipeline operates at three levels of depth:
 
 - **Layer 1: NullDistiller** (automatic, regex, free) — Runs in the ingest pipeline on every hook event. Extracts entities, facts, and scope hints using pattern matching. P95 latency < 5ms.
-- **Layer 2: Context Hook Injection** (automatic, LLM, zero extra cost) — At SessionStart, undistilled content is injected into the session via `hookSpecificOutput.additionalContext` with extraction instructions. Claude Code itself acts as the distiller, extracting structured facts at no additional API cost.
+- **Layer 2: Context Hook Injection** (automatic, LLM, zero extra cost) — At SessionStart, undistilled content is injected into the session via `hookSpecificOutput.additionalContext` with extraction instructions. Claude Code itself acts as the distiller, extracting structured facts at no additional API cost. The same prompt also asks Claude to emit episodic **observations** (the Layer-2 Claude-as-observer) in the `observations` field of its `memory.store_extraction` call — coerced/validated at the handler border and persisted via the resolver alongside facts.
 - **Layer 3: `/distill-transcripts` Skill** (manual, on-demand) — Deep extraction triggered by the user. Processes undistilled content with depth-aware prompts (initial extraction, consolidation, contradiction resolution).
 
 New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipeline by tracking which content items have been deeply distilled.
@@ -233,7 +233,7 @@ New MCP tools `memory.undistilled` and `memory.mark_distilled` support the pipel
   - Modes: shared (repo), local (uncommitted), home (user directory)
 
 - **`MCP`**: Model Context Protocol server and tools (`mcp/`)
-  - Exposes memory tools to Claude Code (23 tools total)
+  - Exposes memory tools to Claude Code (28 tools total)
   - `Telemetry`: Records tool invocations to `mcp_tool_calls` table for usage stats
   - Dual content/structuredContent responses with compact mode
 
@@ -256,6 +256,7 @@ Key tables (defined in `sqlite_store.rb`):
 - `mcp_tool_calls`: MCP server tool invocation telemetry (schema v13)
 - `activity_events`: Hook/recall/context/sweep/nudge telemetry (schema v15) — powers the dashboard timeline, moments feed, efficacy reports. Event types: `hook_ingest`, `hook_context` (carries `context_tokens` since 0.11.0), `hook_sweep`, `hook_publish`, `recall`, `store_extraction`, `roi_nudge` (since 0.11.0).
 - `moment_feedback`: Per-moment 👍/👎 verdicts with optional notes (schema v16) — unique on event_id, repeat clicks upsert
+- `observations`: Episodic "what happened" layer (schema v19–v20) — append-only narrative rows complementing facts ("what is true"). Columns: `body`, `kind` (decision/preference/event/…), `priority` (1=🔴/2=🟡/3=info), `scope`, `source_content_item_id` (provenance), `consolidated_into` (Reflector tombstone lineage — never hard-deleted), `token_count`, `status`, `corroboration_count` (folded by dedup; the promotion-gate signal), `promoted_at`/`promoted_fact_id` (set when promoted to a fact). Written by the Resolver from `Extraction#observations` (NullDistiller is the Layer-1 Observer). The full observational layer (Observer → injection → deterministic Reflector → promotion bridge) is in `lib/claude_memory/observe/`; see [docs/influence/mastra-observational-memory.md](docs/influence/mastra-observational-memory.md).
 
 Facts include:
 - `scope`: "global" or "project" (determines applicability)
@@ -354,7 +355,7 @@ Also update `SECTION_MAP` if the predicate should appear in a specific snapshot
 
 The gem includes an MCP server (`claude-memory serve-mcp`) that exposes memory operations as tools. Configuration should be in `.mcp.json` at project root.
 
-Available MCP tools (23 total):
+Available MCP tools (28 total):
 - **Query & Recall**: `memory.recall`, `memory.recall_index`, `memory.recall_details`, `memory.recall_semantic`, `memory.search_concepts`
 - **Provenance**: `memory.explain`, `memory.fact_graph`
 - **Shortcuts**: `memory.decisions`, `memory.conventions`, `memory.architecture`
@@ -362,6 +363,7 @@ Available MCP tools (23 total):
 - **Management**: `memory.promote`, `memory.reject_fact`, `memory.store_extraction`
 - **Distillation**: `memory.undistilled`, `memory.mark_distilled`
 - **Monitoring**: `memory.status`, `memory.stats`, `memory.changes`, `memory.conflicts`, `memory.activity`
+- **Observational layer** (experimental): `memory.observations` (read-only episodic log), `memory.promote_observation` (corroboration-gated observation→fact promotion), `memory.consolidate_observations` (semantic reflection: merge related observations, combine corroboration)
 - **Maintenance**: `memory.sweep_now`
 - **Discovery**: `memory.check_setup`, `memory.list_projects`
 
@@ -373,13 +375,16 @@ ClaudeMemory integrates with Claude Code via hooks in `.claude/settings.json`:
   - Calls `claude-memory hook ingest` with stdin JSON
   - Reads transcript delta and updates both global and project databases
 
-- **Context hook**: Triggers on SessionStart
+- **Context hook**: Triggers on SessionStart (and PreCompact — see below)
   - Calls `claude-memory hook context`
   - Injects recent facts via `hookSpecificOutput.additionalContext`
+  - Two-block layout (observational layer): Block 1 = the episodic observation log (`Observe::ObservationsRenderer`, 🔴-marked), Block 2 = the undistilled "Pending Knowledge Extraction" tail. `ContextInjector#emitted_observation_count` feeds the `hook_context` telemetry.
+  - On **PreCompact** the same `claude-memory hook context` injects only the reflection nudge (`ContextInjector#reflection_context` — the promote/consolidate instructions for corroborated/related observations), not the full snapshot, since PreCompact is context-pressure (Mastra's token-threshold analog). `HooksConfigurator` wires it into the PreCompact hook set alongside ingest + sweep.
 
 - **Sweep hook**: Triggers on PreCompact/SessionEnd events
   - Runs time-bounded maintenance on both databases
   - Cleans up vec0 entries for superseded/expired facts
+  - Runs the deterministic observation Reflector (`Observe::Reflector` via `Maintenance#reflect_observations`): dedupes near-identical observations + expires stale 🟢 info-level ones (TTL `observation_info_ttl_days`). Free/no-LLM, provenance-preserving (tombstone). Context-pressure-triggered — the analog of Mastra's token-threshold reflection.
 
 - **Nudge hook** (0.11.0+): Triggers on SessionEnd, fires after ingest+sweep
   - Calls `claude-memory hook nudge`
@@ -394,7 +399,7 @@ Hook commands read JSON payloads from stdin for robustness. Supports `--async` f
 
 Local web UI for inspecting memory state. Started via `claude-memory dashboard` (default port 3377). Reads from both global and project databases; no write side effects from page loads.
 
-The dashboard is a thin web layer over the same `Recall`/`Conflicts`/`Trust`/`Moments`/`Knowledge`/`Reuse`/`Health`/`Timeline` classes the MCP server uses. Each panel is backed by a dedicated module under `lib/claude_memory/dashboard/`; `Dashboard::API` holds HTTP-shape glue and per-endpoint formatting (delegating non-trivial logic to the panel classes).
+The dashboard is a thin web layer over the same `Recall`/`Conflicts`/`Trust`/`Moments`/`Knowledge`/`Reuse`/`Health`/`Timeline`/`Observations` classes the MCP server uses. Each panel is backed by a dedicated module under `lib/claude_memory/dashboard/`; `Dashboard::API` holds HTTP-shape glue and per-endpoint formatting (delegating non-trivial logic to the panel classes). The `Observations` panel (`/api/observations`, Advanced → Observations tab) surfaces the episodic layer: counts by status/kind/priority, corroboration + promotion readiness, a compression ratio (source content tokens ÷ observation tokens), and a recent timeline.
 
 Connections are released after each request — never holds a WAL writer lock open across page loads.
 

data/README.md

@@ -12,9 +12,13 @@ It automatically:
 - ✅ Remembers project-specific and global knowledge
 - ✅ Provides instant recall without manual prompting
 - ✅ Maintains truth (handles conflicts, supersession)
+- ✅ Tracks *what happened*, not just *what's true* — an episodic observation log alongside the facts (0.13.0+)
+- ✅ Promotes an observation to a fact only after it recurs — a corroboration gate against one-off noise
 
 **No API keys. No configuration. Just works.**
 
+ClaudeMemory now has **two complementary halves**: a *semantic* fact store ("what is true" — your stack, conventions, decisions) and an *episodic* observation layer ("what happened" — the narrative of your sessions). Observations are deduplicated and consolidated automatically, and only graduate to facts once corroborated — so fleeting mentions never harden into false memory. See [Episodic Memory](#episodic-memory-observations).
+
 ## Quick Start
 
 ### 1. Install the Gem
@@ -137,6 +141,7 @@ File-searchable questions ("what version is this?") and one-shot code generation
 - **Progressive Disclosure**: Lightweight queries before full details
 - **Semantic Shortcuts**: Quick access to decisions, conventions, architecture
 - **Truth Maintenance**: Automatic conflict resolution
+- **Episodic Memory** (0.13.0+): An append-only observation log of *what happened* alongside the semantic fact store. Auto-consolidated via deterministic + LLM reflection on `PreCompact`/`SessionEnd`; corroborated observations are promoted to facts (anti-hallucination gate). See **[Episodic Memory →](#episodic-memory-observations)**.
 - **Claude-Powered**: Uses Claude's intelligence to extract facts (no API key needed)
 - **Token Efficient**: 10x reduction in memory queries with progressive disclosure
 - **Database Maintenance**: Compact, export, and backup commands
@@ -152,6 +157,36 @@ File-searchable questions ("what version is this?") and one-shot code generation
 
   Only metrics and event names are captured by default — verbatim prompts and bodies stay off until you explicitly opt in via `claude-memory otel --capture-prompts`. The receiver binds to `127.0.0.1` only.
 
+## Episodic Memory (Observations)
+
+Facts answer **"what is true"** (your stack, conventions, decisions). Observations answer **"what happened"** — a narrative log of the moments in your sessions. ClaudeMemory now keeps both, modeled on [Mastra's Observational Memory](docs/influence/mastra-observational-memory.md).
+
+| | Facts (semantic) | Observations (episodic) |
+|---|---|---|
+| Capture | Durable truths — `uses_database: sqlite` | Narrative events — "decided to add a corroboration gate to avoid reject-churn" |
+| Change | Explicitly, via supersession/rejection | Automatically — deduped, consolidated, low-priority ones expire |
+| Promotion | — | Promoted to a fact only after corroboration (≥2 sightings) |
+
+**Why it's a leap forward:** the distiller used to commit a fact the first time it saw a claim — so a database mentioned once in a comparison could harden into a false `uses_database`. The observation layer makes repeated sighting the gate: an observation becomes a fact only after it recurs. That's an **anti-hallucination defense built into the memory model**, not a cleanup afterthought.
+
+**How it runs (no extra API cost):**
+- **Observer** — a regex Layer-1 pass plus Claude-as-observer in the SessionStart context hook emit observations as sessions happen.
+- **Reflector** — deterministic dedup + TTL-expiry runs on `PreCompact`/`SessionEnd`; semantic consolidation rides the next turn's context hook (Claude-as-reflector). Superseded observations are *tombstoned*, never deleted, preserving provenance.
+- **Promotion bridge** — corroborated observations graduate to facts on the corroboration gate.
+
+**See it / use it:** the dashboard's **Observations** panel (counts by kind/priority, corroboration + promotion readiness, source→observation compression ratio, recent timeline); the `claude-memory observations` CLI; the `memory.observations` / `memory.promote_observation` / `memory.consolidate_observations` MCP tools; and the `/reflect` skill for a guided survey→consolidate→promote pass.
+
+## What's New in 0.13.0
+
+**Episodic Observation Layer** — ClaudeMemory gains a second kind of memory (see [Episodic Memory](#episodic-memory-observations) above):
+
+- New `observations` table (schema v19–v20), append-only with `consolidated_into` tombstone lineage and `corroboration_count` / `promoted_at` / `promoted_fact_id` promotion tracking.
+- Two-block SessionStart injection: a stable observation log (🔴-marked) + the undistilled "pending knowledge" tail.
+- Automatic reflection on `PreCompact` (context-pressure, Mastra's token-threshold analog) and `SessionEnd` — deterministic GC shell-side in Ruby, semantic consolidation via the context hook (no extra API spend).
+- Corroboration-gated observation→fact promotion — repeated sightings required before commitment, an anti-hallucination gate against reject-churn from one-off doc/example text.
+- New surfaces: dashboard **Observations** panel, `claude-memory observations` command (+ `claude-memory stats --observations`), `claude-memory audit` observation health checks, three `memory.*observation*` MCP tools, and the `/reflect` skill.
+- Dependencies refreshed to current (sequel, standard, rubocop, and others).
+
 ## What's New in 0.11.0
 
 Five user-visible signals so you can answer "is memory still worth it?" with

data/db/migrations/019_add_observations.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Migration v19: Add observations table — the episodic memory layer.
+#
+# Facts answer "what is true" (semantic memory); observations answer "what
+# happened" (episodic memory). This is the storage half of Phase 1 of the
+# observational layer (see docs/influence/mastra-observational-memory.md).
+#
+# Observations are append-only: the Reflector consolidates by writing a new
+# observation and pointing superseded ones at it via consolidated_into,
+# rather than hard-deleting — preserving provenance (unlike Mastra's lossy
+# drop). source_content_item_id links each observation back to the raw
+# transcript chunk it was distilled from.
+Sequel.migration do
+  up do
+    create_table?(:observations) do
+      primary_key :id
+      String :body, text: true, null: false        # dense narrative text — the observation itself
+      String :kind, null: false, default: "event"  # user_statement | agent_action | tool_result | preference | decision | event
+      Integer :priority, null: false, default: 3    # 1=important (🔴), 2=maybe (🟡), 3=info (🟢)
+      String :scope, null: false, default: "project" # "project" or "global"
+      String :project_path                          # set for project-scoped observations
+      Integer :source_content_item_id               # provenance: raw transcript chunk
+      Integer :consolidated_into                    # Reflector lineage: id of the observation this was merged into
+      Integer :token_count                          # for budget / compression math (Phase 2)
+      String :status, null: false, default: "active" # "active" or "consolidated"
+      String :session_id                            # session that produced the observation
+      String :observed_at, null: false              # ISO 8601 event time
+      String :created_at, null: false               # ISO 8601 row creation time
+      String :reflected_at                          # ISO 8601 — set when the Reflector last touched it
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_observations_status ON observations(status)"
+    run "CREATE INDEX IF NOT EXISTS idx_observations_scope ON observations(scope)"
+    run "CREATE INDEX IF NOT EXISTS idx_observations_observed_at ON observations(observed_at)"
+    run "CREATE INDEX IF NOT EXISTS idx_observations_source ON observations(source_content_item_id)"
+    run "CREATE INDEX IF NOT EXISTS idx_observations_consolidated_into ON observations(consolidated_into)"
+  end
+
+  down do
+    drop_table?(:observations)
+  end
+end

data/db/migrations/020_add_observation_promotion.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Migration v20: observation→fact promotion bridge (Phase 4 of the
+# observational layer).
+#
+# - corroboration_count: how many times this observation has been sighted.
+#   Starts at 1; the deterministic Reflector's dedup pass folds duplicates'
+#   counts into the keeper instead of just dropping them. This count is the
+#   "repeated sightings" signal the promotion gate requires — an observation
+#   is only eligible to become a structured fact once corroborated, which
+#   doubles as an anti-hallucination gate against one-off doc/example text.
+# - promoted_at / promoted_fact_id: set when an observation has been promoted
+#   to a fact, so it is not re-suggested. The observation row is preserved
+#   (provenance), it just stops appearing as a promotion candidate.
+Sequel.migration do
+  up do
+    alter_table(:observations) do
+      add_column :corroboration_count, Integer, null: false, default: 1
+      add_column :promoted_at, String       # ISO 8601, set on promotion
+      add_column :promoted_fact_id, Integer  # the fact this was promoted into
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_observations_promoted_at ON observations(promoted_at)"
+  end
+
+  down do
+    alter_table(:observations) do
+      drop_column :corroboration_count
+      drop_column :promoted_at
+      drop_column :promoted_fact_id
+    end
+  end
+end

data/docs/GETTING_STARTED.md

@@ -119,6 +119,44 @@ claude-memory promote <fact_id>
 "Remember that I prefer descriptive commit messages - make that a global preference"
 ```
 
+## Two Kinds of Memory: Facts and Observations
+
+ClaudeMemory remembers two complementary things:
+
+- **Facts** answer *"what is true"* — durable, structured truths about your
+  project (`uses_database: sqlite`, conventions, decisions). This is the
+  semantic layer the sections above describe.
+- **Observations** answer *"what happened"* — an append-only narrative log of
+  the moments in your sessions ("decided to add a corroboration gate so
+  fleeting mentions don't harden into facts"). This is the **episodic** layer
+  (0.13.0+).
+
+| | Facts | Observations |
+|---|---|---|
+| Captures | Durable truths | Events / narrative |
+| Changes | Explicitly (supersession, rejection) | Automatically (dedup, consolidation, expiry) |
+| Promotion | — | Promoted to a fact after corroboration (≥2 sightings) |
+
+**Why this matters:** the distiller used to commit a fact the first time it
+saw a claim — so a database named once in a comparison could become a false
+`uses_database`. Observations make repeated sighting the gate: an observation
+graduates to a fact only after it recurs. That's an anti-hallucination defense
+built into the memory model.
+
+Observations are managed for you — deduplicated and consolidated automatically
+on `PreCompact`/`SessionEnd` at no extra API cost. To see or curate them:
+
+```bash
+# Inspect the episodic log (counts, promotion readiness, compression, recent)
+claude-memory observations
+
+# Promote a corroborated observation to a fact
+claude-memory observations promote <id> --predicate uses_database --object sqlite
+```
+
+The dashboard's **Observations** panel shows the same at a glance, and the
+`/reflect` skill runs a guided survey → consolidate → promote pass.
+
 ## Setting Up Your First Project
 
 ### Scenario 1: Fresh Install (New Project)

data/docs/api_stability.md

@@ -114,7 +114,7 @@ Renaming or repurposing a code is a major-version change.
 
 ## 3. Public MCP tool surface
 
-All 23 tools registered via `MCP::ToolDefinitions.all`. Argument schemas, return shapes (both `content` and `structuredContent`), and tool-annotation hints (`readOnlyHint`, `idempotentHint`, `destructiveHint`) are **stable** for the listed tools.
+All 28 tools registered via `MCP::ToolDefinitions.all` — 25 stable + 3 experimental (the observational-layer tools below). Argument schemas, return shapes (both `content` and `structuredContent`), and tool-annotation hints (`readOnlyHint`, `idempotentHint`, `destructiveHint`) are **stable** for the listed stable tools.
 
 ### Stable MCP tools
 
@@ -134,7 +134,7 @@ All 23 tools registered via `MCP::ToolDefinitions.all`. Argument schemas, return
 | `memory.facts_by_context` | Context | Stable. |
 | `memory.promote` | Management | Stable. |
 | `memory.reject_fact` | Management | Stable since 0.10.0. |
-| `memory.store_extraction` | Management | Argument schema (`facts`, `entities`, `decisions`) stable. |
+| `memory.store_extraction` | Management | Argument schema (`facts`, `entities`, `decisions`) stable. The `observations` field (Layer-2 observer) is **experimental** while the observational layer is built out. |
 | `memory.undistilled` | Distillation | Stable since 0.10.0. |
 | `memory.mark_distilled` | Distillation | Stable since 0.10.0. |
 | `memory.status` | Monitoring | Stable. |
@@ -146,6 +146,16 @@ All 23 tools registered via `MCP::ToolDefinitions.all`. Argument schemas, return
 | `memory.check_setup` | Discovery | Stable. |
 | `memory.list_projects` | Discovery | Stable since 0.10.0. |
 
+### Experimental MCP tools
+
+These are registered in `MCP::ToolDefinitions.all` but **not yet covered by the stability guarantees above** — argument schema and return shape may change while the feature is built out.
+
+| Tool | Group | Status |
+|---|---|---|
+| `memory.observations` | Observational layer | Experimental (0.13.0+). Read-only listing of episodic observations by status/kind/priority with corroboration counts. Return shape may change. |
+| `memory.promote_observation` | Observational layer | Experimental (0.13.0+). Promotes a corroborated observation (≥2 sightings) into a fact; refuses uncorroborated or already-promoted ones (anti-hallucination gate). Args/shape may change. |
+| `memory.consolidate_observations` | Observational layer | Experimental (0.13.0+). Merges related observations into one synthesized row (corroboration combines, sources tombstoned via `consolidated_into`). Args/shape may change. |
+
 ### Stability of tool responses
 
 Both response shapes are stable:
@@ -201,7 +211,7 @@ Adding a new field to `detail_json` is a stable-surface addition (non-breaking).
 
 Current covered events (0.11.0):
 
-- `hook_context`: `context_length`, `context_tokens` (since 0.11.0), `top_fact_ids`, `fact_count`.
+- `hook_context`: `context_length`, `context_tokens` (since 0.11.0), `top_fact_ids`, `fact_count`. (`observation_count`, added with the observational layer, is additive and **experimental** — not yet on the smoke-gate manifest.)
 - `roi_nudge`: `n`, `used`, `pct`, `prior_count` (all since 0.11.0).
 
 `hook_ingest`, `hook_sweep`, `hook_publish` event detail fields are currently **internal** (not on the smoke-gate manifest). Promoting them to stable is a 0.12.x or later task.
@@ -255,7 +265,7 @@ If you need a feature from one of the internal classes, **open an issue** so we
 
 ### Schema migrations
 
-Schema is at v18 as of 0.12.0 with 18 migrations under `db/migrations/`. Migrations remain forward-compatible per the round-trip-spec convention (`feedback_round_trip_migration_specs.md`): each release's specs verify that DBs from the prior 3 schema boundaries can be migrated into the current schema without data loss.
+Schema is at v20 (v18 shipped in 0.12.0; v19–v20 add the observational `observations` table in 0.13.0) with 20 migrations under `db/migrations/`. Migrations remain forward-compatible per the round-trip-spec convention (`feedback_round_trip_migration_specs.md`): each release's specs verify that DBs from the prior 3 schema boundaries can be migrated into the current schema without data loss.
 
 **What's stable:**
 
@@ -268,6 +278,7 @@ Schema is at v18 as of 0.12.0 with 18 migrations under `db/migrations/`. Migrati
 
 - The `vec0` virtual-table internals — sqlite-vec evolution may shift representation.
 - `mcp_tool_calls` retention behavior (currently 90 days, configurable); the column set is stable, the retention default is not.
+- The `observations` table (v19–v20, incl. `corroboration_count`/`promoted_at`/`promoted_fact_id`) — episodic layer. Column set may still change while the layer is experimental.
 
 **What's internal:**
 
@@ -324,7 +335,7 @@ Listed here for honesty — these surfaces look public but are not.
 
 - **Dashboard JSON HTTP API.** The `claude-memory dashboard` server's endpoints are an internal interface for the bundled UI. Don't build scripts against `GET /api/trust` etc. — endpoints, response shapes, and even URL paths may change without notice.
 - **`activity_events.detail_json` fields not in `spec/smoke/expected_fields.yml`.** Inspecting a missing field during debugging is fine; relying on it in scripts is not.
-- **The exact text of `additionalContext`.** The Markdown sections (`## Decisions`, `## Conventions`, `## Architecture`, `## Pending Knowledge Extraction`, `## Auto-Memory Mirror`) and their order are stable; the per-fact rendering format inside each section is tuned for prompt quality and may change.
+- **The exact text of `additionalContext`.** The Markdown sections (`## Decisions`, `## Conventions`, `## Architecture`, `## Pending Knowledge Extraction`, `## Auto-Memory Mirror`) and their order are stable; the per-fact rendering format inside each section is tuned for prompt quality and may change. The `## Observations` and `## Observation Reflection` sections (observational layer) and the published `.claude/rules/claude_memory.observations.md` snapshot are **experimental** while the layer is built out.
 - **Internal env vars** (anything not listed in `Configuration` instance methods or in this doc). Examples that exist but are internal: `CLAUDE_MEMORY_LOG_LEVEL`, debug flags surfaced during development.
 - **Test/spec/fixture infrastructure.** `spec/benchmarks/`, `spec/evals/`, `spec/support/` are not public APIs.
 - **Plugin-format paths.** `.claude-plugin/`, `scripts/serve-mcp.sh`, etc. are part of the Claude Code plugin format integration; treat them as opaque.

data/docs/architecture.md

@@ -14,20 +14,22 @@ ClaudeMemory is architected using Domain-Driven Design (DDD) principles with cle
                        │
 ┌──────────────────────▼──────────────────────────────────────┐
 │                   Core Domain Layer                          │
-│  Domain Models: Fact, Entity, Provenance, Conflict          │
+│  Domain Models: Fact, Entity, Provenance, Conflict,         │
+│                 Observation (episodic)                       │
 │  Value Objects: SessionId, TranscriptPath, FactId           │
 │  Null Objects: NullFact, NullExplanation                    │
 └──────────────────────┬──────────────────────────────────────┘
                        │
 ┌──────────────────────▼──────────────────────────────────────┐
 │                 Business Logic Layer                         │
-│  Recall → Resolve → Distill → Ingest → Publish             │
-│  Sweep → Embeddings → MCP → Hook                           │
+│  Recall → Resolve (semantic) → Distill → Ingest → Publish  │
+│  Observe → Reflect (episodic) → Sweep → Embeddings →       │
+│  MCP → Hook                                                  │
 └──────────────────────┬──────────────────────────────────────┘
                        │
 ┌──────────────────────▼──────────────────────────────────────┐
 │                 Infrastructure Layer                         │
-│  Store (SQLite v17 + WAL) → FileSystem → Index (FTS5+Vector)│
+│  Store (SQLite v20 + WAL) → FileSystem → Index (FTS5+Vector)│
 │  Templates                                                   │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -129,10 +131,19 @@ end
 - `DualQueryTemplate`: Query template handling for dual-database queries
 
 #### Resolve (`resolve/`)
-- Truth maintenance and conflict resolution
+- Truth maintenance and conflict resolution (the **semantic** "what is true" layer)
 - **Transaction safety**: Multi-step operations wrapped in DB transactions
 - PredicatePolicy: Controls single vs. multi-value predicates
 - Handles supersession and conflict detection
+- Also persists observations from the extraction inside the same transaction (see Observe & Reflect)
+
+#### Observe & Reflect (`observe/`)
+- The **episodic** "what happened" layer, complementing the semantic fact store
+- **Observer**: `NullDistiller` emits high-precision Layer-1 observations (regex); Claude-as-observer enriches them via the SessionStart context hook (Layer-2, no extra API cost)
+- **Reflector** (`Observe::Reflector`): deterministic dedup + TTL-expiry of info-level observations runs on `PreCompact`/`SessionEnd`; semantic consolidation (Claude-as-reflector) rides the next turn's context hook
+- **Append-only/tombstoning**: superseded observations are linked via `consolidated_into`, never deleted — preserving provenance
+- **Promotion bridge**: observations are promoted to facts only after corroboration (≥2 sightings) — an anti-hallucination gate
+- `ObservationsRenderer` formats the injected log; `Domain::Observation` is the immutable value object
 
 #### Distill (`distill/`)
 - Extracts facts and entities from transcripts
@@ -164,7 +175,7 @@ end
 
 #### MCP (`mcp/`)
 - Model Context Protocol server
-- Exposes 19 tools including: recall, explain, promote, status, decisions, conventions, architecture, semantic search, check_setup, and more
+- Exposes 28 tools including: recall, explain, promote, status, decisions, conventions, architecture, semantic search, check_setup, the observational-layer tools (observations, promote_observation, consolidate_observations), and more
 - `ResponseFormatter`: Consistent MCP response formatting
 - `SetupStatusAnalyzer`: Initialization and version status analysis
 
@@ -212,6 +223,7 @@ end
   - `Reuse`: most-used facts within window
   - `Health`: db / hooks / vec checks with actionable fix strings
   - `Timeline`: 30-day daily rollup
+  - `Observations` (0.13.0+): episodic-layer panel — counts by status/kind/priority, corroboration + promotion readiness, source→observation compression ratio, recent timeline (first-class main-sidebar panel + Advanced tab)
   - `FactPresenter`, `ScopedFactResolver`: shared rendering / scope-aware ID resolution
 - Connections released after every request — no held WAL writer locks across page loads
 - See [docs/dashboard.md](dashboard.md) for the user-facing guide

data/docs/audit_runbook.md

@@ -178,6 +178,73 @@ Exit code is `0` when `ok: true`, `1` otherwise. `--no-exit` always returns `0`.
 3. Clean up: `claude-memory reject` the historical disputed/superseded rows (or accept them as historical record).
 4. Re-audit.
 
+### C011 — Orphaned observations
+
+**Severity:** warn
+
+**Scope:** both the project and global DBs (observations may be scoped either way).
+
+**Triggered when:** an observation has `source_content_item_id` set but no `content_items` row with that id exists.
+
+**Why it matters:** An observation's `source_content_item_id` is its provenance link back to the transcript chunk it was distilled from. A dangling pointer means the source row was pruned (or never existed), so the observation can no longer be explained — breaking the same provenance guarantee facts enjoy. Observations with a `nil` source (e.g. consolidated ones synthesized from several sources) are *not* flagged.
+
+**Remediation:**
+- Inspect with `memory.observations` (or the dashboard Observations tab).
+- The table is append-only — do **not** delete. If the provenance is genuinely unrecoverable, let the Reflector consolidate or expire the row on the next PreCompact/SessionEnd pass.
+
+### C012 — Observation promotion consistency
+
+**Severity:** error
+
+**Scope:** both DBs.
+
+**Triggered when:** any of the following promotion-state invariants is violated —
+- `promoted_at` is set but `promoted_fact_id` is `NULL`;
+- `promoted_fact_id` points at a fact that does not exist;
+- `promoted_fact_id` points at a fact that is **not** active (rejected/superseded);
+- `promoted_fact_id` is set but `promoted_at` is `NULL`.
+
+**Why it matters:** Promotion is meant to be atomic — `mark_observation_promoted` sets both `promoted_at` and `promoted_fact_id` pointing at a freshly-created, active fact. Half-set state means the write ran partially, or the target fact was later rejected/superseded, leaving the observation pointing at nothing usable. The promotion bridge keys off these columns, so an inconsistent row either re-promotes (duplicate facts) or is silently stuck.
+
+**Remediation:**
+1. `claude-memory explain <fact_id>` on the `promoted_fact_id` to see why the fact is missing/inactive.
+2. If the fact was intentionally rejected, re-open the observation for re-promotion via `memory.promote_observation`.
+3. If `mark_observation_promoted` half-ran, re-run promotion so both columns are set together.
+
+### C013 — Observation tombstone-chain validity
+
+**Severity:** error
+
+**Scope:** both DBs.
+
+**Triggered when:** any of the following tombstone invariants is violated —
+- `consolidated_into` points at a non-existent observation;
+- `consolidated_into` is a self-link (`consolidated_into == id`);
+- a row is `status='active'` yet carries a `consolidated_into` target;
+- a row is `status='consolidated'` yet has no `consolidated_into` keeper.
+
+**Why it matters:** Supersession is append-only: a merged-away observation gets `status='consolidated'` and `consolidated_into` pointing at the surviving keeper, preserving lineage instead of hard-deleting (unlike Mastra's lossy drop). A broken chain corrupts that lineage — recall could surface a tombstoned row, or a consolidated row could orphan its history. A self-link or active-but-tombstoned row is a Reflector bug, not user error.
+
+**Remediation:**
+- Inspect with `memory.observations`.
+- Re-running the deterministic Reflector (fires on PreCompact/SessionEnd) re-derives consolidation for dangling links.
+- A self-link or `active` + `consolidated_into` row signals a Reflector defect — file it rather than hand-editing the append-only table.
+
+### C014 — Observation status / corroboration sanity
+
+**Severity:** warn
+
+**Scope:** both DBs.
+
+**Triggered when:** an observation has a `status` outside `active`/`consolidated`/`expired`, or a `corroboration_count` less than 1.
+
+**Why it matters:** Every observation should carry a known lifecycle status and at least one sighting (a fresh insert counts as 1; the migration default is 1). An unknown status means a migration or an external writer bypassed `insert_observation`; a `corroboration_count < 1` means `increment_corroboration` math went negative. Both break downstream behavior — recall filters key off `status`, and the promotion gate keys off `corroboration_count`.
+
+**Remediation:**
+- Inspect with `memory.observations`.
+- For a bad `corroboration_count`, re-derive sighting counts via the Reflector's dedup pass.
+- For an unknown status, find the writer that bypassed `insert_observation` (the only sanctioned insert path).
+
 ## Adding a new check
 
 The audit is extensible by design.