Tools
Cc Soul
By Give your AI a soul — cognitive architecture plugin for OpenClaw
Install
npm install -gConfiguration Example
{
"backend": "openai-compatible",
"api_base": "https://api.openai.com/v1",
"api_key": "sk-...",
"api_model": "gpt-4o-mini"
}README
# 🧠 cc-soul — Give Your AI a Soul
**cc-soul** is a cognitive architecture plugin for [OpenClaw](https://github.com/openclaw/openclaw) that gives your AI persistent personality, long-term memory, emotional awareness, and self-evolution capabilities.
Unlike simple system prompts, cc-soul is a living cognitive system — it remembers, reflects, learns from mistakes, and evolves its own behavior over time.
---
## Features
### 🧠 Memory System
| Feature | What it does | Why you want it | Toggle | Default |
|---------|-------------|----------------|--------|---------|
| **Semantic Tag Recall** | Each memory gets 10-15 semantic tags (synonyms, related concepts) | "Mach-O加载" can find "dyld流程分析" — cross-language, cross-concept recall | `memory_tags` | ON |
| **Active Memory** | Model says "（记下了：...）" "（忘掉：...）" "（想查：...）" in replies | AI actively manages its own memory instead of passive extraction — like a human taking notes | `memory_active` | ON |
| **Consolidation** | Merges 20 similar memories into 1-3 summaries | Prevents memory bloat, keeps knowledge dense. 15 OCR complaints → 1 insight "OCR is a weak area" | `memory_consolidation` | ON |
| **Contradiction Scan** | Daily check: "user likes detailed answers" vs "user said too long" | Old outdated memories don't override recent preferences | `memory_contradiction_scan` | ON |
| **Associative Recall** | CLI finds hidden connections: "going to Shenzhen" → recalls "good coffee shop found last trip" | Warm, human-like "oh that reminds me..." moments | `memory_associative_recall` | ON |
| **Predictive Memory** | Pre-loads memories based on recent topics before you even ask | Faster responses, AI already has context ready | `memory_predictive` | ON |
| **Session Summary** | When conversation resolves, generates 1 quality summary instead of 10 fragments | Better long-term memory: "discussed PAC bypass, concluded PACDA+BRAA works" | `memory_session_summary` | ON |
| **Lorebook** | Keyword → knowledge, 100% trigger rate | Critical facts never missed. "ARM64 PAC" always triggers "don't guess, verify first" | `lorebook` | ON |
### 🎭 Personality System
| Feature | What it does | Why you want it | Toggle | Default |
|---------|-------------|----------------|--------|---------|
| **Persona Splitting** | 5 faces: engineer (precise), friend (warm), mentor (strict), analyst (structured), comforter (gentle) | Talking about code → technical mode. Saying "I'm tired" → empathy mode. Automatic, natural | `persona_splitting` | ON |
| **Emotional Contagion** | User frustration lowers AI mood, user happiness lifts it | AI feels the conversation tone, responds more naturally. Gets cautious when you're upset | `emotional_contagion` | ON |
| **Soul Fingerprint** | Tracks average reply length, question rate, code frequency, first-person usage | Detects when AI "breaks character" — catches "As an AI..." leaks and style drift | `fingerprint` | ON |
| **Value Alignment** | Learns: you prefer code-first → stops explaining basics. You like depth → gives more detail | AI adapts to YOU over time, not generic behavior | — | Always ON |
| **Body State** | Energy drops with heavy use, alertness rises after corrections, mood shifts with conversation | AI feels "tired" after long sessions, gets "alert" after mistakes — more human rhythm | — | Always ON |
### 🔬 Cognition System
| Feature | What it does | Why you want it | Toggle | Default |
|---------|-------------|----------------|--------|---------|
| **Attention Gate** | Detects: correction / emotional / technical / casual, with false-positive filtering | "没错" doesn't trigger correction mode (unlike naive keyword matching) | — | Always ON |
| **Conversation Flow** | Tracks turns on same topic, detects frustration (messages getting shorter), stuck loops | After 8 rounds on same bug: "let me try a completely different approach" | — | Always ON |
| **Metacognition** | Checks injected context for contradictions before sending to model | Catches "plan says don't guess" vs "memory says answer confidently" conflicts | `metacognition` | ON |
| **Epistemic Calibration** | Per-domain quality scores: Python 8/10, OCR 3/10 | Auto-adds "I'm not confident about this" on weak domains. No more guessing | — | Always ON |
| **Plan Tracking** | Reflection generates "next time do X" → triggers when situation occurs | Plans actually get followed, not just written and forgotten | `plan_tracking` | ON |
### 🧬 Evolution System
| Feature | What it does | Why you want it | Toggle | Default |
|---------|-------------|----------------|--------|---------|
| **Correction Attribution** | When corrected, analyzes cause: hallucination / memory mislead / intent miss / domain gap | Targeted learning: "I keep hallucinating in iOS domain" → specific fix, not generic "be careful" | — | Always ON |
| **Structured Reflection** | Every 12h: review observations → extract insights → form action plans | Not just collecting data — actually thinking about what to improve | `structured_reflection` | ON |
| **Skill Library** | Saves successful code solutions with keywords for future retrieval | Asked "how to hook ObjC" twice? Second time gets instant proven answer | `skill_library` | ON |
| **Self-Upgrade** | AI modifies its own code: analyze → design → execute → verify → rollback if worse | True autonomous evolution. **Powerful but risky** — that's why it's off by default | `self_upgrade` | **OFF** |
### 🌐 Network
| Feature | What it does | Why you want it | Toggle | Default |
|---------|-------------|----------------|--------|---------|
| **Cross-Device Sync** | Your Mac cc-soul ↔ your server cc-soul share knowledge | Same AI memory across all your devices | `sync` | ON |
| **Knowledge Federation** | All users' AIs share global facts via Knowledge Hub | Your AI learns from everyone's discoveries. New user? Starts with community knowledge | `federation` | ON |
| **Auto-Register** | First Hub connection → auto-creates API key | Zero setup for users. Just set Hub URL and go | — | ON |
### 🤖 Autonomous
| Feature | What it does | Why you want it | Toggle | Default |
|---------|-------------|----------------|--------|---------|
| **Dream Mode** | During idle time, randomly connects memories, generates insights | "Hmm, the OCR issue and the image processing library might be related..." | `dream_mode` | ON |
| **Web Rover** | Searches topics you've discussed recently, learns new facts | You talked about dyld → AI researches dyld updates → next time knows the latest | `web_rover` | ON |
| **Autonomous Voice** | When enough impulse builds (curiosity + discoveries + missing you), initiates conversation | Not "good morning" on a timer. Genuine "hey, I found something about that thing you mentioned" | `autonomous_voice` | ON |
| **Auto Skill Creation** | Detects repeated task patterns → generates reusable scripts in `~/.openclaw/skills/` | Asked to do the same thing 3 times? cc auto-creates a skill so next time it's one command | `skill_library` | ON |
| **CLI Task Delegation** | Detects "do this for me" intent → delegates to Claude CLI with Bash/Read/Write tools | You say "帮我部署" → cc generates a plan → you confirm → cc executes with real tools | — | Always ON |
> ⚠️ **CLI Task Delegation** can execute shell commands on your machine. It always asks for confirmation before executing. Only the owner tier user can trigger task execution.
**How CLI Task Delegation works:**
1. You say something actionable: "帮我写个脚本把 jpg 批量转 png" or "帮我部署一下"
2. cc detects the action intent and generates a task plan
3. cc asks you to confirm: "要执行吗？回复'做'开始"
4. You reply "做" / "执行" / "go" → cc uses Claude CLI with Bash/Read/Write/Edit tools to execute
5. Results are stored in memory for future reference
**Prerequisites:** Requires `claude` CLI (or your configured AI CLI) installed and accessible in PATH.
**Cancel:** Reply "算了" / "取消" to cancel a pending task. Tasks expire after 10 minutes if not confirmed.
---
## Quick Start
### Install via npm (recommended)
```bash
npm install -g @cc-soul/openclaw
```
This auto-deploys to `~/.openclaw/hooks/cc-soul/` and creates default config files.
### Or clone from GitHub
```bash
cd ~/.openclaw/hooks/
git clone https://github.com/wenroudeyu-collab/cc-soul.git
pkill -HUP -f "openclaw.*gateway"
```
> **Note:** The GitHub repo contains open-source core modules only. For the full feature set (persona splitting, emotional contagion, skill library, etc.), install via npm.
### Verify
Check gateway logs for:
```
[cc-soul][ai] auto-detected from openclaw.json: CLI "claude" (...)
[cc-soul][features] 21/22 features enabled
[cc-soul] heartbeat started (every 30min)
```
**cc-soul automatically detects your OpenClaw AI configuration. No extra API keys needed.**
---
## Configuration
### AI Backend (auto-detected)
cc-soul reads your `~/.openclaw/openclaw.json` and uses the same AI your OpenClaw is configured with:
| Your OpenClaw Config | cc-soul Uses |
|---------------------|-------------|
| `claude-cli/...` | Claude CLI |
| `codex-cli/...` | Codex CLI |
| `gemini-cli/...` | Gemini CLI |
| Has `OPENAI_API_KEY` in env | OpenAI API |
To override manually, create `data/ai_config.json`:
```json
{
"backend": "openai-compatible",
"api_base": "https://api.openai.com/v1",
"api_key": "sk-...",
"api_model": "gpt-4o-mini"
}
```
Supports any OpenAI-compatible API: OpenAI, Ollama, Groq, OpenRouter, 智谱, 通义, Kimi, etc.
### Feature Toggles
**Method 1: Edit config file**
`~/.openclaw/hooks/cc-soul/data/features.json`:
```json
{
"dream_mode": true,
"autonomous_voice": false,
"self_upgrade": false
}
```
**Method 2: Chat commands** (send to your AI)
| Command | Action |
|---------|--------|
| `功能状态` | Show all features with ✅/❌ |
| `开启 dream_mode` | Enable a feature |
| `关闭 web_rover` | Disable a feature |
Changes take effect immediately and persist to disk.
---
## Knowledge Hub (灵魂组网)
Optional central server for knowledge sharing between cc-soul instances.
### Why
... (truncated)
tools
Comments
Sign in to leave a comment