189 lines
6.9 KiB
Markdown
189 lines
6.9 KiB
Markdown
---
|
|
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*
|