claude-soul

Claude Soul

  

Claude Code forgets everything between sessions. Claude Soul doesn't.

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 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.

$ 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)

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>

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:

{
  "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