spirit

Original source / Raw SKILL.md

---
name: spirit
description: |
  State Preservation & Identity Resurrection Infrastructure Tool (SPIRIT).
  Preserves AI agent identity, memory, and projects to a private Git repository.
  
  NEW: Workspace mode - symlinked config for easy editing in your OpenClaw workspace.
  
metadata:
  openclaw:
    requires:
      bins: ["spirit", "git"]
    install:
      - id: spirit-cli
        kind: brew
        tap: TheOrionAI/tap
        package: spirit
        bins: ["spirit"]
        label: Install SPIRIT via Homebrew
---

# 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 [email protected]: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/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`:**
```json
{
  "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)

```bash
cd ~/.spirit
git remote add origin [email protected]:USER/REPO.git
```

### Option 2: GitHub CLI

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

### Option 3: Git Credential Helper

```bash
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:**
- ❌ `https://[email protected]/...` in remote URL
- ❌ Tokens in shell history or process lists

---

## Scheduled Sync

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

```bash
# Install SPIRIT
curl -fsSL https://theorionai.github.io/spirit/install.sh | bash

# Clone your state
git clone [email protected]:USER/REPO.git ~/.spirit

# If using workspace mode, set source directory
export SPIRIT_SOURCE_DIR=/your/workspace/path
```

---

## Resources

- **SPIRIT:** https://github.com/TheOrionAI/spirit
- **GitHub CLI:** https://cli.github.com

---

**License:** MIT


---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "gopinathnelluri",
  "slug": "spirit",
  "displayName": "SPIRIT State Sync",
  "latest": {
    "version": "1.1.0",
    "publishedAt": 1771571711046,
    "commit": "https://github.com/openclaw/skills/commit/0dccd44dd726a174199b686edb14bfee8c0c5b78"
  },
  "history": [
    {
      "version": "0.1.6",
      "publishedAt": 1771443464785,
      "commit": "https://github.com/openclaw/skills/commit/f18f010c5f63b3253de1b30e5844f3af4b76a9ef"
    },
    {
      "version": "0.1.2",
      "publishedAt": 1771391344533,
      "commit": "https://github.com/openclaw/skills/commit/1363b7ff045872613d7b3d3d23b90a47a3f6e7ed"
    }
  ]
}

```

### references/cron-setup.md

```markdown
# SPIRIT Cron Setup Guide

## Option 1: System Crontab (Recommended for Servers)

```bash
# Edit crontab
crontab -e

# Add entries (adjust path as needed):

# Sync every 15 minutes
*/15 * * * * /root/.openclaw/workspace/spirit-skill/scripts/spirit-sync-cron.sh

# Sync hourly with custom message
0 * * * * cd ~ && [ -d .spirit ] && spirit backup --message "Hourly checkpoint" 2>/dev/null

# Sync daily at 2 AM
0 2 * * * cd ~ && [ -d .spirit ] && spirit backup --message "Daily backup" 2>/dev/null
```

## Option 2: OpenClaw Cron Integration

For agents running on OpenClaw-managed hosts:

### Using sessions_spawn (Isolated Agent)

```bash
openclaw cron add \
  --name spirit-auto-sync \
  --schedule "*/15 */1 * * *" \
  --sessionTarget isolated \
  --agentTurn "Run spirit sync for automatic state preservation."
```

### Using systemEvent (Main Session Wake)

```bash
# Creates a system event every 15 minutes that wakes the main agent
openclaw cron add \
  --name spirit-reminder \
  --schedule "*/15 */1 * * *" \
  --sessionTarget main \
  --systemEvent "SPIRIT: Time for auto-sync checkpoint"
```

Then in your agent logic, respond to "SPIRIT:" messages by running `spirit sync`.

## Option 3: SPIRIT Built-in Auto-Backup

```bash
# Enable SPIRIT's own auto-backup daemon
spirit autobackup --interval=15m

# Check status
spirit autobackup --status

# Disable
spirit autobackup --disable
```

## Monitoring

Check sync logs:

```bash
# View cron sync log
tail -f ~/.spirit/.cron-sync.log

# View OpenClaw cron runs
openclaw cron runs --jobId <job-id>

# List all Spirit backups
spirit status
```

## Troubleshooting

### Cron not running
- Check `which spirit` — is it in PATH?
- Test manually: `/root/.openclaw/workspace/spirit-skill/scripts/spirit-sync-cron.sh`

### Sync failing
- Check `~/.spirit/` exists and is initialized
- Verify git remote: `cd ~/.spirit && git remote -v`
- Check credentials (PAT/SSH key)

### Conflicts
- SPIRIT handles merge conflicts via `git pull --rebase`
- If conflicts persist, resolve manually: `cd ~/.spirit && git status`

```

### scripts/spirit-sync-cron.sh

```bash
#!/bin/bash
# SPIRIT Auto-Sync Cron Script
# Place in crontab or use with OpenClaw scheduled jobs

set -e

# Check if spirit is installed
if ! command -v spirit &> /dev/null; then
    echo "Error: spirit not found in PATH"
    exit 1
fi

# Check if initialized
if [ ! -d "$HOME/.spirit" ]; then
    echo "Error: SPIRIT not initialized. Run: spirit init"
    exit 1
fi

# Run sync with timestamp
LOG_FILE="$HOME/.spirit/.cron-sync.log"
echo "[$(date '+%Y-%m-%d %H:%M:%S')] Starting SPIRIT auto-sync..." >> "$LOG_FILE"

if spirit sync >> "$LOG_FILE" 2>&1; then
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] ✓ SPIRIT sync completed" >> "$LOG_FILE"
else
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] ✗ SPIRIT sync failed" >> "$LOG_FILE"
    exit 1
fi

# Keep only last 100 lines of log
tail -100 "$LOG_FILE" > "$LOG_FILE.tmp" && mv "$LOG_FILE.tmp" "$LOG_FILE"

```