# Claude Soul

[![npm version](https://img.shields.io/npm/v/claude-soul.svg)](https://www.npmjs.com/package/claude-soul)
[![npm downloads](https://img.shields.io/npm/dm/claude-soul.svg)](https://www.npmjs.com/package/claude-soul)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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