DomDemetz/claude-soul

> Claude Code forgets everything between sessions. Claude Soul doesn't.
One command. No API key, no cloud, everything local.
**Prerequisites:** Node.js >= 18, Claude Code (Pro or Max plan).
Three things it does
1. Remembers across sessions
Cross-session memory with semantic search. Facts, decisions, lessons — all searchable by meaning, not just keywords. Uses local SQLite + optional Ollama embeddings.
2. Tracks your corrections
Every time you correct your Claude — "that's wrong", "you missed this", "stop doing that" — the system detects the pattern, classifies it, and tracks whether it's getting better or worse.
Patterns move through lifecycle stages: **new → active → improving → internalized**. After 200 sessions of real data: robot_mode went from 0.8 corrections/session to zero.
3. Develops judgment over time
The system extracts behavioral signals from every session and periodically reflects on them. Frameworks that keep working get promoted. Bad ones get retired. After a few weeks, you get a Claude that pushes back on bad ideas, catches its own confabulation, and develops techniques you never prompted.
Install
Quick start (no extra dependencies)
Add this to your CLAUDE.md:
Done. Memory works with keyword search, everything else runs automatically.
With semantic memory
Semantic search finds memories by meaning — "auth decision" finds a memory stored as "chose JWT tokens for login." Without it, search is keyword-based (still works, just less flexible).
The system auto-detects Ollama. No configuration needed.
For agents (non-interactive)
Skips the name/context questions. Add the CLAUDE.md snippet to your agent's working directory and it works the same way — memory, correction tracking, and framework evolution all run through Claude Code's hooks and MCP server regardless of whether a human is typing or an agent is running.
Already installed? Upgrade
Your soul files, frameworks, and data stay untouched. The upgrade re-registers hooks and MCP server with the latest version and adds any new features.
After upgrading, run claude-soul index once to backfill existing data into the memory system.
What's new in v0.2
- **Memory system** — 6 new MCP tools (memory_save, memory_search, recall, etc.) for cross-session fact storage with semantic search
- **Correction tracking** — auto-detects when you correct your Claude and classifies the pattern
- **Shadow analysis** — claude-soul shadow shows behavioral patterns with trend arrows and lifecycle stages
- **Indexing** — claude-soul index loads your existing journals and soul files into the memory database
CLI commands
These are optional — the system runs automatically. The CLI is for inspecting collected data from your terminal.
| Command | What it does |
|---------|-------------|
| claude-soul status | System health — frameworks, signals, phase |
| claude-soul shadow | Your correction patterns with trends |
| claude-soul shadow --generate | Auto-generate a SHADOW.md from your data |
| claude-soul index | Index existing files into memory database |
| claude-soul upgrade | Update hooks without touching your data |