grimoire

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/brand/grimoire-dark.svg"> <img src="docs/brand/grimoire-light.svg" alt="Grimoire" width="420"> </picture> </p> <h3 align="center">Memory your agents read. You edit.</h3> <p align="center"> <a href="https://github.com/JeremiahM37/grimoire/releases/latest"><img alt="release" src="https://img.shields.io/github/v/release/JeremiahM37/grimoire?label=release&color=8b5cf6"></a> <a href="https://github.com/JeremiahM37/grimoire/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/JeremiahM37/grimoire/actions/workflows/ci.yml/badge.svg"></a> <img alt="Go 1.26+" src="https://img.shields.io/badge/Go-1.26%2B-00add8"> <img alt="license MIT" src="https://img.shields.io/badge/license-MIT-97ca00"> <img alt="MCP server" src="https://img.shields.io/badge/MCP-server-8b5cf6"> <a href="benchmarks/locomo/"><img alt="LoCoMo 92.6% (lenient J judge)" src="https://img.shields.io/badge/LoCoMo%20(J)-92.6%25-e3b341"></a> <a href="benchmarks/locomo/"><img alt="LoCoMo multi-hop 89.1% (lenient J judge)" src="https://img.shields.io/badge/LoCoMo%20multi--hop%20(J)-89.1%25-e3b341"></a> </p> <p align="center"> <a href="docs/FIRST_INSTALL.md">Quickstart</a> · <a href="docs/">Docs</a> · <a href="#mcp-tools-what-claude-gets-in-one-mount">MCP tools</a> · <a href="benchmarks/locomo/">Benchmarks</a> · <a href="https://github.com/JeremiahM37/grimoire/releases">Releases</a> </p> <p align="center"><img src="docs/media/hero.png" alt="Grimoire's editor open on a demo vault" width="900"></p> <p align="center"> Point it at the markdown vault you already have. Your agents read what you know, remember what they learn back into the same files, and act with credentials they can use but never see. One self-hosted Go binary, mounted over MCP. </p> </div>

• Jev-checked memory, now running locally on Laya. We fine-tuned Laya (421M parameters, runs on CPU) on Jev's judgements. It flags facts that have probably gone stale before an agent relies on them, and on held-out real facts it ties its teacher (AUC 0.92 vs 0.90). Open weights.
• Memory that fires when it matters. The right memory is injected with each prompt and again right before a risky command. Rule violations fell from 26 to 11 in 101 cases, and from 10 to 3 in long sessions. When you repeat yourself, Jev spots it and the memory learns that situation.
• Credentials it can use but never read. Agents call APIs through Grimoire with scoped, time-boxed grants; the secret never enters their context. Keep secrets in Grimoire's vault or in Bitwarden, 1Password, KeePassXC or HashiCorp Vault.
• Your notes always win. Agents propose; they never overwrite what you wrote.
• It dreams. Overnight it merges duplicates, fixes broken links, re-checks procedures and sweeps for leaked secrets.
• An Obsidian-like notes app for you and your agents. Take your own notes in it, and agents write theirs into the same vault, side by side, with backlinks and a live graph. It works on your phone, and with Obsidian itself via the plugin.
• One memory for every agent, wired into your stuff. Claude Code, Codex or any MCP client reads the same vault. It pulls in Google Drive and Docs, Gmail, Calendar, Slack, GitHub, Notion, Jira, Confluence and Outlook, and agents can search them live.

curl -fsSL https://raw.githubusercontent.com/JeremiahM37/grimoire/main/install.sh | sh   # Linux, macOS

GRIMOIRE_VAULT=~/obsidian-vault grimoire serve &   # the folder you already have
claude mcp add grimoire -- grimoire-mcp            # your agent now has all of it

| | | |---|---| | Homebrew (macOS) | brew install JeremiahM37/tap/grimoire | | Windows (PowerShell) | irm https://raw.githubusercontent.com/JeremiahM37/grimoire/main/install.ps1 \| iex | | Scoop (Windows) | scoop bucket add jeremiahm37 https://github.com/JeremiahM37/scoop-bucket && scoop install grimoire | | Debian / Ubuntu, Fedora / RHEL | the .deb / .rpm on the latest release | | Docker | docker run -p 127.0.0.1:9111:9111 -v grimoire-vault:/vault ghcr.io/jeremiahm37/grimoire:latest | | Go | go install github.com/JeremiahM37/grimoire/go/cmd/grimoire@latest (and …/grimoire-mcp@latest) |

Release archives and packages ship static binaries for Linux, macOS and Windows on amd64 and arm64, verified against checksums.txt, plus console/plugin files. go install installs the executables only. The shell installer defaults to ~/.local; the native server defaults to localhost. See fresh installs and remote setup for Docker, tokens, services and upgrades.

To build the console from a source checkout, use Node 24 and the Go version in go/go.mod:

npm ci --prefix frontend
npm run build --prefix frontend
go -C go build -o grimoire ./cmd/grimoire
GRIMOIRE_VAULT=~/obsidian-vault ./go/grimoire

