---
title: OpenClaw Memory System
category: OpenClaw
type: Architecture/Documentation
status: active
date: 2026-02-16
last_updated: 2026-02-23
source_file: memory_system_architecture.md
tags: [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:**
  ```sql
  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*