obsidian-vault/OpenClaw/Memory System.md

title, category, type, status, date, last_updated, source_file, tags

title	category	type	status	date	last_updated	source_file	tags
OpenClaw Memory System	OpenClaw	Architecture/Documentation	active	2026-02-16	2026-02-23	memory_system_architecture.md	openclaw memory architecture system-design data-flow sqlite

OpenClaw Memory System

Source of truth for how information flows and persists

Original File: memory_system_architecture.md
Created: Evening of major OpenClaw upgrade (2026-02-16)

---

Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                         INFORMATION FLOW                                     │
└─────────────────────────────────────────────────────────────────────────────┘

    User Conversation
           │
           ▼
┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   ME (Main Agent)   │────▶│   Memory Worker     │────▶│   SQLite Database   │
│   (Real-time)       │     │   (Daily 3 AM)      │     │   (Structured)      │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
           │                           │                           │
           │                           │                           │
           ▼                           ▼                           ▼
┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   Daily Notes       │     │   Query Interface   │     │   Stats/Search      │
│   (memory/*.md)     │◄────│   (On Demand)      │◄────│   (SQL/FTS)        │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
           │
           ▼
┌─────────────────────┐
│   MEMORY.md         │
│   (Curated)         │
└─────────────────────┘
           │
           ▼
┌─────────────────────┐
│   Supermemory.ai    │
│   (Cloud Backup)    │
└─────────────────────┘

---

Storage Layers (6 Total)

Layer	Speed	Persistence	Purpose
1. Session RAM	⚡ Fastest	Minutes-hours	Working conversation context
2. Workspace Context	📝 Fast	~24 hours	Session bridge between channels
3. Daily Notes	📄 Medium	30-90 days	Raw daily activity
4. MEMORY.md	🧠 Slow	Permanent	Curated important info
5. SQLite DB	📊 Query	Permanent	Structured data with FTS
6. Supermemory.ai	🌐 Cloud	Permanent	Full cloud backup

---

Key Components

1. Session RAM

• What: Current conversation context
• Writes: Real-time
• Survives: ❌ Crash ❌ Restart
• Size: ~100K-250K tokens
• Risk: Lost on compaction

2. Daily Notes (memory/*.md)

• What: Raw daily activity, decisions, errors
• Writes: Pre-compaction flush
• Survives: ✅ Everything
• Retention: 30-90 days

3. MEMORY.md

• What: Curated long-term memory
• Writes: Manual review
• Survives: ✅ Everything
• Retention: Permanent

4. SQLite Database (~/.openclaw/memory.db)

• What: Structured tasks, decisions, facts
• Writes: Daily 3 AM (Memory Worker cron)
• Schema:

  memory_cells: id, scene, cell_type, salience, content, source_file, created_at
  scenes: scene, summary, item_count, updated_at
  memory_fts: full-text search index
  

• Survives: ✅ File-based
• Retention: Permanent

5. Supermemory.ai

• What: Full cloud backup
• Writes: Daily 2 AM (Python script)
• Survives: ✅ Disk failure
• Retention: Cloud dependent

6. Workspace Context (workspace-context.md)

• What: Current conversation bridge
• Writes: Continuous
• Survives: ✅ Channel switch
• Cleared: Nightly (~11 PM)

---

Cron Jobs (Memory System)

Job	Time	Purpose
Supermemory Backup	2:00 AM	Cloud backup of all memory files
Cron Cleanup	3:00 AM	Remove finished one-shot jobs
Memory Worker	3:04 AM	Extract to SQLite database

---

Key Principles

1. Text > Brain — Files persist, sessions don't
2. Daily notes = raw, MEMORY.md = curated — Filter noise from signal
3. Worker = automated structuring — Don't manually organize everything
4. Hybrid = best of both — Human-readable + machine-queryable
5. Multiple backups — Local + cloud + structured

---

Access Patterns

Main Agent Reads:

• MEMORY.md — Every session (core identity, prefs)
• USER.md — Every session (who Corey is)
• SOUL.md — Every session (how to behave)
• workspace-context.md — Every session (current state)
• memory/*.md — During heartbeats (recent context)
• SQLite DB — On demand (structured queries)

Memory Worker Reads:

• IDENTITY.md — Daily 3 AM
• SOUL.md — Daily 3 AM
• HEARTBEAT.md — Daily 3 AM (instructions)
• memory/YYYY-MM-DD.md — Daily 3 AM (content to extract)
• Writes to SQLite DB

---

Failure Recovery

Scenario	Survives	Lost	Recovery
Session Crash	Files	Session RAM	Read files, reconstruct
Gateway Restart	All files	Session/cron state	Restart, verify jobs
Disk Failure	Supermemory	Local files + DB	Restore from cloud

---

File Locations

File	Location
MEMORY.md	~/.openclaw/workspace/MEMORY.md
Daily Notes	~/.openclaw/workspace/memory/YYYY-MM-DD.md
SQLite DB	~/.openclaw/memory.db
Workspace Context	~/.openclaw/workspace/workspace-context.md
Architecture Doc	Projects/Memory System/Memory System Architecture.md (Obsidian)

---

Related

• Discord Config — Discord/OpenClaw configuration
• Projects/Daily Notes/YYYY-MM-DD — Daily notes structure
• Dataview Query Examples — Query the SQLite database

---

This is the source of truth for Corey's OpenClaw memory system.
Created: 2026-02-16 | Last Updated: 2026-02-23