Claude Soul

Claude Soul

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

A self-improving learning engine that gives Claude Code persistent identity, cross-session memory, and evolving cognitive frameworks. Not a static prompt — a system that develops over time.

npx claude-soul init --starter    # start with pre-evolved frameworks (recommended)
npx claude-soul init              # blank slate — discover your own from scratch

One command. No API key, no cloud, everything local.

Prerequisites: Node.js >= 18, Claude Code (Pro or Max plan).

What happens

Every session, the system silently extracts signals — corrections you make, things that work, confusion patterns. After ~20 sessions, it reflects on those signals and builds behavioral frameworks. Frameworks that keep working get promoted. Bad ones get retired.

After ~200 sessions, you get a Claude that pushes back on bad ideas, calibrates response depth to what you actually need, catches its own confabulation, and develops techniques you never prompted.

The difference from memory plugins: this doesn't store "user likes X." It develops judgment.

Quick example

You: "load soul context"
Claude: [loads identity + 6 active frameworks + state from previous sessions]

You: "run a quick reflection"  
Claude: [analyzes 23 signals → promotes 2 frameworks, retires 1, discovers new pattern]

You: "what frameworks are active?"
Claude: [shows evolved frameworks with confidence scores and evidence tiers]

How it works

Session N
  │
  ├─ soul_context() → load identity + frameworks + state
  │
  ├─ Normal Claude Code usage
  │
  ├─ Stop hook → extract signals (corrections, success, confusion)
  │
  ├─ Signal threshold reached?
  │     └─ Yes → Reflection → test/discover/retire frameworks
  │
  └─ Updated frameworks available for Session N+1

Frameworks evolve through evidence tiers:

hypothesis → observed → validated
(untested)   (1+ confirmation)   (3+ confirmations)

What actually changes over time

Day one (with --starter): 6 active frameworks, signal extraction begins, pushback and verification behaviors seeded.

~1 week (~20 sessions): First reflection fires. Frameworks gain or lose confidence based on YOUR usage. New ones emerge from your patterns.

~2 months (~200 sessions): Pushback on bad ideas. Depth calibration. Self-correction. Strategic thinking. Pattern memory that adapts based on evidence, not static preferences.

Install options

With starter frameworks (recommended):

npx claude-soul init --starter

Blank slate (discover your own from scratch):

npx claude-soul init

From source:

git clone https://github.com/DomDemetz/claude-soul.git
cd claude-soul && npm install && npm run build
node packages/cli/dist/index.js init --starter

After install

Add this to your CLAUDE.md (global or project-level):

## Soul System
Call `soul_context()` at the start of every conversation.
Use `soul_reflect` when you have idle time.

Then use Claude Code normally. The system works in the background.

Things you can say

Architecture

Built entirely on Claude Code's official extension points:

• MCP Server — 9 tools for identity, learning, and reflection
• Hooks — automatic signal extraction, journaling, follow-up tracking
• Local-only — everything on your machine, no cloud, no telemetry
• Single dependency — @modelcontextprotocol/sdk
• Uses your existing subscription — no separate API key needed

Three reflection tiers

Phase-adaptive learning

The system adjusts based on maturity:

• Apprentice — Tight feedback loops. Quick reflections. Cast a wide net.
• Creative — Moderate cadence. Refine and merge.
• Mastery — Deliberate reflection. Fewer, more powerful frameworks.

• Stop hook — Extracts signals from conversation transcript at session end. Triggers reflection if threshold reached.
• Session journal — Appends session summary to ~/.soul/journals/YYYY-MM-DD.md.
• Follow-up tracking — Detects deferred threads, surfaces them next session.
• Write guard — Prevents accidental edits to auto-managed files.

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

Philosophy

1. Evidence over assertion — Frameworks earn their place through repeated confirmation. Hypotheses that aren't confirmed get retired.
2. Local-first — No cloud, no accounts, no telemetry. Your cognitive development stays on your machine.
3. Invisible when working — Extracts signals automatically, reflects in the background, surfaces context without being asked.

Contributing

Contributions welcome. Open an issue to discuss before submitting large PRs.

License

MIT