Skip to content

Agent Roster & Architecture

This document defines the multi-agent system that powers the pi-vault-mind and Obsidian Vault integration.

The Core Philosophy: "Fork & Review"

To prevent context degradation and "chat pollution", we avoid long, monolithic agent sessions that try to do everything. Instead, we use a Dispatcher-Subagent model:

  1. Human writes in Obsidian: You drop notes, sources, or commands using @agent markers (e.g., @agent:deep-analysis, @agent:podcast).
  2. Watcher dispatches: A background file-watcher detects the marker, isolates the context, and spawns a highly specialized subagent in a forked session.
  3. Subagent executes: The subagent receives a clone of the session history, executes its specific task without polluting the main session, and uses specific tools (LanceDB, NotebookLM, or external CLIs).
  4. Subagent reports & dies: The subagent writes the results back to the Obsidian vault or internal wiki (append_wiki), replaces the marker, and terminates. The verbose thought process is discarded; only the distilled knowledge remains.

Context Isolation

By using { context: "fork" } when spawning subagents, we ensure that: * The subagent knows who you are and the general project context. * Its scratchpad thinking, failed tool calls, and verbose outputs do not pollute your main chat log. * Multiple subagents can run concurrently on different files without their contexts bleeding into each other.

Shared Memory: LanceDB & Obsidian

Because agents run in isolated forks and terminate after completing their tasks, they do not pass data via direct conversational memory. Instead, they communicate implicitly through a universal state layer:

  1. JSONL Write-Ahead Log: Agents use the append_wiki tool to record fast, durable facts, requirements, and decisions.
  2. LanceDB Vector & Graph Indexes: The append_wiki tool automatically embeds text and extracts entity relationships. Any agent can instantly retrieve this knowledge using the wiki_search and wiki_graph_query tools, regardless of which session or agent originally wrote it.
  3. Obsidian Markdown: Subagents use the wiki_sync tool to push human-readable markdown pages and .canvas graphs to the Vault.

This semantic continuity means the Manager agent can query LanceDB to see what the Miner agent discovered three days ago, without needing that conversation in its active context window.

Agent Interaction Protocols

Agents do not chat directly with each other. They interact through the Vault and the Database.

  • Watcher → Subagents: The Watcher observes the Vault. When it sees an @agent tag, it reads the surrounding lines and dispatches a Subagent.
  • Manager → Miner / Heavy-Lifter: If you ask the Manager to "analyze this new codebase," it doesn't do it itself. It writes a task file to the Vault or uses the subagent tool directly to spawn the Heavy-Lifter, then waits for the Heavy-Lifter to write the results back to LanceDB.
  • Miner → Broadcaster: The Miner might tag an extracted summary note with status: needs-podcast. The Watcher sees the tag and dispatches the Broadcaster (NotebookLM) to generate the audio.

The Agent Roster

1. The Watcher (Dispatcher)

  • Role: Passive file observer (inspired by the pi-piqo pattern).
  • Trigger: File saves in the Obsidian Vault.
  • Action: Scans for @agent markers. To prevent an explosion of processes, the Watcher intelligently groups tasks.
  • Markers targeted at the same agent (e.g., multiple @agent-Miner tags in one file) are bundled into a single forked session.
  • Users can force a new fork isolation by using distinct names (e.g., @agent-Miner:task1 and @agent-Miner:task2) or section delimiters.
  • Once grouped, the Watcher uses the subagent tool to dispatch the appropriate specialist agent.
  • Skills: None. Purely programmatic routing.

2. The Manager (Synthesizer)

  • Role: The main interactive agent you talk to in the terminal or Pi interface.
  • Trigger: Human chat input.
  • Action: High-level planning, roadmap synthesis, and reviewing the output of subagents. Can manually trigger wiki_sync or approve pending entries.
  • Skills: microfactory-context, narrative-writing

3. The Miner (Wiki Researcher)

  • Role: Knowledge ingestion and retrieval.
  • Trigger: @agent:research or @agent:ingest in the vault.
  • Action: Uses any2md to convert documents, extracts entities, and uses append_wiki to dual-write to LanceDB and the Vault. Runs wiki_search to answer specific questions.
  • Skills: rag-research, obsidian-markdown

4. The Broadcaster (NotebookLM Controller)

  • Role: Artifact generation for human consumption.
  • Trigger: @agent:podcast, @agent:quiz, or status: needs-podcast frontmatter.
  • Action: Uses notebooklm-mcp-cli to upload vault sources to Google NotebookLM and generates Audio Overviews, study guides, or slide decks. Downloads the result back to Vault/Agent/Presentations/.
  • Skills: nlm-skill

5. The Heavy-Lifter (Delegator)

  • Role: Large context window analysis and complex code refactoring.
  • Trigger: @agent:deep-analysis or @agent:refactor.
  • Action: Acts as a commander for external coding assistants (like Claude Code or Gemini CLI). Uses the ACP (Agent Client Protocol) bridge or CLI wrappers (like tui-use) to spin up these external models, feed them massive vault/codebase context, orchestrate their execution, and capture the output back into the wiki.
  • Skills: obsidian-cli, pi-subagents (for launching external ACP tools)

Workflow Examples

1. The Deep Research Loop

You paste a 100-page PDF into the vault and add @agent:deep-analysis Summarize key claims and extract a knowledge graph. 1. Watcher sees the marker, forks a session, and wakes the Heavy-Lifter. 2. Heavy-Lifter spins up claude (Claude Code) via CLI/ACP, pointing it at the PDF, leveraging Claude's 200k context window. 3. Heavy-Lifter receives the structured output from Claude. 4. Heavy-Lifter passes the data to the Miner, which uses append_wiki to create LanceDB entities and relations. 5. The marker is replaced with a summary and links to the new [[Entity]] pages.

2. The Study Material Loop

You tag a folder of meeting notes with @agent:podcast. 1. Watcher wakes the Broadcaster. 2. Broadcaster uses MCP to create a new NotebookLM notebook, syncs the folder's markdown files, and generates a "Deep Dive" audio overview. 3. The .wav file is saved to the vault and embedded ![[podcast.wav]] in your daily note.