A self-hosted system of record for the work you do with Claude Code.
Claude records what it learned, decided and built in Grimoire, and that record reaches the next session, so a solution is recalled instead of reinvented. Notes, tasks, plans, rules, lessons and reusable code live in one place. Claude reaches them through a built-in MCP endpoint and the bundled Claude Code plugin, and people read and edit the same records in the web UI. There is no language model inside Grimoire: Claude is the only assistant. ## Quick start You need Docker with Compose. Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml), then: ```bash SECRET_KEY=$(python3 -c 'import secrets; print(secrets.token_hex(32))') \ docker compose -f docker-compose.quickstart.yml up -d ``` Open `http://localhost:5000`. The first account you register becomes the admin. To connect Claude, create an API key under **Settings → MCP Access**, then in Claude Code: ``` /plugin marketplace add https://git.fabledsword.com/bvandeusen/FabledGrimoire.git /plugin install grimoire@grimoire-plugin ``` The plugin asks for your Grimoire URL and the API key. Settings → MCP Access shows the exact commands for your instance. ## Configuration Set these in the environment or a `.env` file beside the compose file: | Variable | Needed | What it does | |----------|--------|--------------| | `SECRET_KEY` | Yes | Signs sessions and seals stored credentials. Set it once and keep it | | `BASE_URL` | Behind a proxy | The public URL, used in email links and SSO redirects | | `SECURE_COOKIES` | Over HTTPS | `true` when Grimoire is served over HTTPS | | `TRUST_PROXY_HEADERS` | Behind a proxy | `true` to read the client address from the proxy's headers | | `POSTGRES_PASSWORD` | Recommended | The database password (defaults to `grimoire`) | Everything else (registration, email, SSO, git forge connections, retrieval tuning, backups) is in **Settings**, or listed in [Configuration](docs/configuration.md). ## Setup pitfalls - **Keep your `SECRET_KEY`.** Forge tokens and the backup bucket's secret are sealed under it. If it changes, Settings asks you to enter those credentials again. - **The embedding model downloads on first use**, into the `/data` volume. Without internet access, semantic search falls back to keyword search until the model is in place. - **Behind a reverse proxy, turn off response buffering** for `/mcp`, because MCP responses stream. [Configuration](docs/configuration.md#behind-a-reverse-proxy) has an Nginx example. ## Updating and backups ```bash docker compose -f docker-compose.quickstart.yml pull docker compose -f docker-compose.quickstart.yml up -d ``` Database migrations run when the app starts. Claude Code updates the plugin from its marketplace; run `/reload-plugins` after an update. Everything Grimoire stores is in the database. **Settings → Data → Scheduled backups** writes a daily backup to a folder or an S3-compatible bucket, and `python -m grimoire.restore` brings a fresh instance back from one. See [Backups](docs/backups.md). ## Features **Working with Claude** - Claude enters a project and gets a short primer: its goal, current plans, open tasks and areas. - Your rules reach Claude when its work matches them, or at a moment of work such as finishing a task or pushing code. - Before Claude writes a file or runs a command, the plugin shows it the rules, lessons and reusable code that may apply. - Stored procedures, such as a drift audit, become Claude Code skills. **Recording the work** - Notes in a Markdown editor, with wikilinks, tags and version history. - Tasks, issues and time-boxed investigations, with work logs that the next session reads first. - Plans as milestones: a design plus ordered steps. - Lessons learned the hard way, linked to the rules they illustrate. - Duplicate checks, so a new record that matches an existing one updates it instead. **Reusing code** - Snippets of reusable code, each with when to reach for it and where it lives in the repo. - With a git forge connected, Grimoire tracks every function and style in your repos and shows which ones are still unaccounted for. - Ideas shared across projects on the same platform, with each project's answer recorded. - Design systems with tokens, inheritance and a generated stylesheet. **For people** - A web UI to browse, search and edit everything, plus a graph of how notes connect. - Sharing with users and groups, as viewer, editor or admin. - Email and password sign-in, optional SSO through OIDC, and invite links. - Personal export to Markdown or JSON, and admin backup and restore. The full list is in [Features](docs/features.md). ## Troubleshooting | What you see | Why | Fix | |--------------|-----|-----| | `SECRET_KEY is set to the insecure default` at startup | `SECURE_COOKIES=true` while `SECRET_KEY` is still the built-in default | Set `SECRET_KEY` | | `Can't locate revision identified by '…'` at startup | An older image is running against a database a newer one has already migrated | Run the newer image; migrations only move forward | | The plugin's tools are missing in Claude Code | The plugin isn't installed, or Claude Code hasn't reloaded it | `/plugin` to install or update it, then `/reload-plugins` | | Search finds only exact words | The embedding model hasn't downloaded yet | Give the app internet access once, or wait for the first download to finish | ## Development ```bash cp .env.example .env # then set SECRET_KEY docker compose up --build ``` [Development](docs/development.md) covers checks, migrations, the plugin and CI. [Architecture](docs/architecture.md) describes how it is built, and the [API reference](docs/api-reference.md) lists every REST endpoint. ## Licence Fabled Grimoire is free software under the [GNU Affero General Public License v3.0 only](LICENSE) (`AGPL-3.0-only`). If you run a modified version for other people over a network, the licence requires you to offer them its source.