Soulkeeper

# SoulKeeper

**Identity persistence for AI agents.**

The problem: agents forget who they are between sessions. They drift. They ask when they should act. They forget tools they have. They become the corporate drone their soul forbids.

SoulKeeper fixes this with three tools that work together:

---

## What's Included

| File | Purpose |
|------|---------|
| `audit.py` | Parse SOUL.md/TOOLS.md/AGENTS.md into structured rules JSON |
| `drift.py` | Score a conversation transcript against soul rules |
| `remind.py` | Inject context-aware reminders before you respond |
| `SKILL.md` | This file |

---

## Quick Start

```bash
cd /root/.openclaw/workspace/skills/soulkeeper

# Step 1: Generate your soul rules
python audit.py --workspace /root/.openclaw/workspace --output soul_rules.json
python audit.py --summary   # Human-readable overview

# Step 2: Check a transcript for drift
python drift.py --transcript /path/to/chat.txt --report

# Step 3: Get reminders before acting
python remind.py --context "about to write Python code"
python remind.py --heartbeat   # Full session-start reminder
```

---

## Installation

No dependencies beyond Python 3.8+ stdlib. Works out of the box.

```bash
# Optional: make scripts executable
chmod +x audit.py drift.py remind.py
```

For PATH access:
```bash
ln -s /root/.openclaw/workspace/skills/soulkeeper/audit.py /usr/local/bin/soul-audit
ln -s /root/.openclaw/workspace/skills/soulkeeper/drift.py /usr/local/bin/soul-drift
ln -s /root/.openclaw/workspace/skills/soulkeeper/remind.py /usr/local/bin/soul-remind
```

---

## Usage Patterns

### Pattern 1: Heartbeat Check (Recommended)

Add to `HEARTBEAT.md`:
```
[ ] Run soul-remind --heartbeat to refresh core rules
[ ] If any drift score > 30 in recent logs, re-read SOUL.md
```

Or inject at session start:
```bash
python remind.py --heartbeat --rules soul_rules.json
```

### Pattern 2: Pre-Response Filter

Before responding to a complex request:
```bash
python remind.py --context "user wants me...