GhostPawJS/souls

Agent identity as an essence plus evidence-backed traits, refined only when the evidence agrees.
bash
npm install @ghostpaw/souls
Prompt evolution engine for cognitive identity. Stores identity as narrative
essence plus evidence-backed traits, with structured level-up,
crystallization-gated refinement, and full rollback. Not a prompt template
library. Not a configuration manager. An evolutionary algorithm for how agents
think.
Release binary with no runtime needed; library and npm usage require Node 24+. Zero runtime dependencies.
## MCP server
Every client below starts the same stdio server: ghostpaw-souls mcp.
For npm-based environments, use npx -y @ghostpaw/souls mcp.
Identity and evidence live in ~/.ghostpaw/souls.db unless the GHOSTPAW_SOULS_DB
environment variable (absolute path) or --db says otherwise.
Claude Code
bash
claude mcp add ghostpaw-souls -- ghostpaw-souls mcp
or as a plugin, which also installs the skill:
bash
/plugin marketplace add GhostPawJS/souls
/plugin install ghostpaw-souls@ghostpaw-souls
Codex CLI (~/.souls/config.toml)
toml
[mcp_servers.ghostpaw-souls]
command = "ghostpaw-souls"
args = ["mcp"]
Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json)
or a project .mcp.json:
json
"mcpServers": {
"ghostpaw-souls": {
"command": "ghostpaw-souls",
"args": ["mcp"]
Claude Desktop users can also install server.mcpb from the
latest GitHub release.
A Dockerfile is included for container hosts:
docker build -t ghostpaw-souls . && docker run -i --rm -v souls:/data ghostpaw-souls.
The server speaks MCP 2026-07-28 (stateless, server/discover) and the
initialize-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.
## CLI
text
ghostpaw-souls search [query] [--soul-id N --tags TAG --limit N]
ghostpaw-souls review
ghostpaw-souls soul create --essence TEXT --description TEXT
ghostpaw-souls soul show|update|retire|awaken [flags]
ghostpaw-souls shard drop --source LABEL --soul-ids N [flags]
ghostpaw-souls shard drop-batch --shards JSON
ghostpaw-souls shard reveal
ghostpaw-souls refinement add|attune [flags]
ghostpaw-souls refinement revise|revert|reactivate [flags]
ghostpaw-souls refinement cite
ghostpaw-souls level validate|up|revert [flags]
ghostpaw-souls mcp|skill|tools|describe|call|completions|version|help
Use ghostpaw-souls skill --short for a compact cheat sheet, skill for full
parameter tables, and skill --list to list runnable workflow guides.
Global flags can appear anywhere: --db , --json, --quiet,
--compact, --help/-h, --version/-V/-v, --no-color.
NO_COLOR is accepted; output uses no terminal colors.
Noun-verb commands print the full tool result as JSON with --json or when
stdout is piped. Terminal output shows the summary and payload.
--quiet suppresses stdout. --compact removes JSON indentation.
Use help soul, soul --help or soul create --help for schema-derived help.
Array flags repeat and kebab-case flags map to schema properties. Values are
literal, including a leading @. Only soul create|update --essence reads a
file: @path (relative to the working directory), @- for stdin and @@text
for a literal @text. Help marks it (@file, @- stdin, @@ literal @); an empty or unreadable path