bvandeusenandClaude Opus 5.5
81fe851509
LICENSE carries the GNU Affero General Public License v3.0 text, the same file the other Fabled projects ship. pyproject.toml, the frontend's package.json and lockfile, and the plugin manifest declare it as the SPDX expression AGPL-3.0-only, and the README says what it asks of anyone who runs a modified version over a network. Reading `license` as an SPDX expression needs setuptools 77, so the build floor rises to it. The project description now matches the README's tagline. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Fabled Grimoire
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, then:
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.
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
/datavolume. 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 has an Nginx example.
Updating and backups
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.
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.
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
cp .env.example .env # then set SECRET_KEY
docker compose up --build
Development covers checks, migrations, the plugin and CI. Architecture describes how it is built, and the API reference lists every REST endpoint.
Licence
Fabled Grimoire is free software under the GNU Affero General Public License v3.0 only (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.