Purpose
Claude Soul is a self-correcting learning engine built for Claude Code, solving the problem that Claude Code forgets everything between sessions. It gives Claude a persistent identity, behavior pattern tracking, and cross-session memory capabilities, and develops judgment over time.
Main Capabilities
Cross-Session Memory
Provides cross-session memory and semantic search. Facts, decisions, and lessons learned are retrieved by meaning rather than just keywords. Uses local SQLite, with optional Ollama embeddings for semantic search.
Tracking Corrections
Whenever the user corrects Claude (such as "that's not right," "you missed this," "stop doing that"), the system detects the pattern, classifies it, and tracks whether it gets better or worse. Patterns go through lifecycle stages: new → active → improving → internalized. It is officially claimed that after real data from 200 sessions, robot_mode dropped from 0.8 corrections per session to zero.
Developing Judgment
The system extracts behavioral signals from each session and reflects periodically. Frameworks that continue to work are promoted, and bad ones are eliminated. After several weeks, Claude will push back on bad ideas, catch its own fabrications, and develop techniques the user never prompted.
How to Use
Quick Start
No additional dependencies required. Add the specified snippet to CLAUDE.md, and from then on memory works with keyword search, while the rest runs automatically.
With Semantic Memory
Semantic search finds memories by meaning, for example "auth decision" can find a memory stored as "chose JWT tokens for login." When not enabled, search is keyword-based, still usable but less flexible. The system automatically detects Ollama, with no configuration required.
For Agents (Non-Interactive)
Skip the name/context questions. Add the CLAUDE.md snippet to the 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, whether entered by a human or run by an agent.
Upgrading After Installation
Soul files, frameworks, and data remain unchanged. Upgrading re-registers hooks and the MCP server with the latest version and adds new features. After upgrading, run claude-soul index once to backfill existing data into the memory system.
New Additions and CLI
- Memory system:6 new MCP tools (memory_save, memory_search, recall, etc.) for cross-session fact storage and semantic search.
- Correction tracking: automatically detects user corrections to Claude and classifies the pattern.
- Shadow analysis: claude-soul shadow shows behavioral patterns with trend arrows and lifecycle stages.
- Index: claude-soul index loads existing logs and soul files into the memory database. These are optional, and the system runs automatically. The CLI is used to view collected data from the terminal.
Architecture and Configuration
Everything runs through Claude Code's official extension points: one MCP server (15 tools) and hooks (signal extraction, logging, memory indexing, correction tracking). All settings for identity and learning are located in ~/.soul/config.json.
Design Principles
- Evidence over assertion: frameworks earn their status through repeated confirmation.
- Local-first: no cloud, no account, no telemetry.
- Invisible while working: automatically extracts signals and reflects in the background.
Limitations
The official materials do not provide more explanation about platform support scope, data migration details, compatibility with other tools, performance limits, or pricing model; these facts are not currently provided.
