---
name: vault
description: Read and write notes in ginnoir's self-hosted Obsidian vault via the Obsidian MCP server. Use when loading persistent context for a session, saving new context, writing a note, or querying vault contents. The vault is the canonical persistent-context store across Codex sessions.
---

# vault

Obsidian vault accessed via the **`mcp__obsidian__*` MCP tools**. Do not attempt to connect to CouchDB directly — use MCP only.

The MCP server is configured in `~/.mcp.json` and is available in every Codex session. If the tools are listed as deferred, load them with `ToolSearch` before calling.

## Core tools

| Tool | Use |
|---|---|
| `mcp__obsidian__vault_list` | List files/dirs in a directory (omit path for vault root) |
| `mcp__obsidian__vault_read` | Read a file's full content + metadata (tags, frontmatter, links, backlinks) |
| `mcp__obsidian__vault_write` | Create or overwrite a file |
| `mcp__obsidian__vault_patch` | Append or patch a section without a full rewrite |
| `mcp__obsidian__vault_delete` | Delete a file |
| `mcp__obsidian__vault_move` | Move or rename a file |
| `mcp__obsidian__search_simple` | Full-text search across the vault |
| `mcp__obsidian__search_query` | Advanced query search |
| `mcp__obsidian__tag_list` | List all tags |

## Load context at session start

```
1. mcp__obsidian__vault_read  path="Codex/Context.md"
2. Follow [[wikilinks]] to read specific notes as needed
```

`Codex/Context.md` is the master index. It links to all other context notes under `Codex/`.

## Read a note

```
mcp__obsidian__vault_read  path="Codex/Homelab.md"
```

Returns: `content` (full markdown), `tags`, `frontmatter`, `links`, `backlinks`, `stat`.

To read only a section:
```
mcp__obsidian__vault_read  path="Codex/Services.md"  targetType="heading"  target="BookStack"
```

## Write a note

```
mcp__obsidian__vault_write  path="Codex/MyNote.md"  content="# Title\n\nContent here."
```

Creates parent directories automatically. Overwrites without warning.

## Append to a note

```
mcp__obsidian__vault_patch  path="Codex/Context.md"  ...
```

Use `vault_patch` when adding a section to an existing note to avoid rewriting the whole file.

## Search the vault

```
mcp__obsidian__search_simple  query="portainer env vars"
```

## Vault structure

```
Codex/
  Context.md       — master index, session start guide, quick nav
  Homelab.md       — topology, stacks, networks, paths
  Deploy.md        — deployment channels
  SSH.md           — SSH ops, container management
  Portainer.md     — env interpolation gotcha, new stack registration
  Services.md      — per-service quirks (BookStack, Caddy, secrets policy)
  ROM Library.md   — RomM, igir, Pokémon romhacks, EmuDeck tree
  Monitoring.md    — Uptime Kuma v2 socket technique
  Vault.md         — this stack's infrastructure, MCP access
testing.md         — original connectivity test note
Pokémon ROM Hacks/   — Pokémon romhack KB in the live vault; catalog + build
                       scripts live in the standalone Documents\pokemon repo
```

## Load tool schemas (if deferred)

If `mcp__obsidian__vault_read` is not yet callable, run:
```
ToolSearch  query="select:mcp__obsidian__vault_list,mcp__obsidian__vault_read,mcp__obsidian__vault_write"
```