johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add comprehensive compaction documentation

Browse Source 
- Updated README.md with Tier 1/2 info, restore command, cost analysis
- Created COMPACTION.md with full guide covering:
  - How compaction works (architecture, two-tier system)
  - CLI reference and examples
  - Eligibility rules and configuration
  - Cost analysis with detailed tables
  - Automation examples (cron, workflows)
  - Safety, recovery, and troubleshooting
  - FAQ and best practices
- Added examples/compaction/ with 3 scripts:
  - workflow.sh: Interactive compaction workflow
  - cron-compact.sh: Automated monthly compaction
  - auto-compact.sh: Smart threshold-based compaction
  - README.md: Examples documentation

Closes bd-265

Amp-Thread-ID: https://ampcode.com/threads/T-8113e88e-1cd0-4a9e-b581-07045a3ed31e
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-10-16 01:09:48 -07:00
parent 6786d68365
commit 54469936a7
7 changed files with 913 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

@@ -446,18 +446,30 @@ bd compact --id bd-42
# Force compact (bypass eligibility checks)
bd compact --id bd-42 --force
# Restore from snapshot (full recovery)
bd compact --restore bd-42
# Tier 2 ultra-compression (90+ days, 95% reduction)
bd compact --tier 2 --all
```
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.
Compaction uses Claude Haiku to semantically summarize issues:
- **Tier 1**: 70-80% space reduction (30+ days closed)
- **Tier 2**: 90-95% space reduction (90+ days closed, rarely referenced)
**Requirements:**
- Set `ANTHROPIC_API_KEY` environment variable
- Cost: ~$1 per 1,000 issues compacted
- Cost: ~$1 per 1,000 issues compacted (Haiku pricing)
**When issues are eligible:**
**Eligibility:**
- Status: closed
- Age: 30+ days since closed
- No open dependents (blocking other work)
- Tier 1: 30+ days since closed, no open dependents
- Tier 2: 90+ days since closed, rarely referenced in commits/issues
**Safety:** Full snapshots are kept - you can restore any compacted issue to its original state.
See [COMPACTION.md](COMPACTION.md) for detailed documentation, cost analysis, and automation examples.
## Database Discovery