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:
CODEBLOCK0

Quick Start

1. Set Up Directory Structure

CODEBLOCK1

2. Initialize State Files

Copy templates from assets/:
CODEBLOCK2

3. Install Scripts

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

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:
CODEBLOCK4

Core Scripts

ensuredailylog.py

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

CODEBLOCK5

appendtodaily.py

Append events to today's daily log programmatically.

CODEBLOCK6

rollup-daily.py

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

CODEBLOCK7

rollup-weekly.py

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

CODEBLOCK8

rollup-monthly.py

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

CODEBLOCK9

verifymemoryintegrity.py

Check memory system integrity and detect anomalies.

CODEBLOCK10

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 INLINECODE4

3. Weekly Rollup (23:59 every Sunday)

Compress to themes, trajectory, milestones → append to INLINECODE5

4. Monthly Rollup (Last day of month)

Distill major themes, lessons learned → update INLINECODE6

5. Timeless Facts (Anytime)

Extract facts that recur 3+ times → store in INLINECODE7

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. 1. TODAY - INLINECODE8
2. THIS WEEK - INLINECODE9
3. THIS MONTH - INLINECODE10
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. 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:
CODEBLOCK11

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: INLINECODE13

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

CODEBLOCK12

Advanced Usage

Custom Rollup Schedule

Modify cron expressions in references/cron-setup.md

Sticky Notes Categories

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

Manual Rollup

Run rollup scripts manually anytime: CODEBLOCK14

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