From 392379efad04466f31cd1fe465e8a8c1a00c3e19 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Thu, 16 Oct 2025 00:29:10 -0700
Subject: [PATCH] Document compaction feature in README

Added light documentation for bd compact command:
- Feature list entry: Memory decay
- Usage section with examples
- Requirements and eligibility criteria
- Emphasizes intentional graceful decay vs reversible compression
---
 README.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 5eaf3d5d..b5581d4d 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,7 @@ Agents report that they enjoy working with Beads, and they will use it spontaneo
 - 🎨 **Beautiful CLI** - Colored output for humans, JSON for bots
 - 💾 **Full audit trail** - Every change is logged
 - ⚡ **High performance** - Batch operations for bulk imports (1000 issues in ~950ms)
+- 🗜️ **Memory decay** - Semantic compaction gracefully reduces old closed issues
 
 ## Installation
 
@@ -426,6 +427,38 @@ bd stats
 bd ready --json
 ```
 
+### Compaction (Memory Decay)
+
+Beads can semantically compress old closed issues to keep the database lightweight. This is agentic memory decay - the database naturally forgets details over time while preserving essential context.
+
+```bash
+# Preview what would be compacted
+bd compact --dry-run --all
+
+# Show compaction statistics
+bd compact --stats
+
+# Compact all eligible issues (30+ days closed, no open dependents)
+bd compact --all
+
+# Compact specific issue
+bd compact --id bd-42
+
+# Force compact (bypass eligibility checks)
+bd compact --id bd-42 --force
+```
+
+Compaction uses Claude Haiku to semantically summarize issues, achieving ~70-80% space reduction. The original content is permanently discarded - this is intentional graceful decay, not reversible compression.
+
+**Requirements:**
+- Set `ANTHROPIC_API_KEY` environment variable
+- Cost: ~$1 per 1,000 issues compacted
+
+**When issues are eligible:**
+- Status: closed
+- Age: 30+ days since closed
+- No open dependents (blocking other work)
+
 ## Database Discovery
 
 bd automatically discovers your database in this order: