GhostPaw Grimoire

@ghostpaw/grimoire

SKILL.md フォルダーとしてのエージェントスキル。改善のたびに Git コミットとして記録され、いつでもロールバックできます。

npm install @ghostpaw/grimoire

Git、SQLite、ファイルシステムを基盤とする、Node.js 向けの手続き型ナレッジエンジンです。

Grimoire は、呪文（学習した手順）、エビデンス、バージョン管理、健全性を、個別のシステムではなく一貫したモデルとして扱います。実行時依存関係ゼロの、単一の事前バンドル済みファイルとして提供されます。コードを直接扱う人間の開発者と、構造化された soul / tools / skills ランタイムを介して動作する LLM エージェントの両方を対象に設計されています。

MCP サーバー

claude mcp add ghostpaw-grimoire -- npx -y @ghostpaw/grimoire mcp
/plugin marketplace add GhostPawJS/grimoire
/plugin install ghostpaw-grimoire@ghostpaw-grimoire

Codex CLI（~/.codex/config.toml）：

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

Cursor、Claude Desktop、またはプロジェクトの .mcp.json：

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

MCP Bundles に対応するクライアント向けに、リリースから server.mcpb をダウンロードしてください。付属の Dockerfile を docker build -t ghostpaw-grimoire . でビルドし、永続化のために /data をマウントしてください。

MCP 2026-07-28 および initialize ベースのプロトコルバージョン（2025-11-25、2025-06-18、2025-03-26、2024-11-05）をサポートしています。データベースのデフォルトは ~/.ghostpaw/grimoire.db です。--db を指定すると GHOSTPAW_GRIMOIRE_DB が上書きされます。呪文の保存先はデフォルトで ~/.ghostpaw/grimoire/ です。別のディレクトリを選ぶには GHOSTPAW_GRIMOIRE_ROOT を設定してください。ローカルツールの利用に認証情報は必要ありません。

CLI

npx -y @ghostpaw/grimoire tools
npx -y @ghostpaw/grimoire call drop_note '{"source":"practice","content":"Verify the build before release."}'
npx -y @ghostpaw/grimoire call search_grimoire '{"query":"release"}'

エージェントスキルについては、SKILL.md を参照するか、参照資料とともに skills/grimoire ディレクトリをインストールしてください。

インストール

npm install @ghostpaw/grimoire

Node.js 24 以降が必要です（組み込みの node:sqlite モジュールを使用します）。

クイックスタート

import { DatabaseSync } from 'node:sqlite';
import { init, read, write } from '@ghostpaw/grimoire';

const db = new DatabaseSync(':memory:');
const root = '/path/to/my-grimoire';

// Bootstrap: filesystem + SQLite tables + bare git repo with initial commit
init(root, db);

// Inscribe a new spell (content is a spec-compliant SKILL.md string)
const { spell } = write.inscribe(root, db, {
  name: 'deploy-service',
  chapter: 'engineering',
  content: '---\nname: deploy-service\ndescription: Deploy a service to production\n---\n\n# deploy-service\n\n## Steps\n\n1. Run `npm run build`\n2. Push to registry\n3. Apply manifests\n',
});

// Drop an observation note as evidence
write.dropNote(db, {
  source: 'practice',
  content: 'Build step fails if DOCKER_REGISTRY is not exported first.',
});

// Seal the improvement into a git commit, advancing rank
write.seal({ root }, db, [`engineering/${spell.name}`], 'Fix: document required env var for build step');

// Read back the enriched spell
const detail = read.getSpell(root, 'engineering/deploy-service', db);
const chapters = read.listChapters(root);

モデル

8つの概念を、厳密に関心ごとごとに分離します。

概念	目的
Spell	YAML フロントマターと Markdown 本文を含む SKILL.md として保存される、習得済みの手順です
Chapter	関連する Spell をまとめ、目的を絞ったコレクションにするフォルダーです
Seal	検証済みの改善を示す git コミットです。ランクは Seal の数と一致します
Tier	ランクから算出される習熟度です。Uncheckpointed → Apprentice → Journeyman → Expert → Master の順に進みます
Note	Spell に整理されるのを待つ、生の証拠（観察、失敗の経緯、修正）です
Resonance	読み取り時のシグナルで、改善にかける労力に対して最も高い効果が見込める Spell を示します
Draft	記録する前にレビューに提出される、新しい Spell の提案です
Catalogue	健全性のスナップショットです。古さ、休眠状態、過大なサイズ、進捗速度、クラスタリングを示します

