CC-Soul
Persistent memory and code intelligence for Claude Code.
Claude Code that learns how you work.
📖 Documentation & Architecture →
What It Does
CC-soul gives Claude Code persistent memory across sessions. It learns your preferences, remembers your codebase structure, anticipates your needs, and gets smarter the more you use it. One command to install. Zero commands to operate.
What's New in v5.3.0
- FEP attractor network — self-orthogonalizing memory representations derived from the Free Energy Principle (Spisak & Friston, 2026). Memories naturally decorrelate, resist catastrophic forgetting, and support attractor-based pattern completion.
- Asymmetric couplings — prototype transitions and triplet weights now encode directionality. Sequential data produces asymmetric connections (A→B ≠ B→A), enabling non-equilibrium dynamics in the association graph.
- Surprise-modulated plasticity — reconstruction error (how poorly the sparse encoder predicts a memory) modulates decay rate. Surprising memories resist forgetting; predictable ones fade faster.
- Attractor recall — new cortical recall path that iteratively settles partial cues into stored attractor basins via prototype blending and directed transition following.
- Hopfield network — asymmetric energy-based attractor network over memory co-activations. Pattern completion propagates through multi-hop directed couplings.
- Free-energy merge criterion — deduplication now uses a principled accuracy-vs-complexity tradeoff instead of a pure cosine threshold.
- Self-orthogonalizing encoder — Hebbian update replaced with FEP-derived rule: prediction error + complexity penalty + Gram-Schmidt decorrelation between active atoms.
What's in v5.0.0
- HNSW semantic index — activates automatically above 2,000 memories; falls back to IVF+LSH below that threshold. Dense recall at scale without configuration.
- PoE domain reliability — corrections automatically lower recall scores for the domain they target. Mistakes don't just get overwritten — the field learns not to trust that area.
- chitta_thinking — mines Claude's
thinking blocks for perception-change moments every 10 turns. Internal reasoning becomes a memory source.
- chitta_migrate — unified migration tool that auto-detects
soul.db or chitta.duckdb and handles either without manual configuration.
- MacOS portability — all Linux-only APIs guarded with
#ifdef __linux__. The daemon builds and runs on macOS.
- FilterLevel on BM25 code ingestion — Signatures-only or MinimalContext modes for leaner code indexing in chitta-field.
- recall_with_fallback chain — semantic → BM25 → recency. Recall never returns empty.
- Pre-tool hook —
cat on files >500 lines is intercepted: a compact alternative runs instead and the original call is blocked (exit 2). Destructive commands (rm -rf /, dd to raw devices) are blocked outright. Output-type-aware recall: TestResults, BuildOutput, LogOutput routed separately.
- Turn discipline — warns after 15 turns without storing a memory, prompting consolidation.
- Milestone auto-detection — milestones detected in conversation are stored directly via the write queue.
- chitta-research — autonomous research system built on chitta-field. See section below.
Before & After
Without cc-soul:
You: "How should I handle caching?"
Claude: [Generic answer]
You: "No, we tried Redis already. Remember?"
Claude: "I don't have context from previous sessions..."
With cc-soul:
You: "How should I handle caching?"
Claude: "We tried Redis in week 2 and it was too slow. In-memory LRU worked better — that's what we shipped."
Quick Start
# 1. Register marketplace
claude marketplace add https://github.com/genomewalker/cc-soul
# 2. Install plugin
claude plugin add cc-soul@genomewalker-cc-soul
Or manual installation:
git clone https://github.com/genomewalker/cc-soul.git
cd cc-soul && ./scripts/smart-install.sh
How It Works
genomewalker