DomDemetz/claude-soul

npm version npm downloads License: MIT

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.

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

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

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