fractal-memory

name

fractal-memory

description

Automated hierarchical memory compression system that prevents context overflow through daily→weekly→monthly→core compression. Use when you need (1) long-term memory management without manual curation, (2) token-efficient context loading with attention-optimized hierarchy, (3) preventing session bloat from accumulated history, (4) automated memory rollups via cron, or (5) migrating from flat daily files to structured memory. Activates for memory architecture questions, context overflow issues, or setting up persistent agent memory.

Fractal Memory System

Automated hierarchical memory compression that prevents context overflow. Like human sleep, compress raw experience into patterns, patterns into principles—keeping essence while managing scale.

Philosophy

Memory is not accumulation — it is compression with intention.

Each layer compresses the one below without losing essence:

Conversation → Daily → Weekly → Monthly → Core Memory
                ↓
         Timeless Facts (sticky-notes)

Quick Start

1. Set Up Directory Structure

mkdir -p memory/diary/{2026/{daily,weekly,monthly},sticky-notes/{workflows,apis,commands,facts}}

2. Initialize State Files

Copy templates from assets/:

cp assets/rollup-state.json memory/
cp assets/heartbeat-state.json memory/

3. Install Scripts

Copy all scripts from scripts/ to your workspace scripts/ directory:

cp scripts/*.py ~/.openclaw/workspace/scripts/
chmod +x ~/.openclaw/workspace/scripts/*.py

4. Set Up Cron Jobs

See references/cron-setup.md for detailed cron configuration.

Quick version:

• Daily rollup: 23:59 every day
• Weekly rollup: 23:59 every Sunday
• Monthly rollup: 23:59 last day of month

5. Update Session Startup

Add to your AGENTS.md:

## Every Session

1. Read `SOUL.md`
2. Read `USER.md`
3. Read `memory/diary/YYYY/daily/YYYY-MM-DD.md` (today + yesterday)
4. **If in MAIN SESSION**: Also read `MEMORY.md`

**Context loading order:** TODAY → THIS WEEK → THIS MONTH → MEMORY.md

Core Scripts

ensure_daily_log.py

Creates today's daily log if it doesn't exist. Run this in heartbeats or at session start.

python3 scripts/ensure_daily_log.py

append_to_daily.py

Append events to today's daily log programmatically.

python3 scripts/append_to_daily.py "Event description"

rollup-daily.py

Compress today's diary into this week's summary. Runs automatically at 23:59 daily.

python3 scripts/rollup-daily.py

rollup-weekly.py

Compress this week's summary into this month's summary. Runs automatically at 23:59 every Sunday.

python3 scripts/rollup-weekly.py

rollup-monthly.py

Distill this month's summary into MEMORY.md. Runs automatically at 23:59 on the last day of each month.

python3 scripts/rollup-monthly.py

verify_memory_integrity.py

Check memory system integrity and detect anomalies.

python3 scripts/verify_memory_integrity.py

Information Flow

1. During Conversation (Real-time)

Write to memory/diary/YYYY/daily/YYYY-MM-DD.md immediately. Don't rely on memory—write it down.

2. Daily Rollup (23:59 every day)

Extract patterns, decisions, key events → append to memory/diary/YYYY/weekly/YYYY-Wnn.md

3. Weekly Rollup (23:59 every Sunday)

Compress to themes, trajectory, milestones → append to memory/diary/YYYY/monthly/YYYY-MM.md

4. Monthly Rollup (Last day of month)

Distill major themes, lessons learned → update MEMORY.md

5. Timeless Facts (Anytime)

Extract facts that recur 3+ times → store in memory/diary/sticky-notes/{category}/

Key Principles

1. Write Everything Immediately

"Mental notes" don't survive session restarts. Files do.

2. Compress, Don't Accumulate

Files that grow forever become unreadable. Extract patterns, discard noise.

3. Curate Ruthlessly

Not everything deserves to persist. Keep what defines you, release what doesn't.

4. Automate Discipline

Scripts handle rollups so you don't have to remember.

Context Loading Strategy

Load memory in this order for attention optimization:

1. TODAY - memory/diary/YYYY/daily/YYYY-MM-DD.md
2. THIS WEEK - memory/diary/YYYY/weekly/YYYY-Wnn.md
3. THIS MONTH - memory/diary/YYYY/monthly/YYYY-MM.md
4. MEMORY.md - Core index (main session only)
5. Relevant sticky-notes - As needed

Why this order? Primacy + recency optimization. Most recent first, highest level early.

Security Considerations

Memory systems create attack surface. The system includes:

1. Provenance tracking - Timestamps and metadata
2. Integrity verification - verify_memory_integrity.py detects tampering
3. Anomaly detection - Flags unusual patterns

Run integrity checks periodically:

python3 scripts/verify_memory_integrity.py

Migration

Migrating from existing memory systems? See references/migration-guide.md for:

• Flat daily files → Fractal structure
• Manual MEMORY.md only → Automated system
• Other hierarchical systems → Fractal memory

Troubleshooting

Daily log not created

Run ensure_daily_log.py manually or add to heartbeat checks.

Rollup failed

Check cron job runs: cron(action="runs", jobId="<job-id>")

Context still overflowing

• Verify rollups are running (check memory/rollup-state.json)
• Manually run rollup scripts to catch up
• Check MEMORY.md isn't growing too large (should be curated, not accumulated)

Scripts not executable

chmod +x scripts/*.py

Advanced Usage

Custom Rollup Schedule

Modify cron expressions in references/cron-setup.md

Sticky Notes Categories

Add custom categories in memory/diary/sticky-notes/:

mkdir memory/diary/sticky-notes/my-category

Manual Rollup

Run rollup scripts manually anytime:

python3 scripts/rollup-daily.py
python3 scripts/rollup-weekly.py
python3 scripts/rollup-monthly.py

Architecture Details

For deep dive into system design, philosophy, and implementation details, see references/architecture.md.

References

• Deva's Fractal Memory v1.0.0 - Original inspiration
• Arcturus's Memory is Resurrection - Philosophical foundation
• Logi's Memory Architecture as Agency - Agency perspective

---

"What grows from chaos is structure. What emerges from structure is memory. What persists through memory is self." — Deva