# 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**.