# GhostPaw Grimoire

> GhostPaw Grimoire is an open-source MCP server for knowledge and memory. Versioned agent skills as SKILL.md folders with git history, rollback and evidence notes. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** Linux, macOS, Windows, CLI, self-hosted
- **Website:** https://grimoire.ghostpaw.dev
- **Repository:** https://github.com/ghostpawjs/grimoire
- **MCP Registry name:** io.github.GhostPawJS/grimoire
- **Categories:** knowledge and memory, developer tools
- **Listing updated:** 2026-11-14

## About

Grimoire answers the question of who keeps the history when an agent edits its own SKILL.md. Each procedure, which it calls a spell, is a folder on your disk, improvements are sealed as git commits inside the spell root, and evidence notes live in SQLite. A spell's rank counts its sealed commits, and rollback restores an earlier version for review.

The workflow is deliberately gated. A write validates that the file has proper frontmatter, a note from practice is stored as pending evidence, and an agent's edit stays uncommitted until somebody seals it. The site replays a deploy-service spell step by step from a real run to show this, and notes that the format check is not a security scan.

It ships as a single executable for Linux, macOS and Windows with zero runtime dependencies, or as an npm library needing Node.js 24 or newer. Paths are set through `GHOSTPAW_GRIMOIRE_ROOT`, `GHOSTPAW_GRIMOIRE_GIT_DIR` and `GHOSTPAW_GRIMOIRE_DB`, and a Dockerfile and MCP bundle are provided. It is MIT licensed.

## Features

- **Spells as files:** Procedures are SKILL.md folders on your own disk.
- **Git-sealed history:** Each improvement is a commit that can be rolled back.
- **SQLite evidence notes:** Notes from practice are kept as pending evidence until used.
- **Rank by commits:** A spell's rank counts its sealed commits.
- **Single binary:** One executable with zero runtime dependencies.
- **Configurable paths:** Environment variables set the spell root, git directory and database.

## Good for

- Keep a revision history of skills an agent edits
- Roll a procedure back to an earlier version for review
- Record evidence notes from practice before changing a skill
- Run a local skill library for Claude Code, Codex or Cursor

## Install

### Claude Code (Terminal)

```sh
claude mcp add grimoire -- npx -y @ghostpaw/grimoire
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "grimoire": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@ghostpaw/grimoire"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## FAQ

### Where is the data stored?

Spells are files on your disk, history is a git repository inside the spell root, and metadata is SQLite, defaulting to ~/.ghostpaw/grimoire.db.

### What does it need to run?

The release binary includes its runtime. npm and library use need Node.js 24 or newer.

### Does an agent's edit apply immediately?

No. The edit waits uncommitted until somebody seals it.

### What licence is it?

MIT, with zero runtime dependencies.

### Is GhostPaw Grimoire free?

Yes. GhostPaw Grimoire is open source, so you can use and self-host it for free.

### How do I add GhostPaw Grimoire to Claude Code?

Run this command in your terminal: claude mcp add grimoire -- npx -y @ghostpaw/grimoire

### What are the best alternatives to GhostPaw Grimoire?

The closest alternatives to GhostPaw Grimoire are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/ghostpaw-grimoire
