Grimoire stores project knowledge in Markdown files beside the code. The
AGENTS.md contract tells agents when to read and update the wiki. The optional
grimoire-mcp service searches indexed wikis across projects.
Each project has a wiki/ directory. Its README.md is the entry point. It
holds a short project summary, terms, current work, constraints, and links to
useful topic notes. An agent that works alone reads it and the notes for the
task topic before work. A coordinator does the same before it assigns work.
The numbering reference explains how to name new notes.
Topic notes record decisions and meaningful changes. Each note states what changed, why, how to verify it, and how to roll it back when needed.
Copy AGENTS.md into the project root. It gives a portable contract for wiki
orientation, search, documentation, and final reports. It also covers public
technical writing. Setup steps and the note numbering reference live in this
README and in the wiki template.
Use the same contract in every harness. If a harness reads a different project instruction file, copy the contract into that file. Do not remove the required wiki steps.
grimoire-mcp provides local search with BM25. It does not write source wiki
files. Its tools are:
list_projects— show registered projects and index state.query_wiki— search one project's indexed wiki.read_wiki_passage— read a full indexed passage in bounded parts.reindex_project— update one or all project indexes.
Search covers registered project indexes. It can be stale or refer to another
checkout. Read the matching file in the active checkout before using a result
as a current project fact. When a result marks a passage as incomplete, read
each part with read_wiki_passage, using its project, generation, and chunk ID,
until the passage is complete. See the MCP guide.
Run the setup script from the Grimoire repository:
./setup.sh /path/to/your-projectOr copy the template into your project:
cp -r /path/to/grimoire/wiki-template /path/to/your-project/wikiAdd a one-sentence project summary, terms, current work, constraints, and links
to useful notes in wiki/README.md.
Copy the contract to the project root:
cp /path/to/grimoire/AGENTS.md /path/to/your-project/AGENTS.mdReplace the Scope section with one sentence about the project. If your harness uses another instruction filename, copy the same contract into that file. The contract must keep the wiki orientation and update steps.
Install the local MCP package:
cd grimoire-mcp
uv syncSet WIKI_RAG_PROJECTS_ROOT to the directory that contains your project
directories. See the shared local runtime guide
to connect multiple clients to one authenticated HTTP service. Use that HTTP
connection for Codex. Each stdio client starts its own process; use stdio only
when a client requires it. See the MCP guide for
other connection options.
An agent that works alone reads wiki/README.md and the notes for the task
topic before work. A coordinator does the same before it assigns work.
Search the wiki before asking the user to repeat a decision or explain a term.
Use file tools if MCP search is unavailable.
A worker may use sufficient wiki context and source paths from the coordinator. It reads more notes only when needed. After a topic change or context loss, an agent that works alone repeats this initial wiki read. A coordinator does the same. A continuing worker uses new, sufficient wiki context and source paths from the coordinator. It reads more notes only when needed.
After meaningful work, agents that work alone and coordinators update a topic note. They add one short link to the session log. A worker returns findings and draft wiki changes. It edits a wiki note only when the coordinator assigns it. The coordinator assigns note numbers, updates the session log, and makes final wiki edits. It can assign a specific note to a worker. If no project knowledge changed, state why no wiki note was needed.
The setup script previews changes by default. Add --apply to write them:
python scripts/setup-projects.py --projects-root /path/to/projects
python scripts/setup-projects.py --projects-root /path/to/projects --applyThe script adds missing wiki files and agent guidance. It keeps existing files.
Use --scopes-json with a JSON object to set one-line descriptions for new
contracts. Repeated runs do not add duplicate files. Set
WIKI_RAG_PROJECTS_ROOT to the same directory, then refresh the indexes.
To adopt new projects during scheduled refreshes, set WIKI_RAG_AUTO_SETUP=1 in
the ignored config/wiki-rag.env file. The refresh runs setup before indexing.
Set the value to 0 to disable adoption. The refresh continues to update
indexes.
For full install, verification, and rollback steps, see the wiki-RAG setup guide.
Preview recognized Grimoire instructions before you change them:
python scripts/setup-projects.py --projects-root /path/to/projects --upgrade
python scripts/setup-projects.py --projects-root /path/to/projects --upgrade --applyThe preview shows changed lines and does not write files.
The upgrade accepts exact stock Grimoire sections and skips edited or unclear
files. It keeps unrelated instructions and saves the original AGENTS.md bytes
as AGENTS.md.grimoire-backup in each changed project. Inspect the preview
before you apply it. Scheduled index refreshes do not run contract upgrades.
| File | Purpose |
|---|---|
AGENTS.md |
Portable wiki contract for project agents |
setup.sh |
Copy the wiki template into one project |
scripts/setup-projects.py |
Preview or apply wiki setup across projects |
wiki-template/ |
Starter wiki and numbering reference |
grimoire-mcp/ |
Local server for cross-project wiki search |
skills/ |
Optional workflow guides for agents that support skills |
MIT.
