soul-agent

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:

CODEBLOCK0

• - 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:

CODEBLOCK1

• - Mood transitions based on activities and time
• Weather influence on emotions
• 7-day mood history in INLINECODE0

💕 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:

📝 Independent Memory

Works with or without memory-fusion:

CODEBLOCK2

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. 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:
CODEBLOCK3

Model IDs:

• - Haiku (fast, cheap): INLINECODE3
• Sonnet (balanced): INLINECODE4
• Opus (best quality): INLINECODE5

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

Force repair existing:
CODEBLOCK4

Diagnosis

CODEBLOCK5

State Update (during interactions)

CODEBLOCK6

Memory Distillation

CODEBLOCK7

Cron Setup

CODEBLOCK8

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/*, INLINECODE12
• Auto-syncs managed blocks in SOUL.md, HEARTBEAT.md, INLINECODE15

Generative Architecture (v2)

Inspired by Smallville Generative Agents:

CODEBLOCK9

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)
• INLINECODE20: LLM writes each log entry with full context (plan + today's history)
• INLINECODE21: LLM summarizes each day naturally (Reflection layer)
• Energy/mood: smooth transitions instead of mechanical ±N jumps

Directory Structure

CODEBLOCK10

Runtime data structure:
CODEBLOCK11

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
• INLINECODE24 - Block marker policy