@ghostpaw/grimoire 0.2.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +264 -1
- package/package.json +11 -5
package/README.md
CHANGED
|
@@ -1 +1,264 @@
|
|
|
1
|
-
# grimoire
|
|
1
|
+
# @ghostpaw/grimoire
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@ghostpaw/grimoire)
|
|
4
|
+
[](https://nodejs.org)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](package.json)
|
|
7
|
+
[](https://www.typescriptlang.org)
|
|
8
|
+
[](https://ghostpawjs.github.io/grimoire)
|
|
9
|
+
|
|
10
|
+
A procedural knowledge engine for Node.js, built on Git, SQLite, and the filesystem.
|
|
11
|
+
|
|
12
|
+
Grimoire treats spells (learned procedures), evidence, versioning, and health
|
|
13
|
+
as one coherent model instead of separate systems. It ships as a single
|
|
14
|
+
prebundled blob with zero runtime dependencies, designed for two audiences at
|
|
15
|
+
once: human developers working directly in code, and LLM agents operating
|
|
16
|
+
through a structured `soul` / `tools` / `skills` runtime.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @ghostpaw/grimoire
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Requires **Node.js 24+** (uses the built-in `node:sqlite` module).
|
|
25
|
+
|
|
26
|
+
## Quick Start
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { DatabaseSync } from 'node:sqlite';
|
|
30
|
+
import { init, read, write } from '@ghostpaw/grimoire';
|
|
31
|
+
|
|
32
|
+
const db = new DatabaseSync(':memory:');
|
|
33
|
+
const root = '/path/to/my-grimoire';
|
|
34
|
+
|
|
35
|
+
await init({ root, db });
|
|
36
|
+
|
|
37
|
+
// Inscribe a new spell from scratch
|
|
38
|
+
const spell = await write.inscribe(root, {
|
|
39
|
+
name: 'deploy-service',
|
|
40
|
+
title: 'Deploy a service to production',
|
|
41
|
+
tags: ['devops', 'deploy'],
|
|
42
|
+
body: '## Steps\n\n1. Run `npm run build`\n2. Push to registry\n3. Apply manifests',
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
// Drop an observation note as evidence
|
|
46
|
+
write.dropNote(db, {
|
|
47
|
+
topic: 'deploy-service',
|
|
48
|
+
body: 'Build step fails if DOCKER_REGISTRY is not exported first.',
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
// Seal the improvement into a git commit, advancing rank
|
|
52
|
+
await write.seal(root, 'Fix: document required env var for build step');
|
|
53
|
+
|
|
54
|
+
// Read back the enriched spell
|
|
55
|
+
const detail = await read.getSpell(root, db, 'deploy-service');
|
|
56
|
+
const chapters = await read.listChapters(root);
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## The Model
|
|
60
|
+
|
|
61
|
+
Eight concepts, strict separation of concerns:
|
|
62
|
+
|
|
63
|
+
| Concept | Purpose |
|
|
64
|
+
|---|---|
|
|
65
|
+
| **Spell** | A learned procedure stored as `SKILL.md` with YAML frontmatter and a markdown body |
|
|
66
|
+
| **Chapter** | A folder grouping related spells into a focused collection |
|
|
67
|
+
| **Seal** | A git commit marking a verified improvement — rank equals seal count |
|
|
68
|
+
| **Tier** | Mastery level computed from rank: Uncheckpointed → Apprentice → Journeyman → Expert → Master |
|
|
69
|
+
| **Note** | Raw evidence (observation, failure path, correction) awaiting distillation into a spell |
|
|
70
|
+
| **Resonance** | Read-time signal indicating which spells have the highest return on honing effort |
|
|
71
|
+
| **Draft** | A proposed new spell submitted for review before inscription |
|
|
72
|
+
| **Catalogue** | A health snapshot: staleness, dormancy, oversizing, velocity, and clustering |
|
|
73
|
+
|
|
74
|
+
The model means each kind of truth has its own home:
|
|
75
|
+
|
|
76
|
+
| What it looks like | What it actually is |
|
|
77
|
+
|---|---|
|
|
78
|
+
| A how-to guide or runbook | A Spell |
|
|
79
|
+
| Related spells grouped by domain | A Chapter |
|
|
80
|
+
| "This procedure is proven — preserve it" | A Seal |
|
|
81
|
+
| "We got burned by this edge case" | A Note |
|
|
82
|
+
| "This spell hasn't been touched in months" | A Catalogue health signal |
|
|
83
|
+
| "This spell is ready to hone next" | Resonance |
|
|
84
|
+
|
|
85
|
+
State is derived, not hand-toggled. Tier, resonance color, staleness, dormancy,
|
|
86
|
+
and health scores are computed from evidence and commit history at read time,
|
|
87
|
+
never stored as caller-written flags.
|
|
88
|
+
|
|
89
|
+
### Tier progression at a glance
|
|
90
|
+
|
|
91
|
+
Grimoire computes tier markers on every read. They advance as spells accumulate
|
|
92
|
+
sealed improvements:
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
> **Inscription**
|
|
97
|
+
>
|
|
98
|
+
> | | | |
|
|
99
|
+
> |:---:|---|---|
|
|
100
|
+
> | $\color{Gray}{\textsf{◎}}$ | *deploy-service* | `uncheckpointed · no seals yet` |
|
|
101
|
+
> | | ↓   seal a validated improvement | |
|
|
102
|
+
>
|
|
103
|
+
> **Honing**
|
|
104
|
+
>
|
|
105
|
+
> | | | |
|
|
106
|
+
> |:---:|---|---|
|
|
107
|
+
> | $\color{SteelBlue}{\textsf{◎}}$ | *deploy-service* | `apprentice · rank 1–4` |
|
|
108
|
+
> | $\color{MediumSeaGreen}{\textsf{◎}}$ | *deploy-service* | `journeyman · rank 5–14` |
|
|
109
|
+
> | $\color{Goldenrod}{\textsf{◎}}$ | *deploy-service* | `expert · rank 15–29` |
|
|
110
|
+
> | $\color{Orchid}{\textsf{◎}}$ | *deploy-service* | `master · rank 30+` |
|
|
111
|
+
>
|
|
112
|
+
> **Attention signals**
|
|
113
|
+
>
|
|
114
|
+
> | | | |
|
|
115
|
+
> |:---:|---|---|
|
|
116
|
+
> | $\color{OrangeRed}{\textsf{●}}$ | *deploy-service* | `resonance · hone now` |
|
|
117
|
+
> | $\color{Gray}{\textsf{●}}$ | *deploy-service* | `dormant · low return on effort` |
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
Rank is the only experience counter. Tier boundaries gate real capabilities
|
|
122
|
+
(history, diff, rollback), not badges.
|
|
123
|
+
|
|
124
|
+
## Two Audiences
|
|
125
|
+
|
|
126
|
+
### Human developers
|
|
127
|
+
|
|
128
|
+
Use the `read` and `write` namespaces for direct-code access to the domain:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
import { read, write } from '@ghostpaw/grimoire';
|
|
132
|
+
|
|
133
|
+
// Inscribe and evolve a spell
|
|
134
|
+
await write.inscribe(root, { name: 'lint-fix', title: 'Run lint with autofix' });
|
|
135
|
+
write.dropNote(db, { topic: 'lint-fix', body: 'Biome needs --unsafe for some rules.' });
|
|
136
|
+
await write.seal(root, 'Add note about unsafe flag');
|
|
137
|
+
|
|
138
|
+
// Read derived state
|
|
139
|
+
const spell = await read.getSpell(root, db, 'lint-fix');
|
|
140
|
+
const resonance = read.allResonance(db);
|
|
141
|
+
const catalogue = read.readCatalogue(db);
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
See [HUMAN.md](docs/HUMAN.md) for the full direct-code guide with worked
|
|
145
|
+
examples and modeling boundaries.
|
|
146
|
+
|
|
147
|
+
### LLM agents
|
|
148
|
+
|
|
149
|
+
Use the `tools`, `skills`, and `soul` namespaces for a structured runtime
|
|
150
|
+
surface designed to minimize LLM cognitive load:
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
import { tools, skills, soul } from '@ghostpaw/grimoire';
|
|
154
|
+
|
|
155
|
+
// 10 intent-shaped tools with JSON Schema inputs and structured results
|
|
156
|
+
const allTools = tools.grimoireTools;
|
|
157
|
+
const searchTool = tools.getGrimoireToolByName('search_grimoire')!;
|
|
158
|
+
const result = await searchTool.handler({ root, db }, { query: 'deploy' });
|
|
159
|
+
|
|
160
|
+
// Workflow skills for common multi-step scenarios
|
|
161
|
+
const allSkills = skills.grimoireSkills;
|
|
162
|
+
|
|
163
|
+
// Thinking foundation for system prompts
|
|
164
|
+
const prompt = soul.renderGrimoireSoulPromptFoundation();
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
Every tool returns a discriminated result with `outcome: 'success' | 'no_op' |
|
|
168
|
+
'needs_clarification' | 'error'`, structured entities, next-step hints, and
|
|
169
|
+
actionable recovery signals.
|
|
170
|
+
|
|
171
|
+
See [LLM.md](docs/LLM.md) for the full AI-facing guide covering soul, tools,
|
|
172
|
+
and skills.
|
|
173
|
+
|
|
174
|
+
## Tools
|
|
175
|
+
|
|
176
|
+
Ten tools shaped around operator intent, not raw storage operations:
|
|
177
|
+
|
|
178
|
+
| Tool | What it does |
|
|
179
|
+
|---|---|
|
|
180
|
+
| `search_grimoire` | Search spells by name or description |
|
|
181
|
+
| `review_grimoire` | Dashboard views: chapters, health, resonance, notes, drafts, validation, provenance |
|
|
182
|
+
| `inspect_grimoire_item` | Detailed inspection of one spell: tier, resonance, validation, provenance, history |
|
|
183
|
+
| `inscribe_spell` | Create a new spell in the grimoire |
|
|
184
|
+
| `hone_spell` | Seal pending changes into a git commit, advancing rank |
|
|
185
|
+
| `manage_spell` | Shelve, unshelve, move, delete, repair, or rollback a spell |
|
|
186
|
+
| `drop_note` | Drop an observation note for later cataloguing |
|
|
187
|
+
| `manage_draft` | Submit, approve, or dismiss proposed spells |
|
|
188
|
+
| `run_catalogue` | Full maintenance pass: staleness, dormancy, oversizing, note routing, health |
|
|
189
|
+
| `scout_skills` | Scout, search, adopt, and update spells from external sources |
|
|
190
|
+
|
|
191
|
+
Each tool exports runtime metadata, JSON Schema inputs, and structured outputs
|
|
192
|
+
so harnesses can wire them without parsing vague prose.
|
|
193
|
+
|
|
194
|
+
## Key Properties
|
|
195
|
+
|
|
196
|
+
- **Zero runtime dependencies.** Only `node:sqlite` (built into Node 24+) for the SQLite layer.
|
|
197
|
+
- **Single prebundled blob.** One ESM + one CJS entry in `dist/`. No subpath exports, no code splitting.
|
|
198
|
+
- **Three storage backends.** Filesystem for spell content, git for versioning and rank, SQLite for metadata. Each is optional — the package degrades gracefully without any of them.
|
|
199
|
+
- **Evidence-first progression.** Rank is earned by sealing validated improvements. Speculative edits do not count as experience. Tier gates real capabilities, not badges.
|
|
200
|
+
- **Derived health signals.** Resonance, staleness, dormancy, and health scores are computed at read time from evidence and commit history — never stored as flags.
|
|
201
|
+
- **Intention-shaped writes.** `inscribe`, `seal`, `hone`, `dropNote`, `distill`, `adoptSpell`: operations that say what happened, not generic CRUD.
|
|
202
|
+
- **Additive AI runtime.** `soul` for posture, `tools` for actions, `skills` for workflow guidance — layered over the same direct-code API.
|
|
203
|
+
- **Colocated tests.** Every non-type module has a colocated `.test.ts` file. The documented behavior is backed by executable coverage.
|
|
204
|
+
|
|
205
|
+
## Package Surface
|
|
206
|
+
|
|
207
|
+
```ts
|
|
208
|
+
import {
|
|
209
|
+
init, // bootstrap: filesystem + SQLite setup
|
|
210
|
+
initGrimoireTables, // SQLite schema only
|
|
211
|
+
read, // all query functions
|
|
212
|
+
write, // all mutation functions
|
|
213
|
+
tools, // LLM tool definitions + registry
|
|
214
|
+
skills, // LLM workflow skills + registry
|
|
215
|
+
soul, // thinking foundation for system prompts
|
|
216
|
+
} from '@ghostpaw/grimoire';
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
All domain and runtime types are also available at the root for TypeScript
|
|
220
|
+
consumers:
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
import type {
|
|
224
|
+
GrimoireDb,
|
|
225
|
+
GrimoireToolDefinition,
|
|
226
|
+
GrimoireSkill,
|
|
227
|
+
GrimoireSoul,
|
|
228
|
+
GrimoireErrorCode,
|
|
229
|
+
} from '@ghostpaw/grimoire';
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
## Documentation
|
|
233
|
+
|
|
234
|
+
| Document | Audience |
|
|
235
|
+
|---|---|
|
|
236
|
+
| [HUMAN.md](docs/HUMAN.md) | Human developers using the low-level `read` / `write` API |
|
|
237
|
+
| [LLM.md](docs/LLM.md) | Agent builders wiring `soul`, `tools`, and `skills` into LLM systems |
|
|
238
|
+
| [docs/README.md](docs/README.md) | Architecture overview: model, storage topology, and source layout |
|
|
239
|
+
| [docs/entities/](docs/entities/) | Per-concept manuals: spells, notes, events, health, drafts, provenance, registry |
|
|
240
|
+
|
|
241
|
+
## Development
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
npm install
|
|
245
|
+
npm test # node:test runner
|
|
246
|
+
npm run typecheck # tsc --noEmit
|
|
247
|
+
npm run lint # biome check
|
|
248
|
+
npm run build # ESM + CJS + declarations via tsup
|
|
249
|
+
npm run demo:serve # build and serve the browser demo
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
The repo is pinned to **Node 24.14.0** via `.nvmrc` / `.node-version` /
|
|
253
|
+
`.tool-versions` / `mise.toml` / Volta. Use whichever version manager you
|
|
254
|
+
prefer.
|
|
255
|
+
|
|
256
|
+
### Support
|
|
257
|
+
|
|
258
|
+
If this package helps your project, consider sponsoring its maintenance:
|
|
259
|
+
|
|
260
|
+
[](https://github.com/sponsors/Anonyfox)
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
**[Anonyfox](https://anonyfox.com) • [MIT License](LICENSE)**
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ghostpaw/grimoire",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.1",
|
|
4
|
+
"description": "Procedural knowledge management for Node.js — Git, SQLite, zero dependencies, with a built-in LLM tool facade",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"exports": {
|
|
7
7
|
".": {
|
|
@@ -49,11 +49,17 @@
|
|
|
49
49
|
"access": "public"
|
|
50
50
|
},
|
|
51
51
|
"keywords": [
|
|
52
|
-
"skill",
|
|
53
|
-
"capability",
|
|
54
52
|
"grimoire",
|
|
53
|
+
"knowledge-management",
|
|
54
|
+
"knowledge-base",
|
|
55
55
|
"procedure",
|
|
56
|
-
"
|
|
56
|
+
"procedures",
|
|
57
|
+
"runbook",
|
|
58
|
+
"playbook",
|
|
59
|
+
"skill",
|
|
60
|
+
"skills",
|
|
61
|
+
"workflow",
|
|
62
|
+
"git",
|
|
57
63
|
"sqlite",
|
|
58
64
|
"local-first",
|
|
59
65
|
"llm",
|