spirit

# SPIRIT 🌌
> **S**tate **P**reservation & **I**dentity **R**esurrection **I**nfrastructure **T**ool

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:

```bash
# 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:**
- ✅ Edit `.spirit-tracked` config directly in workspace
- ✅ All identity/memory files in one place
- ✅ Sync with `SPIRIT_SOURCE_DIR=/root/.openclaw/workspace spirit sync`

---

## 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)

```bash
# 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)

```bash
# 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/`:

```bash
# One-time sync
SPIRIT_SOURCE_DIR=/path/to/workspace spirit sync

# Or export for session
export SPIRIT_SOURCE_DIR=/path/to/worksp...