diff --git a/PI-DREAM.md b/PI-DREAM.md
new file mode 100644
index 0000000..2fd5217
--- /dev/null
+++ b/PI-DREAM.md
@@ -0,0 +1,89 @@
+# pi-dream — memory consolidation for pi-memory
+
+Local working notes for the `feat/pi-dream-consolidation` branch (PR: https://github.com/jayzeng/pi-memory/pull/34).
+
+> This file is local-only documentation. The upstream-facing docs live in `README.md`.
+
+## What it does
+
+After many sessions, `MEMORY.md` accumulates near-duplicate entries and older entries superseded by newer ones about the same topic. Bloat is injected into every session start — wasted context tokens + stale-recall risk.
+
+pi-dream detects both patterns and removes redundant older copies through the standard recovery-record pipeline (fully reversible).
+
+## Detection
+
+| Pattern | Method | Default threshold |
+|---|---|---|
+| Near-duplicates | Jaccard similarity over word tokens (≥3 chars) | ≥ 0.75 |
+| Superseded | Similar older/newer pair on same topic | ≥ 0.6 similarity AND ≥ 7 days age gap |
+
+Entry unit = timestamped block (`<!-- YYYY-MM-DD HH:MM:SS [session] -->` until next meta comment). Trailing unstamped lines after the last stamp belong to that entry (same semantics as `forgetBlocks`).
+
+## Commands & tools
+
+### `/pi-dream [auto|report|apply]`
+
+Drives the agent via `pi.sendUserMessage`. Modes:
+
+| Mode | Behavior |
+|---|---|
+| *(none)* = **auto** | Report → if ALL findings are pure duplicates (zero content loss) → applies immediately, shows recovery ID. If superseded entries found → stops, presents findings, asks first |
+| `report` | Read-only full findings with previews |
+| `apply` | Apply everything found, show removed entries + recovery ID |
+| bad arg | Usage hint |
+
+### `memory_dream` tool (agent-invocable)
+
+```
+memory_dream {}                                  # report mode (default)
+memory_dream { mode: "report" }                  # read-only findings
+memory_dream { mode: "apply" }                   # consolidate, returns recovery ID
+memory_dream { duplicateSimilarity: 0.8 }        # stricter dup threshold
+memory_dream { supersedeSimilarity: 0.5 }        # looser supersede detection
+```
+
+Returns: findings with previews / removed count + `recoveryId`.
+
+### Undo
+
+```
+memory_restore { recoveryId: "<id from apply>" }
+```
+
+Recovery records live in `~/.pi/agent/memory/recovery/<id>.json` before any file mutation.
+
+## Files
+
+| Path | Role |
+|---|---|
+| `index.ts` | All logic: `parseMemoryBlocks`, `dreamSimilarity`, `dreamAnalyze`, `dreamDropIndices`, `dreamApply` (exported pure functions) + tool/command registration (~line 670 analysis, ~line 2355 tool) |
+| `test/unit.test.ts` | `describe("pi-dream consolidation")` — 10 tests |
+
+Pipeline on apply: `dreamAnalyze` → `dreamDropIndices` → `dreamApply` → `writeRecoveryRecord("long_term")` → write file → `snapshotDirty = true` → `scheduleQmdUpdate()`.
+
+## Install (this machine)
+
+`~/.pi/agent/settings.json`:
+
+```json
+"git:github.com/KrissTos/pi-memory@feat/pi-dream-consolidation"
+```
+
+Note: branch separator is `@`, not `#`. After merge upstream, switch back to `"npm:pi-memory"` and run `pi update --extensions`.
+
+## Dev workflow
+
+```bash
+cd ~/Projects/pi-memory-pr
+bun test test/unit.test.ts      # 192 tests
+bunx tsc --noEmit               # typecheck
+bunx biome check index.ts       # lint/format (pre-commit hook enforces all three)
+git push origin feat/pi-dream-consolidation   # auto-updates PR #34
+```
+
+Pre-commit hooks (`.githooks/`) run tests + lint on every commit — commit fails if format drifts; fix with `bunx biome check --write index.ts`.
+
+## Roadmap ideas
+
+- Weekly scheduled run via `pi-schedule-prompt`: recurring prompt "Run memory_dream report; apply if pure duplicates only" (validate judgment on real runs first)
+- Phase 2: semantic contradiction merging (needs LLM call, e.g. exit-summary-style model access)
diff --git a/README.md b/README.md
index 819156e..a6b658c 100644
--- a/README.md
+++ b/README.md
@@ -41,8 +41,8 @@ pi install npm:pi-memory
 pi install ./pi-memory
 ```
 
-That's it — the six core tools (`memory_write`, `memory_forget`, `memory_restore`,
-`memory_read`, `scratchpad`, `memory_status`) work immediately with no other setup.
+That's it — the core tools (`memory_write`, `memory_forget`, `memory_restore`,
+`memory_dream`, `memory_read`, `scratchpad`, `memory_status`) work immediately with no other setup.
 Search is opt-in below.
 
 ### Optional: enable search with qmd
@@ -80,6 +80,7 @@ Without qmd, the core tools still work fully — only `memory_search` and select
 | `memory_write` | Write to MEMORY.md (long-term) or daily log |
 | `memory_forget` | Delete matching entries and create a durable recovery record |
 | `memory_restore` | Restore a deletion using the recovery ID returned by `memory_forget` |
+| `memory_dream` | Consolidate MEMORY.md: report/apply near-duplicate and superseded entries (pi-dream) |
 | `memory_read` | Read any memory file or list daily logs |
 | `scratchpad` | Add/done/undo/clear/list checklist items |
 | `memory_search` | Search across all memory files (requires qmd) |
@@ -175,6 +176,7 @@ This ensures in-progress context survives compaction and is visible in the next
 
 - **Persistence**: Memory files are plain markdown on disk — readable, editable, and git-friendly.
 - **Recoverable deletion**: `memory_forget` stores complete deleted entries under `recovery/` before changing memory and returns a recovery ID that `memory_restore` can use. Recovery JSON is outside qmd's `**/*.md` index.
+- **pi-dream consolidation** (`memory_dream` tool, `/pi-dream` command): detects near-duplicate entries (Jaccard similarity over word tokens) and older entries superseded by newer ones about the same topic. `mode='report'` analyzes without touching files; `mode='apply'` removes redundant older entries through the same recovery-record pipeline as `memory_forget`, so consolidation is undoable. Thresholds are tunable via `duplicateSimilarity` / `supersedeSimilarity` parameters.
 - **Tool response previews**: Write/scratchpad tools return size-capped previews instead of full file contents.
 - **qmd auto-setup**: On first session start with qmd available, the extension creates the collection and path contexts automatically.
 - **qmd re-indexing**: After every write, a debounced `qmd update` runs in the background (fire-and-forget, non-blocking) unless disabled via `PI_MEMORY_QMD_UPDATE`.
diff --git a/index.ts b/index.ts
index 3ad496d..c521b64 100644
--- a/index.ts
+++ b/index.ts
@@ -724,6 +724,187 @@ export function forgetBlocks(content: string, match: string): { content: string;
 	};
 }
 
+// ---------------------------------------------------------------------------
+// pi-dream: memory consolidation analysis
+// ---------------------------------------------------------------------------
+
+export interface DreamBlock {
+	/** Timestamp meta comment line ("" for unstamped paragraph blocks). */
+	meta: string;
+	body: string;
+	timestamp: Date | null;
+}
+
+export interface DreamAnalysisOptions {
+	/** Jaccard similarity at/below which two entries are considered duplicates. Default 0.75. */
+	duplicateSimilarity?: number;
+	/** Jaccard similarity at which an older entry counts as superseded by a newer one. Default 0.6. */
+	supersedeSimilarity?: number;
+	/** Minimum age gap in days between a superseded entry and its newer replacement. Default 7. */
+	supersedeMinAgeDays?: number;
+}
+
+export interface DreamAnalysis {
+	blocks: DreamBlock[];
+	/** Groups of block indices (length > 1) whose text is near-identical. */
+	duplicateGroups: number[][];
+	/** Pairs where the older entry is considered superseded by the newer one. */
+	superseded: Array<{ olderIndex: number; newerIndex: number }>;
+}
+
+const DREAM_TIMESTAMP_REGEX =
+	/^<!-- (?:(?:last updated: )?(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})|HANDOFF (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})) /;
+
+/** Parse MEMORY.md content into stamped/unstamped blocks (same unit as forgetBlocks removes). */
+export function parseMemoryBlocks(content: string): DreamBlock[] {
+	const normalized = content.replace(/\r\n?/g, "\n").replace(/^\uFEFF/, "");
+	const rawBlocks: string[] = [];
+	let currentLines: string[] = [];
+	let currentIsStamped = false;
+	const flushCurrent = () => {
+		const current = currentLines.join("\n").trim();
+		if (!current) return;
+		if (currentIsStamped) {
+			rawBlocks.push(current);
+		} else {
+			rawBlocks.push(
+				...current
+					.split(/\n{2,}/)
+					.map((block) => block.trim())
+					.filter(Boolean),
+			);
+		}
+	};
+	for (const line of normalized.split("\n")) {
+		if (MEMORY_ENTRY_META_COMMENT_REGEX.test(line)) {
+			flushCurrent();
+			currentLines = [line];
+			currentIsStamped = true;
+		} else {
+			currentLines.push(line);
+		}
+	}
+	flushCurrent();
+
+	return rawBlocks.map((raw) => {
+		const lines = raw.split("\n");
+		const first = lines[0] ?? "";
+		if (MEMORY_ENTRY_META_COMMENT_REGEX.test(first)) {
+			const match = DREAM_TIMESTAMP_REGEX.exec(first);
+			const ts = match ? (match[1] ?? match[2]) : undefined;
+			return {
+				meta: first,
+				body: lines.slice(1).join("\n").trim() || raw,
+				timestamp: ts ? new Date(ts.replace(" ", "T")) : null,
+			};
+		}
+		return { meta: "", body: raw, timestamp: null };
+	});
+}
+
+function dreamTokenSet(text: string): Set<string> {
+	const tokens = text
+		.toLowerCase()
+		.split(/[^a-z0-9]+/)
+		.filter((word) => word.length >= 3);
+	return new Set(tokens);
+}
+
+/** Jaccard similarity over lowercase word tokens (words < 3 chars ignored). */
+export function dreamSimilarity(a: string, b: string): number {
+	const setA = dreamTokenSet(a);
+	const setB = dreamTokenSet(b);
+	if (setA.size === 0 && setB.size === 0) return 1;
+	let intersection = 0;
+	for (const token of setA) {
+		if (setB.has(token)) intersection++;
+	}
+	const union = setA.size + setB.size - intersection;
+	return union === 0 ? 0 : intersection / union;
+}
+
+function dreamDaysBetween(a: Date, b: Date): number {
+	return Math.abs(a.getTime() - b.getTime()) / 86_400_000;
+}
+
+/** Analyze MEMORY.md content for duplicate groups and superseded older entries. */
+export function dreamAnalyze(content: string, opts: DreamAnalysisOptions = {}): DreamAnalysis {
+	const duplicateThreshold = opts.duplicateSimilarity ?? 0.75;
+	const supersedeThreshold = opts.supersedeSimilarity ?? 0.6;
+	const supersedeMinAgeDays = opts.supersedeMinAgeDays ?? 7;
+	const blocks = parseMemoryBlocks(content);
+	const n = blocks.length;
+
+	// Union-find over near-identical pairs.
+	const parent = Array.from({ length: n }, (_, i) => i);
+	const find = (i: number): number => {
+		if (parent[i] !== i) parent[i] = find(parent[i]);
+		return parent[i];
+	};
+	const unionPair = (i: number, j: number) => {
+		parent[find(i)] = find(j);
+	};
+	const superseded: Array<{ olderIndex: number; newerIndex: number }> = [];
+	for (let i = 0; i < n; i++) {
+		for (let j = i + 1; j < n; j++) {
+			const sim = dreamSimilarity(blocks[i].body, blocks[j].body);
+			if (sim >= duplicateThreshold) {
+				unionPair(i, j);
+				continue;
+			}
+			const ti = blocks[i].timestamp;
+			const tj = blocks[j].timestamp;
+			if (sim >= supersedeThreshold && ti && tj) {
+				if (dreamDaysBetween(ti, tj) >= supersedeMinAgeDays) {
+					const olderIsFirst = ti <= tj;
+					superseded.push(olderIsFirst ? { olderIndex: i, newerIndex: j } : { olderIndex: j, newerIndex: i });
+				}
+			}
+		}
+	}
+
+	const groupMap = new Map<number, number[]>();
+	for (let i = 0; i < n; i++) {
+		const root = find(i);
+		const group = groupMap.get(root);
+		if (group) group.push(i);
+		else groupMap.set(root, [i]);
+	}
+	const duplicateGroups = [...groupMap.values()].filter((group) => group.length > 1);
+	return { blocks, duplicateGroups, superseded };
+}
+
+/** Compute which block indices pi-dream would remove: older members of duplicate groups plus superseded entries. */
+export function dreamDropIndices(analysis: DreamAnalysis): number[] {
+	const drops = new Set<number>();
+	for (const group of analysis.duplicateGroups) {
+		// Keep the newest member (largest index = latest position); drop earlier copies.
+		const sorted = [...group].sort((a, b) => a - b);
+		for (const index of sorted.slice(0, -1)) drops.add(index);
+	}
+	for (const pair of analysis.superseded) drops.add(pair.olderIndex);
+	return [...drops].sort((a, b) => a - b);
+}
+
+/** Apply consolidation to content: returns surviving content plus complete removed blocks. */
+export function dreamApply(
+	content: string,
+	opts: DreamAnalysisOptions = {},
+): { keptContent: string; removed: string[] } {
+	const newline = content.includes("\r\n") ? "\r\n" : "\n";
+	const analysis = dreamAnalyze(content, opts);
+	const drops = dreamDropIndices(analysis);
+	if (drops.length === 0) return { keptContent: content, removed: [] };
+	const removed: string[] = [];
+	const kept: string[] = [];
+	analysis.blocks.forEach((block, index) => {
+		const raw = block.meta ? `${block.meta}\n${block.body}` : block.body;
+		if (drops.includes(index)) removed.push(raw.replace(/\n/g, newline));
+		else kept.push(raw.replace(/\n/g, newline));
+	});
+	return { keptContent: kept.length ? `${kept.join("\n\n")}\n` : "", removed };
+}
+
 function recoveryPath(recoveryId: string): string | null {
 	if (!RECOVERY_ID_REGEX.test(recoveryId)) return null;
 	return path.join(RECOVERY_DIR, `${recoveryId}.json`);
@@ -2149,6 +2330,150 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// --- memory_dream (pi-dream) tool ---
+	pi.registerTool({
+		name: "memory_dream",
+		label: "Memory Dream",
+		description: [
+			"Consolidate long-term memory (MEMORY.md): detect near-duplicate entries and older entries",
+			"superseded by newer ones about the same topic. mode='report' (default) analyzes only and",
+			"returns findings; mode='apply' removes redundant older entries via the standard recovery-record",
+			"pipeline (undo with memory_restore). Run this when MEMORY.md has grown bloated or contradictory",
+			"after many sessions.",
+		].join("\n"),
+		parameters: Type.Object({
+			mode: Type.Optional(
+				StringEnum(["report", "apply"] as const, {
+					description: "'report' (default) analyzes without changing files; 'apply' removes redundant entries",
+				}),
+			),
+			duplicateSimilarity: Type.Optional(
+				Type.Number({ description: "Jaccard threshold for duplicates (0-1, default 0.75)" }),
+			),
+			supersedeSimilarity: Type.Optional(
+				Type.Number({ description: "Jaccard threshold for superseded entries (0-1, default 0.6)" }),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			ensureDirs();
+			const existing = readFileSafe(MEMORY_FILE);
+			if (!existing?.trim()) {
+				return {
+					content: [{ type: "text", text: `Nothing stored in ${MEMORY_FILE} — nothing to dream about.` }],
+					details: { path: MEMORY_FILE, removed: 0 },
+				};
+			}
+			const opts: DreamAnalysisOptions = {};
+			if (params.duplicateSimilarity !== undefined) opts.duplicateSimilarity = params.duplicateSimilarity;
+			if (params.supersedeSimilarity !== undefined) opts.supersedeSimilarity = params.supersedeSimilarity;
+
+			const analysis = dreamAnalyze(existing, opts);
+			const dropCount = dreamDropIndices(analysis).length;
+			if (dropCount === 0) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `pi-dream: no duplicates or superseded entries found in ${MEMORY_FILE} (${analysis.blocks.length} entries analyzed). Memory looks healthy.`,
+						},
+					],
+					details: { path: MEMORY_FILE, analyzed: analysis.blocks.length, removed: 0 },
+				};
+			}
+
+			const previewBlock = (index: number): string => {
+				const block = analysis.blocks[index];
+				const raw = block.meta ? `${block.meta}\n${block.body}` : block.body;
+				const preview = buildPreview(raw, { maxLines: 4, maxChars: 300, mode: "start" });
+				return preview.preview;
+			};
+			const findings: string[] = [];
+			for (const group of analysis.duplicateGroups) {
+				findings.push(`Duplicate group (keeping newest #${Math.max(...group)}):`);
+				for (const index of group) findings.push(`  [#${index}] ${previewBlock(index)}`);
+			}
+			for (const pair of analysis.superseded) {
+				findings.push(`Superseded: [#${pair.olderIndex}] replaced by newer [#${pair.newerIndex}]:`);
+				findings.push(`  [#${pair.olderIndex}] ${previewBlock(pair.olderIndex)}`);
+			}
+			const findingsText = findings.join("\n");
+
+			if ((params.mode ?? "report") === "report") {
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								`pi-dream report for ${MEMORY_FILE}: ${dropCount} of ${analysis.blocks.length} entries are removable ` +
+								`(${analysis.duplicateGroups.length} duplicate group(s), ${analysis.superseded.length} superseded).\n\n` +
+								`${findingsText}\n\n` +
+								`Review the findings, then re-run with mode='apply' to remove them (recovery record included).`,
+						},
+					],
+					details: {
+						path: MEMORY_FILE,
+						analyzed: analysis.blocks.length,
+						removable: dropCount,
+						duplicateGroups: analysis.duplicateGroups.length,
+						superseded: analysis.superseded.length,
+					},
+				};
+			}
+
+			const applied = dreamApply(existing, opts);
+			const recovery = writeRecoveryRecord("long_term", undefined, applied.removed);
+			fs.writeFileSync(MEMORY_FILE, applied.keptContent, "utf-8");
+			snapshotDirty = true;
+			await ensureQmdAvailableForUpdate();
+			scheduleQmdUpdate();
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							`pi-dream: consolidated ${MEMORY_FILE}. Removed ${applied.removed.length} redundant entr${applied.removed.length === 1 ? "y" : "ies"} ` +
+							`(was ${analysis.blocks.length}, now ${analysis.blocks.length - applied.removed.length}). ` +
+							`Recovery ID: ${recovery.id}. To undo this consolidation, call memory_restore with that ID.\n\n` +
+							`Removed:\n${findingsText}`,
+					},
+				],
+				details: {
+					path: MEMORY_FILE,
+					analyzed: analysis.blocks.length,
+					removed: applied.removed.length,
+					recoveryId: recovery.id,
+					recoveryPath: recoveryPath(recovery.id),
+				},
+			};
+		},
+	});
+
+	// --- /pi-dream command: drives the agent to run the memory_dream tool ---
+	pi.registerCommand("pi-dream", {
+		description:
+			"Memory consolidation: /pi-dream [auto|report|apply] (default auto: applies pure duplicates, asks about superseded)",
+		handler: async (args, ctx) => {
+			const mode = (args ?? "").trim().toLowerCase();
+			const existing = readFileSafe(MEMORY_FILE);
+			if (!existing?.trim()) {
+				ctx.ui.notify("pi-dream: memory is empty — nothing to consolidate.", "info");
+				return;
+			}
+			if (mode !== "" && mode !== "report" && mode !== "apply" && mode !== "auto") {
+				ctx.ui.notify("pi-dream: unknown argument. Usage: /pi-dream [report|apply]", "warning");
+				return;
+			}
+			const effective = mode === "" ? "auto" : mode;
+			pi.sendUserMessage(
+				effective === "apply"
+					? "Run the memory_dream tool with mode='apply' to consolidate MEMORY.md. Show me what was removed and the recovery ID."
+					: effective === "auto"
+						? "Run the memory_dream tool in report mode on MEMORY.md. If ALL removable entries are near-duplicates of kept newer versions (zero unique content would be lost), immediately re-run with mode='apply' and show me what was removed plus the recovery ID. If any finding involves superseded entries where older content differs meaningfully from its newer replacement, do NOT apply — present those findings and ask me first."
+						: "Run the memory_dream tool in report mode and show me the full findings for MEMORY.md — duplicate groups and superseded entries with previews. Do not modify anything.",
+			);
+		},
+	});
+
 	// --- memory_restore tool ---
 	pi.registerTool({
 		name: "memory_restore",
diff --git a/test/unit.test.ts b/test/unit.test.ts
index 79865a1..616f0c9 100644
--- a/test/unit.test.ts
+++ b/test/unit.test.ts
@@ -28,6 +28,10 @@ import {
 	buildQmdSpawn,
 	clampSearchLimit,
 	dailyPath,
+	dreamAnalyze,
+	dreamApply,
+	dreamDropIndices,
+	dreamSimilarity,
 	ensureDirs,
 	ensureQmdEmbed,
 	forgetBlocks,
@@ -36,6 +40,7 @@ import {
 	isExitSummaryEmpty,
 	isExitSummaryEnabled,
 	nowTimestamp,
+	parseMemoryBlocks,
 	parseScratchpad,
 	qmdCollectionInstructions,
 	qmdInstallInstructions,
@@ -84,6 +89,7 @@ function createMockPi() {
 		on(event: string, handler: (...args: unknown[]) => unknown) {
 			hooks[event] = handler;
 		},
+		registerCommand(_name: string, _def: unknown) {},
 	};
 
 	return { pi, tools, hooks };
@@ -2005,10 +2011,10 @@ describe("KV cache stability: memory snapshot", () => {
 // ==========================================================================
 
 describe("extension registration", () => {
-	test("registers all 7 tools", () => {
+	test("registers all 8 tools", () => {
 		const mockPi = createMockPi();
 		registerExtension(mockPi.pi as any);
-		expect(Object.keys(mockPi.tools)).toHaveLength(7);
+		expect(Object.keys(mockPi.tools)).toHaveLength(8);
 		expect(mockPi.tools.memory_write).toBeDefined();
 		expect(mockPi.tools.memory_forget).toBeDefined();
 		expect(mockPi.tools.memory_restore).toBeDefined();
@@ -2398,3 +2404,142 @@ describe("memory_forget tool", () => {
 		expect(secondRestore.content[0].text).toContain("already restored");
 	});
 });
+
+describe("pi-dream consolidation", () => {
+	const stamp = (iso: string, session = "test-session") => `<!-- ${iso} [${session}] -->`;
+
+	test("parseMemoryBlocks splits stamped entries and unstamped paragraphs", () => {
+		const content = [
+			"# Heading",
+			"",
+			stamp("2026-01-01 10:00:00"),
+			"first entry body",
+			"",
+			stamp("2026-02-01 10:00:00"),
+			"second entry body line one",
+			"second entry body line two",
+			"",
+			"unstamped paragraph one",
+			"",
+			"unstamped paragraph two",
+		].join("\n");
+		const blocks = parseMemoryBlocks(content);
+		expect(blocks.length).toBe(3); // "# Heading" + 2 stamped entries (trailing unstamped lines belong to last entry)
+		expect(blocks[1].meta).toContain("2026-01-01");
+		expect(blocks[2].body).toContain("second entry body line two");
+		expect(blocks[blocks.length - 1].body).toContain("unstamped paragraph two");
+	});
+
+	test("dreamSimilarity is high for near-duplicates and low for unrelated text", () => {
+		const a = "User prefers bun test over vitest for the memory package";
+		const b = "user prefers bun test over vitest for the memory package!";
+		const c = "Deploy pipeline runs on Fridays via GitHub Actions";
+		expect(dreamSimilarity(a, b)).toBeGreaterThan(0.9);
+		expect(dreamSimilarity(a, c)).toBeLessThan(0.2);
+	});
+
+	test("dreamAnalyze groups near-identical entries as duplicates", () => {
+		const body = "API key rotation happens monthly using rotate-keys script";
+		const content = [
+			stamp("2026-01-01 10:00:00"),
+			body,
+			"",
+			stamp("2026-03-01 10:00:00"),
+			`${body} (unchanged)`,
+		].join("\n");
+		const analysis = dreamAnalyze(content);
+		expect(analysis.duplicateGroups.length).toBe(1);
+		expect(dreamDropIndices(analysis)).toEqual([0]); // older copy dropped
+	});
+
+	test("dreamAnalyze flags older entries superseded by newer ones", () => {
+		const content = [
+			stamp("2026-01-01 10:00:00"),
+			"deployment target is staging.example.com with manual approval step before release",
+			"",
+			stamp("2026-06-01 10:00:00"),
+			"deployment target is staging.example.com with automated approval gate before release",
+		].join("\n");
+		const analysis = dreamAnalyze(content);
+		expect(analysis.duplicateGroups.length).toBe(0);
+		expect(analysis.superseded).toEqual([{ olderIndex: 0, newerIndex: 1 }]);
+	});
+
+	test("supersede detection requires minimum age gap", () => {
+		const content = [
+			stamp("2026-06-01 10:00:00"),
+			"database host is db-primary.internal port 5432 with connection pool of twenty",
+			"",
+			stamp("2026-06-03 10:00:00"),
+			"database host is db-replica.internal port 5432 with connection pool of twenty",
+		].join("\n");
+		const analysis = dreamAnalyze(content, { supersedeSimilarity: 0.5 });
+		// Only 2 days apart — below default min age gap; also below duplicate threshold.
+		expect(analysis.superseded.length).toBe(0);
+	});
+
+	test("dreamApply removes older copies, keeps newest, returns full removed blocks", () => {
+		const body = "release checklist lives in docs/release.md and is updated quarterly";
+		const content = [stamp("2026-01-01 10:00:00"), body, "", stamp("2026-05-01 10:00:00"), body].join("\n");
+		const result = dreamApply(content);
+		expect(result.removed.length).toBe(1);
+		expect(result.removed[0]).toContain("2026-01-01");
+		expect(result.keptContent).toContain("2026-05-01");
+		expect(result.keptContent).not.toContain("2026-01-01");
+	});
+
+	let dreamTools: Record<string, any>;
+
+	beforeEach(() => {
+		setupTmpDir();
+		const mockPi = createMockPi();
+		dreamTools = mockPi.tools;
+		registerExtension(mockPi.pi as any);
+	});
+
+	test("memory_dream registers with correct name", () => {
+		expect(dreamTools.memory_dream).toBeDefined();
+	});
+
+	test("memory_dream report mode leaves file untouched", async () => {
+		fs.writeFileSync(
+			path.join(tmpDir, "MEMORY.md"),
+			`${stamp("2026-01-01 10:00:00")}\ndup body shared words here\n\n${stamp("2026-02-01 10:00:00")}\ndup body shared words here\n`,
+			"utf-8",
+		);
+		const result = await dreamTools.memory_dream.execute("c1", { mode: "report" }, null, null, {});
+		expect(result.content[0].text).toContain("pi-dream report");
+		expect(fs.readFileSync(path.join(tmpDir, "MEMORY.md"), "utf-8")).toContain("dup body shared words"); // unchanged
+	});
+
+	test("memory_dream apply mode removes duplicates with recovery id", async () => {
+		fs.writeFileSync(
+			path.join(tmpDir, "MEMORY.md"),
+			`${stamp("2026-01-01 10:00:00")}\ndup body shared words here\n\n${stamp("2026-02-01 10:00:00")}\ndup body shared words here\n`,
+			"utf-8",
+		);
+		const result = await dreamTools.memory_dream.execute("c1", { mode: "apply" }, null, null, {});
+		expect(result.content[0].text).toContain("Removed 1 redundant entry");
+		expect(result.details.recoveryId).toBeDefined();
+		const remaining = fs.readFileSync(path.join(tmpDir, "MEMORY.md"), "utf-8");
+		expect(remaining).toContain("2026-02-01");
+		expect(remaining).not.toContain("2026-01-01");
+
+		// Recovery record must restore the removed entry.
+		const restored = await dreamTools.memory_restore.execute(
+			"c2",
+			{ recoveryId: result.details.recoveryId },
+			null,
+			null,
+			{},
+		);
+		expect(fs.readFileSync(path.join(tmpDir, "MEMORY.md"), "utf-8")).toContain("2026-01-01");
+		void restored;
+	});
+
+	test("memory_dream reports healthy memory when nothing removable", async () => {
+		fs.writeFileSync(path.join(tmpDir, "MEMORY.md"), "one unique fact about bun test runner config\n", "utf-8");
+		const result = await dreamTools.memory_dream.execute("c1", {}, null, null, {});
+		expect(result.content[0].text).toContain("Memory looks healthy");
+	});
+});