GhostPaw Souls

@ghostpaw/souls

本質と証拠に裏付けられた特性からなるエージェントのアイデンティティ。証拠が一致した場合にのみ洗練されます。

npm install @ghostpaw/souls

認知的アイデンティティのためのプロンプト進化エンジンです。アイデンティティを、物語としての本質と証拠に裏付けられた特性として保存し、構造化されたレベルアップ、結晶化を条件とする洗練、完全なロールバックを実現します。プロンプトテンプレートのライブラリではありません。設定マネージャーでもありません。エージェントの思考方法を進化させるアルゴリズムです。

Node 24 以降、組み込みの node:sqlite を使用し、実行時依存関係はゼロです。

MCP サーバー

以下のすべてのクライアントは、同じ stdio サーバーを起動します：npx -y @ghostpaw/souls mcp。アイデンティティと証拠は、GHOSTPAW_SOULS_DB 環境変数（絶対パス）または --db <path> で別途指定しない限り、~/.ghostpaw/souls.db に保存されます。

Claude Code

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

またはプラグインとして利用できます。プラグインにはスキルも含まれます：

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

Codex CLI（~/.souls/config.toml）

[mcp_servers.ghostpaw-souls]
command = "npx"
args = ["-y", "@ghostpaw/souls", "mcp"]

Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）、またはプロジェクトの .mcp.json：

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

Claude Desktop のユーザーは、最新の GitHub リリースから server.mcpb をインストールすることもできます。コンテナホスト向けに Dockerfile も含まれています： docker build -t ghostpaw-souls . && docker run -i --rm -v souls:/data ghostpaw-souls。

サーバーは MCP 2026-07-28（ステートレス、server/discover）と、initialize ベースのリビジョン 2025-11-25、2025-06-18、2025-03-26、2024-11-05 に対応しています。

CLI

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

ghostpaw-souls バイナリを使うには、グローバルにインストールします：npm i -g @ghostpaw/souls。 ghostpaw-souls mcp で stdio サーバーを起動します。

エージェントスキル

SKILL.md（リポジトリのルート）と skills/souls/SKILL.md は Agent Skills の形式に準拠しており、npm パッケージに含まれています。 skills/souls/ をエージェントのスキルフォルダーにコピーするか、内容を出力します：

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

インストール

npm install @ghostpaw/souls

クイックスタート

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

できること

ソウルは、1つの認知的アイデンティティです。プロンプトテンプレートでも設定オブジェクトでもありません。エージェントの思考、判断、問題への取り組み方を表します。

特性は、出典情報を伴う認知的原則です。作り出されたものではなく、経験から得られたものであることを示す証拠があります。

シャードは、あらゆる情報源から得られ、ソウルに関連付けられる行動観察です。シャードは静かに蓄積します。時間をかけて、独立した複数のチャネルから十分な証拠が集まると、ソウルは洗練の対象になります。

レベルアップでは、要素を統合します。重複する特性を統合し、吸収された特性をエッセンスに昇格させ、学びが続いている特性は引き継ぎます。アイデンティティが再構成され、世代カウンターが増加します。

レンダリングされたアイデンティティブロック（エッセンス＋有効な特性）は、変更が発生するまで静的です。変化もコンテキストの蓄積もなく、再レンダリングのオーバーヘッドもありません。変化する要素がないため、変化しないのです。

API の概要

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

名前空間	目的
read	クエリ — ソウル、特性、シャード、証拠レポートを取得し、アイデンティティブロックをレンダリングします
write	変更 — ソウルの作成、特性の追加・改訂・復元、シャードの削除、レベルアップを行います
ether	ソウルテンプレートの発見 — 約 2,800 件のオープンソースプロンプトを検索し、ソウルとして登録します
soul	組み込みのメンターソウル — 洗練を導くためのガーデナーアイデンティティです
tools	LLM ツールファサード — エージェントフレームワークとの統合に使う JSON Schema 定義です
skills	Markdown の手順 — 結晶化、洗練、レベルアップ、メンテナンスのワークフローです

中核となるライフサイクル

observe → crystallize → refine → level up → repeat

シャードはあらゆる情報源から蓄積します。結晶化により、1 日以上にわたって 2 つ以上の独立したチャネルから証拠が集まるまで、洗練が保留されます。特性は出典情報とともに変化します。アイデンティティが現在の形を超えたとき、レベルアップによって再構成されます。

メンター

このパッケージには、洗練のライフサイクル全体を導くよう調整された組み込みソウル、メンターが 1 つ含まれています。

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

const systemPrompt = soul.renderSoulsSoulPromptFoundation();

Ether — テンプレートの発見

オープンソースのシステムプロンプトのカタログを閲覧・検索し、完成したソウルとして登録できます。

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;

ソースは ETag キャッシュを使って必要に応じて取得されます。更新はアトミックに行われ、取得に失敗しても既存のデータが消去されることはありません。

LLM ツール

JSON Schema のツール定義を使って、あらゆるエージェントフレームワークに接続できます。

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

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

エコシステム

Souls は GhostPaw の認知基盤を構成する 4 つの機能の 1 つです。

機能	領域	中核となるループ
questlog	タスクと約束	計画、追跡、完了、報酬
affinity	人々と関係	出会い、絆を深め、交流し、維持する
codex	信念と知識	記憶、想起、改訂、フラグ付け
souls	認知的アイデンティティ	観察、結晶化、洗練、レベルアップ

各機能は状態の一部を管理します。同じアーキテクチャを採用し、ストレージ層を軽量に保っています。Node 24 以上、組み込みの node:sqlite、実行時依存関係ゼロです。

4 つの機能の中で Souls は独自の存在です。出力がシステムプロンプトになる唯一の機能です。Questlog はタスク状態を生成します。Affinity は関係状態を生成します。Codex は信念状態を生成します。Souls は、ほかのすべての状態の解釈方法を形作るアイデンティティブロックを生成します。

これらが一体となり、成長するエージェントのための完全な認知基盤を形成します。

ドメインへの対応

このエンジンは、「証拠から進化するアイデンティティ」という単一の抽象化を提供します。観察に基づいて行動を改善するあらゆる領域に適用できます。

領域	ソウル	特性
LLM エージェント	エージェントのアイデンティティ	行動原則
ゲーム NPC	NPC の性格	キャラクターの資質
AI コンパニオン	コンパニオンのアイデンティティ	性格の側面
創作	架空の人物	キャラクターの特性
ブランドボイス	ブランドのアイデンティティ	ボイスガイドライン
教育チューター	指導スタイル	教育原則
コードレビュー	レビュアーのスタイル	チームの好み

デモ

RPG のキャラクターシートを思わせるデザインの、ローカルファーストなインタラクティブデモアプリです。

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

ドキュメント

ドキュメント	対象読者
CONCEPT.md	設計の根拠、研究文献、変更不可の前提条件について詳しく説明します
docs/LLM.md	LLM ハーネスの開発者 — ツールのインターフェース、レンダリング、ソウルレイヤー
docs/HUMAN.md	人間の開発者 — read/write/ether API を直接利用します
docs/PAGES.md	デモアプリのページ、アーキテクチャ、開発
docs/entities/	エンティティの詳細解説：ソウル、特性、シャード、レベル、エーテル

ライセンス

MIT