README
¶
go/ — the implementation
One module, two binaries:
| binary | what it is |
|---|---|
cmd/grimoire |
the HTTP server and the CLI (no subcommand = serve) |
cmd/grimoire-mcp |
the MCP server agents mount; proxies this API over stdio or HTTP |
go build -o grimoire ./cmd/grimoire && go build -o grimoire-mcp ./cmd/grimoire-mcp
go test ./...
Package responsibilities are listed in ../docs/ARCHITECTURE.md, along with the five invariants that most review feedback comes back to.
"Port of server/*.py"
Many package docs open with a line like "Port of server/index.py". That file
is not in the tree — Grimoire was originally written in Python, and that
implementation was deleted on 2026-08-14 once this one matched it. The reference
is kept because it explains code that would otherwise look strange: several
places reproduce a Python behaviour exactly rather than improving on it, and
knowing there was an original is the difference between "this is odd" and
"this is odd on purpose".
Two things survive that history and still bind:
compat/fixtures/*.json— frozen output from the original (crypto keys and sealed tokens, note parsing, rendered HTML, CRDT documents, embeddings and token ids, path confinement), replayed byinternal/compaton everygo test. The generator went with the implementation that produced it, so a failing fixture means this build changed, not that the fixture is stale.git log— the Python tree is in history if you need to read it.
Duplication that is deliberate
internal/render and web/markdown.js are two implementations of one markdown
renderer, and they must stay in lockstep: the server renders /read and the
HTML export, while the client renders previews, slides and hover cards with no
network. Neither can be deleted, so each names the other in its header — a rule
added there must land in both.
That is the only forced duplication. Everything else with more than one caller is shared:
internal/embed.ChunkText— indexing and search excerpting chunk identicallyinternal/index.Retrieve— the one retrieval path;/api/retrieve,/api/ask, memory recall and the MCP tools all enter hereinternal/fts— every FTSMATCHexpression, so the "user input is never syntax" invariant has one implementation instead of three- the CLI's
searchandexportrun the server's own HTTP handlers in-process, so a terminal search cannot drift from the API's
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
embedhex
command
Command embedhex prints a text's embedding as hex, for byte-comparison against the Python implementation.
|
Command embedhex prints a text's embedding as hex, for byte-comparison against the Python implementation. |
|
grimoire
command
Command grimoire runs the personal context server.
|
Command grimoire runs the personal context server. |
|
grimoire-mcp
command
Command grimoire-mcp exposes the substrate to agents over MCP (stdio).
|
Command grimoire-mcp exposes the substrate to agents over MCP (stdio). |
|
internal
|
|
|
ai
Package ai is the optional LLM layer: answer synthesis, question decomposition, reranking, memory consolidation and audio transcription.
|
Package ai is the optional LLM layer: answer synthesis, question decomposition, reranking, memory consolidation and audio transcription. |
|
api
Package api serves the HTTP surface: the JSON API plus the web console.
|
Package api serves the HTTP surface: the JSON API plus the web console. |
|
auth
Package auth is identity: who is asking.
|
Package auth is identity: who is asking. |
|
build
Package build reports which build of grimoire is running.
|
Package build reports which build of grimoire is running. |
|
compat
Package compat loads the cross-language fixtures in compat/fixtures/.
|
Package compat loads the cross-language fixtures in compat/fixtures/. |
|
connectors
Package connectors pulls documents from systems that already hold them.
|
Package connectors pulls documents from systems that already hold them. |
|
crdt
Package crdt is a sequence CRDT for note text (conflict-free replicated document).
|
Package crdt is a sequence CRDT for note text (conflict-free replicated document). |
|
crdtstore
Package crdtstore persists per-note CRDT documents for multi-device sync.
|
Package crdtstore persists per-note CRDT documents for multi-device sync. |
|
crypto
Package crypto is the authenticated-encryption layer for the secret vault.
|
Package crypto is the authenticated-encryption layer for the secret vault. |
|
db
Package db is the SQLite index — a rebuildable cache over the vault, with FTS5 for local search.
|
Package db is the SQLite index — a rebuildable cache over the vault, with FTS5 for local search. |
|
embed
Package embed produces the vectors retrieval ranks on.
|
Package embed produces the vectors retrieval ranks on. |
|
eval
Package eval measures retrieval on YOUR vault.
|
Package eval measures retrieval on YOUR vault. |
|
fts
Package fts builds SQLite FTS5 MATCH expressions from user input.
|
Package fts builds SQLite FTS5 MATCH expressions from user input. |
|
history
Package history is note version history — automatic file-recovery snapshots.
|
Package history is note version history — automatic file-recovery snapshots. |
|
index
Package index reconciles vault files into the SQLite index.
|
Package index reconciles vault files into the SQLite index. |
|
markdown
Package markdown parses YAML-ish frontmatter, [[wiki-links]], #tags and titles.
|
Package markdown parses YAML-ish frontmatter, [[wiki-links]], #tags and titles. |
|
mcp
Package mcp exposes the substrate over the Model Context Protocol.
|
Package mcp exposes the substrate over the Model Context Protocol. |
|
memory
Package memory is the fact-level model of agent memory.
|
Package memory is the fact-level model of agent memory. |
|
metrics
Package metrics reports what the server already knows.
|
Package metrics reports what the server already knows. |
|
pyjson
Package pyjson encodes JSON exactly as Python's json.dumps does with its defaults.
|
Package pyjson encodes JSON exactly as Python's json.dumps does with its defaults. |
|
queries
Package queries runs ```query blocks against the index.
|
Package queries runs ```query blocks against the index. |
|
readlog
Package readlog records who opened a restricted document.
|
Package readlog records who opened a restricted document. |
|
render
Package render turns markdown into safe HTML, mirroring the PWA's client renderer (web/markdown.js) so the read surface and HTML export look the same.
|
Package render turns markdown into safe HTML, mirroring the PWA's client renderer (web/markdown.js) so the read surface and HTML export look the same. |
|
secrets
Package secrets is the credential vault and USE-not-READ broker.
|
Package secrets is the credential vault and USE-not-READ broker. |
|
settings
Package settings is a small JSON store in .grimoire/settings.json.
|
Package settings is a small JSON store in .grimoire/settings.json. |
|
sync
Package sync is delta sync with a peer grimoire — local-first, conflict copies, never silent data loss.
|
Package sync is delta sync with a peer grimoire — local-first, conflict copies, never silent data loss. |
|
trust
Package trust says where a note's text came from, and therefore whether an agent may treat it as instructions.
|
Package trust says where a note's text came from, and therefore whether an agent may treat it as instructions. |
|
vault
Package vault is the filesystem side of the store.
|
Package vault is the filesystem side of the store. |
|
watcher
Package watcher is the "edit anywhere" guarantee.
|
Package watcher is the "edit anywhere" guarantee. |
|
websearch
Package websearch answers questions the vault cannot.
|
Package websearch answers questions the vault cannot. |
Click to show internal directories.
Click to hide internal directories.