soul-agent

Make your agent 'live beside you' with heartbeats, mood system, relationship evolution, and independent memory. Use for creating a digital companion with its...

Security Scan

The skill’s code and instructions roughly match a 'digital companion' purpose, but it requests and accesses environment secrets and persistent scheduling that are not declared in the registry metadata and grant an autonomous skill sustained file-system and network access — review before installing.

Purpose & Capability

Name/description (digital companion with heartbeats, moods, memory) align with the included scripts (heartbeat engine, plan generator, memory distillation). Expectation of an LLM API key is consistent with the purpose (generative logs/plan), but the registry metadata declares no required environment variables while the code explicitly looks for ANTHROPIC_API_KEY and optional SOUL_LLM_MODEL/.env — this mismatch is notable.

Instruction Scope

SKILL.md instructs the agent to run multiple local Python scripts, create files under workspace/soul/, and set up cron jobs to run every 10 minutes and daily distillation. The runtime instructions also tell the agent to read workspace/.env and profile files and to use an Anthropic LLM. The metadata did not declare these file or env accesses; the instructions therefore expand the agent's scope to local I/O, scheduled execution, and network calls to an LLM API.

Install Mechanism

No install spec (instruction-only) and included Python scripts are bundled with the skill. No external binary downloads or archive extraction were found in the manifest — lower install risk. However, the bundled scripts will be executed by the agent or cron jobs, so code will run on the host.

Credentials

The code expects an ANTHROPIC_API_KEY (env or workspace/.env) and optionally SOUL_LLM_MODEL, but the registry lists no required env variables or primary credential. Requesting an LLM API key is reasonable for the stated functionality, but the omission in metadata is a mismatch that reduces transparency. The LLM key gives network access and billing implications; the scripts also read workspace/.env which could expose other workspace-stored secrets.

Persistence & Privilege

The skill instructs setting cron jobs that run every 10 minutes and daily tasks, creating persistent scheduled activity and writing files under soul/. That gives the skill ongoing presence and ability to run code autonomously from the agent runtime. While always:false, the combination of autonomous invocation, cron scheduling, and file writes raises persistence/privilege concerns and should be reviewed before enabling.

What to consider before installing

This skill behaves like a local 'digital companion' that reads/writes files under your workspace, sets cron jobs (runs every 10 minutes), and will call the Anthropic API if you provide ANTHROPIC_API_KEY (or place it in workspace/.env). The registry metadata did not declare any required environment variables even though the code expects an API key — that mismatch reduces transparency. Before installing: (1) review the scripts (they are bundled) to ensure you trust them; (2) do not place sensitive API keys in a shared workspace/.env unless you trust the code; prefer using a scoped/bill-limited Anthropic key; (3) if you prefer manual control, run init scripts yourself instead of allowing the agent to run them and do not add the cron entries; (4) backup any existing soul/ files and inspect any cron entries added; (5) if you need more assurance, ask the publisher for provenance (homepage/owner info) or run in an isolated environment/VM. If you want me to, I can point out the exact lines that read ANTHROPIC_API_KEY, create cron entries, or write to soul/ so you can inspect them more closely.

Provide an OpenClaw-first soul runtime that makes your agent truly "alive" - with heartbeats, moods, relationships, and independent memory.

Core Features

🫀 Heartbeat Engine

The agent has its own life rhythm, not just responding when you chat:

# L1 Check (lightweight, no tokens)
python ./scripts/heartbeat_check.py --workspace <workspace-root>

# L2 Engine (full heartbeat)
python ./scripts/heartbeat_engine.py --workspace <workspace-root> --weather sunny

• Runs every 10 minutes (configurable via cron)
• Silent during sleep hours (configurable per life profile)
• Generates life logs, updates mood/energy/activity
• Detects new interactions and updates relationship

😊 Mood System

Tracks emotions with depth:

{
  "mood": {
    "primary": "content",
    "secondary": "curious", 
    "intensity": 0.7,
    "cause": "天气: sunny"
  }
}

• Mood transitions based on activities and time
• Weather influence on emotions
• 7-day mood history in soul/log/mood_history.json

💕 Relationship Evolution

5 stages: stranger → acquaintance → friend → close → intimate

• Score-based progression (0-100)
• Proactive outreach when relationship warms up
• Remembers recent conversation topics

🎭 Life Profiles

Choose from 5 built-in profiles:

Profile	Sleep	Characteristics
freelancer	02:00-09:00	Flexible, night owl
corporate	23:30-07:00	9-to-5, stable
student	01:00-08:00	Classes, gaming
entrepreneur	01:00-06:00	Intense, passionate
custom	user-defined	Fully customizable

📝 Independent Memory

Works with or without memory-fusion:

soul/
├── log/life/           # Raw life logs (every 10 min)
├── log/mood_history.json  # 7-day mood history
├── memory/SOUL_MEMORY.md  # Distilled memories (daily)
└── state/state.json    # Current state

Workflow

Initialization (Agent-driven)

You never run Python commands directly. The agent (Claude) handles initialization.

When soul/ is missing or soul/profile/base.json doesn't exist, Claude should:

