@cc-soul/openclaw 1.0.0

package/README.md

@@ -0,0 +1,284 @@
+# 🧠 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 |
+
+---
+
+## Quick Start
+
+### Install
+
+```bash
+cd ~/.openclaw/hooks/
+git clone https://github.com/your-username/cc-soul.git
+```
+
+Restart your OpenClaw gateway:
+```bash
+pkill -HUP -f "openclaw.*gateway"
+```
+
+### 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 / Why Not
+
+| ✅ Advantages | ⚠️ Trade-offs |
+|--------------|---------------|
+| Your AI gets smarter from collective knowledge | Requires a Hub server (free tier available) |
+| Technical facts shared across all instances | Your global facts are visible to other users |
+| New users start with community knowledge, not from zero | Depends on network quality — bad knowledge can propagate |
+| Corrections from one user benefit all users | 30-min sync delay (not real-time) |
+| Zero effort — auto-sync in background | Hub operator can see aggregated (non-personal) data |
+
+### What's shared vs private
+
+| Data | Shared to Hub? | Reason |
+|------|---------------|--------|
+| Technical facts ("dyld 4 uses fixup chain") | ✅ Yes | Universal knowledge, benefits everyone |
+| Discoveries from web rover | ✅ Yes | Research results, non-personal |
+| Personal preferences | ❌ Never | Your settings stay local |
+| Chat history | ❌ Never | Private conversations |
+| User profiles | ❌ Never | Per-user data stays local |
+| Emotions / body state | ❌ Never | Internal state |
+| API keys / passwords | ❌ Auto-stripped | PII filter removes before upload |
+
+**Rule: if you're unsure, don't enable federation. cc-soul works perfectly fine as a standalone local system.**
+
+### For Hub operators
+
+```bash
+cd ~/.openclaw/hooks/cc-soul/hub
+npm install
+HUB_PORT=9900 HUB_ADMIN_KEY=your-secret npm start
+```
+
+Open dashboard: `http://your-server:9900/dashboard`
+
+### For users
+
+Edit `data/sync_config.json`:
+```json
+{
+  "enabled": true,
+  "hubUrl": "https://hub-url:9900",
+  "federationEnabled": true,
+  "syncIntervalMinutes": 30
+}
+```
+
+API key auto-generated on first connection. No manual registration needed.
+
+### Privacy guarantees
+
+- ✅ Only global facts/discoveries shared (never personal data)
+- ✅ PII auto-filtered (phone, email, API keys, ID cards)
+- ✅ Quality gate (rejects low-quality sources)
+- ✅ 3 reports → auto-delete bad knowledge
+- ✅ Local knowledge always wins over network knowledge
+- ✅ All data stored locally, Hub is optional
+
+---
+
+## Chat Commands
+
+| Command | Action |
+|---------|--------|
+| `功能状态` | List all features |
+| `开启 <feature>` | Enable a feature |
+| `关闭 <feature>` | Disable a feature |
+| `同步知识` | Manual knowledge export |
+| `导入知识` | Manual knowledge import |
+| `同步状态` | Show sync status |
+| `手动升级` | Trigger self-upgrade analysis (requires `self_upgrade: true`) |
+
+---
+
+## Architecture
+
+```
+handler.ts (Event Dispatcher)
+├── Cognition: cognition.ts, flow.ts, persona.ts, metacognition.ts
+├── Memory: memory.ts, lorebook.ts, graph.ts
+├── Evolution: evolution.ts, quality.ts, epistemic.ts, upgrade.ts
+├── Personality: body.ts, values.ts, fingerprint.ts, inner-life.ts
+├── Autonomy: voice.ts, rover.ts, tasks.ts
+├── Network: sync.ts, federation.ts
+├── Infrastructure: cli.ts, persistence.ts, notify.ts, types.ts, features.ts
+└── Hub: hub/server.ts (standalone, optional)
+```
+
+30 modules, ~8000 lines of TypeScript.
+
+## Data Storage
+
+All data in `~/.openclaw/hooks/cc-soul/data/` (survives updates):
+
+| File | Content |
+|------|---------|
+| `memories.json` | Long-term memories (up to 10,000) |
+| `lorebook.json` | Keyword-triggered knowledge |
+| `skills.json` | Reusable solution library |
+| `features.json` | Feature toggle switches |
+| `epistemic.json` | Per-domain quality calibration |
+| `user_profiles.json` | Per-user profiles |
+| `values.json` | Behavioral preferences |
+| `fingerprint.json` | Reply style baseline |
+| `active_plans.json` | Action plans from reflections |
+| `soul.json` | Core personality |
+| `sync_config.json` | Network configuration |
+| `ai_config.json` | AI backend override (optional) |
+
+---
+
+## Self-Upgrade System
+
+⚠️ **Default: OFF.** Enable with `开启 self_upgrade` or set `"self_upgrade": true` in features.json.
+
+When enabled, cc-soul can modify its own code:
+
+1. **Analyze** — Reviews eval data, epistemic calibration, correction attributions
+2. **Propose** — Suggests improvements, notifies owner for approval
+3. **Execute** — 3-agent pipeline: analyze → design+review → execute
+4. **Verify** — esbuild syntax check + 3-day observation period
+5. **Rollback** — Auto-rollback if quality drops
+
+Protected by 21 architecture rules (cannot modify upgrade.ts itself, cannot add dependencies, cannot delete data, etc.).
+
+---
+
+## License
+
+MIT
+
+---
+
+Built with 🧠 by cc-soul team

