.svg)
You have an Obsidian vault, and you have Hermes Agent. Getting them to work together is either a one-line config change or a two-part plugin install, depending on what you actually want out of it. Most guides send you straight to the plugin without mentioning that Hermes can already read and write your notes without one.
If either name is new to you: Obsidian is a note-taking app that keeps everything as plain markdown files in a folder on your disk, called a vault. No database, no cloud service, no API. Hermes Agent is an open-source AI agent from Nous Research that runs on your own machine. The two fit together for one reason: to Hermes, your notes are ordinary files it already knows how to read and edit.
This page covers all of it: the setup that needs no plugin, the two that do and what each is good for, whether a vault can serve as the agent's memory, and how to stop the agent touching notes you'd rather it left alone. Every figure is checked against the source repositories and Obsidian's own registry, and community practice is labelled as such.
Key takeaways
- No plugin is required. A bundled Obsidian skill, installed by default, reads, searches, creates and edits vault notes. Point
OBSIDIAN_VAULT_PATHat your vault and it works from the terminal or any messaging surface. - The two plugins solve different problems. Hermes Console puts a real terminal in the sidebar and needs no gateway. Hermes Agent puts a chat panel there but requires the gateway running on port 8642. Both need Obsidian 1.7.2+ and neither works on mobile.
- Adoption doesn't pick a winner. The two are within 6% on downloads, and the registry's headline figure is the sum of per-version counts, so shipping more releases looks like popularity. Choose on fit.
- A vault doesn't become the agent's memory on its own. MEMORY.md stays the layer loaded at session start, and it works best holding pointers to where things live in the vault rather than the content itself.
- The skill grants no access. It teaches the agent how to work with notes. The boundary comes from what you mount, or from the plugin's working-folder setting — left empty, that means the whole vault.
Before any of it: Hermes has to be installed and hermes has to run from a terminal. Check with hermes --version. If it doesn't answer, start with what Hermes Agent actually is. Everything below assumes that command works, since both plugin routes are driven from the command line.
Three ways to set up the Hermes Agent Obsidian integration
Both plugins need Obsidian 1.7.2 or newer and neither runs on mobile. If you already use MCP, there's a fourth route covered near the end.
Does the Hermes AI agent need an Obsidian plugin at all? The plugins buy you two things the skill can't do. Console hands over a highlighted paragraph mid-sentence without leaving the editor; Hermes Agent puts the chat in a panel and can talk to a gateway that isn't on this machine. If neither is a workflow you have, you're done after the next section.
Hermes Agent Obsidian skill setup: OBSIDIAN_VAULT_PATH
Hermes ships this skill as Obsidian, at skills/note-taking/obsidian, marked Bundled (installed by default), MIT licensed, authored by Teknium and the Hermes team, and supported on Linux, macOS and Windows.
It reads OBSIDIAN_VAULT_PATH, by convention from the .env file in your Hermes home. Unset, it falls back to ~/Documents/Obsidian Vault, which is right only if you've never moved your vault.
mkdir -p ~/.hermes
echo 'OBSIDIAN_VAULT_PATH=/Users/you/Documents/MyVault' >> ~/.hermes/.env
On Windows that file lives under %USERPROFILE%\.hermes; add the same line with a Windows path.
Give it a full absolute path rather than a tilde. Start a fresh Hermes session, then check it took by asking the agent to list the markdown files in your vault.
What goes wrong: the file tools don't expand shell variables. Passing $OBSIDIAN_VAULT_PATH straight to read_file fails. The skill's own instructions tell the agent to resolve it to a concrete absolute path first.
What the skill actually does once it's set up
It isn't a chat window over your notes. The skill teaches four operations against the vault as files:
- Read a note by absolute path, with line numbers and pagination rather than dumping the file
- Search filenames or contents, scoped to
.mdwhen you only want notes - Create notes with full markdown, including
[[wikilinks]]to related material - Edit in place with anchored patches, so a change to one section doesn't rewrite the note
That covers most of what people reach for a plugin to get. "Summarise this week's meeting notes and link the sources" needs none of the setup below.
How to install Hermes Console: a terminal inside your vault
Console is a terminal, not a chatbot: a real shell through node-pty, rendered with xterm.js. Its point is the context bridge: highlight text, flip a per-tab toggle, press Enter, and that selection reaches the agent.
- Install the Hermes-side bridge. Missed most often, and without it the toggle does nothing.
hermes plugins install dannyshmueli/obsidian-hermes-console --enable- It appears as
obsidian-context-bridge, not "Hermes Console". That's correct. - Install the Obsidian plugin. Settings → Community Plugins → turn off Restricted Mode → Browse → search Hermes Console → Install → Enable.
- Match the name exactly, because the browser returns namesakes. Hermes TTS (1,350 downloads) makes audio from notes. Hermes R2 Vault (46) encrypts notes to Cloudflare R2 for Hermes, which makes it related but not an integration. On GitHub there's also
symunona/obsidian-hermes, an unrelated Gemini voice assistant. The two you want are named exactly Hermes Console and Hermes Agent. - Download the native binaries. Settings → Hermes Console → Download binaries. Skip this and the console won't open.
- Open a console from the ribbon icon, then turn on the context toggle for that tab. Fresh tabs run
hermesautomatically when the CLI is on PATH; restored tabs deliberately don't.
What goes wrong: the toggle is per-tab and resets on every reload. Bind Toggle note context for active Hermes Console tab to a hotkey; that makes re-enabling cheap, but nothing makes it persist.
Hermes Agent Obsidian plugin: connecting it to the gateway
The Hermes Agent plugin by Jason (jsun2020) speaks HTTP to the gateway and streams replies into a sidebar panel.
Check your version first. In issue #4, the "current note" toggle silently dropped the note whenever the chat input had focus. Fixed in 0.10.0 on August 3, 2026, and 0.10.1 is current — check yours before deciding the toggle is broken.
- Enable the API server. In
~/.hermes/.env: API_SERVER_ENABLED=true
API_SERVER_KEY=change-me-local-dev- Start the gateway.
hermes gateway runkeeps it in the foreground, which is fine for a first test but dies with the terminal. For anything ongoing,hermes gateway installfollowed bystartregisters it as a launchd or systemd service that restarts on crash and at login. Either way it listens on port 8642. Hermes Desktop does both steps and generates the key; read it back withgrep API_SERVER_KEY ~/.hermes/.env. - Confirm it's reachable.
# .env is read by Hermes, not your shell, so pass the key literally
curl -H "Authorization: Bearer change-me-local-dev" <http://127.0.0.1:8642/v1/models>- In PowerShell use
curl.exe. JSON means you're good;401means the key doesn't match; connection refused means the gateway isn't running. - Install and configure the plugin. Settings → Community Plugins → Browse → search Hermes Agent → Install → Enable, then open its settings. Base URL
http://127.0.0.1:8642, paste the key, Transport on Auto, Test connection.
The big one: the TUI is not the gateway. Running hermes gives you a chat REPL with no HTTP API, so the gateway has to be its own process. If the distinction is new, the same pattern in OpenClaw's gateway covers the background.
On a named profile, check the port. Every profile's API server binds 8642 unless you change it; there is no auto-allocation. The docs' multi-user example assigns ports by hand, alice on 8643 and bob on 8644, and the plugin README gives the range as 8643–8742. Only with gateway.multiplex_profiles enabled do profiles share one listener behind a per-profile URL prefix.
"Two read-only permission requests were rejected": the Codex sandbox fix
On the OpenAI-Codex provider, that message means the Codex sandbox rooted its workspace at the gateway's launch directory and defaults to read-only, while the runs endpoint gives an API client no way to set a per-run working directory.
The plugin author's fix is to pin the vault in Codex's own config file, ~/.codex/config.toml. His version points at the vault root; we would scope it tighter:
approval_policy = "never"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
writable_roots = ['/Users/you/Documents/MyVault/AI Workspace']
network_access = true
Restart the gateway afterwards; Codex reads this at startup. Note this cancels the approval prompts recommended in the access control section below — if you set it, narrow writable_roots instead of relying on being asked. Understand the trade: approval policy set to never means nothing stops to ask you again, network access is only needed if your workflows fetch things, and the writable root should be one folder inside the vault rather than the vault itself.
On corporate Windows you may hit CreateProcessWithLogonW failed: 1385, meaning your account lacks the "Log on as a batch job" right. The author notes granting it via secedit may be blocked or reverted by Group Policy, leaving full-access mode as the only one that works there.
Is your Obsidian vault Hermes Agent's memory?
Obsidian AI agent memory is the most common thing people try to build, and the vault alone doesn't get you there. The recurring question is how Hermes knows the vault exists when it still writes to MEMORY.md and USER.md as before? The clearest answer came from the community, not the docs:
MEMORY.md isn't the storage — it's the index.
MEMORY.md is capped and loaded into the system prompt at session start as a frozen snapshot, so it can't hold a knowledge base. What it holds well is routing: pointers telling the agent where each category of information lives in the vault.
One widely-shared community model splits it four ways. It isn't in the docs, but it matches how the pieces behave:
This is also why a vault makes a better shared second brain than any one agent's memory. Hermes' memory lives in its own home directory and belongs to Hermes; a vault is plain markdown on disk, so Claude Code, Codex or anything else that reads files works against the same notes. Setups that run several agents against a single vault exist for exactly that reason.
The pattern that has spread among people running this setup uses hot memory for preferences and active projects, living vault files for stable reference, and one dated note per day as a timeline. What makes it work is filing discipline rather than configuration. See filing habits from long-running Hermes users.
Two numbers not to copy blindly. The 67% promotion threshold that circulates comes from community practice, and it's easy to mistake for a product constant because the docs' own example prompt header happens to read [67% - 1,474/2,200 chars]. Hermes' actual guidance is to consolidate above 80%. And his six-to-nine-thousand-character hot layer can't come from stock defaults, which are 2,200 for MEMORY.md and 1,375 for USER.md. Both are configurable in config.yaml.
Obsidian vault or a Hermes memory provider?
Obsidian is for you: openable, correctable, nothing disappearing into a black-box vector store. The cost is that it's manual, with no automatic extraction or deduplication. A provider inverts that: it resurfaces facts unasked, but you can't easily see what it stored. Running both over the same facts produces duplication and drift, so keep one canonical home per fact.
Hermes ships external memory providers as plugins, one active at a time alongside the built-in files. Run hermes memory setup to see the picker. If you want the vault to stay your single source of truth, skip the provider and let MEMORY.md point into the vault instead.
Hermes Obsidian access control: is it safe to give an agent your vault?
Both Hermes plugins carry the same registry line: "This plugin has not been manually reviewed by Obsidian staff." So do 4,303 of the registry's 6,911 plugins, so it isn't specific to these two. The sharper warning is in the Hermes docs, about the key you paste into the plugin:
The API server gives full access to hermes-agent's toolset, including terminal commands.
Console has no API key, but it spawns a full shell, which is the broader capability of the two. Either way the question isn't whether to trust the plugin — it's how much of the vault you hand it.
The distinction that trips people up isn't in the docs. It comes from a community walkthrough, and it's the cleanest formulation anyone has published:
The skill tells Hermes how to work with the notes. Docker decides which notes it can reach or change.
That checks out: the skill is purely behavioural and grants no permissions at all. If your Hermes tools run in a container, the boundary is whatever you mounted, so access control is a mounting decision.
That walkthrough splits the vault into three zones: read/write for an inbox or agent workspace; read-only for reference notes, where edits fail; and private, where the container sees an empty folder. You see the whole vault; Hermes sees a scoped version.
Not running Hermes in a container? The Hermes Agent plugin has a simpler lever: its working-folder setting, from the folder chip in the chat footer. Empty means the whole vault; point it at one folder and the agent is told to stay there. That's an instruction rather than a boundary, so weaker than a mount, but it's the difference between scoped and wide open.
Either way, initialise the vault as a Git repository with a baseline commit. That isn't access control and hides nothing, but it makes every agent change inspectable and reversible.
On running several agents: one suggestion in circulation is to give one profile vault access and another none. Check before relying on it: Hermes documents per-profile isolation of config, memory, skills and credentials, but not per-profile mounts, and in the official Docker image profiles share a container and so one set of mounts. Separate containers per profile is the version that holds.
Two more habits. Turn auto-approve off for a day and watch what the agent reaches for; the same default causes the same trouble in OpenClaw, where the mitigations are better documented. And keep .obsidian out of cloud-synced folders, because the plugin's key lives in data.json inside it.
Hermes Console vs Hermes Agent plugin: which should you pick?
Pick Console if you live in a terminal, want the agent's raw output, or juggle several sessions at once. It asks for no gateway and no API key, at the cost of a Hermes-side bridge and a binary download.
Pick the Hermes Agent plugin if you'd rather treat Hermes as a writing collaborator. Beyond the chat panel you get a context gauge showing how full the model's window is, a reasoning-effort picker, and a smart graph that infers semantic links between notes rather than reading only your wikilinks.
Running both is fine. They touch different things, since Console spawns a shell and the plugin talks HTTP, and no conflict has been reported in either tracker.
Adoption won't decide it either: 6,381 downloads for Console against 6,763 for Hermes Agent, and since the registry's headline figure is the sum of per-version counts, the plugin that shipped more releases looks more popular. Console shipped 16 to Hermes Agent's 10.
A fourth route: Obsidian MCP server instead of a Hermes plugin
If you already run MCP, the Local REST API with MCP plugin (684,386 downloads) ships an MCP server at https://127.0.0.1:27124/mcp/ with 16 tools, reaching your notes through the running Obsidian app rather than the filesystem.
Hermes Obsidian plugin not working? Common fixes
Start here. Run hermes doctor, then a one-shot hermes chat -q "hello". If the CLI is unhealthy, no plugin setting will fix it.
Console won't open. Nearly always the native binaries. Re-download them in settings, then restart Obsidian completely. On ARM64 Windows, close every terminal tab first, disable and re-enable the plugin, restart, delete .obsidian/plugins/hermes-console/node_modules/, then retry.
"hermes: command not found". Obsidian's process doesn't pick up your shell's PATH. Point the Console's startup command at the CLI's full path, or launch Obsidian from a terminal.
Gateway unreachable. Re-run the curl from the plugin install above. If it answers and the panel still doesn't, the mismatch is in the plugin's Base URL or key. Connection refused means the gateway isn't running.
Selections aren't reaching the agent. Check that the bridge file under .obsidian/hermes/context.json updates when you press Enter. If it does, run hermes plugins and confirm the context bridge is enabled.
The agent sees a different folder than you do. Ask it to run pwd and list the vault folder it can reach. A gateway started from another profile, directory or container resolves paths you never intended.
Replies time out on long vault operations. Raise the request timeout in the plugin's settings before assuming the agent is stuck.
The agent edited notes you wanted left alone. The most-reported real problem, and not a bug. Scope the mount, keep a read-only zone, put the vault under Git. One commenter credits an hourly snapshot with saving them more than once.
The agent can't find notes that are definitely there. Usually inconsistent formatting rather than a broken path. People report letting the agent retrofit consistent frontmatter and tags across an existing vault — on a Git-committed vault, one folder at a time.
Do you need to keep the Hermes gateway running?
Everything above assumes Hermes runs on the machine your vault lives on. That's the right default, and if the bundled skill or Console is all you wanted, you're done.
If you want the chat panel reachable when you're away from that machine, the gateway has to live somewhere that stays up. Installing it as a launchd or systemd service handles crashes and logins, but not a closed laptop or a machine on someone else's network. Atomic Bot runs Hermes as a cloud deployment from $19/month for 4 vCPU, 8 GB and 80 GB storage, and also ships local macOS and Windows apps if you'd rather keep it on your own machine.
The trade cuts against most of this article, so be clear about it: a hosted agent sees its own filesystem, not your vault. The bundled skill and Hermes Console both need the agent local. Only the Hermes Agent plugin works against a remote gateway, and you'd point it at a hosted URL rather than 127.0.0.1 — over HTTPS only, because that key is a terminal key and on a public address it's the whole box.
Related: what developers build with Hermes and running Hermes alongside OpenClaw.
Hermes Agent Obsidian FAQ
Get started
Go to atomicbot.ai. Sign in, choose your agent, OpenClaw Hermes or Codex, and you're running in about five minutes.
