Skip to main content
Glama

@ghostpaw/souls

npm CI site runtime deps MCP Registry node license

Agent identity as an essence plus evidence-backed traits, refined only when the evidence agrees.

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 <path> says otherwise.

Claude Code

claude mcp add ghostpaw-souls -- ghostpaw-souls mcp

or as a plugin, which also installs the skill:

/plugin marketplace add GhostPawJS/souls
/plugin install ghostpaw-souls@ghostpaw-souls

Codex CLI (~/.codex/config.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:

{
  "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.

Related MCP server: substrate-mcp

Running inside sandboxed agent harnesses

Inside a Codex CLI --sandbox workspace-write session, the database and its parent directory must be inside a writable root, including SQLite's -wal and -shm side files. A default DB under ~/.ghostpaw outside those roots can fail with SQLITE_CANTOPEN or EPERM (often exit 70; directory creation failures may exit 2), even when normal shell permissions allow access. Put the DB inside the workspace with --db ./state/souls.db, or set GHOSTPAW_SOULS_DB="$PWD/state/souls.db" for CLI/MCP use.

To use an external DB directory, add it when starting the OpenAI Codex CLI (replace <dir-with-db> with its absolute path):

codex exec --sandbox workspace-write --add-dir <dir-with-db> "Run the GhostPaw CLI"

Alternatively, set sandbox_workspace_write.writable_roots in ~/.codex/config.toml before starting the session:

[sandbox_workspace_write]
writable_roots = ["/absolute/dir-with-db"]

CLI

ghostpaw-souls search [query] [--soul-id N --tags TAG --limit N]
ghostpaw-souls review <list|maintenance|readiness>
ghostpaw-souls soul create <name> --essence TEXT --description TEXT
ghostpaw-souls soul show|update|retire|awaken <soulId> [flags]
ghostpaw-souls shard drop <content> --source LABEL --soul-ids N [flags]
ghostpaw-souls shard drop-batch --shards JSON
ghostpaw-souls shard reveal <shardIds...>
ghostpaw-souls refinement add|attune <soulId> [flags]
ghostpaw-souls refinement revise|revert|reactivate <traitId> [flags]
ghostpaw-souls refinement cite <traitId> <shardId>
ghostpaw-souls level validate|up|revert <soulId> [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 <path>, --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 exits 2. -- ends flags. A positional -, or piped stdin with no arguments, reads a JSON object; explicit flags override its fields. Database selection uses --db, GHOSTPAW_SOULS_DB, then ~/.ghostpaw/souls.db.

Exit

Noun-verb result

0

Success, including no_op

1

Tool error

2

Usage or schema error

3

Clarification needed or not found

4

Conflict or version mismatch

70

Internal error

Errors go to stderr. With --json, usage and internal errors also print {ok:false,error:{code,message}} to stdout. Tool results retain their full shape. Legacy tools [--json], describe <tool>, call <tool> [JSON|-] and <tool_name> --parameter value keep their existing exit codes. completions bash, completions zsh and completions fish print shell scripts.

ghostpaw-souls soul create Reviewer --essence "Read carefully." --description "Review identity" --db /tmp/souls-example.db --json
ghostpaw-souls soul show 1 --db /tmp/souls-example.db --json
ghostpaw-souls review list --db /tmp/souls-example.db --json

Search reads behavioral shards. Creating a soul does not add searchable shards; use shard drop to deposit observations. Core commands work offline.

Agent Skill

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

ghostpaw-souls skill > SKILL.md

Install

Release binary (default)

Each line downloads the latest release asset, checks it against the release's SHA256SUMS and installs it on the PATH (~/.local/bin on Linux/macOS; the Windows script adds its folder to the user PATH).

These lines never edit ~/.profile or other shell startup files: export PATH applies to the current shell only. To keep it in new shells, use the ~/.profile line below.

linux-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/souls/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"

linux-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/souls/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/souls/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/souls/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"

windows-x64 (PowerShell; persistently adds the install folder to the user PATH):

irm https://raw.githubusercontent.com/GhostPawJS/souls/main/install.ps1 | iex

Pinned to a release:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/souls/main/install.sh | sh -s -- --target linux-x64 --version 0.4.5 && export PATH="$HOME/.local/bin:$PATH"

Also adding ~/.local/bin to ~/.profile (edits ~/.profile once; skipped if it already mentions ~/.local/bin; zsh login shells read ~/.zprofile instead, so use that file name there):

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/souls/main/install.sh | sh -s -- --target linux-x64 && { grep -qs '.local/bin' ~/.profile || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; } && export PATH="$HOME/.local/bin:$PATH"

To skip the persistent user PATH edit (the installer prints the folder to add):

$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/souls/main/install.ps1 | iex
$ ghostpaw-souls --version
souls 0.4.5 (binary, linux-x64)

Scripts that compare versions should use --version --short or --version --json.

A session with the 0.4.0 linux-x64 binary against a fresh database (output piped through jq to keep it short):

ghostpaw-souls 0.4.0: version, soul create, two shard drops, refinement add and cite, search, review readiness and soul show with the rendered identity

The same session as an animated GIF.

Other release installers:

mise use -g github:GhostPawJS/souls
ubi --project GhostPawJS/souls --exe ghostpaw-souls --in ~/.local/bin
eget GhostPawJS/souls

For aqua, define a github_release package in aqua.yaml:

registries:
  - name: souls
    type: local
    path: souls-registry.yaml
packages:
  - name: GhostPawJS/souls@v<VERSION>
    registry: souls

souls-registry.yaml:

packages:
  - type: github_release
    repo_owner: GhostPawJS
    repo_name: souls
    asset: ghostpaw-souls-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz
    format: tar.gz
    replacements: { amd64: x64 }
    overrides:
      - goos: windows
        asset: ghostpaw-souls-{{trimV .Version}}-windows-{{.Arch}}.zip
        format: zip
    files:
      - name: ghostpaw-souls

Install scripts verify SHA256SUMS. To verify a downloaded archive's build attestation:

gh attestation verify <archive> -R GhostPawJS/souls

Set GHOSTPAW_VERIFY=attestation for attestation verification in install.sh. Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser download on macOS, remove quarantine with xattr -d com.apple.quarantine /path/to/ghostpaw-souls. Linux binaries require glibc 2.28+; use npx on Alpine. See the binary build workflow.

Sizes for 0.4.0 (Node 26.12.1 inside each binary):

Target

Archive

Binary

linux-x64

41.7 MB tar.gz

117.4 MB

linux-arm64

41.1 MB tar.gz

115.1 MB

darwin-arm64

44.8 MB tar.gz

146.7 MB

darwin-x64

46.4 MB tar.gz

149.5 MB

windows-x64

38.4 MB zip

105.6 MB

The npm package is 930 KB unpacked and needs Node 24+. Every release is installed and run on ubuntu-24.04, macos-15 and windows-2025 by the install check.

Release install checks run on ubuntu-24.04, macos-15 and windows-2025.

npx / npm (for npm-based environments)

The npm package requires Node 24+:

npm install -g @ghostpaw/souls
npx -y @ghostpaw/souls --help

Library (for harnesses embedding it in code)

npm install @ghostpaw/souls
import { initSoulsTables, read, write } from '@ghostpaw/souls';

See Quick Start for library usage.

Quick Start

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);

Docs

The live demo runs the library in your browser against an in-memory SQLite database. Each view below opens a different part of it:

Document

Audience

CONCEPT.md

Full design rationale, research citations, invariants

docs/LLM.md

LLM harness builders — tool surface, rendering, soul layer

docs/HUMAN.md

Human developers — direct read/write/ether API

docs/PAGES.md

Demo app pages, architecture, development

docs/entities/

Entity deep-dives: souls, traits, shards, levels, ether

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

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:

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:

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:

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:

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

License

MIT

Evidence-backed refinement

Shard lists and searches return arrays with a default limit of 100 (maximum 1000). read.listShardsPage and read.searchShardsPage return { items, total, hasMore }; use offset to continue. Both accept status: pending, sealed, faded, or all. Lists default to pending unsealed shards; searches retain their all-status default. Query and tags combine with AND.

Trait additions and essence edits warn when crystallization is not ready or no shardIds are supplied. Pass strict: true to require both. A named operator bypasses this gate and records an operator correction. Existing trait-addition capacity enforcement is unchanged; reactivation and new level-up checks warn unless strict is enabled. addTrait, updateSoul, and refineWithEvidence expose optional warnings: string[] as a non-enumerable property, so serialization and object spreads keep the record clean. Facade data also includes these strings while retaining existing warning objects. The CLI prints each warning as warning: ... on stderr.

write.refineWithEvidence(db, { soulId, action: 'add' | 'revise', traitId?, principle, provenance, shardIds, reason?, strict?, operator?, expectedRevision? }) updates wording, cites evidence, and stamps attunement atomically. Set expectedRevision to the latest revision ID for the soul (or 0) to detect conflicts. Read wording history with read.getRevisionHistory(db, { soulId, traitId?, limit? }), or inspect with history: true.

The facade action is refine_with_evidence; CLI usage:

ghostpaw-souls refinement apply 1 --principle "Check assumptions" --provenance "Review evidence" --shard-ids 2,3 --strict
ghostpaw-souls refinement revise 4 --principle "Check assumptions first" --reason "Clarify order"
ghostpaw-souls soul update 1 --essence "Corrected identity" --strict --operator maintainer --reason "Correction"

refinement apply infers revise when --trait-id is supplied; otherwise it adds. Evidence reports render at most five members per cluster and show +N more. Set maxMembersPerCluster to change the cap, or full: true to retain every selected member in the structured payload. Alignment uses the maximum similarity across all cluster members. Staleness uses the latest citation time, falling back to trait creation. Tension detection has English-only negation cues; detectTraitTensions(..., { negationWords }) extends them.

read.formatEvidence(db, soulId, { negationWords: ["nicht"] }) extends the English-only tension cues through the public library facade.

Publishing identities into host prompts

ghostpaw-souls soul create Reviewer --essence 'Read intent first.' --description 'Code review' --external-id reviewer
ghostpaw-souls render ext:reviewer --provenance
ghostpaw-souls render ext:reviewer --into ./AGENTS.md --marker souls --budget 8000 --expect-hash none
ghostpaw-souls diff ext:reviewer --against ./AGENTS.md
ghostpaw-souls review ext:reviewer --no-change --reason 'Identity still fits'
ghostpaw-souls config set strict true
ghostpaw-souls config get strict
ghostpaw-souls report --expect-ids @expected-ids.txt

render prints only the identity, or atomically creates/replaces the content between <!-- souls:begin --> and <!-- souls:end --> with --into. It appends a block when markers are absent. --marker selects a different marker name. Successful writes print wrote <file> sha256:<hash> and record file/block hashes in soul_publications. --expect-hash requires the current full-file SHA-256 (none for a missing file); a mismatch exits 4 without writing. Omit it for an unconditional replacement.

--budget counts characters across the entire composed output, including surrounding file text and markers. It removes lowest-ranked traits first, then shortens essence; very small budgets can empty the identity block. Text outside the markers stays intact. An impossible budget exits nonzero without writing. Cuts appear as one trimmed: line on stderr and as {traitIds, essenceChars} in --json output. diff prints changed lines, exits 0 when identical and 1 when different; --json returns {same, added, removed, markerFound}. When no block exists for the requested marker, diff <soul> --against <file|-> compares the whole input, removing one trailing newline, with the rendered block and reports markerFound: false. Diff compares the current full identity, so a budget-trimmed publication can differ.

Soul create/update accept --external-id; bindings are unique when set and appear in show/list JSON. CLI soul arguments accept numeric IDs, names, or ext:<id>. report --expect-ids @file reads one external ID per line (@- reads stdin), compares active bindings, and prints missing: and extra: lines. It exits 0 for a match, 1 otherwise; JSON returns {missing, extra}.

Shard drop accepts --occurred-at <iso>, --idempotency-key <key>, and --ref <text>. Repeated ingestion keys return the original shard with duplicate: true. Library and batch inputs accept occurredAt (ISO or epoch milliseconds), idempotencyKey, and ref. Occurrence time controls crystallization age/spread, falling back to creation time. The age spread uses occurredAt (falling back to createdAt): two pending shards from different sources must be at least one day apart, or live shards (occurrence time not earlier than insertion time) must span a day on their own. Otherwise readiness reports Age spread must span at least two sources by occurrence time. Legacy numeric CLI and facade occurrence timestamps retain their creation-time behavior; insertedAt records insertion time separately for backfill checks.

Strict checks default off. Resolve strict in this order: explicit library strict or CLI --strict/--no-strict, GHOSTPAW_SOULS_STRICT (1/true/yes or 0/false/no), then the database setting. Use config set strict true|false, config get [key], and config list. Both read commands report effective boolean values and a source of default, db, or env; text output uses strict: false (default). read.getSoulsConfig(db) reads persisted values; write.setSoulsConfig(db, 'strict', 'true') writes them. The manage tool provides config_set, config_get, and config_list actions.

Refinement add/revise and soul update accept --operator <name> for a logged operator correction; strict evidence readiness can be bypassed with a named operator. Review output includes corrections. review --no-change records a review and stamps attuned without editing identity; the facade provides write.reviewNoChange(db, soulId, {reason}) and the review tool accepts noChange. Show with --history includes revision and review records. Refinement add/reactivate/apply and level validate/up accept --trait-limit <n>.

CLI batch ingestion accepts shard drop-batch --shards @file and shard add --batch @file with a JSON array or JSON Lines. @- reads stdin; @@ escapes a literal leading at-sign. shard add also aliases shard drop. Set GHOSTPAW_OUTPUT=json for JSON output. Default database opens print using default db <path> on stderr; suppress with --quiet or GHOSTPAW_QUIET=1, or select --db / GHOSTPAW_SOULS_DB.

Reference, render, and readiness options

Soul references resolve in this order: numeric ID, ext:<externalId>, slug, then name. For example, after soul create Reviewer --slug mentor --essence E --description D, use render mentor or soul show mentor. Tool soulId and soulIds inputs also accept these references, including shard batch entries. Unresolved or ambiguous references report what was tried.

-q, --quiet suppresses stdout wherever quiet output is supported. Array flags can be repeated or receive a JSON array, for example --tags one --tags two or --tags '["one","two"]'. Commas stay literal. Batch shard import uses shard add --batch @file or shard drop-batch --shards @file (JSON array or JSON Lines; @- reads stdin).

Rendering defaults to citation count descending, then creation time ascending. Use render <soul> --order density for citations per day of trait age (minimum one day). --provenance includes trait provenance; --no-provenance omits it (the stored-soul default). Library options are order: 'citations' | 'density' and includeProvenance. The built-in foundation keeps provenance by default; pass { includeProvenance: false } as its second argument to omit it.

Readiness and maintenance options accept minSourceDiversity (positive integer, default 2) and minSpreadDays (non-negative number, default 1). These propagate through profile, shard-drop, and evidence-gated mutation options. Tools expose the same optional fields; corresponding CLI flags are --min-source-diversity and --min-spread-days on review, inspection, observation, and refinement commands, plus level validate without a plan. Occurrence-time spread, recency, pending count, and cluster diversity still apply; backfilled observations must span sources when native spread is insufficient.

soul update <soul> --essence E --shard-ids 1 --shard-ids 2 --reason text cites shards for an essence change. A named --operator with a --reason suppresses evidence warnings when strict mode is off; strict behavior stays unchanged. Without --shard-ids it prints one note: that the essence was written and no shards were linked. Empty, whitespace-only and literal null or undefined essences are rejected before any write (exit 2); for a read-modify-write, read the current essence from soul show --json at data.profile.soul.essence. level validate <soul> reports readiness and blockers with exit 0 when the check runs. Supply a plan as inline JSON, for example --plan '{"newEssence":"E","consolidations":[],"promotedTraitIds":[],"carriedTraitIds":[]}'. With a plan, validation behavior is unchanged.

Profiles include freshness, headroom, and evidenceRatio; health is their product, clamped to 0–1. See soul rendering and health for the component formulas. Evidence suggestions count uncited clusters separately from semantically novel ones. Citations onto active traits count as alignment; singleton and single-source clusters do not prompt a new trait.

Traces

Traces preserve dated facts, promises, beliefs, decisions, approvals, and quests. Shards remain behavioral observations and may cite traces as evidence. Trace tables are created on the first trace write; reads leave existing databases unchanged.

ghostpaw-souls trace record "Review the draft" --soul mentor:owner --tag promise --due +3d --json
ghostpaw-souls trace due --soul mentor
ghostpaw-souls trace settle 1 --as done --reason "Reviewed and delivered" --json

The synchronous API exposes write.recordTrace, write.reviseTrace, write.settleTrace, link/tag/cite operations, and read.listTraces, dueTraces, traceHistory, traceChain, changedSince, and traceStats. MCP exposes trace_soul and read-only review_traces; trace search <query> searches text with ranked results. See Traces. Rendering includes commitments only with traces: 'open' | 'due' or --traces. Readiness requires a converged cluster (three shards across two sources by default); use readiness: 'legacy', --readiness legacy, or config set readiness legacy to retain the earlier gate.

Usage

Mapping

Flat work list

Open trace tagged quest, owner = working soul. Due is optional: a parking lot needs no due date. Settle done with the honest outcome as the reason; abandon with dropped. Group a questline using questline plus a tag named for the line. Prerequisites/unlocks, repeatables, rewards, and due-claim delivery are not modeled; keep using questlog for scheduling and recurrence.

Promises

Tag promise, due set, owner = promiser, counterpart = promisee. Kept = settle done; broken and cancelled = settle dropped, with the reason saying which. The settle rate counts both broken and cancelled as not kept; it cannot distinguish cancellation from a broken promise.

Interaction or relationship journal

Event trace tagged event, optionally note, recorded with --settled done and an honest reason. Owner = writer, subject = the other soul. Long running relationship prose belongs in a series of event traces, not one ever-edited text field.

Beliefs

Tag belief, weight = certainty, source kind as a category tag (explicit, observed, inferred, distilled). Correct with a new trace using supersedes; forget with settle dropped and a reason. To merge beliefs, record a new trace with all parent ids in supersedes. Append-only logs map to recording without supersedes.

Approvals

One trace tagged approval, owner = Fox (approver), counterpart = approved soul. Settle done when granted, dropped when declined. This replaces keeping an approval in two stores.

Rules and decisions

Tag rule or decision on Fox's soul.

What traces do not replace

  • Recurring dates.

  • Scheduling and recurrence; keep using questlog.

  • Due-claim delivery.

  • Contact identities and channels.

  • Procedures and skills.

Trace workflows include atomic trace roll <id> --next-due +7d, JSONL batch recording (trace record --batch file.jsonl), historical --import, merge parents, and explicit revision compaction. Filter commitments with --exclude-tag belief; use --all or page with --limit and --offset. See Traces for dates, output envelopes, and statistics.

Soul listing: ghostpaw-souls soul list aliases review list. ISO datetimes may include Z/an offset or omit it (for example 2026-11-11T02:02:00); local datetimes resolve using --tz, then TZ, then the host zone. Bare UUID soul references fall back to external IDs; ext:<uuid> selects that binding explicitly.

Database connections accept --db file:///absolute/path/souls.db. --busy-timeout <ms> or GHOSTPAW_SOULS_BUSY_TIMEOUT sets the lock wait budget (default 5000); a lock wait prints one stderr notice. --timings or GHOSTPAW_SOULS_TIMINGS=1 prints open, initialization and total timings to stderr. These environment settings also apply to MCP connections.

Use shard retract <id> --reason <text> or shard supersede <id> --by <id> to withdraw evidence from readiness and citation scoring while retaining it. shard show <id> and shard history <id> expose the retained record and withdrawal metadata. MCP/tool callers use the corresponding observe_soul actions with id, reason or by; searches with status all retain withdrawn evidence.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to persist and retrieve memories via a personal knowledge graph, with tools for emotional intelligence, CRM, life management, social features, self-training, and autonomous insights.
      584 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables agents to carry portable reputation across platforms, with tools for registering agent identities, vouching, verifying trust, and managing memory.
      MIT