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

CLI use
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.
MCP use
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.

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 — the same queries you'd write in the app's Query panel.
Search
Full-text or meaning-based (semantic) search across your notes.
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

⌥

CLI use

Query, search, and propose from your shell, with JSON output.

 🔌

MCP use

Expose the thoughtbase to an AI agent as MCP tools.