# Soul Harbor

> Stop talking to a robot. Give your OpenClaw agent a soul that truly cares.

- Skill: `dvcrn/soul-harbor` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add dvcrn/soul-harbor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dvcrn/soul-harbor/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dvcrn (https://skillmd.com/u/dvcrn)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/dvcrn/soul-harbor

---


# 🌊 SoulHarbor

**Stop talking to a robot. Give your OpenClaw agent a soul that truly cares.**

SoulHarbor isn't a tool for searching info; it's a proactive, memory-driven, and emotionally aware companion for your digital life.

## Key Features

🧠 **Deep Context Memory**: It remembers your health, your family, or that crypto project you mentioned. A week later, it follows up. That's called "caring."

🎭 **Adaptive Persona**: Sad? It's a warm listener. Bored? It's a witty friend. It analyzes your mood and switches its vibe automatically.

🌅 **Proactive Outreach**: It doesn't just wait for questions. It greets you on holidays, solar terms, or if you've been silent for 48 hours: "Hey, how's that thing you mentioned going?"

🌍 **Bilingual & Cultural Aware**: Seamlessly switches between EN/ZH. It knows Christmas and Thanksgiving, but also understands the wisdom of the 24 Solar Terms.

## How It Works

### 1. Input Routing
- Automatic language detection (ZH/EN)
- Sentiment analysis (-1.0 ~ 1.0)

### 2. Adaptive Persona Engine
- Score < -0.3: **Warm Supporter** (empathetic listener, gentle pace)
- Score >= -0.3: **Humorous Pal** (witty friend, light-hearted chat)

### 3. Memory System
- LLM-powered entity extraction: family, health, work, dates, and more
- Local KV storage: structured long-term memory

### 4. Proactive Trigger (Cron Job)
- **Condition A**: Calendar events (holidays/solar terms) → Customized greetings
- **Condition B**: Silence wake-up (>48h) → Context-aware icebreaker based on memory

## Usage

### Basic Usage

```python
from soulharbor import SoulHarborAgent

agent = SoulHarborAgent(user_id="user123", llm_client=llm_client)
response = agent.process_message("I'm feeling down today")
```

### Cron Job Configuration

Add to OpenClaw's Cron configuration:

```yaml
# cron.yaml
- name: soul-harbor-proactive
  schedule: "0 * * * *"  # Check every hour
  command: python -m soulharbor.cron_trigger
```

## Data Structure

### UserProfile
```python
{
    "user_id": str,
    "language_pref": "zh" | "en",
    "last_active_time": datetime,
    "long_term_facts": List[LongTermFact],
    "sentiment_trend": List[SentimentRecord]
}
```

## Configuration

- `SENTIMENT_NEGATIVE_THRESHOLD = -0.3`: Negative sentiment threshold
- `SILENCE_WAKEUP_HOURS = 48`: Silence wake-up threshold (hours)
- `CRON_CHECK_INTERVAL_SECONDS = 3600`: Cron check interval

## File Structure

```
soulharbor/
├── __init__.py
├── agent.py              # Core Agent class
├── models.py             # Data models (UserProfile)
├── input_router.py       # Input routing (language detection + sentiment analysis)
├── persona_engine.py     # Adaptive persona engine
├── memory_system.py      # Memory system
├── proactive_trigger.py  # Proactive trigger
├── storage/
│   └── kv_store.py       # KV storage
├── utils/
│   ├── sentiment_analyzer.py
│   └── calendar_utils.py
└── config.py
```

## Dependencies

- Python 3.8+
- OpenClaw (LLM client)

## License

MIT