engrm 0.4.4 → 0.4.6

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/hooks/session-start.js

@@ -2496,41 +2496,233 @@ function formatSplashScreen(data) {
 }
 function formatVisibleStartupBrief(context) {
   const lines = [];
-  const latest = context.summaries?.[0];
+  const latest = pickBestSummary(context);
+  const observationFallbacks = buildObservationFallbacks(context);
   if (latest) {
     const sections = [
-      ["Investigated", latest.investigated],
-      ["Learned", latest.learned],
-      ["Completed", latest.completed],
-      ["Next Steps", latest.next_steps]
+      ["Request", chooseRequest(latest.request, observationFallbacks.request), 1],
+      ["Investigated", chooseSection(latest.investigated, observationFallbacks.investigated, "Investigated"), 2],
+      ["Learned", latest.learned, 2],
+      ["Completed", chooseSection(latest.completed, observationFallbacks.completed, "Completed"), 2],
+      ["Next Steps", latest.next_steps, 2]
     ];
-    for (const [label, value] of sections) {
-      const formatted = toSplashBullet(value, label === "Next Steps" ? 140 : 180);
-      if (formatted) {
-        lines.push(`${c2.cyan}${label}:${c2.reset} ${formatted}`);
+    for (const [label, value, maxItems] of sections) {
+      const formatted = toSplashLines(value, maxItems ?? 2);
+      if (formatted.length > 0) {
+        lines.push(`${c2.cyan}${label}:${c2.reset}`);
+        for (const item of formatted) {
+          lines.push(`  ${item}`);
+        }
       }
     }
   }
-  if (context.staleDecisions && context.staleDecisions.length > 0) {
-    const stale = context.staleDecisions[0];
+  const stale = pickRelevantStaleDecision(context, latest);
+  if (stale) {
     lines.push(`${c2.yellow}Watch:${c2.reset} ${truncateInline(`Decision still looks unfinished: ${stale.title}`, 170)}`);
   }
   if (lines.length === 0 && context.observations.length > 0) {
-    const top = context.observations.slice(0, 2);
+    const top = context.observations.filter((obs) => !looksLikeFileOperationTitle(obs.title)).slice(0, 2);
     for (const obs of top) {
       lines.push(`${c2.cyan}${capitalize(obs.type)}:${c2.reset} ${truncateInline(obs.title, 170)}`);
     }
   }
-  return lines.slice(0, 5);
+  return lines.slice(0, 10);
 }
-function toSplashBullet(value, maxLen) {
+function toSplashLines(value, maxItems) {
   if (!value)
+    return [];
+  const lines = value.split(`
+`).map((line) => line.trim()).filter(Boolean).map((line) => line.replace(/^[-*]\s*/, "")).map((line) => dedupeFragments(line)).filter(Boolean).sort((a, b) => scoreSplashLine(b) - scoreSplashLine(a)).slice(0, maxItems).map((line) => `- ${truncateInline(line, 140)}`);
+  return dedupeFragmentsInLines(lines);
+}
+function pickBestSummary(context) {
+  const summaries = context.summaries || [];
+  if (!summaries.length)
     return null;
-  const cleaned = value.split(`
-`).map((line) => line.trim().replace(/^[-*]\s*/, "")).filter(Boolean).join("; ");
-  if (!cleaned)
+  return [...summaries].sort((a, b) => scoreSummary(b) - scoreSummary(a))[0] ?? null;
+}
+function scoreSummary(summary) {
+  let score = 0;
+  if (summary.request)
+    score += 3;
+  if (summary.investigated)
+    score += 4;
+  if (summary.learned)
+    score += 5;
+  if (summary.completed)
+    score += 5;
+  if (summary.next_steps)
+    score += 4;
+  score += Math.min(4, sectionItemCount(summary.completed) + sectionItemCount(summary.learned));
+  return score;
+}
+function sectionItemCount(value) {
+  if (!value)
+    return 0;
+  return value.split(`
+`).map((line) => line.trim()).filter(Boolean).length;
+}
+function dedupeFragments(text) {
+  const parts = text.split(";").map((part) => part.trim()).filter(Boolean);
+  const seen = new Set;
+  const deduped = [];
+  for (const part of parts) {
+    const normalized = part.toLowerCase();
+    if (seen.has(normalized))
+      continue;
+    seen.add(normalized);
+    deduped.push(part);
+  }
+  return deduped.join("; ");
+}
+function dedupeFragmentsInLines(lines) {
+  const seen = new Set;
+  const deduped = [];
+  for (const line of lines) {
+    const normalized = line.toLowerCase().replace(/\s+/g, " ").trim();
+    if (!normalized || seen.has(normalized))
+      continue;
+    seen.add(normalized);
+    deduped.push(line);
+  }
+  return deduped;
+}
+function chooseRequest(primary, fallback) {
+  if (primary && !looksLikeFileOperationTitle(primary))
+    return primary;
+  return fallback;
+}
+function chooseSection(primary, fallback, label) {
+  if (!primary)
+    return fallback;
+  if (label === "Completed" && isWeakCompletedSection(primary))
+    return fallback || primary;
+  if (label === "Investigated" && sectionItemCount(primary) === 0)
+    return fallback;
+  return primary;
+}
+function isWeakCompletedSection(value) {
+  const items = value.split(`
+`).map((line) => line.trim().replace(/^[-*]\s*/, "")).filter(Boolean);
+  if (!items.length)
+    return true;
+  const weakCount = items.filter((item) => looksLikeFileOperationTitle(item)).length;
+  return weakCount === items.length;
+}
+function looksLikeFileOperationTitle(value) {
+  return /^(modified|updated|edited|touched|changed|extended|refactored|redesigned)\s+[A-Za-z0-9_.\-\/]+(?:\s*\([^)]*\))?$/i.test(value.trim());
+}
+function scoreSplashLine(value) {
+  let score = 0;
+  if (!looksLikeFileOperationTitle(value))
+    score += 2;
+  if (/[:;]/.test(value))
+    score += 1;
+  if (value.length > 30)
+    score += 0.5;
+  return score;
+}
+function buildObservationFallbacks(context) {
+  const request = context.observations.find((obs) => !looksLikeFileOperationTitle(obs.title))?.title ?? null;
+  const investigated = collectObservationTitles(context, (obs) => obs.type === "discovery", 2);
+  const completed = collectObservationTitles(context, (obs) => ["feature", "refactor", "change", "digest"].includes(obs.type) && !looksLikeFileOperationTitle(obs.title), 2);
+  return {
+    request,
+    investigated,
+    completed
+  };
+}
+function collectObservationTitles(context, predicate, limit) {
+  const seen = new Set;
+  const picked = [];
+  for (const obs of context.observations) {
+    if (!predicate(obs))
+      continue;
+    const normalized = obs.title.toLowerCase().replace(/\s+/g, " ").trim();
+    if (!normalized || seen.has(normalized))
+      continue;
+    seen.add(normalized);
+    picked.push(`- ${obs.title}`);
+    if (picked.length >= limit)
+      break;
+  }
+  return picked.length ? picked.join(`
+`) : null;
+}
+function pickRelevantStaleDecision(context, summary) {
+  const stale = context.staleDecisions || [];
+  if (!stale.length)
     return null;
-  return truncateInline(cleaned, maxLen);
+  const summaryText = [
+    summary?.request,
+    summary?.investigated,
+    summary?.learned,
+    summary?.completed,
+    summary?.next_steps
+  ].filter(Boolean).join(" ");
+  let best = null;
+  let bestScore = 0;
+  for (const item of stale) {
+    if ((item.days_ago ?? 999) > 21)
+      continue;
+    const overlap = keywordOverlap(item.title || "", summaryText);
+    const similarity = item.best_match_similarity ?? 0;
+    const score = overlap * 4 + similarity;
+    if (score > bestScore && overlap > 0) {
+      best = item;
+      bestScore = score;
+    }
+  }
+  return best;
+}
+function keywordOverlap(a, b) {
+  if (!a || !b)
+    return 0;
+  const stop = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "into",
+    "this",
+    "that",
+    "was",
+    "were",
+    "have",
+    "has",
+    "had",
+    "but",
+    "not",
+    "you",
+    "your",
+    "our",
+    "their",
+    "about",
+    "added",
+    "fixed",
+    "created",
+    "updated",
+    "modified",
+    "changed",
+    "investigate",
+    "next",
+    "steps",
+    "decision",
+    "still",
+    "looks",
+    "unfinished"
+  ]);
+  const wordsA = new Set(a.toLowerCase().match(/[a-z0-9_+-]{4,}/g)?.filter((w) => !stop.has(w)) || []);
+  const wordsB = new Set(b.toLowerCase().match(/[a-z0-9_+-]{4,}/g)?.filter((w) => !stop.has(w)) || []);
+  if (!wordsA.size || !wordsB.size)
+    return 0;
+  let overlap = 0;
+  for (const word of wordsA) {
+    if (wordsB.has(word))
+      overlap++;
+  }
+  return overlap / Math.max(1, Math.min(wordsA.size, wordsB.size));
 }
 function truncateInline(text, maxLen) {
   const compact = text.replace(/\s+/g, " ").trim();

package/dist/hooks/stop.js

@@ -35,35 +35,34 @@ function extractInvestigated(observations) {
   const discoveries = observations.filter((o) => o.type === "discovery");
   if (discoveries.length === 0)
     return null;
-  return discoveries.slice(0, 5).map((o) => {
-    const facts = extractTopFacts(o, 2);
-    return facts ? `- ${o.title}
-${facts}` : `- ${o.title}`;
-  }).join(`
-`);
+  return formatObservationGroup(discoveries, {
+    limit: 4,
+    factsPerItem: 2
+  });
 }
 function extractLearned(observations) {
   const learnTypes = new Set(["bugfix", "decision", "pattern"]);
   const learned = observations.filter((o) => learnTypes.has(o.type));
   if (learned.length === 0)
     return null;
-  return learned.slice(0, 5).map((o) => {
-    const facts = extractTopFacts(o, 2);
-    return facts ? `- ${o.title}
-${facts}` : `- ${o.title}`;
-  }).join(`
-`);
+  return formatObservationGroup(learned, {
+    limit: 4,
+    factsPerItem: 2
+  });
 }
 function extractCompleted(observations) {
   const completeTypes = new Set(["change", "feature", "refactor"]);
   const completed = observations.filter((o) => completeTypes.has(o.type));
   if (completed.length === 0)
     return null;
-  return completed.slice(0, 5).map((o) => {
-    const files = o.files_modified ? parseJsonArray(o.files_modified) : [];
-    const fileCtx = files.length > 0 ? ` (${files.slice(0, 2).map((f) => f.split("/").pop()).join(", ")})` : "";
-    return `- ${o.title}${fileCtx}`;
-  }).join(`
+  const prioritized = dedupeObservationsByTitle(completed).sort((a, b) => scoreCompletedObservation(b) - scoreCompletedObservation(a)).slice(0, 4);
+  const lines = prioritized.map((o) => {
+    const title = normalizeCompletedTitle(o.title, o.files_modified);
+    const facts = extractTopFacts(o, 1);
+    return facts ? `- ${title}
+${facts}` : `- ${title}`;
+  });
+  return dedupeBulletLines(lines).join(`
 `);
 }
 function extractNextSteps(observations) {
@@ -77,11 +76,78 @@ function extractNextSteps(observations) {
   return unresolved.map((o) => `- Investigate: ${o.title}`).slice(0, 3).join(`
 `);
 }
+function formatObservationGroup(observations, options) {
+  const lines = dedupeObservationsByTitle(observations).slice(0, options.limit).map((o) => {
+    const facts = extractTopFacts(o, options.factsPerItem);
+    return facts ? `- ${o.title}
+${facts}` : `- ${o.title}`;
+  });
+  const deduped = dedupeBulletLines(lines);
+  return deduped.length ? deduped.join(`
+`) : null;
+}
+function dedupeBulletLines(lines) {
+  const seen = new Set;
+  const deduped = [];
+  for (const line of lines) {
+    const normalized = line.toLowerCase().replace(/\([^)]*\)/g, "").replace(/\s+/g, " ").trim();
+    if (!normalized || seen.has(normalized))
+      continue;
+    seen.add(normalized);
+    deduped.push(line);
+  }
+  return deduped;
+}
+function dedupeObservationsByTitle(observations) {
+  const seen = new Set;
+  const deduped = [];
+  for (const obs of observations) {
+    const normalized = normalizeObservationKey(obs.title);
+    if (!normalized || seen.has(normalized))
+      continue;
+    seen.add(normalized);
+    deduped.push(obs);
+  }
+  return deduped;
+}
+function scoreCompletedObservation(obs) {
+  let score = obs.quality || 0;
+  if (obs.type === "feature")
+    score += 0.5;
+  if (obs.type === "refactor")
+    score += 0.2;
+  if (hasMeaningfulFacts(obs))
+    score += 0.4;
+  if (looksLikeFileOperation(obs.title))
+    score -= 0.6;
+  if (obs.narrative && obs.narrative.length > 80)
+    score += 0.2;
+  return score;
+}
+function hasMeaningfulFacts(obs) {
+  return parseJsonArray(obs.facts).some((fact) => fact.trim().length > 20);
+}
+function looksLikeFileOperation(title) {
+  return /^(modified|updated|edited|touched|changed)\s+[A-Za-z0-9_.\-\/]+$/i.test(title.trim());
+}
+function normalizeCompletedTitle(title, filesModified) {
+  const trimmed = title.trim();
+  if (!trimmed)
+    return "Completed work";
+  if (!looksLikeFileOperation(trimmed))
+    return trimmed;
+  const files = parseJsonArray(filesModified);
+  const filename = files[0]?.split("/").pop();
+  if (filename) {
+    return `Updated implementation in ${filename}`;
+  }
+  return trimmed;
+}
 function extractTopFacts(obs, n) {
-  const facts = parseJsonArray(obs.facts);
+  const facts = parseJsonArray(obs.facts).filter((fact) => isUsefulFact(fact, obs.title)).slice(0, n);
   if (facts.length === 0)
     return null;
-  return facts.slice(0, n).map((f) => `    ${f}`).join(`
+  return facts.map((f) => `    ${f}`).join(`
 `);
 }
 function parseJsonArray(json) {
@@ -95,6 +161,23 @@ function parseJsonArray(json) {
   } catch {}
   return [];
 }
+function isUsefulFact(fact, title) {
+  const cleaned = fact.trim();
+  if (!cleaned)
+    return false;
+  const normalizedFact = normalizeObservationKey(cleaned);
+  const normalizedTitle = normalizeObservationKey(title);
+  if (normalizedFact && normalizedFact === normalizedTitle)
+    return false;
+  if (/^[A-Za-z0-9_.\-\/]+\.[A-Za-z0-9]+$/.test(cleaned))
+    return false;
+  if (/^\(?[A-Za-z0-9_.\-\/]+\.[A-Za-z0-9]+\)?$/.test(cleaned))
+    return false;
+  return cleaned.length > 16 || /[:;]/.test(cleaned);
+}
+function normalizeObservationKey(value) {
+  return value.toLowerCase().replace(/\([^)]*\)/g, "").replace(/\b(modified|updated|edited|touched|changed)\b/g, "").replace(/\s+/g, " ").trim();
+}
 
 // src/config.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";

package/dist/server.js

@@ -16947,7 +16947,7 @@ process.on("SIGTERM", () => {
 });
 var server = new McpServer({
   name: "engrm",
-  version: "0.1.0"
+  version: "0.4.6"
 });
 server.tool("save_observation", "Save an observation to memory", {
   type: exports_external.enum([

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "engrm",
-  "version": "0.4.4",
-  "description": "Cross-device, team-shared memory layer for AI coding agents",
+  "version": "0.4.6",
+  "description": "Shared memory across devices, sessions, and coding agents",
+  "mcpName": "io.github.dr12hes/engrm",
   "type": "module",
   "main": "dist/server.js",
   "bin": {