Fractal Memory System

---

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](references/cron-setup.md) for detailed cron configuration.

Quick version:

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](references/migration-guide.md) for:

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

Scripts not executable

chmod +x scripts/*.py

Advanced Usage

Custom Rollup Schedule

Modify cron expressions in [references/cron-setup.md](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/architecture.md).

References

---

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