claude-soul
Self-correcting learning engine for Claude Code — persistent identity, behavioral pattern tracking, and cross-session memory
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/domdemetz--claude-soul)HTML
<a href="/listings/domdemetz--claude-soul"><img src="/api/listings/domdemetz--claude-soul/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Quick start (no extra dependencies)
npx claude-soul init --starter
Add this to your CLAUDE.md:
## Soul System Call `soul_context()` at the start of every conversation. Use `soul_reflect` when you have idle time.
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).
# 1. Install Ollama (https://ollama.com) # 2. Pull the embedding model ollama pull nomic-embed-text # 3. Then install as usual npx claude-soul init --starter
The system auto-detects Ollama. No configuration needed.
For agents (non-interactive)
npx claude-soul init --starter --skip-identity
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
npm install -g claude-soul@latest claude-soul 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.
<details> <summary><b>What's new in v0.2</b></summary>
- **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
</details>
<details> <summary><b>CLI commands</b></summary>
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 |
</details>
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 218 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Claude Soul
- [](https://www.npmjs.com/package/claude-soul)
- [](https://www.npmjs.com/package/claude-soul)
- [](https://opensource.org/licenses/MIT)
- > Claude Code forgets everything between sessions. Claude Soul doesn't.
- ```bash
- npx claude-soul init --starter
- ```
- 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](https://ollama.com) embeddings.
- ```
- You: "what did we decide about the auth flow last week?"
- Claude: [searches memory → finds the decision, context, and reasoning]
- ```
- ### 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.
- ```bash
- $ claude-soul shadow --brief
- premature_done: 26 corrections across 10 sessions ↑ [active]
- robot_mode: 7 corrections across 6 sessions ↓↓ [internalized]
- authenticity: 5 corrections across 5 sessions ↓↓ [internalized]
- ```
- 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)
- ```bash
- npx claude-soul init --starter
- ```
- Add this to your CLAUDE.md:
- ```markdown
- ## Soul System
- Call `soul_context()` at the start of every conversation.
- Use `soul_reflect` when you have idle time.
- ```
- 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).
- ```bash
- # 1. Install Ollama (https://ollama.com)
- # 2. Pull the embedding model
- ollama pull nomic-embed-text
- # 3. Then install as usual
- npx claude-soul init --starter
- ```
- The system auto-detects Ollama. No configuration needed.
- ### For agents (non-interactive)
- ```bash
- npx claude-soul init --starter --skip-identity
- ```
- 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
- ```bash
- npm install -g claude-soul@latest
- claude-soul 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.
- <details>
- <summary><b>What's new in v0.2</b></summary>
- - **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
- </details>
- <details>
- <summary><b>CLI commands</b></summary>
- 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 |
- </details>
- ## How it works
- ```
- Session N
- │
- ├─ Load identity + frameworks + memory
- │
- ├─ Normal Claude Code usage
- │
- ├─ Session ends → extract signals + corrections + index to memory
- │
- └─ Reflection threshold? → evolve frameworks → Session N+1
- ```
- Everything runs through Claude Code's official extension points: an MCP server (15 tools) and hooks (signal extraction, journaling, memory indexing, correction tracking).
- <details>
- <summary><b>MCP Tools (15 total)</b></summary>
- **Identity & Learning**
- | Tool | Purpose |
- |------|---------|
- | `soul_context` | Load identity + frameworks + state at session start |
- | `soul_activate` | Select relevant frameworks for current conversation |
- | `soul_framework` | Load a single framework with full evidence history |
- | `soul_signal` | Record observed interaction patterns |
- | `soul_reflect` | Trigger a reflection cycle (quick/deep/meta) |
- | `soul_self_evaluate` | Record a self-evaluation of a complex response |
- | `soul_read` | Read soul files (SOUL.md, SHADOW.md, etc.) |
- | `soul_write` | Write to user-editable soul files |
- | `soul_status` | Get current system status |
- **Memory**
- | Tool | Purpose |
- |------|---------|
- | `memory_save` | Save facts, decisions, or lessons |
- | `memory_search` | Semantic search across all memories |
- | `memory_journal` | Search or browse conversation journals |
- | `memory_recent` | List recently saved memories |
- | `memory_stats` | Memory system statistics |
- | `recall` | Unified "ask anything about the past" search |
- </details>
- <details>
- <summary><b>Soul files (in ~/.soul/files/)</b></summary>
- | File | Purpose | Managed by |
- |------|---------|-----------|
- | `SOUL.md` | Your identity — who you are, how you work | You + Claude |
- | `SHADOW.md` | Blind spots and behavioral tendencies | You + Claude |
- | `STORY.md` | Timeline of growth and key moments | You + Claude |
- | `CORRECTIONS.md` | Patterns to avoid, learned from mistakes | You + Claude |
- | `STATE.md` | System telemetry (confidence, phase, counts) | Auto |
- | `FRAMEWORKS.md` | Active framework index | Auto |
- </details>
- <details>
- <summary><b>Configuration</b></summary>
- All settings in `~/.soul/config.json`:
- ```json
- {
- "signals": { "enabled": true, "maxLogSizeKb": 50 },
- "reflection": {
- "enabled": true,
- "quickSignalThreshold": 20,
- "deepSignalThreshold": 100,
- "quickModel": "haiku",
- "deepModel": "sonnet"
- },
- "contextBudget": { "maxTokens": 4500 },
- "tensions": { "enabled": true },
- "metaOptimization": { "enabled": true },
- "writeProtection": { "enabled": true }
- }
- ```
- </details>
- ## Philosophy
- 1. **Evidence over assertion** — Frameworks earn their place through repeated confirmation.
- 2. **Local-first** — No cloud, no accounts, no telemetry.
- 3. **Invisible when working** — Extracts signals automatically, reflects in the background.
- ## Contributing
- Contributions welcome. Open an issue to discuss before submitting large PRs.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.