fractal-memory

自动分层内存压缩系统，通过每日→每周→每月→核心压缩来防止上下文溢出。当您需要（1）无需手动管理的长期内存管理，（2）具有注意力优化层次结构的令牌高效上下文加载，（3）防止累积历史记录导致会话膨胀，（4）通过 cron 自动内存汇总，或（5）从平面日常文件迁移到结构化内存时使用。针对内存架构问题、上下文溢出问题或设置持久代理内存而激活。

## 概述（中文）

自动分层内存压缩系统，通过每日→每周→每月→核心压缩来防止上下文溢出。当您需要（1）无需手动管理的长期内存管理，（2）具有注意力优化层次结构的令牌高效上下文加载，（3）防止累积历史记录导致会话膨胀，（4）通过 cron 自动内存汇总，或（5）从平面日常文件迁移到结构化内存时使用。针对内存架构问题、上下文溢出问题或设置持久代理内存而激活。

## 原文

# 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