MCP Server
Reference for the hermes_brain_mcp.py Model Context Protocol server.
Hermes Brain bundles a Model Context Protocol (MCP) server, _System/Scripts/hermes_brain_mcp.py. It exposes your vault to Hermes Agent, OpenClaw, and other MCP clients such as Claude and Cursor over stdio JSON-RPC.
Tools
| Tool | Purpose | Arguments |
|---|---|---|
vault_search | Search markdown notes by keywords, tags, or text snippets | query (required), folder (optional, e.g. 01-Projects), limit (default 10) |
read_note | Read the full content of a note | path (required, relative to the vault root) |
get_user_profile | Fetch alignment rules, behavioural guidelines, and communication boundaries from User-Profile.md | none |
get_active_adrs | Fetch all accepted Architecture Decision Records so the agent stays consistent | none |
stage_memory_candidate | Stage a fact into Memory-Review for human verification | fact (required), category, source, rationale |
vault_stats | Vault telemetry: session count, active projects, pending reviews, skills | none |
stage_memory_candidate accepts these categories: user_preference (default), project_fact, architectural_rule, learned_workflow.
Resources
The server also publishes a few notes as MCP resources: the Map of Content (MOC), the User Profile & Boundaries, and the Vault Operational Dashboard.
Examples
Searching the vault:
{
"name": "vault_search",
"arguments": {
"query": "prompt optimization",
"folder": "03-Resources",
"limit": 5
}
}
Staging a memory candidate:
{
"name": "stage_memory_candidate",
"arguments": {
"fact": "User prefers concise, practical guidance over theory.",
"category": "user_preference",
"source": "session-2026-11-03",
"rationale": "Stated twice in one session when asking for summaries."
}
}
Staged candidates appear in 04-Archives/Memory-Review/. Run promote_memory.py --review to approve or dismiss them. Nothing becomes permanent memory without you reading it first.
Self-test
From the vault root:
python _System/Scripts/hermes_brain_mcp.py --test
Expected output ends with All hermes-brain-mcp self-tests PASSED. No Hermes install is needed for this check.
Security
- Never commit real vault content, API keys, or chat history back to the template repository.
Daily/,Memory-Review/*(exceptTEMPLATE.md), and.smart-env/are git-ignored for this reason.- The Local REST API plugin generates its own key on first enable. Store it with
hermes config set env.OBSIDIAN_REST_API_KEY "<key>", never as a plaintext note.