Ultra Agent Upgrade

README

# Ultra Agent Upgrade

A complete upgrade suite for OpenClaw agents: nightly backup + revival system,
fractal branching memory (Mandelbrot-based), Active Memory integration, and
SwiftBar menu bar monitor.

Zero personal data. Any agent can install this for any user.

<!-- SEO: openclaw ai agent upgrade, ai assistant memory system, fractal branching memory,
mandelbrot memory, ai agent backup, openclaw backup revival, ai agent persistent memory,
cross-session memory ai, active memory plugin, swiftbar menu bar monitor, launchd backup,
ai agent disaster recovery, personal ai assistant, chatgpt claude openclaw, llm memory,
ai automation macos, digital assistant upgrade, agent framework -->

---

## Requirements

- **macOS** (required for Keychain, launchd, SwiftBar)
- **OpenClaw** installed and running
- **Python 3.10+**
- **Homebrew** (`brew`) — for SwiftBar installation
- **Ollama** with an embedding model (recommended: `nomic-embed-text`) — for FBM
  - Alternatively, any OpenClaw-supported embedding provider works (OpenAI, Gemini, etc.)

### Verify requirements before starting

Run this block in Terminal. Each command should succeed:

```bash
# macOS — must be 12 (Monterey) or newer
sw_vers -productVersion

# OpenClaw — must show a version number
openclaw --version

# Python — must be 3.10 or higher
python3 --version

# Homebrew
brew --version

# Ollama (optional — only needed for FBM coordinate generation)
ollama --version 2>/dev/null && echo "Ollama OK" || echo "Ollama not found — FBM will work but coordinate embedding is disabled"
```

**If `openclaw` is not found:** OpenClaw may not be in your shell's PATH. Try:
```bash
# Common fix — add to your shell profile
echo 'export PATH="$HOME/.openclaw/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
openclaw --version
```

**If `python3` is not found or is below 3.10:**
```bash
brew install [email protected]
# Then use python3.12 instead of python3 in all commands below
```

---

## Quick Start: Let Your AI Agent Set It Up

**Don't want to deal with terminal commands? Just ask your OpenClaw agent to do it.**

Copy and paste this to your agent (webchat, Telegram, Discord — wherever you talk to it):

```
Install the Ultra Agent Upgrade for me.

Repo: https://github.com/jeremy26ai/ultra-agent-upgrade
Clone it, read the SKILL.md, and follow the 6-step installation guide.
Install everything in order. After each step, verify it works before moving on.
When you're done, run a fresh backup so the manifest captures everything.

If anything breaks, check the Troubleshooting section in the README.
```

That's it. Your agent will:
1. Clone this repo
2. Read the installation guide
3. Install each system in order (backup → fractal memory → active memory → menu bar monitor)
4. Verify each step
5. Run a final backup

**Prefer to do it yourself?** Follow the manual installation guide below.

---

## What You Get

| System | What it does |
|---|---|
| **Revival System** | Nightly full-state backup of `~/.openclaw` → tar.gz archive + a pasteable revival manifest that can restore your entire setup on a new Mac. |
| **Fractal Branching Memory** | Advanced memory system based on the Mandelbrot equation `z = z² + c`. Every memory is a point in the complex plane. Memories consolidate or forget through fractal dynamics — no arbitrary expiry dates. Cross-session recall works across all channels. |
| **Active Memory Integration** | Configures OpenClaw's built-in Active Memory plugin to automatically search memory before every response — including the fractal memory bridge. No more starting from zero. |
| **SwiftBar Menu Bar Monitor** | Green/amber/red icon in your menu bar showing backup health at a glance, with one-click "Back Up Now", archive browsing, and a restore helper. |

---

## Find Your Workspace Directory

OpenClaw uses a workspace directory for agent files, skills, scripts, and memory.
The default is `~/.openclaw/workspace/`, but it can be customized. Before installing,
find your workspace path:

```bash
# Option 1: Check OpenClaw status
openclaw status | grep -i workspace

# Option 2: Check if the default exists
ls ~/.openclaw/workspace/ 2>/dev/null && echo "Default workspace found"

# Option 3: Check your config file
python3 -c "import json; print(json.load(open('$HOME/.openclaw/openclaw.json')).get('workspace',{}).get('path','~/.openclaw/workspace'))"
```

Once you know your workspace path, set it as a variable for the installation:

```bash
# Replace this with your actual workspace path
WORKSPACE="$HOME/.openclaw/workspace"
```

All installation steps below use `$WORKSPACE` — adjust it if your path differs.

---

## Installation

Install each component in order. Each step includes the expected output and what to do if something goes wrong.

> **Run all commands from the repo directory you cloned.** If you cloned to `~/Desktop/ultra-agent-upgrade`, `cd ~/Desktop/ultra-agent-upgrade` first.

### Step 1 — Revival System (Backup + Revival)

