85 lines
3.2 KiB
Markdown
85 lines
3.2 KiB
Markdown
---
|
|
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]]
|