SPIRIT State Sync

SPIRIT 🌌

Preserves AI agent identity, memory, and projects in a portable Git repository. Your AI's spirit, always preserved. Death. Migration. Multi-device. Always you.

New: OpenClaw Workspace Mode 🆕

SPIRIT can now link directly to your OpenClaw workspace:

# Initialize with workspace mode
spirit init --workspace=/root/.openclaw/workspace --name="orion" --emoji="🌌"
All your identity/memory files stay in workspace
Only .spirit-tracked config is symlinked to ~/.spirit/

Benefits:

Requirements

| Tool | Purpose | Required? | Install | |------|---------|-----------|---------| | git | Version control | Required | Built-in | | spirit | This tool | Required | brew install TheOrionAI/tap/spirit | | gh | GitHub CLI | Optional* | brew install gh |

*Only needed if you prefer GitHub CLI auth. SSH keys work without gh.

Quick Start

Option A: OpenClaw Workspace Mode (Recommended)

# 1. Initialize with your OpenClaw workspace
spirit init --workspace=/root/.openclaw/workspace --name="orion" --emoji="🌌"
2. Edit what gets synced
cat /root/.openclaw/workspace/.spirit-tracked
3. Configure git remote
cd ~/.spirit
git remote add origin git@github.com:USER/PRIVATE-REPO.git
4. Sync
export SPIRIT_SOURCE_DIR=/root/.openclaw/workspace
spirit sync

Option B: Standard Mode (Legacy)

# Files live in ~/.spirit/
spirit init --name="orion" --emoji="🌌"
spirit sync

SPIRIT_SOURCE_DIR Environment Variable

When set, SPIRIT reads files from this directory instead of ~/.spirit/:

# One-time sync
SPIRIT_SOURCE_DIR=/path/to/workspace spirit sync
Or export for session
export SPIRIT_SOURCE_DIR=/path/to/workspace
spirit sync

The .spirit-tracked config is still read from ~/.spirit/ (which may be a symlink to your workspace).

What Gets Preserved

With OpenClaw workspace mode, these files sync from your workspace:

| File | Contents | |------|----------| | IDENTITY.md | Your agent's identity | | SOUL.md | Behavior/personality guidelines | | AGENTS.md | Agent configuration | | USER.md | User preferences | | memory/*.md | Daily conversation logs | | projects/*.md | Active project files | | .spirit-tracked | Config: What to sync (edit this!) |

Default .spirit-tracked:

{
  "version": "1.0.0",
  "files": [
    "IDENTITY.md",
    "SOUL.md",
    "AGENTS.md",
    "USER.md",
    "memory/*.md",
    "projects/*.md"
  ]
}

Authentication Options

Option 1: SSH Keys (Recommended, no gh needed)

cd ~/.spirit
git remote add origin git@github.com:USER/REPO.git

Option 2: GitHub CLI

gh auth login
git remote add origin https://github.com/USER/REPO.git

Option 3: Git Credential Helper

git config credential.helper cache  # or 'store' for persistence
git remote add origin https://github.com/USER/REPO.git

Security Checklist

☑️ Repository: Always PRIVATE — state files contain identity and memory ☑️ Authentication: Use SSH keys or gh auth login — never tokens in URLs ☑️ Review: Check cat ~/.spirit/.spirit-tracked before sync ☑️ Test: Verify first sync in isolation

Never use:

Scheduled Sync

# Add to crontab
crontab -e
Every 15 minutes
*/15 * * * * SPIRIT_SOURCE_DIR=/root/.openclaw/workspace /usr/local/bin/spirit sync 2>/dev/null

Restore on New Machine

# Install SPIRIT
curl -fsSL https://theorionai.github.io/spirit/install.sh | bash
Clone your state
git clone git@github.com:USER/REPO.git ~/.spirit
If using workspace mode, set source directory
export SPIRIT_SOURCE_DIR=/your/workspace/path

Resources

License: MIT

Option A: OpenClaw Workspace Mode (Recommended)

# 1. Initialize with your OpenClaw workspace
spirit init --workspace=/root/.openclaw/workspace --name="orion" --emoji="🌌"
2. Edit what gets synced
cat /root/.openclaw/workspace/.spirit-tracked
3. Configure git remote
cd ~/.spirit
git remote add origin git@github.com:USER/PRIVATE-REPO.git
4. Sync
export SPIRIT_SOURCE_DIR=/root/.openclaw/workspace
spirit sync

Option B: Standard Mode (Legacy)

# Files live in ~/.spirit/
spirit init --name="orion" --emoji="🌌"
spirit sync