Skip to content

Architecture

The "Fork & Review" multi-agent model is the heart of pi-vault-mind. It solves the core problem of long-running LLM sessions: context degradation. By the time you've asked 12 different questions, the model is burdened by the irrelevant thought processes of the first 11.

Documents in this section

  • Agent roster

    The five specialist agents — Manager, Miner, Broadcaster, Heavy-Lifter, Watcher — and how they interact through the vault and LanceDB rather than direct conversation.

  • Extension wiring

    The hard dependencies on pi-subagents and pi-context, the optional extensions, the runtime wiring, and the auto-install patterns.

  • Dispatcher spec

    The technical spec for the passive file-watcher. Marker syntax, grouping logic, subagent invocation, and the writeback protocol.

  • Passive interaction model

    The "Fork & Dispatch" model in detail — why we use { context: "fork" }, how subagents inherit project knowledge without polluting the main session, and how to resume specific threads.

  • Passive ingestion workflow

    The "Drop & Forget" document ingestion pipeline. Drop a PDF/URL in the Inbox folder, the Miner handles conversion, extraction, embedding, and vault sync.

High-level architecture

┌──────────────────────────────────────────────────────────────────┐
│                       Obsidian Vault                              │
│   (You write notes with @agent markers)                           │
└────────────┬─────────────────────────────────────────────────────┘
             │ file save event
             ▼
┌──────────────────────────────────────────────────────────────────┐
│                  Vault Watcher (pi-vault-mind)                    │
│   debounce 1s → scan for @agent-* → group by role → emit dispatch │
└────────────┬─────────────────────────────────────────────────────┘
             │ pi.sendUserMessage()
             ▼
┌──────────────────────────────────────────────────────────────────┐
│              Manager Agent (interactive pi session)               │
│   calls subagent({ agent: "vault-mind-miner", context: "fork" })        │
└────────────┬─────────────────────────────────────────────────────┘
             │ forked session
             ▼
┌──────────────────────────────────────────────────────────────────┐
│        Specialist subagents (Miner, Broadcaster, Heavy-Lifter)    │
│   run in isolated context, write to JSONL + LanceDB + vault, die  │
└────────────┬─────────────────────────────────────────────────────┘
             │ dual-write
             ▼
┌──────────────────────────────────────────────────────────────────┐
│       LanceDB (vector + FTS + graph)  +  JSONL WAL  +  Vault      │
│   hybrid search across all three layers                            │
└──────────────────────────────────────────────────────────────────┘

Why this design?

  • No context pollution. The Manager session stays clean. The subagent's scratchpad thinking, tool calls, and verbose outputs are confined to its own session file.
  • Parallel execution. Multiple markers in one file become multiple parallel subagent dispatches, each in its own forked context.
  • Resumable threads. Named IDs (@agent-Miner:followup) let you resume a specific subagent's session, picking up exactly where it left off.
  • Local-first. LanceDB runs embedded. No external service. No API keys. Your data never leaves your machine.
  • Multi-project knowledge sharing. The vault is global. A fact written in ~/projects/foo appears in the same vault as a fact from ~/projects/bar.