# @ghostpaw/souls

[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.GhostPawJS%2Fsouls-06d6a0)](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.GhostPawJS%2Fsouls/versions/latest)

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.

Node 24+, built-in `node:sqlite`, zero runtime dependencies.

## MCP server

Every client below starts the same stdio server: `npx -y @ghostpaw/souls mcp`.
Identity and evidence live in `~/.ghostpaw/souls.db` unless the `GHOSTPAW_SOULS_DB`
environment variable (absolute path) or `--db <path>` says otherwise.

**Claude Code**

```bash
claude mcp add ghostpaw-souls -- npx -y @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 = "npx"
args = ["-y", "@ghostpaw/souls", "mcp"]
```

**Cursor** (`.cursor/mcp.json`), **Claude Desktop** (`claude_desktop_config.json`)
or a project `.mcp.json`:

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

Claude Desktop users can also install `server.mcpb` from the
[latest GitHub release](https://github.com/GhostPawJS/souls/releases/latest).
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

```bash
npx -y @ghostpaw/souls tools
npx -y @ghostpaw/souls call search_souls '{"query":"review"}'
npx -y @ghostpaw/souls describe manage_soul
```

Install globally for the `ghostpaw-souls` binary: `npm i -g @ghostpaw/souls`.
`ghostpaw-souls mcp` starts the stdio server.

## Agent Skill

`SKILL.md` (repo root) and `skills/souls/SKILL.md` follow the
[Agent Skills](https://agentskills.io) format and ship in the npm package.
Copy `skills/souls/` into your agent's skills folder, or print it:

```bash
npx -y @ghostpaw/souls skill > SKILL.md
```

## Install

```bash
npm install @ghostpaw/souls
```

## Quick Start

```ts
import { DatabaseSync } from 'node:sqlite';
import { initSoulsTables, read, write } from '@ghostpaw/souls';

const db = new DatabaseSync(':memory:');
initSoulsTables(db);

const soul = write.createSoul(db, {
  name: 'Reviewer',
  essence: 'I review code by reading for intent before scanning for bugs.',
  description: 'Code review specialist',
});

write.addTrait(db, soul.id, {
  principle: 'Read the PR description before the diff.',
  provenance: 'Reviews that started with code missed architectural intent 3 of 4 times.',
});

write.dropShard(db, {
  content: 'Reviewer caught a naming inconsistency by reading the RFC first.',
  source: 'session',
  soulIds: [soul.id],
});

const rendered = read.renderSoul(db, soul.id);
```

## What It Does

A **soul** is one cognitive identity — not a prompt template, not a config
object. How an agent thinks, judges, and approaches problems.

A **trait** is a cognitive principle with provenance — evidence proving it was
earned, not invented.

A **shard** is a behavioral observation from any source, attributed to souls.
Shards accumulate silently. When enough evidence converges across independent
channels over time, the soul becomes eligible for refinement.

**Level-up** consolidates: merge overlapping traits, promote absorbed ones into
the essence, carry forward those still teaching. The identity restructures and
the generation counter increments.

The rendered identity block (essence + active traits) is static between
mutations — no drift, no context accumulation, no re-rendering overhead. It
does not drift because there is nothing to drift.

## API Surface

```ts
import { read, write, ether, soul, tools, skills } from '@ghostpaw/souls';
```

| Namespace | Purpose |
|-----------|---------|
| `read` | Queries — get souls, traits, shards, evidence reports, render identity blocks |
| `write` | Mutations — create souls, add/revise/revert traits, drop shards, level up |
| `ether` | Soul template discovery — search ~2,800 open-source prompts, manifest as souls |
| `soul` | The built-in Mentor soul — gardener identity for guiding refinement |
| `tools` | LLM tool facade — JSON Schema definitions for agent framework integration |
| `skills` | Markdown procedures — crystallization, refinement, level-up, maintenance workflows |

### Core Lifecycle

```
observe → crystallize → refine → level up → repeat
```

Shards accumulate from any source. Crystallization gates refinement until
evidence converges across 2+ independent channels over 1+ days. Traits mutate
with provenance. Level-up restructures when the identity outgrows its current
form.

### The Mentor

The package ships one built-in soul — the Mentor — tuned for guiding the
entire refinement lifecycle:

```ts
import { soul } from '@ghostpaw/souls';

const systemPrompt = soul.renderSoulsSoulPromptFoundation();
```

### Ether — Template Discovery

Browse and search a catalog of open-source system prompts, then manifest them
as fully-formed souls:

```ts
import { DatabaseSync } from 'node:sqlite';
import { ether } from '@ghostpaw/souls';

const etherDb = new DatabaseSync('ether.db');
ether.initEtherTables(etherDb);
ether.registerDefaults(etherDb);
await ether.refreshAll(etherDb);

const [hit] = ether.search(etherDb, 'security architect');
const entry = hit ? ether.getEntry(etherDb, hit.id) : undefined;
const newSoul = entry ? ether.manifest(soulsDb, entry) : undefined;
```

Sources are fetched lazily with ETag caching. Refresh is atomic — failed
fetches never erase existing data.

### LLM Tools

Wire into any agent framework via JSON Schema tool definitions:

```ts
import { tools } from '@ghostpaw/souls';

const allTools = tools.listSoulsToolDefinitions();
const tool = tools.getSoulsToolByName('search_souls');
const result = tool?.handler(db, { query: 'architect' });
```

## Ecosystem

Souls is one of four faculties in the GhostPaw cognitive substrate:

| Faculty | Domain | Core Loop |
|---------|--------|-----------|
| **questlog** | tasks and commitments | plan, track, complete, reward |
| **affinity** | people and relationships | meet, bond, interact, maintain |
| **codex** | beliefs and knowledge | remember, recall, revise, flag |
| **souls** | cognitive identity | observe, crystallize, refine, level up |

Each faculty owns one slice of state. Each stays lean at the storage layer
with the same architecture: Node 24+, built-in `node:sqlite`, zero runtime
dependencies.

Souls is unique in the quartet: it is the only faculty whose output becomes
the system prompt. Questlog produces task state. Affinity produces relationship
state. Codex produces belief state. Souls produces the identity block that
shapes how all other state is interpreted.

Together they form a complete cognitive substrate for agents that grow.

## Domain Mapping

The engine provides a single abstraction — identity that evolves from
evidence — that maps to any domain where behavior should improve from
observation:

| Domain | Soul is | Traits are |
|--------|---------|------------|
| LLM agents | agent identity | behavioral principles |
| Game NPCs | NPC personality | character qualities |
| AI companions | companion identity | personality facets |
| Creative writing | fictional character | character traits |
| Brand voice | brand identity | voice guidelines |
| Educational tutor | teaching style | pedagogical principles |
| Code review | reviewer style | team preferences |

## Demo

An interactive local-first demo app with RPG character sheet aesthetics:

```bash
npm run demo:ether   # fetch template catalog
npm run demo:serve   # build and serve at localhost:7777
```

## Docs

| Document | Audience |
|----------|----------|
| [CONCEPT.md](CONCEPT.md) | Full design rationale, research citations, invariants |
| [docs/LLM.md](docs/LLM.md) | LLM harness builders — tool surface, rendering, soul layer |
| [docs/HUMAN.md](docs/HUMAN.md) | Human developers — direct read/write/ether API |
| [docs/PAGES.md](docs/PAGES.md) | Demo app pages, architecture, development |
| [docs/entities/](docs/entities/) | Entity deep-dives: souls, traits, shards, levels, ether |

## License

MIT