Docs/Connecting to Minerva
Connecting to Minerva
A thoughtbase is plain files and a knowledge graph, so you don't have to be sitting in the app to use it. Minerva ships a command-line interface and a Model Context Protocol (MCP) server that let scripts and AI agents query your notes and propose new ones from outside — even while the app is closed. They reuse the same core the app does, so what they see is exactly what Minerva sees.
Two ways in
Headless, scriptable access from your shell — query the graph, search notes, and file proposals, with grounded JSON output you can pipe straight into other tools.
The same reads and proposals exposed as tools to any MCP client — Claude Desktop, a coding agent, an editor — so an AI agent can ground itself in your thoughtbase and hand work back.
Both are Minerva reaching outward. For the opposite — third-party MCP servers whose tools Minerva's own assistant can call — see Settings → MCP Servers.
What you can do
Both surfaces expose the same core operations over an open thoughtbase:
Query
Run
SPARQL over the knowledge graph or
SQL over your CSV tables, as you would in the app's
Query panel. From your own shell, SQL works just as it does there; an MCP agent's SQL can only read the tables Minerva registered, not files by path (see
why agents are fenced in).
Search
Full-text, meaning-based (semantic), or exact text and pattern search across your notes — the last finds every literal occurrence of a string or regular expression, with the path and line of each match.
Read
Fetch a note's raw markdown by path.
Gather context
Pull a task-relevant slice for a topic — the matching notes plus their link neighborhood — so an agent can seed itself before it starts work.
Propose a note
File a new note as a pending proposal — never a direct write.
Grounded reads, gated writes
Reads come back grounded: query results carry node identifiers, search hits carry the note's path — so an agent can cite exactly what it drew on. Writes are never direct. A proposal goes through the same approval gate as the built-in AI, stamped with who proposed it, and nothing touches your notes until you approve it in the Proposals panel. See Conversations for that review flow.
In depth