How to Connect Hermes Agent to a Markdown Knowledge Base via Native MCP
To connect Hermes Agent to Sphene, register Sphene as a Stdio MCP server via hermes mcp add sphene --command /usr/local/bin/sphene --args mcp --env SPHENE_URL=http://127.0.0.1:8743.
This provides Hermes with sub-millisecond SQLite FTS5 search, AST-level heading extraction, and staged patch folding under 25MB RAM—completely eliminating brittle terminal shell piping and quote-escaping errors.
Why Native MCP Replaces Brittle Shell Piping
When autonomous agents interact with markdown folders via bash commands (such as cat << 'EOF', grep -rn, or curl pipelines),
multiple operational failure points occur:
- Terminal Escaping Misfires: Markdown content with nested backticks, quotes, or LaTeX math breaks bash heredocs, causing silent note truncation.
- Subprocess Overhead: Spawning a new shell, parsing curl flags, and formatting raw text introduces 100–300ms latency per tool turn.
- Context Exhaustion: Dumping entire 3,000-word files into agent memory just to read one checklist burns thousands of tokens per step.
With Model Context Protocol (MCP), Hermes calls strongly-typed JSON-RPC methods directly over stdio. Tool execution completes in under 1.5 milliseconds with zero shell interpolation.
Step 1: Verify Sphene Kernel Daemon
Ensure the Sphene kernel daemon is running on your host system or container network:
# Start Sphene background daemon (<25MB RAM)
sphene daemon &
# Verify HTTP gateway health
curl -s http://127.0.0.1:8743/api/v1/health
# Output: {"status":"ok","version":"2.2.0"}Step 2: Add Sphene to Hermes Agent MCP Configuration
Run the official Hermes CLI command to register Sphene as an active MCP server:
hermes mcp add sphene --command /usr/local/bin/sphene --args mcp --env SPHENE_URL=http://127.0.0.1:8743
Alternatively, add Sphene directly to your ~/.hermes/config.yaml (or /opt/data/config.yaml):
mcp_servers:
sphene:
command: /usr/local/bin/sphene
args:
- mcp
env:
SPHENE_URL: http://127.0.0.1:8743
enabled: trueStep 3: Available MCP Toolset
Once enabled, Hermes automatically discovers 8 native Sphene tools:
| Tool Name | Capability | Latency |
|---|---|---|
sphene_search |
Sub-millisecond FTS5 search across notes, tags, and content | < 0.20 ms |
sphene_find_in_doc |
Intra-document pinpoint match for sentences, facts, or tasks | < 0.05 ms |
sphene_read |
Read note with heading AST extraction & staged review notice | < 0.10 ms |
sphene_patch |
Surgical section append/prepend/replace folded into Timeline | < 0.50 ms |
sphene_write |
Create new notes in Workspace/ with instant FTS5 indexing | < 0.50 ms |
sphene_daily |
Append updates to today's daily log note | < 0.50 ms |
Step 4: Human Veto & Differential Timeline Review
When Hermes updates an existing document via sphene_patch, Sphene does not silently overwrite your file.
Instead, the modification is staged in .sphene/staged/. Open the Sphene dashboard at
http://localhost:8743 to inspect the side-by-side color-coded diff
and accept or reject it with 1 click.