---
title: Vault ↔ Agent Integration
created: '2026-05-23'
updated: '2026-05-23'
type: concept
namespace: work
tags: [vault, obsidian, wiki, ingest, mcp, hermes, system, architecture]
sources: [wiki/obsidian-mcp-wrapper.md, wiki/wiki-ingest-process.md, wiki/personal-os-architecture.md, wiki/vault-filling-guide.md]
confidence: high
---

# Vault ↔ Agent Integration

How Eagle, wiki-ingest, and the obsidian-mcp-wrapper work together as a
unified knowledge layer. Three distinct subsystems each own a slice of
the vault.

## The Three Subsystems

### 1. obsidian-mcp-wrapper (runtime read/write)

A Node.js proxy (`~/scripts/obsidian-mcp-wrapper.js`) wraps `obsidian-mcp`
to fix four production bugs: ZodError on init, race condition at gateway
restart, UTF-8 chunk corruption on large payloads, and a 5-second watchdog
for hung child processes.

Eagle reads the vault through this wrapper via MCP tool calls. It can search,
read, and write notes in real time during conversations.

**Allowed write paths** (Eagle only, with prior draft shown):
- `work/projects/`, `work/decisions/`, `personal/`, `family/`
- Never `wiki/` — that's wiki-ingest territory

### 2. wiki-ingest (nightly synthesis, 22:00 launchd)

A `claude -p` session (not Hermes) that runs nightly. It reads files in
`~/obsidian/raw/` (symlinks to external project files), computes SHA256
hashes, and synthesises wiki pages only when the source has changed.

**Invariants:**
- Output is synthesis, never verbatim copy
- Frontmatter `source` + `content_hash` are the ingestion contract
- Pages with `confidence: 1.0` are immutable

### 3. wiki-curation (daily Hermes cron, 02:00)

A Hermes cron job (this script) that maintains the wiki as a compounding
knowledge base: processes inbox, crystallises session knowledge, creates
synthesis pages, lints orphans and broken links.

## Division of Labour

| Layer | Tool | Vault path | Trigger |
|-------|------|-----------|---------|
| Reactive reads/writes | obsidian-mcp-wrapper | `work/`, `personal/`, `family/` | On-demand |
| Source synthesis | wiki-ingest (claude -p) | `wiki/` ← `raw/` | 22:00 nightly |
| Knowledge curation | wiki-curation (Hermes cron) | `wiki/` | 02:00 daily |
| Vault sync | sync-vault.sh | entire vault | Hourly |

## Why obsidian-mcp Is Wrapped

The wrapper exists because `obsidian-mcp` v1.0.6 had four production-breaking
bugs that would have been too fragile to fix upstream (updates would reintroduce
them). A proxy wrapper is cleaner: it intercepts the MCP protocol stream without
modifying the underlying package.

See [[obsidian-mcp-wrapper]] for the four bugs and their fixes.

## Vault Sync (Eagle ↔ Taiga ↔ Kraken)

All three nodes share a sparse vault via a TrueNAS bare git repo. Eagle has
the full vault; Kraken and Taiga have `personal/` and `family/` only (sparse
checkout). The `sync-vault.sh` cron runs hourly on all three.

```
Eagle (full)  ──push/pull──┐
Taiga (sparse) ────────────├── mallexxx.duckdns.org:/mnt/RED_2TB/storage/git/obsidian-vault.git
Kraken (sparse) ───────────┘
```

## See Also

[[obsidian-mcp-wrapper]] [[wiki-ingest-process]] [[vault-filling-guide]]
[[personal-os-architecture]]