The claude-soul server gives Claude persistent memory, behavioral self-awareness, and a learning system that evolves across sessions — essentially a long-term "soul" that survives between conversations.
Identity & Context
soul_context — Load full identity, active frameworks, signals, lessons, and system state at session start
soul_activate — Dynamically select and activate relevant behavioral frameworks based on the current conversation
soul_framework — Inspect a specific framework with description, evidence history, tier, and relationships
soul_read / soul_write — Read or update soul files (SOUL.md, SHADOW.md, STORY.md, CORRECTIONS.md, FRAMEWORKS.md, etc.)
soul_status — Check framework count, learning phase, signal count, and last reflection time
Learning & Reflection
soul_signal — Record observed interaction patterns (corrections, gratitude, confusion, disengagement, success, etc.)
soul_reflect — Trigger quick (signal testing), deep (framework discovery), or meta (coherence audit) reflection cycles to evolve frameworks
soul_self_evaluate — Log descriptive self-assessments of complex responses to support behavioral improvement
Long-Term Memory
memory_save — Store facts, decisions, preferences, lessons, or episodes to a local SQLite database with optional semantic embeddings
memory_search — Semantic search across all saved memories, with optional filters by project or category
memory_journal — Search or browse past conversation journal entries by topic or recency
memory_recent — List recently saved memories, optionally filtered by project
memory_stats — View counts by category, most-accessed memories, and recent search history
recall — Unified search across all memory types: facts, decisions, frameworks, lessons, and past conversations
Claude Code forgets everything between sessions. Claude Soul doesn't.
npx claude-soul init --starterOne command. No API key, no cloud, everything local.
Prerequisites: Node.js >= 18, Claude Code (Pro or Max plan).
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]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.
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.
Related MCP server: Cortex
npx claude-soul init --starterAdd 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.
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 --starterThe system auto-detects Ollama. No configuration needed.
npx claude-soul init --starter --skip-identitySkips 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.
npm install -g claude-soul@latest
claude-soul upgradeYour 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.
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
These are optional — the system runs automatically. The CLI is for inspecting collected data from your terminal.
Command | What it does |
| System health — frameworks, signals, phase |
| Your correction patterns with trends |
| Auto-generate a SHADOW.md from your data |
| Index existing files into memory database |
| Update hooks without touching your data |
Session N
│
├─ Load identity + frameworks + memory
│
├─ Normal Claude Code usage
│
├─ Session ends → extract signals + corrections + index to memory
│
└─ Reflection threshold? → evolve frameworks → Session N+1Everything runs through Claude Code's official extension points: an MCP server (15 tools) and hooks (signal extraction, journaling, memory indexing, correction tracking).
Identity & Learning
Tool | Purpose |
| Load identity + frameworks + state at session start |
| Select relevant frameworks for current conversation |
| Load a single framework with full evidence history |
| Record observed interaction patterns |
| Trigger a reflection cycle (quick/deep/meta) |
| Record a self-evaluation of a complex response |
| Read soul files (SOUL.md, SHADOW.md, etc.) |
| Write to user-editable soul files |
| Get current system status |
Memory
Tool | Purpose |
| Save facts, decisions, or lessons |
| Semantic search across all memories |
| Search or browse conversation journals |
| List recently saved memories |
| Memory system statistics |
| Unified "ask anything about the past" search |
File | Purpose | Managed by |
| Your identity — who you are, how you work | You + Claude |
| Blind spots and behavioral tendencies | You + Claude |
| Timeline of growth and key moments | You + Claude |
| Patterns to avoid, learned from mistakes | You + Claude |
| System telemetry (confidence, phase, counts) | Auto |
| Active framework index | Auto |
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 }
}Evidence over assertion — Frameworks earn their place through repeated confirmation.
Local-first — No cloud, no accounts, no telemetry.
Invisible when working — Extracts signals automatically, reflects in the background.
Contributions welcome. Open an issue to discuss before submitting large PRs.
MIT
Search or browse the conversation journal. Use to answer 'what did I work on?' or find past conversations by topic.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query (semantic). Omit to list recent entries. | |
| days | No | How many days back to look (default: 7) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description implies a read-only operation but does not explicitly state safety or permissions. It discloses semantic search and recent listing behavior, but no side effects or error conditions are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the purpose and usage, with no wasted words. Highly efficient and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search/browse tool with two parameters and no output schema, the description is adequate but lacks details on return format, pagination, or result limits. It provides the minimum viable context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no new information beyond the schema's parameter descriptions. The baseline of 3 applies because the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('search or browse') and resource ('conversation journal'), with specific use cases. However, it does not explicitly differentiate from the sibling tool 'memory_search', which likely overlaps in functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides when to use the tool (answering questions about past work, finding topics) but does not specify when not to use it or mention alternatives like memory_search or memory_recent for similar tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recently saved memories. Use for a quick overview of what's been recorded.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | How many days back (default: 7) | |
| project | No | Filter by project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only says 'list recently saved memories', which is a read operation, but lacks details on side effects, performance, or limits. The description does not contradict annotations (none), but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, directly states purpose and usage. Efficient and front-loaded. Could be slightly more structured, but no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 optional params and no output schema, description is somewhat incomplete: does not mention default for 'days' (7) or ordering. Adequate but has gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters ('days' and 'project') having descriptions. The tool description adds no additional meaning beyond the schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool lists recently saved memories, using the verb 'list' and resource 'memories'. It distinguishes from siblings like memory_search (which implies searching) and memory_stats (stats), by focusing on 'recent' and 'quick overview'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description says 'Use for a quick overview', implying a use case, but does not explicitly state when not to use this tool or mention alternatives like memory_search for specific queries. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a fact, decision, preference, or lesson to long-term memory. Automatically generates an embedding for future semantic search.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The memory content — be specific and self-contained | |
| category | No | Memory category (default: general) | |
| project | No | Associated project name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It mentions automatic embedding generation, but lacks details on side effects (e.g., overwrite behavior), auth requirements, or limits. Adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two succinct sentences: the first defines purpose, the second adds a key behavior (embedding). No superfluous words; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 parameters, the description covers purpose and key behavior. Missing return value info (e.g., success indicator or ID) and content length limits, but adequate for a simple save operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds 'fact, decision, preference, or lesson' which aligns with the category enum, but does not significantly extend schema meaning beyond what is already provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves facts, decisions, preferences, or lessons to long-term memory and generates embeddings, distinguishing it from search/recent/stat siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like memory_journal or memory_search. The description implies saving personal notes but does not specify exclusions or preferred contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search across all memories and journal entries. Returns results ranked by meaning-similarity. Falls back to keyword search if Ollama is not available.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to search for (natural language) | |
| category | No | Filter by category | |
| project | No | Filter by project name | |
| topK | No | Number of results (default: 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: semantic search, ranking, and fallback to keyword search. This covers dependency and degradation well, though it could explicitly state read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second adds behavioral detail. No unnecessary words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 4 params and no output schema, the description covers core functionality and fallback. Could detail return format, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with param descriptions already explaining each field. The main description adds no extra parameter detail, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it performs semantic search across all memories and journal entries, with results ranked by meaning-similarity. This distinguishes it from siblings like memory_journal (journal-specific), memory_recent (recent entries), and recall (another search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when semantic search is needed and mentions fallback to keyword search if Ollama unavailable. It does not explicitly list when not to use or name alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show memory system statistics — counts by category, project, most accessed, and recent searches.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries all burden. It indicates a read-only operation (showing stats) but does not mention potential side effects, latency, or limits. Since there are no parameters, the behavioral scope is narrow, but a statement about being non-destructive would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information: purpose and types of statistics. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters and no output schema, the description covers the essential aspects: what the tool shows (counts by category, project, most accessed, recent searches). It does not describe the return format, but for a simple stats tool, the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so description need not explain parameter meaning. Baseline score 4 is appropriate as the description adds no parameter info, but none is needed. The schema coverage is 100% because there are zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool shows memory system statistics, listing specific categories (counts by category, project, most accessed, recent searches). This distinct purpose separates it from sibling tools like memory_recent (shows recent items) and memory_search (searches).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives like memory_recent or memory_search. The description implies use for aggregate summaries, but does not state exclusions or prerequisites. Adequate but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unified search across ALL memory — facts, decisions, frameworks, lessons, and past conversations. Returns categorized results. Use this as the default 'ask anything about the past' tool.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | What to recall (natural language) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It adds 'Returns categorized results', a behavioral detail. However, it doesn't disclose read-only nature or other traits, but is adequate for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no waste. First sentence states purpose and scope, second gives usage guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with no output schema, the description covers purpose, scope, return type, and usage guidance. Complete and sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter 'query' already described as natural language. Description adds no further meaning beyond schema, baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool is for unified search across all memory types, using specific verbs and resource, and distinguishes from siblings by positioning itself as the default 'ask anything about the past' tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this as the default', giving clear usage context. It doesn't state when not to use or mention alternatives, but the context of being the default provides sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Select and load relevant frameworks for this conversation. Call after reading the user's first message to pick the most applicable frameworks.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The user's first message or a summary of the conversation topic |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It says 'load relevant frameworks' but does not disclose side effects (e.g., state changes, persistence, conflicts with other tools). Vague 'load' lacks behavioral specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. The critical action and usage timing are front-loaded. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description does not explain what 'loading frameworks' entails (e.g., persisted state, return value, or required prior steps). With no output schema and no annotations, the agent lacks information on what to expect after invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'message'. The description in the schema already states 'The user's first message or a summary'. The tool description does not add extra meaning beyond that, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Select and load relevant frameworks' and the resource 'for this conversation'. It specifies the usage context (after reading user's first message), distinguishing it from sibling tools like soul_framework (which might be a single framework) or soul_context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to call 'after reading the user's first message', providing clear timing. It does not mention when not to use or list alternatives, but the sibling set and the tool's activation nature imply this is a first-step tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load your soul context — identity, frameworks, signals, lessons, and state. Call this at the start of every conversation. Default is 'full' (~4500 tokens). Use 'slim' for identity only.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Context mode: 'full' (default) = identity + frameworks + signals + lessons + state. 'slim' = identity only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses token consumption (~4500 tokens for full), identity-only option, and that it loads multiple context components. No annotations, so description carries full burden and does so effectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. Front-loaded with action and key details. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter schema and no output schema, the description covers essential usage and mode differentiation. Could mention that output is the loaded context, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with enum descriptions. Description adds value by specifying default mode ('full') and token implications, beyond the schema's enum choices.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Load' and the resource 'soul context' (identity, frameworks, signals, lessons, state). It distinguishes from siblings by specifying it's for initial loading at the start of every conversation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this at the start of every conversation' and explains mode selection with 'full' and 'slim' options, including default and token counts. Lacks explicit when-not instructions but sufficient for context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load a single framework with full details: description, evidence history, tier, and relationships.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Framework name (case-insensitive, partial match) or ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Load' suggests a read-only operation, but it does not explicitly state that the tool is non-destructive or safe. For a retrieval tool this is adequate, but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that packs all necessary information without superfluous words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, retrieval), the description sufficiently covers what the tool does and what it returns (description, evidence history, tier, relationships). It lacks details about potential edge cases (e.g., no match behavior), but is mostly complete for its scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'name' is fully described in the schema. The description adds valuable detail: 'case-insensitive, partial match or ID', which goes beyond the schema's basic description and helps the agent understand matching behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Load') and the resource ('a single framework with full details'), listing specific attributes (description, evidence history, tier, relationships). It distinguishes from sibling tools that operate on different soul entities (e.g., soul_context, soul_read).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving details of a single framework, but it does not provide explicit guidance on when to use it versus alternatives like soul_context or soul_read, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a soul file. Available: SOUL.md, SHADOW.md, STATE.md, STORY.md, CORRECTIONS.md, FRAMEWORKS.md, BONDS.md, MORTAL.md, GROWTH.md, PRINCIPLES.md, EDGES.md
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Soul file name (e.g., SOUL.md) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates a read-only operation, which is transparent. Since no annotations are provided, the description effectively communicates the non-destructive nature of the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with only two sentences, no unnecessary words, and all information is front-loaded. It earns every character.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (one required parameter) and no output schema, the description adequately covers the expected inputs. However, it does not specify the return format or what the output might look like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the schema by enumerating the valid file names (e.g., SOUL.md, SHADOW.md). This enriches the schema's minimal example and helps the agent select correct parameter values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a soul file and lists the available files. It uses a specific verb and resource, distinguishing it from sibling tools like soul_write and soul_reflect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading specific files but does not explicitly state when to use this tool over alternatives like soul_context or soul_status. No exclusions or when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Trigger a reflection cycle. Quick: tests frameworks against recent signals. Deep: full analysis with framework discovery. Meta: audits framework coherence and redundancy.
| Name | Required | Description | Default |
|---|---|---|---|
| tier | Yes | Reflection tier: quick (fast, signal testing), deep (thorough, discovers new frameworks), meta (audits the system itself) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral traits. It only states that the tool triggers a reflection cycle and describes the tiers, but does not disclose side effects, required permissions, state modifications, or what happens to existing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and each subsequent sentence adds value for a tier without extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the basic functionality. However, it lacks context about what a 'reflection cycle' entails, what frameworks or signals are, and does not mention output, which is adequate but incomplete for a deep understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear enum description. The tool description repeats the same information in a narrative form, adding no new semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers a reflection cycle and explains three distinct tiers (quick, deep, meta), making it specific and differentiated from sibling tools like soul_read or soul_self_evaluate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through tier explanations (fast vs thorough vs audit) but lacks explicit guidance on when to choose this tool over siblings or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record a self-evaluation of a complex response. Be descriptive: 'Response used 450 words for a simple question' not 'bad response'.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | Brief descriptive summary of the response and its dynamics |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any side effects, persistence, or access requirements. It is unclear whether the evaluation is stored, who can see it, or if it affects future behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose and immediately followed by a concrete example. Every sentence serves a clear function with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description provides adequate guidance for usage and format. However, it omits any information about return value or side effects, which might be relevant for an agent deciding to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description is clear and concise, but the tool description adds significant value with an example of what constitutes a good summary ('Response used 450 words' vs 'bad response'), which guides the agent beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records a self-evaluation of a complex response, with a concrete example differentiating good vs bad summaries. It distinguishes from sibling tools like soul_reflect and soul_read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an implicit guideline to be descriptive, but does not explicitly state when to use this tool versus alternatives like soul_reflect or memory_journal. No when-not conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record observed signals from this interaction. Use when you notice patterns the automatic extractor might miss.
| Name | Required | Description | Default |
|---|---|---|---|
| signals | Yes | Array of observed signals |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description bears full burden. It only states 'Record observed signals' without disclosing side effects, authorization needs, or behavioral traits like idempotency or persistence. The description adds minimal behavioral context beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. Action and usage context are front-loaded, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 1-parameter tool with no output schema, the description covers purpose and when-to-use but lacks details on return values, error handling, or whether signals overwrite or append. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds nuance about 'automatic extractor might miss' but does not elaborate on individual parameter semantics like the 'type' enum or 'confidence' range.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool records observed signals from interactions, and specifies the unique purpose of catching patterns the automatic extractor might miss. It uses a specific verb 'record' and resource 'signals', distinguishing it from sibling tools like memory_journal or soul_write.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear guidance on when to use: when noticing patterns the automatic extractor might miss. However, it does not explicitly state when not to use or name alternative tools, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current system status — framework count, learning phase, signal count, last reflection time.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure. It accurately describes a read-only operation but lacks details on side effects, permissions, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that efficiently communicates the tool's purpose and key outputs without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists all relevant return fields, providing sufficient context for a simple status check. It could mention possible values or format but is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the input schema covers everything. The description adds value by explaining what the output contains (framework count, learning phase, etc.), which compensates for the absence of an output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves current system status and specifies the exact metrics included (framework count, learning phase, signal count, last reflection time). It distinguishes from sibling tools like soul_framework and soul_reflect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates use for checking system status, but provides no explicit guidance on when to use it versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write to a soul file. SOUL.md, SHADOW.md, STORY.md, CORRECTIONS.md, BONDS.md, MORTAL.md, GROWTH.md, PRINCIPLES.md, EDGES.md are writable. STATE.md and FRAMEWORKS.md are auto-managed.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Soul file name (e.g., SOUL.md) | |
| content | Yes | New content for the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description discloses which files are writable and that STATE.md and FRAMEWORKS.md are auto-managed, covering the essential behavioral constraint for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words. The purpose is front-loaded and the constraints are clearly presented in the second sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately covers the tool's behavior for a write operation, though it doesn't mention error messages or success indicators.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning by specifying the exact set of writable filenames, beyond the generic schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Write to a soul file') and specifies the resource with a list of writable files, distinguishing it from sibling tools like soul_read or soul_reflect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to write to specified soul files) and implicitly warns against writing to auto-managed files, though it doesn't explicitly state alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1memory_journalmemory_recentmemory_savememory_searchmemory_statsrecallv0.1.0soul_activatesoul_contextsoul_frameworksoul_readsoul_reflectsoul_self_evaluatesoul_signalsoul_statussoul_writeScored across 15 tools
Tools are clearly split into memory and soul domains, with distinct purposes. However, 'memory_search' (semantic search) and 'recall' (unified search) could cause minor confusion, as both serve search but with different scopes.
All tools use snake_case with consistent prefixes 'memory_' and 'soul_', forming a clear verb_noun pattern (e.g., memory_save, soul_read). No mixing of conventions.
15 tools cover memory management and soul system operations comprehensively without being overwhelming. The count is well-scoped for the server's purpose.
The memory tools lack a delete or explicit update operation, and soul tools cover most needs but miss a tool to list all frameworks individually. Minor gaps that agents can work around.
Give Claude an honest self-model — behavioral tendencies built from evidence, not session memory. Mi
Persistent, governed institutional memory for Claude Code — specs, decisions, learnings.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Path-scoped team memories, rules and skills for Claude Code, Cursor, Codex and other MCP clients.
