Claude Soul
Self-improving learning engine for Claude Code. Extracts signals from sessions (corrections, successes,confusion), runs periodic reflections, and evolves behavioral frameworks through evidence. 9 MCP tools, automatichooks, local-only.
What is Claude Soul?
Claude Soul is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to self-improving learning engine for claude code. extracts signals from sessions (corrections, successes,confusion), runs periodic reflections, and evolves behavioral frameworks through evidence. 9 mcp ...
Self-improving learning engine for Claude Code. Extracts signals from sessions (corrections, successes,confusion), runs periodic reflections, and evolves behavioral frameworks through evidence. 9 MCP tools, automatichooks, local-only.
This server falls under the Coding Agents category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Self-improving learning engine for Claude Code. Extracts sig
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx claude-soulConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Claude Soul
Claude Soul is a self-improving learning engine for Claude Code that makes your AI assistant smarter over time by learning from your actual sessions. It extracts signals from corrections, successes, and moments of confusion, runs periodic reflections at configurable thresholds, and evolves behavioral frameworks stored locally in ~/.soul/. The system provides 15 MCP tools covering identity, signal logging, reflection, memory search, and journaling — all operating entirely on your machine with no data leaving your device.
Prerequisites
- Node.js 18+ installed
- Claude Code CLI installed: npm install -g @anthropic-ai/claude-code
- Optional: Ollama running locally with the nomic-embed-text model for semantic memory search (keyword search works without it)
- An MCP-compatible Claude Code session (Claude Soul hooks into Claude Code's extension points)
Initialize Claude Soul
Run the init command with the --starter flag to scaffold the ~/.soul directory structure, write default config, and register the MCP server and hooks with Claude Code automatically.
npx claude-soul init --starterVerify the installation
Check that the MCP server is registered and the soul directory was created with the expected config file.
claude mcp list
# Should show claude-soul in the server list
ls ~/.soul/
# Should show config.json and initial framework filesReview and customize the config
Open the generated config to tune reflection thresholds, model selection (haiku is faster, sonnet is more thoughtful), context budget, and feature flags.
# ~/.soul/config.json key settings:
# reflection.thresholds.quick: 20 (signals before a quick reflection)
# reflection.thresholds.deep: 100 (signals before a deep reflection)
# reflection.model: "haiku" (or "sonnet" for richer reflections)
# context.maxTokens: 4500
# signals.maxLogSize: 51200 (50KB)Start a Claude Code session — hooks fire automatically
Open Claude Code normally. Claude Soul's hooks intercept session events to log signals, journal interactions, and inject soul context at the start of each conversation without any manual steps.
claudeManually trigger reflection or check status
You can invoke Claude Soul's MCP tools directly in a session to inspect state or force a reflection cycle.
# In a Claude Code session, ask:
"Run soul_status to show current signal count and last reflection time"
"Run soul_reflect to trigger a reflection now"
"Search memory for notes about TypeScript error handling"Upgrade to the latest version
Keep Claude Soul current to get the latest behavioral framework improvements.
claude-soul upgradeClaude Soul Examples
Client configuration
Claude Soul registers itself via the init command. If you need to add it manually to claude_desktop_config.json:
{
"mcpServers": {
"claude-soul": {
"command": "npx",
"args": ["claude-soul"]
}
}
}Prompts to try
Use these prompts inside Claude Code to interact with Claude Soul's memory and learning tools:
- "Call soul_context to load my behavioral frameworks for this session"
- "Log a signal: I prefer explicit type annotations over inferred types in TypeScript"
- "Search my memory for previous notes about database migration patterns"
- "Show soul_stats — how many signals have been collected and when did I last reflect?"
- "Run a deep reflection on my last 100 signals and update my behavioral frameworks"Troubleshooting Claude Soul
soul_context returns empty or no frameworks on session start
The system needs a few sessions worth of signals before meaningful frameworks emerge. Run 'claude-soul index' from the terminal to rebuild the index if you have existing sessions that haven't been processed yet.
Semantic memory search returns no results
Semantic search requires Ollama running locally with the nomic-embed-text model: 'ollama pull nomic-embed-text'. Without it, only keyword search is available. Verify Ollama is running with 'ollama list'.
Hooks are not firing between sessions
Check that the hooks were written to ~/.claude/settings.json during init. If missing, re-run 'npx claude-soul init --starter'. Hooks require Claude Code 1.0+ and will silently do nothing on older versions.
Frequently Asked Questions about Claude Soul
What is Claude Soul?
Claude Soul is a Model Context Protocol (MCP) server that self-improving learning engine for claude code. extracts signals from sessions (corrections, successes,confusion), runs periodic reflections, and evolves behavioral frameworks through evidence. 9 mcp tools, automatichooks, local-only. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Claude Soul?
Follow the installation instructions on the Claude Soul GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Claude Soul?
Claude Soul works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Claude Soul free to use?
Yes, Claude Soul is open source and available under the MIT License license. You can use it freely in both personal and commercial projects.
Claude Soul Alternatives — Similar Coding Agents Servers
Looking for alternatives to Claude Soul? Here are other popular coding agents servers you can use with Claude, Cursor, and VS Code.
Dify
★ 142.2kProduction-ready platform for agentic workflow development.
Ruflo
★ 54.0k🌊 The leading agent orchestration platform for Claude. Deploy intelligent multi-agent swarms, coordinate autonomous workflows, and build conversational AI systems. Features enterprise-grade architecture, self-learning swarm intelligence, RAG integrat
Goose
★ 45.7kan open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM
Antigravity Awesome Skills
★ 38.3kInstallable GitHub library of 1,400+ agentic skills for Claude Code, Cursor, Codex CLI, Gemini CLI, Antigravity, and more. Includes installer CLI, bundles, workflows, and official/community skill collections.
AgentScope
★ 25.5kBuild and run agents you can see, understand and trust.
Serena
★ 24.5kA coding agent toolkit that provides IDE-like semantic code retrieval and editing tools, enabling LLMs to efficiently navigate and modify codebases using symbol-level operations instead of basic file reading and string replacements.
Browse More Coding Agents MCP Servers
Explore all coding agents servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Claude Soul in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Claude Soul?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.