# Obsidian as a Control Layer for Your AI Agent

Most people who connect Obsidian to an AI agent expect a note-taking feature. What you actually get is more useful: a shared folder that you and the agent both read and write, visible on every device you own, and editable by hand at any time.

This article covers the design, the tooling that exists today, how to wire it up on [Hermes](https://hermes-agent.nousresearch.com/) and [OpenClaw](https://docs.openclaw.ai/), and the technical implications you should know about before you point an autonomous agent at your notes.

## The whole trick is plain files

An Obsidian vault is a directory of Markdown files. Obsidian is an editor and viewer on top of that directory. Nothing more.

That means an agent doesn't need a deep integration. It needs a path. Hermes' bundled [Obsidian skill](https://github.com/NousResearch/hermes-agent/blob/main/skills/note-taking/obsidian/SKILL.md) describes itself as filesystem-first: it lists, searches, reads, creates and patches notes, and adds `[[wikilinks]]`. You point it at a directory and it treats what's inside as notes.

Obsidian itself doesn't have to be running on the machine where the agent runs. So this works:

```text
   Your laptop / phone            Server or VPS
   ┌───────────────┐             ┌───────────────┐
   │   Obsidian    │             │    Hermes     │
   │  you read     │             │  reads notes  │
   │  you edit     │             │  writes notes │
   └───────┬───────┘             └───────┬───────┘
           │                             │
           └────── same vault ───────────┘
                (Markdown files)
```

The agent writes `Projects/Website.md` on the server. Seconds later you read it on your phone. You correct a paragraph. Next session, the agent reads your correction. That two-way flow is the interesting part.

Andrej Karpathy's "LLM Wiki" note from April 2026 is the reference point most of this ecosystem now cites. His summary: "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase." His layering is worth copying:

*   `raw/` — sources you collected. The agent reads these and never edits them. You can always recompile from here.
    
*   `wiki/` — Markdown the agent owns. Entity pages, summaries, cross-links, an index.
    
*   **A schema file** — `AGENTS.md`, `CLAUDE.md` or `.hermes.md` at the root, describing the conventions and the workflows. This is the part that turns a general chatbot into a disciplined maintainer, and it's the file most people underinvest in.
    

## Three jobs, three places

An agent setup like this has three storage layers, and keeping them separate saves a lot of pain.

| Layer | Question it answers | Example |
| --- | --- | --- |
| Agent memory | What should the agent remember? | "This project uses SQLite for v1." |
| Skills | How should the agent do a recurring task? | "How I deploy this website." |
| Obsidian vault | What are we working on, and why? | Project notes, research, decisions |

Memory is compressed on purpose. In Hermes it's `MEMORY.md` and `USER.md`; in OpenClaw it's `MEMORY.md` plus dated files under `memory/`. Either way it gets loaded into context, so it has to stay small. If you dump project detail into it, you end up with a long list of unsorted claims and no way to tell which still hold.

The vault is where the long version lives. Memory says the project uses SQLite for v1. The vault holds the decision record: alternatives, benchmark numbers, what got rejected, what would trigger a migration. Memory is the index. The vault is the corpus.

## The tooling landscape

Four distinct integration shapes exist, and they solve different problems.

**1\. Filesystem-direct.** The agent runs on the same machine as the files and uses ordinary read/write/search tools. Hermes' Obsidian skill works this way; so does running Claude Code or Codex from inside the vault folder. No plugin, no server, works headless, works when Obsidian is closed. This is the default choice.

**2\. Local REST API and MCP.** Adam Coddington's [Local REST API plugin](https://community.obsidian.md/plugins/obsidian-local-rest-api) exposes the vault over an authenticated local HTTPS API and now ships an MCP endpoint at `https://127.0.0.1:27124/mcp/`. The advantage over raw file access is surgical writes: you can target a specific heading, block reference or frontmatter key and append or replace just that section, plus you get Obsidian's own search rather than grep. A pile of third-party MCP servers wrap it ([cyanheads](https://lobehub.com/mcp/cyanheads-obsidian-mcp-server), [orvice](https://lobehub.com/mcp/orvice-obsidian-mcp), [jordanm37](https://lobehub.com/mcp/jordanm37-mcp-obsidian) and others), and there's a newer [REST and MCP server](https://community.obsidian.md/plugins/cli-rest-mcp) plugin exposing Obsidian's CLI commands the same way. The catch: Obsidian has to be running, so this fits a desktop workflow rather than a VPS.

**3\. Agent inside the vault.** [ObsidianClaw](https://github.com/oscarhenrycollins/obsidianclaw) is an official OpenClaw plugin that puts a chat panel with your agent inside Obsidian; it expects a running gateway and Tailscale between your devices. The Claudian plugin does something similar for local coding agents. Good if you want to stay in one window.

**4\. Vault-as-memory-provider.** Several projects turn the vault into the agent's actual memory backend rather than a side channel. [hermes-llmwiki](https://pypi.org/project/hermes-llmwiki/) is a memory provider for Hermes built on the Karpathy three-layer model with no Docker or vector DB. [obsidian-wiki](https://github.com/Ar9av/obsidian-wiki) installs a set of wiki skills across many agents at once. [Vault-for-LLM](https://github.com/zycaskevin/Vault-Agent-Memory/releases) goes further and treats Obsidian as a human review inbox for candidate memories.

You can mix these. Filesystem access on a server, plus the REST plugin on your laptop, is a common combination.

## Setting it up on Hermes

**Point the skill at a vault.** The documented convention is an environment variable, usually in `${HERMES_HOME:-~/.hermes}/.env`:

```bash
# ~/.hermes/.env
OBSIDIAN_VAULT_PATH="/home/me/Obsidian/AgentVault"
```

If it's unset the skill falls back to `~/Documents/Obsidian Vault`. One detail from the skill itself that will bite you otherwise: file tools don't expand shell variables, so the path has to be resolved to a concrete absolute path before it's passed to `read_file`, `patch` or `search_files`. Avoiding spaces in the folder name saves trouble here and in several other tools.

**Add the wiki structure if you want the Karpathy pattern.** Hermes bundles an [LLM Wiki skill](https://hermes-agent.nousresearch.com/docs/user-guide/skills/bundled/research/research-llm-wiki) that builds `raw/` and `wiki/` with wikilinks and YAML frontmatter. Its docs suggest pointing Obsidian's attachment folder at `raw/assets/`, keeping wikilinks enabled, and installing Dataview so you can query pages like a table. If you run both skills, set `OBSIDIAN_VAULT_PATH` to the same directory as the wiki.

**Sync a headless server.** This is the piece that makes the server-side setup practical. [Obsidian Headless](https://obsidian.md/help/headless) is an official command line client (open beta at time of writing) that syncs vaults without the desktop app, keeping the speed and end-to-end encryption of Obsidian Sync. It's published on npm as [`obsidian-headless`](https://www.npmjs.com/package/obsidian-headless) and needs Node.js 22 or later. Obsidian's own docs list giving agentic tools access to a vault without access to your full computer among the reasons to use it, which is exactly this use case.

Don't confuse it with Obsidian CLI, which drives the desktop app from your terminal. Headless runs standalone, with no desktop app anywhere on the machine.

```bash
npm install -g obsidian-headless      # needs Node.js 22+
ob login                               # prompts for email, password, 2FA
ob sync-create-remote --name "Agent Vault"
cd ~/Obsidian/AgentVault
ob sync-setup --vault "<vault-id>"
ob sync                                # initial
ob sync --continuous                   # foreground
```

`ob login` is interactive by default and asks for a 2FA code if the account has it enabled. You can pass `--email`, `--password` and `--mfa` for scripted provisioning, which means a password in your shell history unless you're careful. Log in by hand once and let the stored credentials do the rest.

For background operation, a user systemd unit running `ob sync --continuous` with `Restart=on-failure`, then:

```bash
systemctl --user enable --now obsidian-wiki-sync
sudo loginctl enable-linger $USER      # survives logout
```

Changes show up on the other side within seconds.

**Schedule the notes.** Hermes' [cron](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) accepts natural language schedules and can attach skills to a job:

```python
cronjob(
    action="create",
    skills=["obsidian"],
    prompt="Write today's session log to Agent/Sessions/<date>.md using the template at Agent/_Templates/Session.md.",
    schedule="every 1d at 18:00",
    name="Session log",
)
```

Or from the CLI, scoped to the vault directory:

```bash
hermes cron create "every 1d at 09:00" \
  "Read Projects/*/Agent Instructions.md and write a plan for today into Daily/<date>.md" \
  --workdir /home/me/Obsidian/AgentVault
```

Two things matter here. Cron jobs run in fresh sessions with no conversation history, though persistent memory still loads, so the prompt has to stand on its own. And Hermes automatically discovers project context files (`.hermes.md`, `AGENTS.md`, `CLAUDE.md`, `SOUL.md`) in the working directory. Between those two facts, putting your conventions in a file at the vault root is what makes unattended runs behave consistently.

## Setting it up on OpenClaw

OpenClaw's memory is already Markdown in the agent workspace, which makes the overlap larger. Per its [memory docs](https://docs.openclaw.ai/concepts/memory/index.html), the default layout is an append-only daily log at `memory/YYYY-MM-DD.md` (today and yesterday are read at session start) plus an optional curated `MEMORY.md` that loads only in the main private session. The agent gets `memory_search` and `memory_get`, and there's a small vector index over those files, configured under `agents.defaults.memorySearch` in `~/.openclaw/openclaw.json`.

Two ways to combine that with a vault:

**Workspace inside the vault.** Point `agents.defaults.workspace` at a folder inside your vault, or symlink `memory/` into it. Obsidian then renders the agent's daily logs as daily notes, and you can edit them. Simple, and you keep OpenClaw's own semantic search.

**Vault as a separate project.** Keep the workspace where it is and treat the vault as a working directory with its own `AGENTS.md` contract. This is the shape the [zazencodes guide](https://zazencodes.substack.com/p/ultimate-obsidian-agent-guide-openclaw) walks through for OpenClaw and Hermes together, using a PARA-style structure, Git, and `AGENTS.md` as the shared source of truth.

Worth knowing before you commit: reliable indexing of arbitrary external directories has been an [open feature request](https://github.com/openclaw/openclaw/issues/22958) rather than a settled feature, and the config keys have moved between versions (`memorySearch` used to sit at top level and now lives under `agents.defaults`). Check the current docs rather than trusting a blog post, this one included. There's also an official [openclaw/obsidian skill](https://smithery.ai/skills/openclaw/obsidian) if you want the filesystem-direct route.

## Choosing a sync mechanism

|  | Obsidian Sync + headless | Git | Syncthing / Tailscale |
| --- | --- | --- | --- |
| Version history | built in | excellent | none |
| Conflict handling | conflict copies | real merges | conflict copies |
| Cost | paid | free | free |
| Mobile | first-class | awkward | workable |
| Agent-friendly | very | very | very |

Obsidian Sync plus the headless client is the least work and the only one with good mobile support. Git is what Karpathy uses, and it's the best fit if you want to review agent changes as diffs before accepting them; a vault of Markdown is a well-behaved repo. Syncthing over Tailscale is the free option people reach for when they don't want a subscription or a remote copy.

Whatever you choose, plan for concurrent writes:

*   Give the agent its own files. `Agent/Sessions/`, `Agent/Proposed Memories/`, `Daily/`. Don't have both parties editing the same note in the same minute.
    
*   Prefer anchored appends over whole-file rewrites. Patching under a heading survives your simultaneous edit elsewhere in the file; a full rewrite doesn't.
    
*   Expect conflict copies and clean them up. Nothing here does row-level merging.
    
*   Don't sync `.obsidian/` between machines with wildly different plugin sets unless you like surprises.
    

## Technical implications

**Retrieval is search, not embeddings.** With the filesystem-direct approach the agent finds notes with `grep`, `rg` or glob patterns. That has consequences: filenames carry weight, headings carry weight, and consistent YAML frontmatter (`status`, `tags`, `project`, `created`) is what makes filtering possible. A short index or map-of-content note per project buys you more than any plugin. Dataview and Bases turn frontmatter into queryable tables, which helps you and the agent both.

**Notes cost tokens.** A 3,000-word architecture note is a real chunk of context. Atomic notes with clear headings let the agent read and patch a section instead of loading the whole thing. This is the practical argument for the REST plugin's heading-targeted writes on desktop setups.

**The vault becomes untrusted input.** This is the implication people skip. Once your agent does web research and writes findings into the vault, the vault contains text from the internet, and next session the agent reads it as context. Indirect prompt injection is the dominant attack pattern for agents in 2026: instructions hidden in retrieved content, acted on with whatever permissions the agent already holds. Skill security audits of Obsidian tooling flag this repeatedly, because these skills ingest untrusted note content and hold file-write capability at the same time.

What actually helps, roughly in order of value:

*   **Scope write authority.** The agent writes inside the vault autonomously; anything outside it, and anything network- or shell-shaped, prompts for confirmation.
    
*   **Human review at ingestion.** Treat adding a new source as a supervised step, not an automated pipeline.
    
*   **Provenance.** Require source tags on claims. Content the agent wrote with a citation is more trustworthy than content it pasted from a page.
    
*   **Separate reading from acting.** Don't let a turn that consumed fresh external content also invoke tools that write outside the vault or send data anywhere.
    

What doesn't help: telling the agent to ignore instructions found in notes, or running keyword scanners over ingested text. Both are well documented as ineffective. Semantic injection reads like normal prose.

**Instruction notes are soft control.** A note like this is genuinely useful:

```markdown
# Current priorities
1. Fix the checkout bug
2. Leave the database schema alone

# Constraints
- Don't deploy to production without approval
- Ask before deleting infrastructure
```

You change priorities by editing Markdown instead of repeating yourself every session. But text influences an agent, it doesn't restrain one. Constraints that matter need to be tool permissions, sandbox boundaries and approval gates. Keep both, and don't confuse them.

**The agent's machine is a trusted endpoint.** Obsidian Sync can be end-to-end encrypted, and the vault is encrypted before it leaves a device. The agent still needs plaintext locally, so whichever box runs it holds a decrypted copy. Scope accordingly:

```text
Obsidian/
├── Personal/     ← private notes, separate vault, agent has no path
└── AgentVault/   ← Projects, Research, Agent, Daily
```

Point `OBSIDIAN_VAULT_PATH` at `AgentVault` only. Whatever the agent can reach, it can read, summarise and potentially leak. A separate vault is a cleaner boundary than a subfolder you hope it respects.

**Multiple agents work, with conventions.** A shared vault is a decent blackboard: a research agent writes `Research/Postgres vs SQLite.md`, a planning agent turns it into `Decisions/Database.md`, a coding agent implements it, and you read the whole chain. The Hermes community has [worked examples](https://www.hermesbible.com/flows/3-agent-research-department-notebooklm-obsidian) of exactly this with separate profiles per role, coordinated only through the vault. There's no locking, so the convention that saves you is one writer per file.

## The review loop

The nicest property of this design is that you can see what the agent believes before it becomes permanent.

```text
        agent writes
             ↓
  Agent/Proposed Memories/
             ↓
       you review it
        ↙        ↘
   discard      promote → MEMORY.md
```

Have the agent propose durable facts into a folder instead of writing them to memory itself. You skim, delete the wrong ones, and tell it to promote the rest. Vault-for-LLM formalises the same idea as a candidate-first memory queue with a review dashboard.

This heads off the failure mode that makes agent memory untrustworthy over time: a bad inference gets stored as fact, retrieved in later sessions, and quietly becomes an assumption nobody questions. When the intermediate state is a Markdown file you can open and delete, that loop stays visible.

## What this doesn't give you

Being clear about the gaps makes the design more useful.

There's no automatic recall unless you add it. A memory system surfaces relevant facts without being asked; a vault gets searched, which means it depends on your naming and the agent's diligence.

The graph view is for you. Wikilinks give the agent explicit relationships to follow once it's reading a note, which is real value, but a graph isn't a retrieval system on its own.

And the vault doesn't prune itself. Compression is the thing memory providers do well and files don't. Schedule a consolidation pass: fold overlapping research notes together, archive dead projects, promote the conclusions.

## A minimal setup you can build today

1.  Create a dedicated vault folder, no spaces in the name. Open it in Obsidian.
    
2.  Point the agent at it (`OBSIDIAN_VAULT_PATH` for Hermes, workspace or project dir for OpenClaw).
    
3.  Write `AGENTS.md` at the root: folder purposes, naming conventions, frontmatter fields, and what the agent may write without asking.
    
4.  Create three notes for one real project: `Overview.md`, `Decisions.md`, `Agent Instructions.md`.
    
5.  Add a daily cron job that writes a session log into `Agent/Sessions/`.
    
6.  Add sync (headless client, Git, or Syncthing) when you want it on your phone.
    

Then let it grow from use. A folder you never open is a signal to delete it, not to reorganise it.

## The short version

*   **Memory:** remember this.
    
*   **Skills:** do it this way.
    
*   **Vault:** here's everything relevant to what we're working on.
    
*   **Sync:** make that context available everywhere, to me and to the agent.
    

The point was never note-taking. It's a persistent shared workspace an autonomous agent can read and write, that you can audit and correct with a text editor. For anything running longer than one conversation, that inspectability is the feature worth paying for.

* * *

## Further reading

*   [Hermes Obsidian skill](https://github.com/NousResearch/hermes-agent/blob/main/skills/note-taking/obsidian/SKILL.md) and [LLM Wiki skill](https://github.com/NousResearch/hermes-agent/blob/main/skills/research/llm-wiki/SKILL.md) — the filesystem-first source of truth, including the headless sync recipe
    
*   [Obsidian Headless docs](https://obsidian.md/help/headless) — official CLI sync client, open beta, and the [`obsidian-headless` npm package](https://www.npmjs.com/package/obsidian-headless) that installs it
    
*   [Obsidian Sync security](https://obsidian.md/help/sync/security) — how E2EE works and what it covers
    
*   [Local REST API with MCP](https://community.obsidian.md/plugins/obsidian-local-rest-api) — heading-targeted patching and an MCP endpoint
    
*   [OpenClaw memory concepts](https://docs.openclaw.ai/concepts/memory/index.html) — workspace layout, `memory_search`, vector index config
    
*   [ObsidianClaw](https://github.com/oscarhenrycollins/obsidianclaw) — chat with your agent from inside the vault
    
*   [Ultimate Obsidian Agent Guide](https://zazencodes.substack.com/p/ultimate-obsidian-agent-guide-openclaw) — PARA structure, Git, `AGENTS.md`, local and remote agents on one vault
    
*   [A 3-agent research department on one vault](https://www.hermesbible.com/flows/3-agent-research-department-notebooklm-obsidian) — multi-profile setup coordinated through Obsidian
    
*   [Claude Code + Obsidian workspace layout](https://agenticpm.substack.com/p/claude-code-obsidian-ai-second-brain) — the single `ai-workspace/` folder pattern
    
*   [obsidian-second-brain](https://github.com/eugeniughelbur/obsidian-second-brain) — skill that turns a conversation into cross-linked entity, project and daily notes
    
*   [Prompt injection as residual risk](https://github.com/crcresearch/llm-wiki-memory-template/wiki/Limitation-Prompt-Injection-Residual) — clear write-up of the threat model for exactly this setup
    
*   [awesome-hermes-agent](https://github.com/0xNyk/awesome-hermes-agent) — skills, plugins and memory providers worth browsing