+
+
+
A self-hosted system of record for the work you do with Claude Code.
-Notes, tasks and issues; projects with milestones as plans; rules that reach Claude when its work matches them or at a moment of work; lessons, snippets of prior art and a ledger of the code they account for; design systems; ideas shared across projects on the same platform; and stored processes. Semantic search feeds both Claude's recall and the plugin's context injection. A knowledge graph, sharing with users and groups, and scheduled backups round it out. See [Features](docs/features.md). +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 +## Quick start -**Prerequisites:** Docker and Docker Compose. No GPU or local model needed — Claude is the sole assistant, reached over MCP. - -Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml) from this repo, then: +You need Docker with Compose. Download [`docker-compose.quickstart.yml`](docker-compose.quickstart.yml), then: ```bash -# Optional but recommended — set a secret key -export SECRET_KEY=your-random-secret-here +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 ``` -Open `http://localhost:5000`. The first user to register becomes admin. To connect Claude, create an API key under **Settings → MCP Access** and install the Claude Code plugin — see [API Keys & MCP](docs/api-keys-and-mcp.md). +Database migrations run when the app starts. Claude Code updates the plugin from its marketplace; run `/reload-plugins` after an update. -> **Development:** To build from source, see [Development](docs/development.md). +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). -## Documentation +## Features -| Doc | Contents | -|-----|----------| -| [Architecture](docs/architecture.md) | Stack, design decisions, data models, key services | -| [Configuration](docs/configuration.md) | Environment variables, Docker Compose, production setup, security | -| [Features](docs/features.md) | Detailed feature breakdown and keyboard shortcuts | -| [Development](docs/development.md) | Dev workflow, CI/CD, migrations, release process | -| [API Keys & MCP](docs/api-keys-and-mcp.md) | API keys and installing the Claude Code plugin | -| [SSO / OAuth](docs/sso-oauth.md) | OIDC setup for Authentik, Keycloak, and other providers | -| [Backups](docs/backups.md) | Scheduled backups to a folder or S3, and restoring from one | -| [Design system](docs/design-system.md) | The FabledSword house style and how Grimoire applies it | -| [API Reference](docs/api-reference.md) | All REST API endpoints | +**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. -## License +**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. -This project is privately maintained. +**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 privately maintained. All rights reserved. diff --git a/frontend/src/components/AppLogo.vue b/frontend/src/components/AppLogo.vue index 30bff082..0a64d744 100644 --- a/frontend/src/components/AppLogo.vue +++ b/frontend/src/components/AppLogo.vue @@ -3,6 +3,8 @@ defineProps<{ size?: number }>(); + - -