このモデルでは、真実の種類ごとに固有の置き場所があります。

どのように見えるか	実際には何か
ハウツーガイドや運用手順書	Spell
分野ごとにまとめられた関連 Spell	Chapter
「この手順は実証済みなので、残しておく」	Seal
「このエッジケースで痛い目に遭った」	Note
「この Spell は何か月も手つかずのまま」	Catalogue の健全性シグナル
「次に改善する Spell はこれ」	Resonance

状態は手動で切り替えるのではなく、導出されます。Tier、Resonance の色、古さ、休眠状態、健全性スコアは、呼び出し元が記述するフラグとして保存されることはなく、読み取り時に証拠とコミット履歴から算出されます。

Tier の進行をひと目で確認

Grimoire は読み取りのたびに Tier マーカーを算出します。Spell に Seal 付きの改善が蓄積するにつれて、Tier が上がります。

 

記録

$\color{Gray}{\textsf{◎}}$	deploy-service	uncheckpointed · no seals yet
	↓   検証済みの改善を Seal する

改善

$\color{SteelBlue}{\textsf{◎}}$	deploy-service	apprentice · rank 1–2
$\color{MediumSeaGreen}{\textsf{◎}}$	deploy-service	journeyman · rank 3–5
$\color{Goldenrod}{\textsf{◎}}$	deploy-service	expert · rank 6–9
$\color{Orchid}{\textsf{◎}}$	deploy-service	master · rank 10+

注意シグナル

$\color{OrangeRed}{\textsf{●}}$	deploy-service	resonance · hone now
$\color{Gray}{\textsf{●}}$	deploy-service	dormant · low return on effort

 

経験を数える指標はランクのみです。Tier が上がるごとに検証の基準も引き上げられます。Journeyman 以降の Spell には失敗時と復旧時の手順が求められ、Expert 以降はエッジケースも必要です。Master では、要約をまとめる必要があります。

2つの対象者

人間の開発者

read および write 名前空間を使って、ドメインに直接コードでアクセスします。

import { read, write } from '@ghostpaw/grimoire';

// Inscribe and evolve a spell
write.inscribe(root, db, { name: 'lint-fix', chapter: 'general', content: '---\nname: lint-fix\ndescription: Run lint with autofix\n---\n\n# lint-fix\n\nRun `npx biome check --fix .`\n' });
write.dropNote(db, { source: 'practice', content: 'Biome needs --unsafe for some rules.' });
write.seal({ root }, db, ['general/lint-fix'], 'Add note about unsafe flag');

// Read derived state
const spell = read.getSpell(root, 'general/lint-fix', db);
const resonance = read.allResonance(db);
const catalogue = read.readCatalogue(db);

実例とモデリングの境界を含む、コードによる直接操作の完全なガイドについては、HUMAN.md を参照してください。

LLM エージェント

LLM の認知負荷を最小限に抑えるよう設計された、構造化ランタイムのインターフェースには、tools、skills、soul 名前空間を使用します。

import { tools, skills, soul } from '@ghostpaw/grimoire';

// 10 intent-shaped tools with JSON Schema inputs and structured results
const allTools = tools.grimoireTools;
const searchTool = tools.getGrimoireToolByName('search_grimoire')!;
const result = await searchTool.handler({ root, db }, { query: 'deploy' });

// Workflow skills for common multi-step scenarios
const allSkills = skills.grimoireSkills;

// Thinking foundation for system prompts
const prompt = soul.renderGrimoireSoulPromptFoundation();

すべてのツールは、outcome: 'success' | 'no_op' | 'needs_clarification' | 'error'、構造化されたエンティティ、次のステップのヒント、実行可能な復旧シグナルを含む、判別可能な結果を返します。

soul、tools、skills を網羅した AI 向けの完全なガイドについては、LLM.md を参照してください。

ツール

生のストレージ操作ではなく、オペレーターの意図を中心に設計された11個のツールです。

