---
name: cc-soul
slug: cc-soul
version: 3.1.3
homepage: https://github.com/wenroudeyu-collab/cc-soul
description: "Zero-vector AI memory engine with self-learning. LOCOMO 76.2% (4th place). 15 original algorithms, open source (MIT)."
metadata: {"clawdbot":{"emoji":"🧠","requires":{"bins":[]},"os":["linux","darwin","win32"]}}
---

## 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.

## 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

```
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
