@ghostpaw/souls

@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.

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

Install

npm install @ghostpaw/souls

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

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 { ether } from '@ghostpaw/souls';

const etherDb = ether.open('ether.db');
ether.registerDefaults(etherDb);
await ether.refreshAll(etherDb);

const results = ether.search(etherDb, 'security architect');
const newSoul = ether.manifest(soulsDb, results[0]);

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.allToolDefinitions();
const result = tools.executeTool(db, toolName, args);

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

Docs

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

License

MIT