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