GhostPaw Grimoire

@ghostpaw/grimoire

以 SKILL.md 文件夹形式组织 Agent 技能，并将每次改进封存为可回滚的 git 提交。

npm install @ghostpaw/grimoire

一款面向 Node.js 的程序化知识引擎，基于 Git、SQLite 和文件系统构建。

Grimoire 将咒语（已掌握的流程）、证据、版本管理和健康状况整合为一个统一模型，而非彼此独立的系统。它以单个预打包文件发布，运行时零依赖，同时面向两类用户：直接编写代码的人类开发者，以及通过结构化的 soul / tools / skills 运行时进行操作的大模型 Agent。

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 的客户端，可从 releases 下载 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"}'

Agent 技能：请参阅 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);

模型

八个概念，严格分离关注点：

概念	用途
Spell	以 SKILL.md 存储的已学习流程，包含 YAML 前置元数据和 Markdown 正文
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 积累 已封印的改进，Tier 也会逐步提升：

 

刻录

$\color{Gray}{\textsf{◎}}$	deploy-service	uncheckpointed · no seals yet
	↓   封印一项已验证的改进

打磨

$\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 时，应附带汇总内容。

两类受众

人类开发者

使用 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 Agent

使用 tools、skills 和 soul 命名空间，借助结构化的运行时接口 降低 LLM 的认知负荷：

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	详细检查单个法术：阶级、共鸣、验证、来源、历史记录
inscribe_spell	在魔法书中创建新法术
update_spell	向现有法术写入新内容，保留未提交状态以供 hone_spell 处理
hone_spell	将待处理的更改封存为 git 提交，并提升阶级；可选择提炼已吸收的笔记
manage_spell	将法术存档、取消存档、移动、删除、修复或回滚
drop_note	记录观察笔记，供日后归档
manage_draft	提交、批准或驳回拟议法术
run_catalogue	全面维护：检查过时、休眠、过度膨胀、笔记路由和健康状况
scout_skills	从外部来源侦察、搜索、采纳和更新法术

每个工具都会导出运行时元数据、JSON Schema 输入和结构化输出， 使各类运行框架无需解析含糊的描述即可将其接入。

主要特性

• 零运行时依赖。 SQLite 层仅使用 node:sqlite（内置于 Node 24+）。
• 单一预打包文件。 dist/ 中提供一个 ESM 入口和一个 CJS 入口。无子路径导出，不拆分代码。
• 三种存储后端。 文件系统用于法术内容，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 接入大模型系统的 Agent 构建者
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