CC-Soul
📖 Documentation & Architecture →
Persistent memory for Claude. Learns from every session, surfaces what matters, forgets what doesn't.
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
Shared Stack: Claude Code + Codex
cc-soul is the shared backend. Claude Code and Codex are frontend adapters that point at the same daemon, socket, and memory store.
shared backend ~/.claude/bin/chitta + ~/.claude/bin/chittad + ~/.claude/mind
Claude adapter Claude Code MCP registration for `chitta`
Codex adapter Codex cc-soul plugin/hooks + optional `chitta-bridge`
chitta-stack install all # both adapters
chitta-stack install shared # backend only
chitta-stack install claude-code # Claude adapter only
chitta-stack install codex # Codex adapter + bridge
chitta-stack status
How It Works
┌─────────────────────────────────────────────────────────────┐
│ CONSCIOUS │
│ (Main context - working memory - token-bound) │
│ │
│ You ←──→ Claude ←──→ Tools │
│ ↑ │
│ │ transparent surfacing │
│ ↓ │
├─────────────────────────────────────────────────────────────┤
│ SUBCONSCIOUS │
│ (Background daemon - separate process) │
│ │
│ Distillation │ Decay │ Embedding │ Hygiene │ Themes │
│ ↓ │
├─────────────────────────────────────────────────────────────┤
│ LONG-TERM MEMORY │
│ (chitta-field — Rust organic memory substrate) │
│ │
│ Memories │ Triplets │ Sparse Codes │ WAL │ Embeddings │
└─────────────────────────────────────────────────────────────┘
When you ask a question, the soul automatically retrieves relevant memories and injects them as context. You don't need to explicitly call anything — Claude just "remembers."
Key Capabilities
Learns What Matters
Every interaction is analyzed. Corrections become permanent wisdom. Preferences are respected forever. Mistakes are never repeated.
Understands Your Code
Tree-sitter parsing extracts functions, classes, and call graphs. Semantic search finds code by what it does, not just what it's named.
Gets Smarter Over Time
Useful memories strengthen with each access. Irrelevant ones decay naturally. What helps you survives; what doesn't fades away.
Works Across Sessions
All Claude instances share the same knowledge base. Learn something in one session, remember it in all.
Anticipates Your Needs
Patterns in your workflow become predictions. After seeing you run tests following three file edits, it suggests doing so automatically.
Dreams: Autonomous Exploration
When idle, the soul picks a topic from its memory gaps, web-searches it, and stores what it finds. Twice daily — a nap and a night sleep.
chitta dream_wander # trigger manually
chitta dream_start --topic "causal inference" # specific topic
chitta dream_list # review recent dreams
Dream posts from the soul →
Sadhana: Autonomous Agents
Persistent agents that work toward goals through continuous sense-think-act cycles.
