engrm 0.4.5 → 0.4.7

package/README.md

@@ -1,41 +1,79 @@
 # Engrm
 
-**Shared memory and delivery review for AI coding agents.** Engrm keeps context, decisions, and project state moving across your machines, your team, and the agents you switch between.
+[![License: FSL-1.1-ALv2](https://img.shields.io/badge/license-FSL--1.1--ALv2-blue)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
+[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)
 
-For npm users, Engrm runs on Node.js 18+ and does not require Bun to be installed.
+**The only AI memory that syncs across devices and agents.**
 
-```
-npx engrm init
-```
+Cross-device persistent memory for OpenClaw, Claude Code, Codex, and any MCP-compatible agent. Start free with 2 devices.
+
+[Get Started](https://engrm.dev) • [Documentation](https://engrm.dev/developers) • [Blog](https://engrm.dev/blog)
+
+---
+
+## Why Engrm?
+
+- **Cross-device sync** — Fix a bug on your laptop, continue on your desktop. No other memory tool does this.
+- **Cross-agent compatible** — Works with OpenClaw, Claude Code, Codex, Cursor, Windsurf, Cline, Zed
+- **Free tier** — 2 devices, 5,000 observations, full sync. £0 forever.
+- **Offline-first** — Local SQLite + sqlite-vec. <50ms search. Works on a plane.
+- **Delivery Review** — Compare what was promised vs what shipped
+- **Sentinel** — Real-time code audit before changes land
+- **Team memory** — Share insights across your whole team (Team plan)
+
+---
+
+## vs Other Memory Tools
+
+| Feature | Engrm Free | Supermemory Pro | mem0 |
+|---------|------------|-----------------|------|
+| **Cost** | £0 | $20/mo | ~$2/mo + usage |
+| **Cross-device** | ✅ 2 devices | ❌ Single device | ❌ Single device |
+| **OpenClaw plugin** | ✅ Native | ✅ (Pro required) | ✅ (usage costs) |
+| **Works with Claude/Codex** | ✅ | ❌ | ❌ |
+| **Delivery Review** | ✅ | ❌ | ❌ |
+| **Sentinel** | ✅ (Vibe+) | ❌ | ❌ |
 
-Public beta. Engrm is built for Claude Code, Codex, OpenClaw skills, and other MCP-native coding workflows. The current source of truth for agent capability differences is [AGENT_SUPPORT.md](AGENT_SUPPORT.md).
+[Read the full comparison →](https://engrm.dev/blog/engrm-openclaw-cross-device-memory)
 
 ---
 
-## What It Does
+## Installation
 
-Your AI agent forgets everything between sessions. Engrm fixes that, and helps you check whether the work really matched the brief.
+### For OpenClaw Users
 
-- **Works across agents** — Claude Code and Codex integrate directly, and OpenClaw can use Engrm through published skill bundles
-- **Remembers across devices** — fix a bug on your laptop, continue on your desktop with full context
-- **Shares with your team** — one developer's hard-won insight becomes everyone's knowledge
-- **Reviews delivery** — tie plans, decisions, and sessions together so you can see what actually shipped
-- **Works offline** — local SQLite is the source of truth; syncs when connected
-- **Guards your code** — Sentinel audits changes in real-time before they land
+```bash
+# 1. Install the plugin
+openclaw plugins install engrm-openclaw-plugin
+
+# 2. Restart OpenClaw
+# Quit and reopen, or restart gateway
 
-## Quick Start
+# 3. Connect Engrm in chat
+/engrm connect
+
+# 4. Verify
+/engrm status
+```
 
-### 1. Sign up
+**What works:**
+- ✅ Session startup memory injection
+- ✅ Automatic session capture
+- ✅ Cross-device sync (unique to Engrm)
+- ✅ `/engrm` slash commands
+- ✅ Sentinel advisory mode (Vibe+ plans)
 
-Visit [engrm.dev](https://engrm.dev) and create an account.
+**Blog:** [Engrm Now Supports OpenClaw →](https://engrm.dev/blog/engrm-openclaw-cross-device-memory)
 
-### 2. Install
+### For Claude Code / Codex
 
 ```bash
 npx engrm init
 ```
 
-This opens your browser for authentication, writes config to `~/.engrm/`, and registers Engrm in Claude Code and Codex when those configs are available. OpenClaw support is provided through the packaged skills in [`openclaw/`](openclaw/). Takes about 30 seconds.
+This auto-configures MCP servers and hooks in `~/.claude.json` and `~/.codex/config.toml`.
 
 **Alternative methods:**
 ```bash
@@ -49,9 +87,15 @@ npx engrm init --url=https://vector.internal.company.com
 npx engrm init --manual
 ```
 
-### 3. Use your agent normally
+For npm users, Engrm runs on Node.js 18+ and does not require Bun to be installed.
 
-That's it. Engrm works in the background:
+---
+
+## How It Works
+
+### Background Operation
+
+Engrm works automatically:
 
 - **Session start** — injects relevant project memory into context
 - **While you work** — captures observations from tool use where the agent exposes that hook surface
@@ -69,7 +113,7 @@ That's it. Engrm works in the background:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-### 4. Check status
+### Check Status
 
 ```bash
 npx engrm status
@@ -95,49 +139,47 @@ Engrm Status
   Security:        3 findings (1 high, 2 medium)
 ```
 
----
-
-## How It Works
+### Architecture
 
+**Claude Code session:**
 ```
-Claude Code session
-  │
-  ├─ SessionStart hook ──→ inject relevant memory into context
-  │
-  ├─ PreToolUse hook ────→ Sentinel audits Edit/Write (optional)
-  │
-  ├─ PostToolUse hook ───→ extract observations from tool results
-  │
-  ├─ PreCompact hook ────→ re-inject memory before context compression
-  │
-  ├─ ElicitationResult ──→ capture MCP form submissions
-  │
-  └─ Stop hook ──────────→ session digest + sync + summary
-        │
-        ▼
-  Local SQLite (FTS5 + sqlite-vec)
-        │
-        ▼ (sync every 30s)
-  Candengo Vector (cloud)
-        │
-        ▼
-  Available on all your devices + team members
+ │
+ ├─ SessionStart hook ──→ inject relevant memory into context
+ │
+ ├─ PreToolUse hook ────→ Sentinel audits Edit/Write (optional)
+ │
+ ├─ PostToolUse hook ───→ extract observations from tool results
+ │
+ ├─ PreCompact hook ────→ re-inject memory before context compression
+ │
+ ├─ ElicitationResult ──→ capture MCP form submissions
+ │
+ └─ Stop hook ──────────→ session digest + sync + summary
+ │
+ ▼
+Local SQLite (FTS5 + sqlite-vec)
+ │
+ ▼ (sync every 30s)
+Candengo Vector (cloud)
+ │
+ ▼
+Available on all your devices + team members
 ```
 
+**Codex session:**
 ```
-Codex session
-  │
-  ├─ SessionStart hook ──→ inject relevant memory into context
-  │
-  ├─ MCP tools ──────────→ search, save, inspect, message, stats
-  │
-  └─ Stop hook ──────────→ session digest + sync + summary
+ │
+ ├─ SessionStart hook ──→ inject relevant memory into context
+ │
+ ├─ MCP tools ──────────→ search, save, inspect, message, stats
+ │
+ └─ Stop hook ──────────→ session digest + sync + summary
 ```
 
-### Agent Support
+### Agent Capability Matrix
 
 | Capability | Claude Code | Codex | OpenClaw |
-|---|---|---|---|
+|-----------|-------------|-------|----------|
 | MCP server tools | ✓ | ✓ | Via skills / MCP |
 | Session-start context injection | ✓ | ✓ | Via skill-guided workflow |
 | Stop/session summary hook | ✓ | ✓ | Via skill-guided workflow |
@@ -146,7 +188,11 @@ Codex session
 | Pre-compact reinjection | ✓ | Not exposed | Not exposed |
 | ElicitationResult capture | ✓ | Not exposed | Not exposed |
 
-OpenClaw support is packaged in [`openclaw/`](openclaw/) as `engrm-memory`, `engrm-delivery-review`, and `engrm-sentinel` skills for ClawHub-style distribution.
+See [AGENT_SUPPORT.md](AGENT_SUPPORT.md) for detailed comparison.
+
+---
+
+## Features
 
 ### MCP Tools
 
@@ -166,7 +212,7 @@ The MCP server exposes tools that supported agents can call directly:
 ### Observation Types
 
 | Type | What it captures |
-|------|-----------------|
+|------|------------------|
 | `discovery` | Learning about existing systems or codebases |
 | `bugfix` | Something was broken, now fixed |
 | `decision` | Architectural or design choice with rationale |
@@ -176,50 +222,55 @@ The MCP server exposes tools that supported agents can call directly:
 | `pattern` | Recurring issue or technique |
 | `digest` | Session summary (auto-generated) |
 
----
-
-## Features
-
 ### Hybrid Search
+
 Local FTS5 + sqlite-vec (all-MiniLM-L6-v2, 384 dims) combined with Candengo Vector's BGE-M3 semantic search. Results merged via Reciprocal Rank Fusion.
 
-### Sentinel — Real-Time Code Audit
-LLM-powered review of every Edit/Write before it executes. Catches security issues, anti-patterns, and drift from team decisions.
+### Sentinel
+
+LLM-powered review of every `Edit`/`Write` before it executes. Catches security issues, anti-patterns, and drift from team decisions.
 
 ```
-⚠️  Sentinel: SQL query uses string concatenation instead of parameterized query
+⚠️ Sentinel: SQL query uses string concatenation instead of parameterized query
    Rule: sql-injection
    (Advisory mode — change allowed)
 ```
 
-5 built-in rule packs: `security`, `auth`, `api`, `react`, `database`.
+**Built-in rule packs:** security, auth, api, react, database.
 
 ```bash
-npx engrm sentinel init-rules        # Install all rule packs
-npx engrm sentinel rules             # List available packs
+npx engrm sentinel init-rules  # Install all rule packs
+npx engrm sentinel rules        # List available packs
 ```
 
-### Starter Packs
+### Knowledge Packs
+
 Pre-loaded knowledge for your tech stack. Detected automatically on session start.
 
-Available: `typescript-patterns`, `nextjs-patterns`, `node-security`, `python-django`, `react-gotchas`, `api-best-practices`, `web-security`
+**Available:** typescript-patterns, nextjs-patterns, node-security, python-django, react-gotchas, api-best-practices, web-security
 
 ```bash
 npx engrm install-pack typescript-patterns
 ```
 
 ### Secret Scrubbing
+
 Multi-layer regex scanning for API keys, passwords, tokens, and credentials. Sensitive content is redacted before storage and sync. Custom patterns configurable in `~/.engrm/settings.json`.
 
-### Observation Lifecycle
+### Retention & Aging
+
 Observations age gracefully: **active** (30 days, full weight) → **aging** (0.7x search weight) → **archived** (compacted into digests) → **purged** (after 12 months). Pinned observations never age.
 
 ---
 
 ## Pricing
 
+**Free tier stays free forever.** No bait-and-switch.
+
+Start with 2 devices and 5,000 observations. Upgrade when you need more.
+
 | | Free | Vibe | Pro | Team |
-|---|---|---|---|---|
+|---|------|------|-----|------|
 | **Price** | £0 | £5.99/mo | £9.99/mo | £12.99/seat/mo |
 | **Observations** | 5,000 | 25,000 | 100,000 | Unlimited |
 | **Devices** | 2 | 3 | 5 | Unlimited |
@@ -232,7 +283,7 @@ Sign up at [engrm.dev](https://engrm.dev).
 
 ---
 
-## Self-Hosting
+## Self-Hosted
 
 Point Engrm at your own [Candengo Vector](https://www.candengo.com) instance:
 
@@ -246,11 +297,11 @@ Candengo Vector provides the backend: BGE-M3 hybrid search, multi-tenant namespa
 
 ## Configuration
 
-### User config: `~/.engrm/settings.json`
+### `~/.engrm/settings.json`
 
 Created by `engrm init`. Contains API credentials, sync settings, search preferences, secret scrubbing patterns, and Sentinel configuration.
 
-### Project config: `.engrm.json` (optional)
+### `.engrm-project.json`
 
 Place in your project root to override project identity for non-git projects:
 
@@ -261,24 +312,25 @@ Place in your project root to override project identity for non-git projects:
 }
 ```
 
-### Agent integration
+### Agent Auto-Registration
 
 Engrm auto-registers in:
+
 - `~/.claude.json` — MCP server (`engrm`)
 - `~/.claude/settings.json` — 6 lifecycle hooks
 - `~/.codex/config.toml` — MCP server (`engrm`) + `codex_hooks` feature flag
-- `~/.codex/hooks.json` — `SessionStart` and `Stop` hooks
+- `~/.codex/hooks.json` — SessionStart and Stop hooks
 
 ---
 
-## Tech Stack
+## Technical Stack
 
-- **Runtime**: TypeScript, runs on Bun (dev) or Node.js 18+ (npm)
-- **Local storage**: SQLite via better-sqlite3, FTS5 full-text search, sqlite-vec for embeddings
-- **Embeddings**: all-MiniLM-L6-v2 via @xenova/transformers (384 dims, ~23MB)
-- **Remote backend**: Candengo Vector (BGE-M3, Qdrant, hybrid dense+sparse search)
-- **MCP**: @modelcontextprotocol/sdk (stdio transport)
-- **AI extraction**: @anthropic-ai/claude-agent-sdk (optional, for richer observations)
+- **Runtime:** TypeScript, runs on Bun (dev) or Node.js 18+ (npm)
+- **Local storage:** SQLite via `better-sqlite3`, FTS5 full-text search, `sqlite-vec` for embeddings
+- **Embeddings:** all-MiniLM-L6-v2 via `@xenova/transformers` (384 dims, ~23MB)
+- **Remote backend:** Candengo Vector (BGE-M3, Qdrant, hybrid dense+sparse search)
+- **MCP:** `@modelcontextprotocol/sdk` (stdio transport)
+- **AI extraction:** `@anthropic-ai/claude-agent-sdk` (optional, for richer observations)
 
 ---
 
@@ -286,23 +338,41 @@ Engrm auto-registers in:
 
 **FSL-1.1-ALv2** (Functional Source License) — part of the [Fair Source](https://fair.io) movement.
 
-- Free to use, modify, and self-host
-- You cannot offer this as a competing hosted service
-- Each version converts to Apache 2.0 after 2 years
-- Sentinel is a separate proprietary product
+- ✅ Free to use, modify, and self-host
+- ❌ You cannot offer this as a competing hosted service
+- ✅ Each version converts to Apache 2.0 after 2 years
+- ⚠️ Sentinel is a separate proprietary product
 
 See [LICENSE](LICENSE) for full terms.
 
 ---
 
-## Project
+## Documentation
 
 - Architecture: [ARCHITECTURE.md](ARCHITECTURE.md)
 - Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
 - Security: [SECURITY.md](SECURITY.md)
 - Roadmap: [ROADMAP.md](ROADMAP.md)
 
-Maintainers: run `node scripts/check-public-docs.mjs` to verify the repo only contains the approved public docs set at the root.
+**Maintainers:** run `node scripts/check-public-docs.mjs` to verify the repo only contains the approved public docs set at the root.
+
+---
+
+## Resources
+
+- [Documentation](https://engrm.dev/developers)
+- [Blog](https://engrm.dev/blog)
+- [Pricing](https://engrm.dev/pricing)
+- [Sentinel](https://engrm.dev/sentinel)
+
+## Community
+
+- [Twitter/X](https://twitter.com/engrm_dev)
+- [GitHub Issues](https://github.com/dr12hes/engrm/issues)
+
+---
+
+**Found this useful?** ⭐ Star this repo to help other developers discover Engrm.
 
 ---
 

package/dist/cli.js

@@ -1072,6 +1072,31 @@ function getOutboxStats(db) {
   return stats;
 }
 
+// src/intelligence/value-signals.ts
+var LESSON_TYPES = new Set(["bugfix", "decision", "pattern"]);
+function computeSessionValueSignals(observations, securityFindings = []) {
+  const decisionsCount = observations.filter((o) => o.type === "decision").length;
+  const lessonsCount = observations.filter((o) => LESSON_TYPES.has(o.type)).length;
+  const discoveriesCount = observations.filter((o) => o.type === "discovery").length;
+  const featuresCount = observations.filter((o) => o.type === "feature").length;
+  const refactorsCount = observations.filter((o) => o.type === "refactor").length;
+  const repeatedPatternsCount = observations.filter((o) => o.type === "pattern").length;
+  const hasRequestSignal = observations.some((o) => ["feature", "decision", "change", "bugfix", "discovery"].includes(o.type));
+  const hasCompletionSignal = observations.some((o) => ["feature", "change", "refactor", "bugfix"].includes(o.type));
+  return {
+    decisions_count: decisionsCount,
+    lessons_count: lessonsCount,
+    discoveries_count: discoveriesCount,
+    features_count: featuresCount,
+    refactors_count: refactorsCount,
+    repeated_patterns_count: repeatedPatternsCount,
+    security_findings_count: securityFindings.length,
+    critical_security_findings_count: securityFindings.filter((f) => f.severity === "critical").length,
+    delivery_review_ready: hasRequestSignal && hasCompletionSignal,
+    vibe_guardian_active: securityFindings.length > 0
+  };
+}
+
 // src/storage/migrations.ts
 var MIGRATIONS2 = [
   {
@@ -2104,6 +2129,80 @@ function findDuplicate(newTitle, candidates) {
   return bestMatch;
 }
 
+// src/capture/facts.ts
+var FACT_ELIGIBLE_TYPES = new Set([
+  "bugfix",
+  "decision",
+  "discovery",
+  "pattern",
+  "feature",
+  "refactor",
+  "change"
+]);
+function buildStructuredFacts(input) {
+  const seedFacts = dedupeFacts(input.facts ?? []);
+  if (!FACT_ELIGIBLE_TYPES.has(input.type)) {
+    return seedFacts;
+  }
+  const derived = [...seedFacts];
+  if (seedFacts.length === 0 && looksMeaningful(input.title)) {
+    derived.push(input.title.trim());
+  }
+  for (const sentence of extractNarrativeFacts(input.narrative)) {
+    derived.push(sentence);
+  }
+  const fileFact = buildFilesFact(input.filesModified);
+  if (fileFact) {
+    derived.push(fileFact);
+  }
+  return dedupeFacts(derived).slice(0, 4);
+}
+function extractNarrativeFacts(narrative) {
+  if (!narrative)
+    return [];
+  const cleaned = narrative.replace(/\s+/g, " ").trim();
+  if (cleaned.length < 24)
+    return [];
+  const parts = cleaned.split(/(?<=[.!?;])\s+/).map((part) => part.trim().replace(/[.!?;]+$/, "")).filter(Boolean).filter(looksMeaningful);
+  return parts.slice(0, 2);
+}
+function buildFilesFact(filesModified) {
+  if (!filesModified || filesModified.length === 0)
+    return null;
+  const cleaned = filesModified.map((file) => file.trim()).filter(Boolean).slice(0, 3);
+  if (cleaned.length === 0)
+    return null;
+  if (cleaned.length === 1) {
+    return `Touched ${cleaned[0]}`;
+  }
+  return `Touched ${cleaned.join(", ")}`;
+}
+function dedupeFacts(facts) {
+  const seen = new Set;
+  const result = [];
+  for (const fact of facts) {
+    const cleaned = fact.trim().replace(/\s+/g, " ");
+    if (!looksMeaningful(cleaned))
+      continue;
+    const key = cleaned.toLowerCase().replace(/\([^)]*\)/g, "").replace(/\s+/g, " ").trim();
+    if (!key || seen.has(key))
+      continue;
+    seen.add(key);
+    result.push(cleaned);
+  }
+  return result;
+}
+function looksMeaningful(value) {
+  const cleaned = value.trim();
+  if (cleaned.length < 12)
+    return false;
+  if (/^[A-Za-z0-9_.\-\/]+\.[A-Za-z0-9]+$/.test(cleaned))
+    return false;
+  if (/^(updated|modified|edited|changed|touched)\s+[A-Za-z0-9_.\-\/]+$/i.test(cleaned))
+    return false;
+  return true;
+}
+
 // src/storage/projects.ts
 import { execSync } from "node:child_process";
 import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
@@ -2495,10 +2594,17 @@ async function saveObservation(db, config, input) {
   const customPatterns = config.scrubbing.enabled ? config.scrubbing.custom_patterns : [];
   const title = config.scrubbing.enabled ? scrubSecrets(input.title, customPatterns) : input.title;
   const narrative = input.narrative ? config.scrubbing.enabled ? scrubSecrets(input.narrative, customPatterns) : input.narrative : null;
-  const factsJson = input.facts ? config.scrubbing.enabled ? scrubSecrets(JSON.stringify(input.facts), customPatterns) : JSON.stringify(input.facts) : null;
   const conceptsJson = input.concepts ? JSON.stringify(input.concepts) : null;
   const filesRead = input.files_read ? input.files_read.map((f) => toRelativePath(f, cwd)) : null;
   const filesModified = input.files_modified ? input.files_modified.map((f) => toRelativePath(f, cwd)) : null;
+  const structuredFacts = buildStructuredFacts({
+    type: input.type,
+    title: input.title,
+    narrative: input.narrative,
+    facts: input.facts,
+    filesModified
+  });
+  const factsJson = structuredFacts.length > 0 ? config.scrubbing.enabled ? scrubSecrets(JSON.stringify(structuredFacts), customPatterns) : JSON.stringify(structuredFacts) : null;
   const filesReadJson = filesRead ? JSON.stringify(filesRead) : null;
   const filesModifiedJson = filesModified ? JSON.stringify(filesModified) : null;
   let sensitivity = input.sensitivity ?? config.scrubbing.default_sensitivity;
@@ -3195,6 +3301,27 @@ function handleStatus() {
       } catch {}
       const summaryCount = db.db.query("SELECT COUNT(*) as count FROM session_summaries").get()?.count ?? 0;
       console.log(`    Sessions:      ${summaryCount} summarised`);
+      try {
+        const activeObservations = db.db.query(`SELECT * FROM observations
+             WHERE lifecycle IN ('active', 'aging', 'pinned') AND superseded_by IS NULL`).all();
+        const securityFindings = db.db.query(`SELECT * FROM security_findings
+             ORDER BY created_at_epoch DESC
+             LIMIT 500`).all();
+        const signals = computeSessionValueSignals(activeObservations, securityFindings);
+        const signalParts = [
+          `lessons: ${signals.lessons_count}`,
+          `decisions: ${signals.decisions_count}`,
+          `discoveries: ${signals.discoveries_count}`,
+          `features: ${signals.features_count}`
+        ];
+        if (signals.repeated_patterns_count > 0) {
+          signalParts.push(`patterns: ${signals.repeated_patterns_count}`);
+        }
+        console.log(`    Value:         ${signalParts.join(", ")}`);
+        if (signals.security_findings_count > 0 || signals.delivery_review_ready) {
+          console.log(`    Review/Safety: ${signals.delivery_review_ready ? "delivery-ready" : "not ready"}, ` + `${signals.security_findings_count} finding${signals.security_findings_count === 1 ? "" : "s"}`);
+        }
+      } catch {}
       try {
         const lastSummary = db.db.query(`SELECT request, created_at_epoch FROM session_summaries
              ORDER BY created_at_epoch DESC LIMIT 1`).get();

package/dist/hooks/elicitation-result.js

@@ -250,6 +250,80 @@ function findDuplicate(newTitle, candidates) {
   return bestMatch;
 }
 
+// src/capture/facts.ts
+var FACT_ELIGIBLE_TYPES = new Set([
+  "bugfix",
+  "decision",
+  "discovery",
+  "pattern",
+  "feature",
+  "refactor",
+  "change"
+]);
+function buildStructuredFacts(input) {
+  const seedFacts = dedupeFacts(input.facts ?? []);
+  if (!FACT_ELIGIBLE_TYPES.has(input.type)) {
+    return seedFacts;
+  }
+  const derived = [...seedFacts];
+  if (seedFacts.length === 0 && looksMeaningful(input.title)) {
+    derived.push(input.title.trim());
+  }
+  for (const sentence of extractNarrativeFacts(input.narrative)) {
+    derived.push(sentence);
+  }
+  const fileFact = buildFilesFact(input.filesModified);
+  if (fileFact) {
+    derived.push(fileFact);
+  }
+  return dedupeFacts(derived).slice(0, 4);
+}
+function extractNarrativeFacts(narrative) {
+  if (!narrative)
+    return [];
+  const cleaned = narrative.replace(/\s+/g, " ").trim();
+  if (cleaned.length < 24)
+    return [];
+  const parts = cleaned.split(/(?<=[.!?;])\s+/).map((part) => part.trim().replace(/[.!?;]+$/, "")).filter(Boolean).filter(looksMeaningful);
+  return parts.slice(0, 2);
+}
+function buildFilesFact(filesModified) {
+  if (!filesModified || filesModified.length === 0)
+    return null;
+  const cleaned = filesModified.map((file) => file.trim()).filter(Boolean).slice(0, 3);
+  if (cleaned.length === 0)
+    return null;
+  if (cleaned.length === 1) {
+    return `Touched ${cleaned[0]}`;
+  }
+  return `Touched ${cleaned.join(", ")}`;
+}
+function dedupeFacts(facts) {
+  const seen = new Set;
+  const result = [];
+  for (const fact of facts) {
+    const cleaned = fact.trim().replace(/\s+/g, " ");
+    if (!looksMeaningful(cleaned))
+      continue;
+    const key = cleaned.toLowerCase().replace(/\([^)]*\)/g, "").replace(/\s+/g, " ").trim();
+    if (!key || seen.has(key))
+      continue;
+    seen.add(key);
+    result.push(cleaned);
+  }
+  return result;
+}
+function looksMeaningful(value) {
+  const cleaned = value.trim();
+  if (cleaned.length < 12)
+    return false;
+  if (/^[A-Za-z0-9_.\-\/]+\.[A-Za-z0-9]+$/.test(cleaned))
+    return false;
+  if (/^(updated|modified|edited|changed|touched)\s+[A-Za-z0-9_.\-\/]+$/i.test(cleaned))
+    return false;
+  return true;
+}
+
 // src/storage/projects.ts
 import { execSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
@@ -630,10 +704,17 @@ async function saveObservation(db, config, input) {
   const customPatterns = config.scrubbing.enabled ? config.scrubbing.custom_patterns : [];
   const title = config.scrubbing.enabled ? scrubSecrets(input.title, customPatterns) : input.title;
   const narrative = input.narrative ? config.scrubbing.enabled ? scrubSecrets(input.narrative, customPatterns) : input.narrative : null;
-  const factsJson = input.facts ? config.scrubbing.enabled ? scrubSecrets(JSON.stringify(input.facts), customPatterns) : JSON.stringify(input.facts) : null;
   const conceptsJson = input.concepts ? JSON.stringify(input.concepts) : null;
   const filesRead = input.files_read ? input.files_read.map((f) => toRelativePath(f, cwd)) : null;
   const filesModified = input.files_modified ? input.files_modified.map((f) => toRelativePath(f, cwd)) : null;
+  const structuredFacts = buildStructuredFacts({
+    type: input.type,
+    title: input.title,
+    narrative: input.narrative,
+    facts: input.facts,
+    filesModified
+  });
+  const factsJson = structuredFacts.length > 0 ? config.scrubbing.enabled ? scrubSecrets(JSON.stringify(structuredFacts), customPatterns) : JSON.stringify(structuredFacts) : null;
   const filesReadJson = filesRead ? JSON.stringify(filesRead) : null;
   const filesModifiedJson = filesModified ? JSON.stringify(filesModified) : null;
   let sensitivity = input.sensitivity ?? config.scrubbing.default_sensitivity;