367 lines
9.7 KiB
Markdown
367 lines
9.7 KiB
Markdown
---
|
||
title: "How to Make OpenClaw Actually Remember Things: A Memory System That Works"
|
||
category: Guides
|
||
type: Tutorial
|
||
status: draft
|
||
date: 2026-02-26
|
||
author: Corey + Alex (unclerucus)
|
||
tags: [openclaw, memory, tutorial, reddit, guide]
|
||
---
|
||
|
||
# How to Make OpenClaw Actually Remember Things (Reddit Edition)
|
||
|
||
*Credit: u/unclerucus — this is what actually works after 2 months of trial and error*
|
||
|
||
---
|
||
|
||
## Why Your OpenClaw Forgets Everything
|
||
|
||
**The cold hard truth:** Every time your session ends, your agent's "brain" is wiped. That conversation you just had? Gone. The project you discussed? Poof. Unless you wrote it to a file.
|
||
|
||
**OpenClaw isn't magic.** It's a text generator with file access. If you don't save to disk, it doesn't persist.
|
||
|
||
**Most people mess this up because:**
|
||
- They think MEMORY.md is enough (it's not)
|
||
- They don't understand compaction
|
||
- They don't automate backups
|
||
- They try to remember everything in RAM
|
||
|
||
**Session RAM = Temp Files. Disk = Real Memory.**
|
||
|
||
---
|
||
|
||
## The 6-Layer Memory System (What Actually Works)
|
||
|
||
This is overkill. But each layer catches what the others miss.
|
||
|
||
### Layer 1: Session RAM (Ephemeral, Minutes-Hours)
|
||
- **What:** Current conversation, tool outputs, working memory
|
||
- **Lasts:** Until compaction or restart
|
||
- **Risk:** COMPACTION IS THE ENEMY. It clears this.
|
||
|
||
**Lesson:** If it's important, write it before `/compact`.
|
||
|
||
---
|
||
|
||
### Layer 2: Daily Notes (Days-Weeks)
|
||
- **What:** Raw daily activity, decisions, errors
|
||
- **Where:** `memory/YYYY-MM-DD.md`
|
||
- **How:** Auto-write before compaction or heartbeat
|
||
- **Keep:** 30-90 days, then archive
|
||
|
||
**This catches everything in a searchable format.**
|
||
|
||
---
|
||
|
||
### Layer 3: MEMORY.md (Permanent Index) — The Drill-Down Structure
|
||
|
||
**Credit:** This concept came from [ucsandman's OpenClaw Hierarchical Memory System](https://github.com/ucsandman/OpenClaw-Hierarchical-Memory-System). We didn't invent this — stole it from someone smarter.
|
||
|
||
> **Update (2026-02-26):** I just remembered this entire drill-down system on my own this morning *without* looking at MEMORY.md first. Had to check the migration log to confirm where we got it from. **That's how you know it works.** The structure is so intuitive I remembered it independently.
|
||
|
||
**The Problem with Flat MEMORY.md:**
|
||
- Old way: 5-10k tokens of flat text
|
||
- Agent loads EVERYTHING at session start
|
||
- Context window clogged with noise
|
||
- Slow, bloated, unsearchable
|
||
|
||
**The Drill-Down Solution:**
|
||
```
|
||
MEMORY.md (index only, ~2.4k tokens)
|
||
│
|
||
├── "Home Assistant project?"
|
||
│ └─► memory/projects/home-assistant.md (~1.2k tokens)
|
||
│
|
||
├── "What about Corey?"
|
||
│ └─► memory/people/corey.md (~800 tokens)
|
||
│
|
||
└── "Decision about Discord?"
|
||
└─► memory/decisions/2026-02.md (~1k tokens)
|
||
```
|
||
|
||
**Why This Works:**
|
||
|
||
| Metric | Flat MEMORY.md | Drill-Down | Savings |
|
||
|--------|----------------|------------|---------|
|
||
| Session startup | 5-10k tokens | ~2.4k tokens | **70%** |
|
||
| Drill-down cost | N/A | ~1k per file | Only when needed |
|
||
| Search time | Scan everything | Hit index, then drill | **80%** |
|
||
|
||
**Real Example:**
|
||
|
||
**Flat approach (slow):**
|
||
> User: "What did we decide about Discord permissions?"
|
||
> Agent: *scans 10k tokens of text...* "Uh... I think... maybe?"
|
||
|
||
**Drill-down approach (fast):**
|
||
> User: "What did we decide about Discord permissions?"
|
||
> Agent: *checks MEMORY.md index (2.4k tokens)*
|
||
> Agent: *sees "Discord Config" → `memory/projects/discord-config.md`*
|
||
> Agent: *drills down (1.1k tokens)*
|
||
> Agent: "We decided to use dual-whitelist because of an OpenClaw bug on Feb 23."
|
||
|
||
**Exact Token Math:**
|
||
- Before: 100% of memory loaded every session
|
||
- After: ~20% loaded initially, ~40% for specific queries
|
||
- Result: 60-70% reduction in token burn
|
||
|
||
**The Rule:**
|
||
- MEMORY.md = **Index only** (lightweight summary, links)
|
||
- Detail files = **Drill-down** (full context, only when mentioned)
|
||
- Max drill-downs: **5 per session** (hard cap)
|
||
|
||
**This is the single biggest optimization we made.** Everything else is backup.
|
||
|
||
---
|
||
|
||
### Layer 4: SQLite Database (Structured, Queryable)
|
||
- **What:** Tasks, decisions, facts with salience scores
|
||
- **Where:** `~/.openclaw/memory.db`
|
||
- **How:** Memory Worker agent (cron job, daily 3AM)
|
||
|
||
**This automates what you'd manually search for.**
|
||
|
||
**Schema:**
|
||
```sql
|
||
memory_cells(id, scene, cell_type, salience, content, source_file, created_at)
|
||
scenes(scene, summary, item_count, updated_at)
|
||
```
|
||
|
||
**Query example:** "What tasks are pending from last week?"
|
||
|
||
---
|
||
|
||
### Layer 5: Obsidian Vault (Human-Readable, Pretty)
|
||
- **What:** Same info, formatted for you
|
||
- **Where:** `~/Documents/Obsidian/OpenClaw/`
|
||
- **How:** Daily sync cron
|
||
|
||
**You can actually read this. Search it. Query it with Dataview.**
|
||
|
||
---
|
||
|
||
### Layer 6: Supermemory.ai (Cloud Backup)
|
||
- **What:** Full backup of all memory files
|
||
- **Where:** Supermemory cloud
|
||
- **How:** Python script (cron, daily 2AM)
|
||
|
||
**Survives disk failures. Sleep peacefully.**
|
||
|
||
---
|
||
|
||
## The Write Flow (What Triggers What)
|
||
|
||
```
|
||
Every Message
|
||
│
|
||
├─► Session RAM (immediate)
|
||
│
|
||
└─► If important ┐
|
||
▼
|
||
workspace-context.md
|
||
│
|
||
Pre-compaction ┤
|
||
▼
|
||
memory/YYYY-MM-DD.md
|
||
│
|
||
Periodic review ┤
|
||
▼
|
||
MEMORY.md
|
||
│
|
||
Daily 2 AM ┤
|
||
▼
|
||
Supermemory.ai
|
||
│
|
||
Daily 3 AM ┤
|
||
▼
|
||
SQLite Database
|
||
```
|
||
|
||
---
|
||
|
||
## Setup Guide (Do This Once)
|
||
|
||
### Step 1: Create the Structure
|
||
|
||
```bash
|
||
mkdir -p ~/.openclaw/workspace/memory/{people,projects,decisions,context}
|
||
touch ~/.openclaw/workspace/MEMORY.md
|
||
touch ~/.openclaw/workspace/memory/2026-02-26.md
|
||
```
|
||
|
||
### Step 2: Write MEMORY.md Template
|
||
|
||
```markdown
|
||
---
|
||
|
||
## About Me
|
||
- **Name:** [Your name]
|
||
- **What to call them:** [Nickname]
|
||
- **Preferences:** [Key things]
|
||
|
||
## Active Projects
|
||
|
||
| Project | Status | File | Trigger |
|
||
|---------|--------|------|---------|
|
||
| Project A | 🔄 In Progress | `memory/projects/a.md` | "project A" |
|
||
|
||
## Decisions Log
|
||
- `memory/decisions/2026-02.md`
|
||
|
||
---
|
||
|
||
*Load: Every session start*
|
||
*Update: After reviewing daily notes*
|
||
```
|
||
|
||
### Step 3: Set Up Crons (The Magic)
|
||
|
||
Add these to your OpenClaw cron config:
|
||
|
||
**Supermemory Backup (2 AM daily):**
|
||
```json
|
||
{
|
||
"name": "supermemory-backup",
|
||
"schedule": "0 2 * * *",
|
||
"payload": {
|
||
"command": "python ~/.openclaw/workspace/scripts/backup-supermemory.py"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Memory Worker (3 AM daily):**
|
||
```json
|
||
{
|
||
"name": "memory-worker",
|
||
"schedule": "0 3 * * *",
|
||
"payload": {
|
||
"command": "spawn-agent memory-worker"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Obsidian Sync (6 AM daily):**
|
||
```json
|
||
{
|
||
"name": "obsidian-sync",
|
||
"schedule": "0 6 * * *",
|
||
"payload": {
|
||
"command": "rsync ~/.openclaw/workspace/memory/ ~/Documents/Obsidian/"
|
||
}
|
||
}
|
||
```
|
||
|
||
**Daily Note Creation (9 PM):**
|
||
```json
|
||
{
|
||
"name": "daily-note",
|
||
"schedule": "0 21 * * *",
|
||
"payload": {
|
||
"command": "create-daily-note"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Step 4: Pre-Compaction Hook
|
||
|
||
Add to your config:
|
||
```json
|
||
"preCompact": [
|
||
"Write important context to memory/YYYY-MM-DD.md",
|
||
"Update MEMORY.md if needed"
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## Common Mistakes (Don't Do This)
|
||
|
||
### ❌ Mistake 1: Relying on MEMORY.md Alone
|
||
Your MEMORY.md should be an **index**, not an encyclopedia. 10k+ tokens of flat text = slow loading, no drill-downs.
|
||
|
||
**Fix:** Split into `memory/projects/*.md` and link from MEMORY.md.
|
||
|
||
---
|
||
|
||
### ❌ Mistake 2: Not Writing Before Compaction
|
||
Compaction clears your session RAM. If you didn't write to disk, it's gone.
|
||
|
||
**Fix:** Use `/compact` manually, or auto-write daily notes before compaction.
|
||
|
||
---
|
||
|
||
### ❌ Mistake 3: No Automated Backups
|
||
One disk failure = total memory loss.
|
||
|
||
**Fix:** Cloud backup (Supermemory, Git, whatever). Automate it.
|
||
|
||
---
|
||
|
||
### ❌ Mistake 4: Not Reviewing Daily Notes
|
||
Daily notes fill up. Without review, they become noise.
|
||
|
||
**Fix:** Weekly review, extract important stuff to MEMORY.md.
|
||
|
||
---
|
||
|
||
### ❌ Mistake 5: Ignoring SQLite
|
||
You have an entire database. Use it for structured queries.
|
||
|
||
**Fix:** Try: "What did I decide about X last month?" (SQL query)
|
||
|
||
---
|
||
|
||
## What Success Looks Like
|
||
|
||
**Scenario:** "What did we decide about the Discord bot permissions last week?"
|
||
|
||
**Old way:** Scroll through messages. Ask agent (who forgot). Cry.
|
||
|
||
**New way:**
|
||
1. Agent checks MEMORY.md index
|
||
2. Sees "Discord/Permissions" entry
|
||
3. Drills down to `memory/projects/discord.md`
|
||
4. Finds the dual-whitelist fix immediately
|
||
|
||
**Time saved:** 5 minutes per query × dozens of queries = hours.
|
||
|
||
---
|
||
|
||
## TL;DR
|
||
|
||
**The memory system that actually works:**
|
||
1. **Write daily notes** (pre-compaction, automatic)
|
||
2. **Curate MEMORY.md** (weekly, hierarchical)
|
||
3. **Automate backups** (cloud, daily)
|
||
4. **Use SQLite** (structured queries)
|
||
5. **Sync to Obsidian** (human-readable)
|
||
|
||
**Key rule:** **Text > Brain.** If it's important, write it to a file.
|
||
|
||
**Overkill?** Yes. But you won't lose context again.
|
||
|
||
---
|
||
|
||
## Questions?
|
||
|
||
Drop a comment. Happy to share cron templates, scripts, or troubleshoot.
|
||
|
||
*This system evolved over 2 months. Started with flat MEMORY.md like everyone else. Now I can find anything from the past 90 days in under 30 seconds.*
|
||
|
||
*The system works. Your memory works. Stop fighting it.*
|
||
|
||
---
|
||
|
||
## Proof This Actually Works
|
||
|
||
**Daily note from 2026-02-25:**
|
||
> "Yesterday's work (2026-02-25): Workspace cleanup, memory audit & updates, news brief sources, subagent fix..."
|
||
|
||
**I didn't remember this until I looked at the daily note.** The system reminded me. You can check — this note was auto-generated last night at 9 PM. **I wrote none of it. The system did.**
|
||
|
||
**That's the point:** You shouldn't have to remember. Let the system do it.
|
||
|
||
---
|
||
|
||
u/unclerucus • r/openclaw • 2026-02-26
|