cb28c2649f
One-command persistent memory for Clawdbot. Prevents context amnesia during compaction with: - Two-layer memory: Markdown source of truth + SQLite vector search - Pre-compaction flush to save context before it's lost - Semantic search across all memory files - Daily logs, research intel, and project tracking templates - Interactive installer with dry-run and uninstall support
6.9 KiB
Migration Guide
How to move to the Clawdbot Memory System from your current setup.
Scenario 1: No Memory System → Full System
You have: A fresh Clawdbot install, or one where you never set up memory files.
What happens:
- The installer creates
memory/directory with templates - Configures vector search in
clawdbot.json - Adds memory habits to
AGENTS.md - Creates today's first daily log
What to do:
bash <(curl -sL https://raw.githubusercontent.com/BusyBee3333/clawdbot-memory-system/main/install.sh)
That's it. You're done.
After install:
Your agent will start writing daily logs automatically. Give it a day or two and you'll see memory/ filling up with daily context.
Scenario 2: Existing MEMORY.md Only → Full System
You have: A MEMORY.md file in your workspace with curated long-term memories.
What happens:
- Your
MEMORY.mdis preserved exactly as-is — nothing is changed or moved MEMORY.mdgets indexed into vector search alongside the new daily logs- The installer adds the
memory/directory for daily logs (separate from your curated MEMORY.md) - Your agent can now search both the curated file AND daily logs semantically
What changes:
| Before | After |
|---|---|
| Agent reads MEMORY.md at session start | Agent reads MEMORY.md at session start AND searches it semantically |
| No daily logs | Daily logs in memory/YYYY-MM-DD.md |
| No search across history | Semantic search across all memory files |
| Context lost on compaction | Pre-compaction flush saves context |
What to do:
bash <(curl -sL https://raw.githubusercontent.com/BusyBee3333/clawdbot-memory-system/main/install.sh)
The installer detects your existing MEMORY.md and includes it in the index.
Best practice after migration:
Keep using MEMORY.md for curated, high-signal facts (preferences, key decisions, identity). Use memory/YYYY-MM-DD.md for day-to-day session logs. They complement each other:
MEMORY.md= "who I am and what matters" (manually curated)memory/*.md= "what happened and when" (written by the agent during sessions)
Scenario 3: Existing Daily Logs → Full System
You have: A memory/ directory with some daily log files already.
What happens:
- All your existing
.mdfiles inmemory/are preserved - They all get indexed into vector search
- Templates are added (won't overwrite existing files with the same name)
- Config and AGENTS.md are patched
What to do:
bash <(curl -sL https://raw.githubusercontent.com/BusyBee3333/clawdbot-memory-system/main/install.sh)
The installer will show you how many existing files it found:
ℹ Found 23 existing memory files in /path/to/workspace/memory
These will be preserved and indexed
Scenario 4: Manual Memory Search Setup → This System
You have: You've already configured memorySearch in clawdbot.json manually.
What happens:
- The installer detects your existing
memorySearchconfig - It asks if you want to overwrite or keep your current settings
- If you keep: only templates, AGENTS.md patch, and re-index are done
- If you overwrite: your old config is backed up first
What to do:
bash <(curl -sL https://raw.githubusercontent.com/BusyBee3333/clawdbot-memory-system/main/install.sh)
When prompted about existing config, choose based on your preference.
How Pre-Compaction Flush Prevents Amnesia
This is the most important piece for people who've been losing context.
The Problem
Session starts → You work for hours → Context fills up →
Compaction triggers → Old messages summarized/removed →
Agent has a vague summary but lost all the details →
"What were we working on?" → Agent has no idea 😞
The Solution
Session starts → You work for hours → Context fills up →
│
▼
┌───────────────┐
│ Pre-compaction │
│ flush triggers │
└───────┬───────┘
│
▼
Agent writes ALL
important context to
memory/YYYY-MM-DD.md
│
▼
Compaction happens
(details removed from
context window)
│
▼
But memories are ON DISK
and INDEXED for search
│
▼
"What were we working on?"
→ Agent searches memory →
Full context restored 🎉
How It Works Technically
Clawdbot has a built-in feature: compaction.memoryFlush. When enabled (it is by default), it sends a silent prompt to the agent before compaction saying "store durable memories now." The agent then writes everything important to disk.
The memory system makes this work by:
- Having a place to write (
memory/YYYY-MM-DD.md) - Having instructions to follow (the AGENTS.md memory habits)
- Having a way to retrieve (vector search index)
Without all three, the flush either doesn't happen, writes to nowhere useful, or the agent can't find what it wrote later.
Storage Layout After Migration
~/.clawdbot/workspace/
├── AGENTS.md ← Updated with memory habits
├── MEMORY.md ← Preserved if it existed
├── memory/
│ ├── 2026-01-15.md ← Your existing logs (preserved)
│ ├── 2026-01-16.md ← ...
│ ├── 2026-02-10.md ← Today's log (created by installer)
│ ├── TEMPLATE-daily.md ← Reference template
│ ├── TEMPLATE-research-intel.md ← Reference template
│ └── TEMPLATE-project-tracking.md ← Reference template
└── ...
Rollback
If anything goes wrong, the installer creates backups:
clawdbot.json.pre-memory-backup— your original config- To restore:
cp ~/.clawdbot/clawdbot.json.pre-memory-backup ~/.clawdbot/clawdbot.json
Or use the uninstaller:
bash <(curl -sL https://raw.githubusercontent.com/BusyBee3333/clawdbot-memory-system/main/install.sh) --uninstall
This removes config changes but never deletes your memory files.