```bash
# Set your workspace path (adjust if different from the default)
WORKSPACE="$HOME/.openclaw/workspace"

# 1. Copy the backup script to your workspace
mkdir -p "$WORKSPACE/scripts"
cp scripts/oc-resurrection.sh "$WORKSPACE/scripts/"
chmod +x "$WORKSPACE/scripts/oc-resurrection.sh"

# 2. Create the backup destination
#    (NOT ~/Documents — macOS TCC blocks background jobs from writing there)
mkdir -p ~/Openclaw_Resurrection/archives

# 3. Install the launchd LaunchAgent (nightly at 23:55)
#    This replaces the PLACEHOLDER paths with your actual home directory
sed "s|/Users/PLACEHOLDER|${HOME}|g" \
    launchd/ai.openclaw.resurrection.plist \
    | sed "s|/.openclaw/workspace/scripts/oc-resurrection.sh|${WORKSPACE}/scripts/oc-resurrection.sh|g" \
    > ~/Library/LaunchAgents/ai.openclaw.resurrection.plist

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.resurrection.plist

# 4. Run the first backup manually
bash "$WORKSPACE/scripts/oc-resurrection.sh"

# 5. Verify
ls ~/Openclaw_Resurrection/archives/
head -20 ~/Openclaw_Resurrection/Openclaw_Resurrection.md
```

**Expected output from step 4:**
```
[2026-07-29 23:55:00] Backup start.
[2026-07-29 23:55:00] Keychain: no items configured (edit KEYCHAIN_ITEMS in script to add).
[2026-07-29 23:55:05] Archive written: /Users/yourname/Openclaw_Resurrection/archives/Openclaw_Resurrection_2026-07-29.tar.gz (48M)
[2026-07-29 23:55:05] Manifest written: /Users/yourname/Openclaw_Resurrection/Openclaw_Resurrection.md
[2026-07-29 23:55:05] Backup complete.
```

**Expected output from step 5:**
```
Openclaw_Resurrection_2026-07-29.tar.gz
# OpenClaw Resurrection
> **Purpose:** paste the contents of this file into a fresh OpenClaw chat...
```

**If `launchctl bootstrap` fails with "Service is already loaded":**
```bash
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.resurrection.plist
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/ai.openclaw.resurrection.plist
```

**If the backup script exits with an error immediately:**
The script uses `set -euo pipefail` — any failing command aborts early. Check the log:
```bash
cat ~/Openclaw_Resurrection/last-run.log
```
The last line before `Backup complete.` is missing will tell you exactly which step failed.

**If `ls ~/Openclaw_Resurrection/archives/` shows no `.tar.gz`:**
This means `tar` exited non-zero due to socket files or ACL warnings. These are harmless warnings but can cause `set -e` to abort. The script handles this, but if it still fails:
```bash
# Run with verbose output to see what's happening
bash -x "$WORKSPACE/scripts/oc-resurrection.sh" 2>&1 | tail -40
```

**Adding your Keychain items to the backup:**
Open `$WORKSPACE/scripts/oc-resurrection.sh` and find the `KEYCHAIN_ITEMS` array near the top. Add your services:
```bash
KEYCHAIN_ITEMS=(
    "your-service-name|your-account"
    "another-service|another-account"
    "service-with-auto-discovery|"  # leave account empty to auto-discover
)
```

---

### Step 2 — Fractal Branching Memory System

```bash
# Use the same WORKSPACE variable from Step 1
WORKSPACE="$HOME/.openclaw/workspace"

# 1. Copy the fractal-memory directory to your workspace
cp -R fractal-memory/ "$WORKSPACE/fractal-memory/"

# 2. Ingest your existing memory files into the fractal store
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" ingest

# 3. Verify
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" status
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" visualize
```

**Expected output from `fbm.py status`:**
```
Fractal Branching Memory — Status
  Store: ~/.openclaw/workspace/fractal-memory/data/nodes.json
  Memories: 47 total  (42 bounded, 5 escaped/fading)
  Sessions: 12 registered
  Last iteration: 2026-07-29T22:10:00Z
```

**Expected output from `fbm.py visualize`:**
```
Fractal Memory Landscape (ASCII)
  . . * * . . .
  . * * * * . .
  * * * * * * .
  ...
```

**If `fbm.py ingest` shows "0 memories ingested":**
This is normal if you don't yet have a `memory/` directory with `.md` files. Start adding memories manually:
```bash
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" add "This is my first memory"
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" recall "first"
```

**If `fbm.py` crashes with `ModuleNotFoundError: No module named 'sqlite3'`:**
```bash
# Reinstall Python with sqlite support
brew install [email protected]
python3.12 "$WORKSPACE/fractal-memory/scripts/fbm.py" status
```

**If `fbm.py` crashes with `ImportError` or `SyntaxError`:**
```bash
python3 --version  # must be 3.10+
# If too old:
brew install [email protected] && python3.12 "$WORKSPACE/fractal-memory/scripts/fbm.py" status
```

**CLI commands:**
```bash
WORKSPACE="$HOME/.openclaw/workspace"

python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" status      # system overview
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" add "text"  # add a memory
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" recall "q"  # recall memories
python3 "$WORKSPACE/fractal-memory/scripts/fbm.py" manifest    # continuity manifest


... (truncated)