Skip to content
MCP server

GhostPaw Souls

Local MCP server for an agent identity kept as evidence-backed traits in SQLite

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, Linux, macOS
Runs
Locally
Version
0.6.3
Listing updated
3 days ago

About GhostPaw Souls

GhostPaw Souls is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.

Souls treats an agent's identity as a narrative essence plus traits that each carry provenance. Observations are dropped in as shards tagged with their source, and a trait is revised only when a cluster of observations from at least two sources agrees. Evidence checks warn by default; strict mode requires readiness and citations, and a named operator can log a correction that bypasses the gate.

The site replays a Reviewer soul through six calls to show the loop, while noting the replay reflects an earlier version. Identity and evidence stay in ~/.ghostpaw/souls.db on your machine, or in a path set by GHOSTPAW_SOULS_DB.

Start it with ghostpaw-souls mcp, or npx -y @ghostpaw/souls mcp. The npm package needs Node.js 24 or newer; a Linux x64 binary is also offered.

Install

Run in a terminal

claude mcp add souls -- npx -y @ghostpaw/souls

Add to claude_desktop_config.json

{
  "mcpServers": {
    "souls": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/souls"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "souls": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/souls"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "souls": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/souls"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "souls": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/souls"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "souls": {
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/souls"
      ]
    }
  }
}

Configuration

  • GHOSTPAW_SOULS_DBSQLite database path (default: ~/.ghostpaw/souls.db)

What it does

Evidence-gated traits
Traits change only when observations converge from several sources.
Reversible level-ups
Each revision can be reverted.
Prompt rendering
Renders the identity for a system prompt.
Local SQLite storage
Everything lives in a file on your machine.
Strict mode
Optionally enforces readiness and citations.

Good for

  • Let a reviewer agent refine its habits from real sessions and CI
  • Keep a roll-back history of how an agent's persona changed
  • Render a current identity into a system prompt
  • Audit why a trait was revised

Pricing

Open source

Free, MIT licensed

Prices change. Check souls.ghostpaw.dev before you buy.

GhostPaw Souls FAQ

Where is data stored?

In ~/.ghostpaw/souls.db unless GHOSTPAW_SOULS_DB or --db says otherwise.

What licence?

MIT, per the project site.

Does it have runtime dependencies?

The site lists zero runtime dependencies.

Is GhostPaw Souls free?

Yes. GhostPaw Souls is open source, so you can use and self-host it for free.

How do I add GhostPaw Souls to Claude Code?

Run this command in your terminal: claude mcp add souls -- npx -y @ghostpaw/souls

What are the best alternatives to GhostPaw Souls?

The closest alternatives to GhostPaw Souls are Codebase Memory, XERJ, Claude Code Ultimate Guide, Nautilus Compass Memory and note1.

Alternatives to GhostPaw Souls

  1. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  2. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  3. MCP server for searching the Claude Code Ultimate Guide from any MCP client

    Runs locally
    • Open source
    • 6.5K GitHub stars
    • AI models and LLM tooling
  4. Local-first long-term memory layer for AI agents, served over MCP

    Not checked yet
    • 5 tools
    • Remote
    • Open source
    • 1.3K GitHub stars
    • Knowledge and memory
  5. note1

    MCP server

    MCP server giving AI assistants search and summaries across your note1 meetings

    • 4 tools
    • Remote
    • Free trial
    • 1 GitHub star
    • Productivity