ツール	機能
search_grimoire	名前または説明から呪文を検索します
review_grimoire	ダッシュボード表示：章、健全性、共鳴、メモ、下書き、検証、来歴
inspect_grimoire_item	1つの呪文を詳細に調査します：階位、共鳴、検証、来歴、履歴
inscribe_spell	グリモワールに新しい呪文を作成します
update_spell	既存の呪文に新しい内容を書き込み、hone_spell で確定するまで未コミットのままにします
hone_spell	保留中の変更を git コミットとして封印し、階位を上げます。吸収したメモを精練することもできます
manage_spell	呪文を保管、保管解除、移動、削除、修復、ロールバックします
drop_note	後でカタログ化するための観察メモを残します
manage_draft	提案された呪文を提出、承認、却下します
run_catalogue	完全なメンテナンス処理を実行します：陳腐化、休眠、過大サイズ、メモの振り分け、健全性
scout_skills	外部ソースから呪文を調査、検索、採用、更新します

各ツールはランタイムメタデータ、JSON Schema 入力、構造化出力をエクスポートするため、ハーネスは曖昧な文章を解析せずに接続できます。

主な特性

• ランタイム依存関係ゼロ。 SQLite レイヤーには、Node 24 以降に組み込まれた node:sqlite のみを使用します。
• 単一の事前バンドル済みファイル。 dist/ に ESM と CJS のエントリーポイントが1つずつあります。サブパスエクスポートやコード分割はありません。
• 3つのストレージバックエンド。 呪文の内容にはファイルシステム、バージョン管理と階位には git、メタデータには SQLite を使用します。いずれも任意であり、どれがなくてもパッケージは適切に機能を縮退します。
• 証拠を重視した進行。 階位は、検証済みの改善を封印することで得られます。推測に基づく編集は経験として加算されません。上位のティアほど、呪文に求められる検証水準が高くなります。
• 証拠から導出される健全性シグナル。 共鳴、陳腐化、休眠、健全性スコアは、証拠とコミット履歴に基づいて読み取り時に計算され、フラグとして保存されることはありません。
• 意図に沿った書き込み。 inscribe、seal、hone、dropNote、distill、adoptSpell は、汎用的な CRUD ではなく、何が起きたかを示す操作です。
• AI ランタイムを追加可能。 soul で姿勢を、tools でアクションを、skills でワークフローのガイダンスを提供し、同じ直接コード API の上にレイヤーを重ねます。
• テストを同じ場所に配置。 型定義専用ではない各モジュールには、同じ場所に .test.ts ファイルがあります。文書化された動作は、実行可能なテストによって裏付けられています。

パッケージの公開範囲

import {
  init,                  // bootstrap: filesystem + SQLite setup
  initGrimoireTables,    // SQLite schema only
  read,                  // all query functions
  write,                 // all mutation functions
  tools,                 // LLM tool definitions + registry
  skills,                // LLM workflow skills + registry
  soul,                  // thinking foundation for system prompts
} from '@ghostpaw/grimoire';

ドメインとランタイムのすべての型は、TypeScript の利用者向けにルートからも利用できます。

import type {
  GrimoireDb,
  GrimoireToolDefinition,
  GrimoireSkill,
  GrimoireSoul,
  GrimoireErrorCode,
} from '@ghostpaw/grimoire';

ドキュメント

ドキュメント	対象読者
HUMAN.md	低レベルの read / write API を使用する人間の開発者
LLM.md	soul、tools、skills を LLM システムに接続するエージェントの構築者
docs/README.md	アーキテクチャの概要：モデル、ストレージ構成、ソースの配置
docs/entities/	概念別マニュアル：呪文、メモ、イベント、健全性、下書き、来歴、レジストリ

開発

npm install
npm test            # node:test runner
npm run typecheck   # tsc --noEmit
npm run lint        # biome check
npm run build       # ESM + CJS + declarations via tsup
npm run demo:serve  # build and serve the browser demo

このリポジトリでは、.nvmrc / .node-version / .tool-versions / mise.toml / Volta によって Node 24.14.0 を固定しています。お好みのバージョンマネージャーを使用してください。

サポート

このパッケージがプロジェクトに役立つ場合は、メンテナンスへのスポンサーをご検討ください。

---

Anonyfox • MIT License