Clawhub Skill

What is cc-soul?#

A zero-vector AI memory engine that learns and improves from every conversation — no vectors, no embeddings, no GPU.

Benchmark#

LOCOMO (Long-term Conversational Memory) — the standard benchmark for AI memory systems:

TypeAccuracyopen_domain89.4%single_hop84.8%multi_hop65.7%temporal_reasoning62.5%adversarial56.5%TOTAL****76.2% (4th place globally)

The only symbolic (non-vector) system in the top 5. All systems above use vector databases + LLM; cc-soul uses pure algorithmic recall.

Install & Start#

bash

npm install @cc-soul/openclaw
# API auto-starts at localhost:18800

Verify: curl http://localhost:18800/health

If auto-start didn't work, start manually:

bash

node ~/.openclaw/plugins/cc-soul/cc-soul/soul-api.js
# or: node node_modules/@cc-soul/openclaw/cc-soul/soul-api.js
# custom port: SOUL_PORT=9900 node ~/.openclaw/plugins/cc-soul/cc-soul/soul-api.js

Requires Node.js 20+.

API — How to Use#

Base URL: http://localhost:18800 (configurable via SOUL_PORT env var)

POST /memories — Store a memory#

bash

curl -X POST http://localhost:18800/memories \
  -H "Content-Type: application/json" \
  -d '{"content": "Alice prefers Python over Java", "user_id": "alice"}'

Response: {"stored": true, "facts_extracted": 2}

POST /search — Search memories#

bash

curl -X POST http://localhost:18800/search \
  -H "Content-Type: application/json" \
  -d '{"query": "programming language preference", "user_id": "alice", "top_n": 5}'

Response:

json

{
  "memories": [{"content": "Alice prefers Python over Java", "scope": "fact", "confidence": 0.85}],
  "facts": [{"predicate": "prefers", "object": "Python", "confidence": 0.9}],
  "fact_summary": "Prefers Python over Java"
}

GET /health — Health check#

bash

curl http://localhost:18800/health

Response: {"status": "ok", "version": "3.2.2", "memoryCount": 1234, "factCount": 567}

LLM Configuration (optional — user self-service)#

Create ~/.cc-soul/data/ai_config.json:

json

{
  "backend": "openai-compatible",
  "api_base": "https://api.deepseek.com/v1",
  "api_key": "your-key-here",
  "api_model": "deepseek-chat"
}

Without LLM: core recall works locally in <30ms. With LLM: adds query rewriting + result reranking. Users configure their own API key — cc-soul never provides or manages LLM credentials.

How It Works#

AAM (Adaptive Associative Memory) — Self-Learning#

cc-soul builds a word association network from conversations. The more you talk, the smarter recall becomes.

• Learning: Every message updates word co-occurrence statistics (PMI-based)
• Expansion: When you search "marathon", AAM automatically expands to related words like "running", "race", "training" — learned from YOUR conversations, not a pre-built dictionary
• Graduation: Strong associations (PMI > 3.0) auto-promote to synonym table — zero manual maintenance
• Learning curve: Hit@3 improves from 30% → 67.5% over 1200 messages (+37.5%)

NAM (Neural Activation Memory) — 9-12 Signal Fusion#

Every memory has a real-time activation score computed from multiple signals:

1. Base activation (ACT-R): frequency + recency decay
2. Context match (BM25+): keyword matching with IDF weighting + phrase detection
3. Emotion resonance: mood-congruent recall (happy → recalls happy memories)
4. Spreading activation: related memories activate each other via AAM network
5. Interference suppression (MMR): prevents redundant results
6. Temporal encoding: time-context matching
7. Sequential co-occurrence (PAM): conversation flow patterns

Three-Layer Distillation#

text

L1: Raw memories (thousands)
  → every 6h →
L2: Topic nodes (~80, with hit/miss scoring)
  → every 12h →
L3: Mental model (identity / style / facts / dynamics)

Topic nodes that score low (miss > hit) are automatically retired. High-scoring nodes promote to core memory.

CNAS Query Dispatch#

Different questions need different strategies:

• precise ("What does Alice like?") → strict BM25, topic partition
• temporal ("When did we discuss...?") → time signal boost, date matching
• multi_entity ("How do Alice and Bob differ?") → coverage rerank, iterative recall
• broad ("Tell me about...") → full scan, relaxed matching

PADCN Emotion System — 5-Dimensional Mood Tracking#

cc-soul tracks user emotion in real-time across 5 dimensions:

• Pleasure / Arousal / Dominance / Certainty / Novelty
• Mood-congruent recall: when you're happy, positive memories surface more easily
• Flashbulb effect: highly emotional memories are stored stronger and recalled faster
• Emotion influences persona selection automatically

11 Auto-Switching Personas#

cc-soul dynamically blends personas based on conversation context:

PersonaTriggersEngineerTechnical questions, code, debuggingFriendCasual chat, personal topicsMentorCareer advice, growth discussionsAnalystComparisons, data-driven decisionsComforterStress, frustration, emotional messagesStrategistPlanning, long-term decisionsExplorerBrainstorming, open-ended questionsExecutorTask execution, step-by-step guidesTeacherExplanations, learning requestsDevil's AdvocateWhen user needs pushbackSocraticWhen user says "帮我理解" / "guide me"

No manual switching needed — persona adapts automatically based on what you're saying.

Self-Learning Feedback Loop#

cc-soul improves itself from every interaction:

1. AAM learns word associations from every message
2. Recall Thermostat adjusts signal weights based on which recalled memories the user actually engaged with
3. Topic Tournament scores topic nodes by hit/miss ratio — low-quality summaries get retired
4. PMI Graduation promotes strong word associations to synonym table automatically
5. Correction Learning stores corrections with Bayesian verification over 3 conversations

The system gets measurably better over time: Hit@3 improves 30% → 67.5% over 1200 messages.

Performance#

MetricValueRecall latency (p50)127msStorage5.7 MB (vs 49.2 MB for vectors — 8.6x smaller)External API calls0 (pure algorithm)LLM dependencyOptional (recall works without LLM)

Technical Specs#

• 75 modules, 15 original algorithms, ~29K lines TypeScript
• SQLite local storage, zero cloud, zero telemetry
• REST API: POST /memories, POST /search, GET /health
• Compatible with DeepSeek, Claude, OpenAI, Ollama, or any OpenAI-compatible API
• Open source: https://github.com/wenroudeyu-collab/cc-soul (MIT)

Data & Privacy#

• All data in ~/.cc-soul/data/ (SQLite)
• PII auto-filtering (emails, phone numbers, API keys stripped)
• Zero external network calls unless user configures optional LLM
• Full data export/delete available

Open Source & Security#

cc-soul is fully open source under MIT license. All source code (TypeScript) is included in this package and on GitHub.

• Source code: https://github.com/wenroudeyu-collab/cc-soul
• License: MIT — free to use, modify, and redistribute
• Security audit: All code is readable. No obfuscation. Review any file before running.
• child_process usage: Used to call local LLM CLI for optional query rewriting. No remote shell execution.
• Network calls: Only to user-configured LLM endpoint (api_base in ai_config.json). Zero calls if no LLM configured.
• notify.ts: Local notification hooks for OpenClaw plugin integration. No external service calls.

If you have security concerns, read the source. Every line is open.