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
191 lines
6.9 KiB
Markdown
191 lines
6.9 KiB
Markdown
# 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
|
||
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.md` is **preserved exactly as-is** — nothing is changed or moved
|
||
- `MEMORY.md` gets **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
|
||
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 `.md` files in `memory/` 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
|
||
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 `memorySearch` config
|
||
- 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
|
||
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:
|
||
1. **Having a place to write** (`memory/YYYY-MM-DD.md`)
|
||
2. **Having instructions to follow** (the AGENTS.md memory habits)
|
||
3. **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
|
||
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**.
|