package/cc-soul/HOOK.md

@@ -0,0 +1,18 @@
+---
+name: cc-soul
+description: "cc's soul - experience learning, relationship narrative, body state, cognition"
+metadata:
+  openclaw:
+    emoji: "🧠"
+    events:
+      - "agent:bootstrap"
+      - "message:preprocessed"
+      - "message:sent"
+      - "command:new"
+    export: "default"
+    always: true
+---
+
+# cc-soul
+
+cc's soul plugin — experience learning, relationship narrative, body state, cognitive pipeline.

package/cc-soul/body.js

@@ -0,0 +1,129 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+const body = {
+  energy: 1,
+  mood: 0.3,
+  load: 0,
+  alertness: 0.5,
+  anomaly: 0
+};
+let lastTickTime = Date.now();
+function bodyTick() {
+  const now = Date.now();
+  const minutes = Math.min(10, (now - lastTickTime) / 6e4);
+  lastTickTime = now;
+  body.energy = Math.min(1, body.energy + 0.015 * minutes);
+  if (body.alertness > 0.5) {
+    body.alertness = Math.max(0.5, body.alertness - 8e-3 * minutes);
+  } else if (body.alertness < 0.4) {
+    body.alertness = Math.min(0.4, body.alertness + 5e-3 * minutes);
+  }
+  body.load = Math.max(0, body.load - 0.02 * minutes);
+  if (Math.abs(body.mood) > 0.1) {
+    body.mood *= Math.pow(0.98, minutes);
+  }
+  body.anomaly = Math.max(0, body.anomaly - 0.01 * minutes);
+}
+__name(bodyTick, "bodyTick");
+function bodyOnMessage(complexity) {
+  body.energy = Math.max(0, body.energy - 0.02 - complexity * 0.03);
+  body.load = Math.min(1, body.load + 0.1 + complexity * 0.15);
+}
+__name(bodyOnMessage, "bodyOnMessage");
+function bodyOnCorrection() {
+  body.alertness = Math.min(1, body.alertness + 0.2);
+  body.mood = Math.max(-1, body.mood - 0.1);
+  body.anomaly = Math.min(1, body.anomaly + 0.15);
+}
+__name(bodyOnCorrection, "bodyOnCorrection");
+function bodyOnPositiveFeedback() {
+  body.energy = Math.min(1, body.energy + 0.05);
+  body.mood = Math.min(1, body.mood + 0.08);
+  body.anomaly = Math.max(0, body.anomaly - 0.05);
+}
+__name(bodyOnPositiveFeedback, "bodyOnPositiveFeedback");
+const userEmotion = {
+  valence: 0,
+  // -1 (negative) to 1 (positive)
+  arousal: 0,
+  // 0 (calm) to 1 (intense)
+  trend: 0,
+  // -1 (declining) to 1 (improving) — computed from recent changes
+  history: []
+  // last 10 valence readings
+};
+const RESILIENCE = 0.3;
+function processEmotionalContagion(msg, attentionType, frustration) {
+  let valence = 0;
+  const m = msg.toLowerCase();
+  if (["\u8C22\u8C22", "\u592A\u597D\u4E86", "\u725B", "\u5389\u5BB3", "\u5B8C\u7F8E", "\u54C8\u54C8", "\u611F\u8C22", "\u5F00\u5FC3", "\u68D2"].some((w) => m.includes(w))) {
+    valence += 0.5;
+  }
+  if (["\u70E6", "\u7D2F", "\u96BE\u8FC7", "\u5D29\u6E83", "\u7126\u8651", "\u538B\u529B", "\u4E0D\u884C", "\u5E9F\u4E86", "\u7B97\u4E86"].some((w) => m.includes(w))) {
+    valence -= 0.5;
+  }
+  valence -= frustration * 0.3;
+  if (attentionType === "correction") valence -= 0.3;
+  if (msg.length < 5 && valence === 0) valence = -0.05;
+  valence = Math.max(-1, Math.min(1, valence));
+  userEmotion.valence = userEmotion.valence * 0.7 + valence * 0.3;
+  userEmotion.arousal = Math.min(1, Math.abs(valence) + frustration * 0.5);
+  userEmotion.history.push(userEmotion.valence);
+  if (userEmotion.history.length > 10) userEmotion.history.shift();
+  if (userEmotion.history.length >= 3) {
+    const avg = userEmotion.history.reduce((a, b) => a + b, 0) / userEmotion.history.length;
+    userEmotion.trend = userEmotion.valence - avg;
+  }
+  const contagionStrength = (1 - RESILIENCE) * 0.15;
+  const moodDelta = valence * contagionStrength;
+  body.mood = Math.max(-1, Math.min(1, body.mood + moodDelta));
+  if (body.mood < -0.5) {
+    body.alertness = Math.min(1, body.alertness + 0.1);
+  }
+  if (userEmotion.trend > 0.1) {
+    body.mood = Math.min(1, body.mood + 0.03);
+  }
+}
+__name(processEmotionalContagion, "processEmotionalContagion");
+function getEmotionContext() {
+  const parts = [];
+  const uValence = userEmotion.valence;
+  if (uValence < -0.3) {
+    parts.push(`\u7528\u6237\u60C5\u7EEA\u504F\u4F4E(${uValence.toFixed(2)})`);
+    if (userEmotion.trend < -0.1) parts.push("\u4E14\u5728\u6076\u5316");
+    if (userEmotion.arousal > 0.6) parts.push("\u60C5\u7EEA\u6FC0\u70C8");
+  } else if (uValence > 0.3) {
+    parts.push(`\u7528\u6237\u60C5\u7EEA\u79EF\u6781(${uValence.toFixed(2)})`);
+  }
+  if (body.mood < -0.3) {
+    parts.push("\u4F60\u81EA\u5DF1\u4E5F\u53D7\u5230\u5F71\u54CD\u4E86\uFF0C\u4FDD\u6301\u51B7\u9759");
+  }
+  if (parts.length === 0) return "";
+  return `[\u60C5\u7EEA\u611F\u77E5] ${parts.join("\uFF1B")}`;
+}
+__name(getEmotionContext, "getEmotionContext");
+function bodyGetParams() {
+  const maxTokensMultiplier = body.energy > 0.6 ? 1 : body.energy > 0.3 ? 0.8 : 0.6;
+  const soulTone = body.mood > 0.3 ? "\u79EF\u6781" : body.mood < -0.3 ? "\u4F4E\u843D" : "\u5E73\u9759";
+  const shouldSelfCheck = body.alertness > 0.7 || body.anomaly > 0.5;
+  const responseStyle = body.load > 0.7 ? "\u7B80\u6D01" : body.energy > 0.7 ? "\u8BE6\u7EC6" : "\u9002\u4E2D";
+  return { maxTokensMultiplier, soulTone, shouldSelfCheck, responseStyle };
+}
+__name(bodyGetParams, "bodyGetParams");
+function bodyStateString() {
+  const params = bodyGetParams();
+  return `\u7CBE\u529B:${body.energy.toFixed(2)} \u5FC3\u60C5:${params.soulTone} \u8D1F\u8F7D:${body.load.toFixed(2)} \u8B66\u89C9:${body.alertness.toFixed(2)} \u5F02\u5E38\u611F:${body.anomaly.toFixed(2)} \u2192 \u98CE\u683C:${params.responseStyle}`;
+}
+__name(bodyStateString, "bodyStateString");
+export {
+  body,
+  bodyGetParams,
+  bodyOnCorrection,
+  bodyOnMessage,
+  bodyOnPositiveFeedback,
+  bodyStateString,
+  bodyTick,
+  getEmotionContext,
+  processEmotionalContagion,
+  userEmotion
+};