Clawhub Skill

Zero-vector AI memory engine with self-learning. LOCOMO 76.2% (4th place). 15 original algorithms, open source (MIT).

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:

Type	Accuracy
open_domain	89.4%
single_hop	84.8%
multi_hop	65.7%
temporal_reasoning	62.5%
adversarial	56.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:

Persona	Triggers
Engineer	Technical questions, code, debugging
Friend	Casual chat, personal topics
Mentor	Career advice, growth discussions
Analyst	Comparisons, data-driven decisions
Comforter	Stress, frustration, emotional messages
Strategist	Planning, long-term decisions
Explorer	Brainstorming, open-ended questions
Executor	Task execution, step-by-step guides
Teacher	Explanations, learning requests
Devil's Advocate	When user needs pushback
Socratic	When 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

Metric	Value
Recall latency (p50)	127ms
Storage	5.7 MB (vs 49.2 MB for vectors — 8.6x smaller)
External API calls	0 (pure algorithm)
LLM dependency	Optional (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.