The console uses React and TypeScript. Its production assets are in frontend/dist; the server uses that directory when running from the checkout. Docker and release archives build and include those assets automatically, with no Node runtime required. Keep the generated worker and hashed assets together when deploying.

Point your agent at the notes you already have

The runbooks and decisions you have been writing for years already answer many of your agent's questions. Without a connection to those notes, you keep pasting the same context into new sessions. Grimoire makes that existing knowledge available alongside the facts your agents deliberately save.

Grimoire's substrate is a folder of markdown you already own — an Obsidian vault, a Logseq graph, a plain ~/notes. It needs no plugin and does not need Obsidian running, because it reads the files, not the app. Nothing is copied or converted; the watcher picks up edits you make in your own editor, and writes through Grimoire preserve foreign frontmatter byte-for-byte, so whatever notes app you use keeps working on the same files.

Everything else follows from that one decision.

The dark-mode workspace

Create notes in a dedicated panel, search titles and content, or explain the current note without changing it. Search results show the line that matched, with the words you typed marked. Both searches use arrow keys to choose a result, Enter to open it, and Escape to clear the query.

Ctrl/⌘ K (or O) opens one box for everything: the notes you had open last, every note by fuzzy title, and every command, with its shortcut beside it. Open it and press Enter to switch back to the previous note. Ctrl/⌘ P lists commands only, Ctrl/⌘ E flips between reading and editing, Ctrl/⌘ G opens the graph, and ? lists the rest.

The graph fills the screen. Notes glow in the colour of their cluster (or their folder), the note you are editing is ringed, and clicking a note dims everything else and lights its links. Scope it to the open note and its neighbours, one to three hops out; filter by folder, tag or type; or play the vault growing over time, or colour notes by who wrote them, you or your agents. It is drawn on the GPU with the layout in a worker: tools/graph_bench.py measures 60 fps while panning a synthetic 50,000-note vault on a software renderer.

Rename, templates, canvas cards and other actions use in-app panels. Dialogs keep keyboard focus inside, return it on close, and fit above the mobile keyboard.

| Notes and connections | Persistent project memory | |---|---| | | |

These are real captures of the current React UI using a disposable sample vault, not personal notes. The project-memory image comes from a real Lectern → Grimoire provisioning and recall walkthrough, with no paid model calls.

Agent memory that lives in your own markdown

What an agent learns lands in those files too, as ordinary bullets with provenance. When it gets something wrong you fix the line — and the fix outranks a recognized conflicting agent write. Explicit correction targets avoid relying on fuzzy matching to identify the fact being corrected.

Reconciliation compares authority before recency — human > agent > pulled — and a refused overwrite becomes a challenge you settle rather than a silent revert.

grimoire challenges                                    # what your agents dispute
grimoire challenges --note memory/ops.md --uphold ID   # your fact stands
grimoire challenges --note memory/ops.md --concede ID  # the agent was right

Hand edits need no marker: an entry's id is a hash of its own content, so text that changed after the id was minted is text another hand changed.

Memory that knows when to re-check

A remembered port, version or deploy target goes stale silently. Each fact can carry a freshness tier (stable, volatile, or a re-check interval such as 7d) and a check: the read-only command that verifies it. Untiered facts get a change rate learned from their own history. recall then marks each fact use or verify, so agents look up only the few facts that are likely to have changed, and they record what they found.

On real agent transcripts, this served 2–3× fewer stale answers than a fixed re-check timer at the same lookup budget. A scheduled dream keeps the tiers honest from each fact's record, and it sweeps memory, including stored check commands, for secrets, injected instructions and dangerous commands. See docs/FRESHNESS.md for the model, the numbers and their caveats.

Most agent memory is prose about the state of work ("the suite passes", "the repo is at …"), and no text pattern can tell that kind of fact from a settled decision. Point GRIMOIRE_DECISION_URL at a typed-decision model and each untiered fact is asked once, when it is written. Two choices, both speaking the same wire format: Jev, hosted, at about 1.5¢ per thousand facts; or Laya, open-weight and run locally with laya-serve. Stock Laya is no better than chance at this question. Fine-tuned on about 900 labelled example facts (half an hour on a CPU), it matched Jev on a real store, and that checkpoint is published. Grimoire works without either. docs/FRESHNESS.md compares accuracy, speed and cost, and shows how to fine-tune.

Memory that reaches the agent when it matters

Most real misses are not facts the agent failed to find. They are standing rules it already had and didn't apply, such as "never push without asking" or "the lead model plans, a cheaper one implements." The prompt hook injects the memories that bear on each request, matched by meaning as well as by words. It also fires again on the tool call a rule governs: the git push, the file edit, the subagent launch. When the user has to repeat something the store already held, the situation the agent was in is learned as a cue, so that memory fires there next time.

On this deployment's own memory, these changes did three things:

• Retrieval: the right memory reached the agent on 59% of requests, up from 46%.
• Framing: with memory framed as something to follow rather than "reference data", actions that went against it fell from 26 to 11 in 101 cases.
• Long sessions: firing a rule again at the action cut violations from 10 to 3 out of 60.

docs/MEMORY_USE.md has the method, the numbers and what didn't work.

In Obsidian

The [Obsidian plugin