---
name: "Vault Agent"
client: "Oliver Internal"
status: design
tech: [Python, Ollama, Qwen, Watchdog, Markdown]
local_path: /Users/ai_leed/.claude/vault-agent
deploy: "python vault_agent.py (background daemon)"
server: local
tags:
  - project
  - domain/ai
  - tech/python
  - tech/ollama
created: 2026-05-18
---

## Overview

Background daemon that maintains the Obsidian vault as a living, transferable knowledge base. Always-on process (independent of Claude Code sessions) that watches for vault changes, audits notes for completeness, enforces PARA structure, and ensures every note has proper frontmatter and at least 2 cross-links. Uses a local LLM (Qwen via Ollama) to avoid cloud costs.

**Status:** Design phase — not yet implemented.

**Goal:** Any AI or human who opens the vault should orient within 3 hops without onboarding.

## Tech Stack

- **Runtime:** Python 3.11+, `watchdog` for filesystem events
- **LLM:** Qwen 35B via Ollama HTTP API (`http://localhost:11434`) — local, no cloud cost
- **Vault I/O:** Direct file read/write of `.md` files; YAML frontmatter parsing
- **Scheduler:** Idle watcher + startup full-scan

## Architecture

```
┌─────────────────────────────────────────────┐
│                vault-agent                   │
│                                              │
│  ┌──────────┐    ┌────────────┐    ┌──────┐ │
│  │ Watcher  │    │  Startup   │    │ Idle │ │
│  │ (events) │    │ (full scan)│    │ loop │ │
│  └────┬─────┘    └─────┬──────┘    └──┬───┘ │
│       └──────────────┬─┘              │     │
│                      ▼                │     │
│          ┌─────────────────────┐      │     │
│          │   Task Queue        │◄─────┘     │
│          └────────┬────────────┘            │
│                   │                         │
│         ┌─────────▼──────────┐              │
│         │  Qwen (Ollama API) │              │
│         │  - frontmatter fix │              │
│         │  - wikilink add    │              │
│         │  - PARA classify   │              │
│         └────────┬───────────┘              │
│                  │                          │
│         ┌────────▼───────────┐              │
│         │  Vault Writer      │              │
│         │  (atomic .md edit) │              │
│         └────────────────────┘              │
└─────────────────────────────────────────────┘
```

**Success criteria:**
- Every note has complete frontmatter (name, status, tags, type, created)
- Every note links to ≥ 2 others via `[[wikilinks]]`
- PARA structure consistent — notes in correct folders
- Vault graph: fragmented clusters → one connected body

## Dev Commands

```bash
# Install deps
cd ~/.claude/vault-agent
uv sync

# Run daemon
python vault_agent.py

# One-shot audit (no daemon)
python vault_agent.py --audit-only

# Test on single file
python vault_agent.py --file /path/to/note.md
```

## Deployment

- **Type:** Local daemon (no server, no Docker)
- **Start on login:** LaunchAgent at `~/Library/LaunchAgents/com.vault-agent.plist`
- **Logs:** `~/.claude/vault-agent/logs/vault-agent.log`

## Related

- [[wiki/architecture/multi-agent-ai-systems|multi-agent-ai-systems]]
- [[obsidian-vault/Obsidian Second Brain|Obsidian Second Brain]]

## Sessions

### 2026-05-18 — Design phase
**Done:** Design spec written (`vault-agent-design.md`), implementation plan created. Not yet coded.

---
## Change Log
| Date | Requested | Changed | Files |
|------|-----------|---------|-------|
| 2026-05-18 | Create project note | Note created from design doc | Vault Agent.md |
