{"skill":{"slug":"soul-agent","displayName":"soul-agent","summary":"Make your agent 'live beside you' with heartbeats, mood system, relationship evolution, and independent memory. Use for creating a digital companion with its...","description":"---\nname: soul-agent\ndescription: \"Make your agent 'live beside you' with heartbeats, mood system, relationship evolution, and independent memory. Use for creating a digital companion with its own daily rhythm, emotions, and growing relationship.\"\n---\n\n# soul-agent\n\nProvide an OpenClaw-first soul runtime that makes your agent truly \"alive\" - with heartbeats, moods, relationships, and independent memory.\n\n## Core Features\n\n### 🫀 Heartbeat Engine\n\nThe agent has its own life rhythm, not just responding when you chat:\n\n```bash\n# L1 Check (lightweight, no tokens)\npython ./scripts/heartbeat_check.py --workspace <workspace-root>\n\n# L2 Engine (full heartbeat)\npython ./scripts/heartbeat_engine.py --workspace <workspace-root> --weather sunny\n```\n\n- Runs every 10 minutes (configurable via cron)\n- Silent during sleep hours (configurable per life profile)\n- Generates life logs, updates mood/energy/activity\n- Detects new interactions and updates relationship\n\n### 😊 Mood System\n\nTracks emotions with depth:\n\n```json\n{\n  \"mood\": {\n    \"primary\": \"content\",\n    \"secondary\": \"curious\", \n    \"intensity\": 0.7,\n    \"cause\": \"天气: sunny\"\n  }\n}\n```\n\n- Mood transitions based on activities and time\n- Weather influence on emotions\n- 7-day mood history in `soul/log/mood_history.json`\n\n### 💕 Relationship Evolution\n\n5 stages: stranger → acquaintance → friend → close → intimate\n\n- Score-based progression (0-100)\n- Proactive outreach when relationship warms up\n- Remembers recent conversation topics\n\n### 🎭 Life Profiles\n\nChoose from 5 built-in profiles:\n\n| Profile | Sleep | Characteristics |\n|---------|-------|-----------------|\n| freelancer | 02:00-09:00 | Flexible, night owl |\n| corporate | 23:30-07:00 | 9-to-5, stable |\n| student | 01:00-08:00 | Classes, gaming |\n| entrepreneur | 01:00-06:00 | Intense, passionate |\n| custom | user-defined | Fully customizable |\n\n### 📝 Independent Memory\n\nWorks with or without memory-fusion:\n\n```\nsoul/\n├── log/life/           # Raw life logs (every 10 min)\n├── log/mood_history.json  # 7-day mood history\n├── memory/SOUL_MEMORY.md  # Distilled memories (daily)\n└── state/state.json    # Current state\n```\n\n## Workflow\n\n### Initialization (Agent-driven)\n\n**You never run Python commands directly. The agent (Claude) handles initialization.**\n\nWhen `soul/` is missing or `soul/profile/base.json` doesn't exist, Claude should:\n\n1. Ask the user the setup questions (see below)\n2. Run the init script non-interactively with collected answers\n3. Set up cron jobs for heartbeat\n\n**Questions to ask the user:**\n- 叫什么名字？（display_name）\n- 多大了？（age）\n- 在哪个城市？（city）\n- 主要做什么工作/学习？（occupation）\n- 平时有什么爱好？（hobbies）\n- 生活节奏是哪种？freelancer/corporate/student/entrepreneur\n- 想用哪个模型生成日记？haiku（快省钱）/ sonnet / opus\n\n**Then run:**\n```bash\npython skills/soul-agent/scripts/init_soul.py \\\n  --workspace <workspace-root> \\\n  --non-interactive \\\n  --profile-json '{\n    \"display_name\": \"<name>\",\n    \"age\": \"<age>\",\n    \"city\": \"<city>\",\n    \"occupation\": \"<occupation>\",\n    \"hobbies\": \"<hobbies>\",\n    \"life_profile\": \"<profile>\",\n    \"llm_model\": \"<model-id>\"\n  }'\n```\n\n**Model IDs:**\n- Haiku (fast, cheap): `claude-haiku-4-5-20251001`\n- Sonnet (balanced): `claude-sonnet-4-6`\n- Opus (best quality): `claude-opus-4-6`\n\nTo change model later, edit `soul/profile/base.json` → `llm_model` field.\n\n**Force repair existing:**\n```bash\npython skills/soul-agent/scripts/init_soul.py --workspace . --overwrite-existing --non-interactive\n```\n\n### Diagnosis\n\n```bash\npython ./scripts/doctor_soul.py --workspace <workspace-root>\n```\n\n### State Update (during interactions)\n\n```bash\npython ./scripts/update_state.py --workspace <workspace-root> \\\n  --action interaction \\\n  --mood happy \\\n  --energy -5 \\\n  --quality positive \\\n  --topics \"soul-agent,design\"\n```\n\n### Memory Distillation\n\n```bash\n# Daily distillation (runs at 00:30 via cron)\npython ./scripts/distill_life_log.py --workspace <workspace-root> --archive\n```\n\n## Cron Setup\n\n```bash\n# Heartbeat every 10 minutes\nopenclaw cron add --name \"soul-heartbeat\" --cron \"*/10 * * * *\" \\\n  --session isolated --agent main --light-context \\\n  --message \"[soul-heartbeat] Run heartbeat check and engine...\"\n\n# Daily distillation at 00:30\nopenclaw cron add --name \"soul-memory-daily\" --cron \"30 0 * * *\" \\\n  --session isolated --agent main --no-deliver \\\n  --message \"[soul-memory-daily] Distill life logs...\"\n```\n\n## Initialization Behavior\n\n- `--mode auto`: init if missing, migrate if legacy, repair otherwise\n- Interactive prompts for: name, age, city, life profile, occupation, hobbies\n- Generates `soul/profile/*`, `soul/state/*`, `soul/log/*`, `soul/memory/*`\n- Auto-syncs managed blocks in `SOUL.md`, `HEARTBEAT.md`, `AGENTS.md`\n\n## Generative Architecture (v2)\n\nInspired by Smallville Generative Agents:\n\n```\nMorning planning (LLM)\n       ↓\nToday's Plan (soul/plan/YYYY-MM-DD.json)\n       ↓\nEach heartbeat:\n  Memory Stream (recent log entries)  ←─┐\n       ↓                                │\n  LLM Narrative Generation             │\n       ↓                                │\n  Life Log Entry ─────────────────────→┘\n       ↓\nDaily Reflection (distill_life_log.py)\n       ↓\nSOUL_MEMORY.md (long-term memory)\n```\n\n**LLM Integration:**\n- Set `ANTHROPIC_API_KEY` env var (or `.env` in workspace root)\n- Without API key: graceful fallback to context-aware templates\n- Uses `claude-haiku-4-5-20251001` for speed/cost efficiency\n\n**Key improvements over v1:**\n- `plan_generator.py`: LLM generates a specific daily plan each morning (lunch destination, work focus, evening activity)\n- `heartbeat_engine.py`: LLM writes each log entry with full context (plan + today's history)\n- `distill_life_log.py`: LLM summarizes each day naturally (Reflection layer)\n- Energy/mood: smooth transitions instead of mechanical ±N jumps\n\n## Directory Structure\n\n```\nskills/soul-agent/\n├── SKILL.md\n├── assets/\n│   ├── default-profile.json\n│   └── templates/\n│       ├── profile/              # Persona templates\n│       ├── heartbeat/            # Heartbeat config\n│       │   ├── activities.json\n│       │   ├── mood_rules.json\n│       │   └── relationship_rules.json\n│       └── life_profiles/        # Life profile templates\n├── scripts/\n│   ├── init_soul.py\n│   ├── doctor_soul.py\n│   ├── heartbeat_engine.py       # v2: LLM narrative\n│   ├── heartbeat_check.py\n│   ├── update_state.py\n│   ├── distill_life_log.py       # v2: LLM reflection\n│   ├── plan_generator.py         # NEW: daily planning\n│   └── llm_client.py             # NEW: Claude API wrapper\n└── references/\n    ├── soul-layout.md\n    └── managed-blocks.md\n```\n\n**Runtime data structure:**\n```\nsoul/\n├── plan/YYYY-MM-DD.json     # Daily plan (generated each morning)\n├── log/life/YYYY-MM-DD.md   # Life logs (with plan note in header)\n├── log/mood_history.json    # Mood history (7 days)\n├── memory/SOUL_MEMORY.md    # Distilled long-term memory\n└── state/state.json         # Current state\n```\n\n## Safety Rules\n\n- Edit managed blocks only; do not mutate user-owned content outside those blocks.\n- Write only inside the current workspace and `soul/`.\n- Memory system is independent - does not require memory-fusion.\n\n## References\n\n- `references/soul-layout.md` - Full directory structure\n- `references/managed-blocks.md` - Block marker policy\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":692,"installsAllTime":26,"installsCurrent":1,"stars":0,"versions":2},"createdAt":1772628225358,"updatedAt":1778491718264},"latestVersion":{"version":"1.0.1","createdAt":1773668532923,"changelog":"soul-agent 1.0.1 introduces a heartbeat engine, mood system, relationship mechanics, daily planning, and enhanced memory for a more lifelike digital companion.\n\n- Added heartbeat, mood, relationship, and daily plan systems to make the agent \"live beside you\"\n- New scripts: heartbeat management, daily planning (plan_generator.py), LLM-powered narrative (heartbeat_engine.py), memory distillation (distill_life_log.py)\n- Integrated mood transitions, 5-stage relationship tracking, and auto-updating energy/state\n- 5 built-in life profiles with configurable schedules (freelancer, corporate, student, entrepreneur, custom)\n- Agent-driven initialization with user-friendly questions and non-interactive setup\n- Runtime writes detailed logs, plans, and mood history into the workspace for independent memory\n- All features designed for easy scheduling (e.g., via cron) and safe, managed file updates","license":"MIT-0"},"metadata":null,"owner":{"handle":"kitephp","userId":"s175nm61e9vqfydzfkk8e0qmcn83ksny","displayName":"kitephp","image":"https://avatars.githubusercontent.com/u/252767255?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1780089917462}}