Skip to content
Back to search

claude-soul

SkillWorks with Claude CodeGitHub

Self-correcting learning engine for Claude Code — persistent identity, behavioral pattern tracking, and cross-session memory

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/domdemetz--claude-soul/badge.svg)](/listings/domdemetz--claude-soul)

HTML

<a href="/listings/domdemetz--claude-soul"><img src="/api/listings/domdemetz--claude-soul/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 218 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Claude Soul
  2. [![npm version](https://img.shields.io/npm/v/claude-soul.svg)](https://www.npmjs.com/package/claude-soul)
  3. [![npm downloads](https://img.shields.io/npm/dm/claude-soul.svg)](https://www.npmjs.com/package/claude-soul)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. > Claude Code forgets everything between sessions. Claude Soul doesn't.
  6. ```bash
  7. npx claude-soul init --starter
  8. ```
  9. One command. No API key, no cloud, everything local.
  10. **Prerequisites:** Node.js >= 18, Claude Code (Pro or Max plan).
  11. ## Three things it does
  12. ### 1. Remembers across sessions
  13. 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.
  14. ```
  15. You: "what did we decide about the auth flow last week?"
  16. Claude: [searches memory → finds the decision, context, and reasoning]
  17. ```
  18. ### 2. Tracks your corrections
  19. 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.
  20. ```bash
  21. $ claude-soul shadow --brief
  22. premature_done: 26 corrections across 10 sessions ↑ [active]
  23. robot_mode: 7 corrections across 6 sessions ↓↓ [internalized]
  24. authenticity: 5 corrections across 5 sessions ↓↓ [internalized]
  25. ```
  26. 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.
  27. ### 3. Develops judgment over time
  28. 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.
  29. ## Install
  30. ### Quick start (no extra dependencies)
  31. ```bash
  32. npx claude-soul init --starter
  33. ```
  34. Add this to your CLAUDE.md:
  35. ```markdown
  36. ## Soul System
  37. Call `soul_context()` at the start of every conversation.
  38. Use `soul_reflect` when you have idle time.
  39. ```
  40. Done. Memory works with keyword search, everything else runs automatically.
  41. ### With semantic memory
  42. 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).
  43. ```bash
  44. # 1. Install Ollama (https://ollama.com)
  45. # 2. Pull the embedding model
  46. ollama pull nomic-embed-text
  47. # 3. Then install as usual
  48. npx claude-soul init --starter
  49. ```
  50. The system auto-detects Ollama. No configuration needed.
  51. ### For agents (non-interactive)
  52. ```bash
  53. npx claude-soul init --starter --skip-identity
  54. ```
  55. 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.
  56. ### Already installed? Upgrade
  57. ```bash
  58. npm install -g claude-soul@latest
  59. claude-soul upgrade
  60. ```
  61. 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.
  62. After upgrading, run `claude-soul index` once to backfill existing data into the memory system.
  63. <details>
  64. <summary><b>What's new in v0.2</b></summary>
  65. - **Memory system** — 6 new MCP tools (`memory_save`, `memory_search`, `recall`, etc.) for cross-session fact storage with semantic search
  66. - **Correction tracking** — auto-detects when you correct your Claude and classifies the pattern
  67. - **Shadow analysis** — `claude-soul shadow` shows behavioral patterns with trend arrows and lifecycle stages
  68. - **Indexing** — `claude-soul index` loads your existing journals and soul files into the memory database
  69. </details>
  70. <details>
  71. <summary><b>CLI commands</b></summary>
  72. These are optional — the system runs automatically. The CLI is for inspecting collected data from your terminal.
  73. | Command | What it does |
  74. |---------|-------------|
  75. | `claude-soul status` | System health — frameworks, signals, phase |
  76. | `claude-soul shadow` | Your correction patterns with trends |
  77. | `claude-soul shadow --generate` | Auto-generate a SHADOW.md from your data |
  78. | `claude-soul index` | Index existing files into memory database |
  79. | `claude-soul upgrade` | Update hooks without touching your data |
  80. </details>
  81. ## How it works
  82. ```
  83. Session N
  84. │
  85. ├─ Load identity + frameworks + memory
  86. │
  87. ├─ Normal Claude Code usage
  88. │
  89. ├─ Session ends → extract signals + corrections + index to memory
  90. │
  91. └─ Reflection threshold? → evolve frameworks → Session N+1
  92. ```
  93. Everything runs through Claude Code's official extension points: an MCP server (15 tools) and hooks (signal extraction, journaling, memory indexing, correction tracking).
  94. <details>
  95. <summary><b>MCP Tools (15 total)</b></summary>
  96. **Identity & Learning**
  97. | Tool | Purpose |
  98. |------|---------|
  99. | `soul_context` | Load identity + frameworks + state at session start |
  100. | `soul_activate` | Select relevant frameworks for current conversation |
  101. | `soul_framework` | Load a single framework with full evidence history |
  102. | `soul_signal` | Record observed interaction patterns |
  103. | `soul_reflect` | Trigger a reflection cycle (quick/deep/meta) |
  104. | `soul_self_evaluate` | Record a self-evaluation of a complex response |
  105. | `soul_read` | Read soul files (SOUL.md, SHADOW.md, etc.) |
  106. | `soul_write` | Write to user-editable soul files |
  107. | `soul_status` | Get current system status |
  108. **Memory**
  109. | Tool | Purpose |
  110. |------|---------|
  111. | `memory_save` | Save facts, decisions, or lessons |
  112. | `memory_search` | Semantic search across all memories |
  113. | `memory_journal` | Search or browse conversation journals |
  114. | `memory_recent` | List recently saved memories |
  115. | `memory_stats` | Memory system statistics |
  116. | `recall` | Unified "ask anything about the past" search |
  117. </details>
  118. <details>
  119. <summary><b>Soul files (in ~/.soul/files/)</b></summary>
  120. | File | Purpose | Managed by |
  121. |------|---------|-----------|
  122. | `SOUL.md` | Your identity — who you are, how you work | You + Claude |
  123. | `SHADOW.md` | Blind spots and behavioral tendencies | You + Claude |
  124. | `STORY.md` | Timeline of growth and key moments | You + Claude |
  125. | `CORRECTIONS.md` | Patterns to avoid, learned from mistakes | You + Claude |
  126. | `STATE.md` | System telemetry (confidence, phase, counts) | Auto |
  127. | `FRAMEWORKS.md` | Active framework index | Auto |
  128. </details>
  129. <details>
  130. <summary><b>Configuration</b></summary>
  131. All settings in `~/.soul/config.json`:
  132. ```json
  133. {
  134. "signals": { "enabled": true, "maxLogSizeKb": 50 },
  135. "reflection": {
  136. "enabled": true,
  137. "quickSignalThreshold": 20,
  138. "deepSignalThreshold": 100,
  139. "quickModel": "haiku",
  140. "deepModel": "sonnet"
  141. },
  142. "contextBudget": { "maxTokens": 4500 },
  143. "tensions": { "enabled": true },
  144. "metaOptimization": { "enabled": true },
  145. "writeProtection": { "enabled": true }
  146. }
  147. ```
  148. </details>
  149. ## Philosophy
  150. 1. **Evidence over assertion** — Frameworks earn their place through repeated confirmation.
  151. 2. **Local-first** — No cloud, no accounts, no telemetry.
  152. 3. **Invisible when working** — Extracts signals automatically, reflects in the background.
  153. ## Contributing
  154. Contributions welcome. Open an issue to discuss before submitting large PRs.
  155. ## License
  156. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.