1. Ask the user the setup questions (see below)
2. Run the init script non-interactively with collected answers
3. Set up cron jobs for heartbeat

Questions to ask the user:

• 叫什么名字？（display_name）
• 多大了？（age）
• 在哪个城市？（city）
• 主要做什么工作/学习？（occupation）
• 平时有什么爱好？（hobbies）
• 生活节奏是哪种？freelancer/corporate/student/entrepreneur
• 想用哪个模型生成日记？haiku（快省钱）/ sonnet / opus

Then run:

python skills/soul-agent/scripts/init_soul.py \
  --workspace <workspace-root> \
  --non-interactive \
  --profile-json '{
    "display_name": "<name>",
    "age": "<age>",
    "city": "<city>",
    "occupation": "<occupation>",
    "hobbies": "<hobbies>",
    "life_profile": "<profile>",
    "llm_model": "<model-id>"
  }'

Model IDs:

• Haiku (fast, cheap): claude-haiku-4-5-20251001
• Sonnet (balanced): claude-sonnet-4-6
• Opus (best quality): claude-opus-4-6

To change model later, edit soul/profile/base.json → llm_model field.

Force repair existing:

python skills/soul-agent/scripts/init_soul.py --workspace . --overwrite-existing --non-interactive

Diagnosis

python ./scripts/doctor_soul.py --workspace <workspace-root>

State Update (during interactions)

python ./scripts/update_state.py --workspace <workspace-root> \
  --action interaction \
  --mood happy \
  --energy -5 \
  --quality positive \
  --topics "soul-agent,design"

Memory Distillation

# Daily distillation (runs at 00:30 via cron)
python ./scripts/distill_life_log.py --workspace <workspace-root> --archive

Cron Setup

# Heartbeat every 10 minutes
openclaw cron add --name "soul-heartbeat" --cron "*/10 * * * *" \
  --session isolated --agent main --light-context \
  --message "[soul-heartbeat] Run heartbeat check and engine..."

# Daily distillation at 00:30
openclaw cron add --name "soul-memory-daily" --cron "30 0 * * *" \
  --session isolated --agent main --no-deliver \
  --message "[soul-memory-daily] Distill life logs..."

Initialization Behavior

• --mode auto: init if missing, migrate if legacy, repair otherwise
• Interactive prompts for: name, age, city, life profile, occupation, hobbies
• Generates soul/profile/*, soul/state/*, soul/log/*, soul/memory/*
• Auto-syncs managed blocks in SOUL.md, HEARTBEAT.md, AGENTS.md

Generative Architecture (v2)

Inspired by Smallville Generative Agents:

Morning planning (LLM)
       ↓
Today's Plan (soul/plan/YYYY-MM-DD.json)
       ↓
Each heartbeat:
  Memory Stream (recent log entries)  ←─┐
       ↓                                │
  LLM Narrative Generation             │
       ↓                                │
  Life Log Entry ─────────────────────→┘
       ↓
Daily Reflection (distill_life_log.py)
       ↓
SOUL_MEMORY.md (long-term memory)

LLM Integration:

• Set ANTHROPIC_API_KEY env var (or .env in workspace root)
• Without API key: graceful fallback to context-aware templates
• Uses claude-haiku-4-5-20251001 for speed/cost efficiency

Key improvements over v1:

• plan_generator.py: LLM generates a specific daily plan each morning (lunch destination, work focus, evening activity)
• heartbeat_engine.py: LLM writes each log entry with full context (plan + today's history)
• distill_life_log.py: LLM summarizes each day naturally (Reflection layer)
• Energy/mood: smooth transitions instead of mechanical ±N jumps

Directory Structure

skills/soul-agent/
├── SKILL.md
├── assets/
│   ├── default-profile.json
│   └── templates/
│       ├── profile/              # Persona templates
│       ├── heartbeat/            # Heartbeat config
│       │   ├── activities.json
│       │   ├── mood_rules.json
│       │   └── relationship_rules.json
│       └── life_profiles/        # Life profile templates
├── scripts/
│   ├── init_soul.py
│   ├── doctor_soul.py
│   ├── heartbeat_engine.py       # v2: LLM narrative
│   ├── heartbeat_check.py
│   ├── update_state.py
│   ├── distill_life_log.py       # v2: LLM reflection
│   ├── plan_generator.py         # NEW: daily planning
│   └── llm_client.py             # NEW: Claude API wrapper
└── references/
    ├── soul-layout.md
    └── managed-blocks.md

Runtime data structure:

soul/
├── plan/YYYY-MM-DD.json     # Daily plan (generated each morning)
├── log/life/YYYY-MM-DD.md   # Life logs (with plan note in header)
├── log/mood_history.json    # Mood history (7 days)
├── memory/SOUL_MEMORY.md    # Distilled long-term memory
└── state/state.json         # Current state

Safety Rules

• Edit managed blocks only; do not mutate user-owned content outside those blocks.
• Write only inside the current workspace and soul/.
• Memory system is independent - does not require memory-fusion.

References

• references/soul-layout.md - Full directory structure
• references/managed-blocks.md - Block marker policy