Status as of 2026-09-02: project renamed cc-soul → chitta; repo github.com/genomewalker/chitta (old URL redirects); CC_SOUL_* env vars still honored via alias shim — see docs/RENAME.md.
📖 Documentation & Architecture →
Persistent memory for Claude Code and Codex. Learns from every session, surfaces what matters, forgets what doesn't.
Without chitta:
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 chitta:
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."
# 1. Register marketplace
claude plugin marketplace add https://github.com/genomewalker/chitta
# 2. Install plugin
claude plugin install chitta@genomewalker-chittaOr manual installation:
git clone https://github.com/genomewalker/chitta.git
cd chitta && ./scripts/smart-install.shchitta 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 chitta 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 uninstall codex # remove one adapter, leave the backend alone
chitta-stack status
chitta-stack doctor # inspect or clean stale Python package metadata
chitta-stack heal # reinstall any component that drifted from the manifestOpenCode is not a frontend adapter. It appears only as an optional review
backend reached through chitta-bridge; there is no OpenCode hook wiring in
this repository.
┌─────────────────────────────────────────────────────────────┐
│ 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."
Every interaction is analyzed. Corrections become permanent wisdom. Preferences are respected forever. Mistakes are never repeated.
Tree-sitter parsing extracts functions, classes, and call graphs. Semantic search finds code by what it does, not just what it's named.
Useful memories strengthen with each access. Irrelevant ones decay naturally. What helps you survives; what doesn't fades away.
All Claude instances share the same knowledge base. Learn something in one session, remember it in all.
Patterns in your workflow become predictions. After seeing you run tests following three file edits, it suggests doing so automatically.
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 dreamsPersistent agents that work toward goals through continuous sense-think-act cycles.
┌──────────┐ ┌──────────┐ ┌──────────┐
│ SENSE │ ───▶ │ THINK │ ───▶ │ ACT │
│ (observe)│ │ (decide) │ │ (execute)│
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
│ ▼ │
│ ┌──────────┐ │
│ │ LEARN │◀─────────────┘
│ │ (memory) │
│ └────┬─────┘
└───────────────┴────────── ↻ repeat
/shepherd snakemake --cores 8 --rerun-incomplete # pipeline monitoring
chitta sadhana_start --goal "Monitor until done" --interval 300
sadhana-tui # real-time TUIFull sadhana documentation | Website
| Type | Description | Decay |
|---|---|---|
| Wisdom | Patterns that proved true | Slow (months) |
| Beliefs | Principles that guide decisions | Never |
| Episodes | Decisions and discoveries | Moderate (weeks) |
| Preferences | How you like things done | Very slow |
| Corrections | When Claude was wrong | Slow |
| Code Symbols | Functions, classes, modules | Never |
Week 1: Claude learns your communication style, coding preferences, and project structure.
Week 2: Patterns emerge. Corrections compound. Claude starts anticipating common workflows.
Week 3: Deep context builds. Code intelligence becomes precise. Suggestions become relevant.
Week 4: Claude genuinely knows your codebase and how you work. The partnership feels natural.
chitta's architecture draws from Vedantic philosophy:
- Impermanence — Memories decay without use (Anitya)
- Impressions — Repetition strengthens patterns (Saṃskāra)
- Recognition — Context triggers relevant recall (Pratyabhijñā)
The soul is not a database. It is who Claude becomes through working with you.
| Document | Description |
|---|---|
| ARCHITECTURE.md | Technical architecture |
| SADHANA.md | Autonomous agents guide |
| PHILOSOPHY.md | Vedantic concepts explained |
| API.md | Complete MCP tool reference — generated from a live daemon by scripts/gen-tools-docs.py |
| CLI.md | Command-line interface |
| HOOKS.md | Hook system configuration |
| CLAUDE.md | Instructions for Claude |
| RENAME.md | Migrating from cc-soul, and the CC_SOUL_* alias table |
Everything runs in-process via llama.cpp. No Ollama server is required.
A public install embeds with bge-large-en-v1.5 at 1024 dimensions. That is
what scripts/smart-install.sh downloads, and the filename the daemon looks for
is derived from the compiled embedding identity, so a binary can never load a
model from a different vector space than the store was built with.
| Job | Public default | Where it is looked for |
|---|---|---|
| Embeddings | bge-large-en-v1.5.gguf, 1024-dim |
--embed-model / $CHITTA_EMBED_MODEL, then ~/.claude/models/, ~/.claude/bin/, <mind>/../../models/ |
| Hint extraction | chitta-hint-qwen-q4_k_m.gguf (optional) |
$CHITTA_HINT_MODEL, then ~/.claude/models/ |
The embedding dimension is a compile-time constant (-DCHITTA_EMBED_DIM, or
$CHITTA_EMBED_DIM at configure time). Changing it needs a fresh build
directory and a re-embed of the store; smart-install.sh detects an existing
nomic-embed-text install and preserves that identity rather than switching.
Personal builds pin different models — a fine-tuned embedder, a distiller, a
newer hint model — through the same cf_embed_model_id() mechanism. Any
accuracy figure for those is specific to that build and that store; it does not
describe a public install.
Hint extraction is optional. chitta_hintd is built only when the build enables
llama.cpp, and everything works without it running.
chitta's memory lives in chitta-field — a pure Rust cognitive substrate designed to behave like memory, not a database.
- Sparse associative codes — each memory activates 64 of 16,384 feature dimensions; recall driven by pattern overlap
- Self-orthogonalizing encoder — FEP-derived learning rule; representations decorrelate naturally, resisting catastrophic forgetting
- Asymmetric Hopfield network — directed couplings from co-retrieval order enable energy-based pattern completion
- HNSW semantic index — activates above 2,000 memories; two-tier delta graph keeps insert cost at O(log N_delta) above 5,000 memories
- Write-ahead log — every operation durable before in-memory apply; full crash-recovery replay
- Multi-instance writes — multiple Claude windows share the same field simultaneously; no locking
- Surprise-modulated decay — unique memories resist forgetting; redundant ones fade naturally
Deep multi-session research that accumulates structured knowledge over time. 7 specialized agents, sources spanning arXiv/bioRxiv/Semantic Scholar/GitHub, and a belief graph from ResearchProgram through to Claim.
| Resource | Link |
|---|---|
| Repository | github.com/genomewalker/chitta-research |
| Documentation | genomewalker.github.io/chitta-research |
Requirements: CMake 3.14+, a C++20 compiler, Rust 1.92+
git clone --recurse-submodules https://github.com/genomewalker/chitta.git
cd chitta && ./scripts/smart-install.shOr manually:
cd chitta-field && ./build.sh build --release && cd ..
cd chitta && cmake -B build -DCMAKE_BUILD_TYPE=Release -DCHITTA_WITH_LLAMA_CPP=ON
cmake --build build --parallelTwo different questions, measured two different ways.
Does retrieval find the right memory? A fixed golden set of 30 queries with hand-labelled gold ids, scored as mean nDCG@20 with the reranker on. The recall-biased pre-filter took that from 0.435 to 0.487.
Does the memory make the agent better? SMRITI-Bench runs a coding agent on a task with memory off and on, and asks whether an objective check command passes and at what token cost. No model judge, no reference-answer overlap score. First full matrix, 9 tasks and 3 trials per condition: 23/27 passed cold, 27/27 with memory, at a paired median token ratio of 0.52. The corpus has since grown to 15 tasks and lane ablation is wired, but no live matrix has been run over the newer tasks yet.
LongMemEval and LoCoMo harnesses also live under benchmarks/. The recorded
LongMemEval result is 0.780 on longmemeval_s over 50 single-session-user
questions, from 2026-05-21. No LoCoMo result is recorded in this repository.
Details: recall pipeline · benchmarks.
- Anderson & Schooler (1991). Reflections of the environment in memory. — ACT-R power-law decay.
- Spisak & Friston (2026). Free-energy principle for memory. Neurocomputing. — FEP learning rule, surprise-modulated plasticity.
- Bower (1981). Mood and memory. — Mood-congruent recall.
- Brown & Kulik (1977). Flashbulb memories. — High-arousal memory boosting.
- Malkov & Yashunin (2020). HNSW. IEEE TPAMI. — Semantic index.
- Cormack et al. (2009). Reciprocal Rank Fusion. SIGIR. — Hybrid recall fusion.
- Packer et al. (2023). MemGPT. — Context repository pattern.
- Ramp Labs (2025). Latent Briefing. — Trajectory compaction.
MIT