Memory Lifecycle

Structured memory management that makes agents smarter over time — not through code, but through disciplined capture, consolidation, and distillation of context.

Philosophy

Memory management is not about saving tokens. It's about crafting high-signal context that makes a powerful LLM more effective.

Core principles:

1. Distill, don't summarise. Output should be better than raw input — structured, actionable, reasoning preserved
2. Preserve decisions and reasoning. "We chose X because Y" > "We did X"
3. Never compress away specifics. Phone numbers, dates, prices are facts, not fluff
4. Daily files are immutable. They're the audit trail — add headers, never edit content
5. Each tier builds upward. Raw → structured → refined → wisdom
6. Archives are a library, not a bin. Full narratives, not one-liners

Setup

Run the setup script to scaffold memory files and create cron jobs:

python3 scripts/setup.py

The script will:

1. Create structured memory files (people.md, decisions.md, lessons.md, commitments.md)
2. Add a ## Recent working memory buffer to MEMORY.md
3. Create four cron jobs (nightly, weekly, monthly, yearly)
4. Add memory micro-attention tasks to HEARTBEAT.md

Run with --dry-run to preview changes without applying them. Run with --agent <id> to target a specific agent (default: main).

The Five Tiers

Tier 1: Heartbeat Micro-Attention (every ~30 min)

Added to the agent's HEARTBEAT.md. Quick focused pass — capture, promote, tag:

1. Capture: Ensure notable events are in today's memory/YYYY-MM-DD.md
2. Promote: Session-critical items (new appointment, key decision) → MEMORY.md → ## Recent
3. Tag: Mark daily file entries with [decision], [lesson], [person] for the nightly cycle
4. Monitor: Check nightly cycle health — if it errored, fix and re-run. Don't just report.

Tier 2: Nightly "Sleep Cycle" (cron, ~2:00 AM local)

Read references/nightly-prompt.md for the full cron prompt.

• Read today's daily file end-to-end
• Write a 2-3 line "day essence" header
• Promote items to structured files (people → people.md, decisions → decisions.md, etc.)
• Update MEMORY.md if active project state changed
• Clear processed items from ## Recent

Rules: Never edit daily file content. Never remove from MEMORY.md unless completed AND archived.

Tier 3: Weekly Reflection (cron, Sunday ~3:00 AM local)

Read references/weekly-prompt.md for the full cron prompt.

• Read all 7 daily files from the past week
• Spot patterns: repeated topics, unresolved threads
• Refine MEMORY.md — improve structure and language (not strip content)
• Review commitments, contacts, decisions for staleness
• Write a "week in review" in Sunday's daily file

Tier 4: Monthly Deep Clean (cron, 1st of month ~4:00 AM local)

Read references/monthly-prompt.md for the full cron prompt.