Skill: bugmaker2/fractal-memory (version 1.0.0)

--- 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 ```bash mkdir -p memory/diary/{2026/{daily,weekly,monthly},sticky-notes/{workflows,apis,commands,facts}} ``` ### 2. Initialize State Files Copy templates from `assets/`: ```bash 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: ```bash 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: - **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: ```markdown ## 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. ```bash python3 scripts/ensure_daily_log.py ``` ### append_to_daily.py Append events to today's daily log programmatically. ```bash 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. ```bash 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. ```bash 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. ```bash python3 scripts/rollup-monthly.py ``` ### verify_memory_integrity.py Check memory system integrity and detect anomalies. ```bash 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: ```bash python3 scripts/verify_memory_integrity.py ``` ## Migration Migrating from existing memory systems? See [references/migration-guide.md](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 ```bash 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/`: ```bash mkdir memory/diary/sticky-notes/my-category ``` ### Manual Rollup Run rollup scripts manually anytime: ```bash 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 - **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

path: assets/heartbeat-state.json

Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)