Getting Started: End-to-End Workflow¶
This guide walks you from zero to a fully operational multi-agent LLM Wiki with passive Obsidian integration.
Where this fits in the docs: This is the day-to-day workflow guide. If you haven't installed yet, start with INSTALL.md. If you want a 60-second "just install this one thing", see QUICKSTART.md. If you want a guided, checkpointed walkthrough you can paste into a fresh pi session, see docs/WALKTHROUGH_PROMPT.md.
Architecture Summary¶
┌──────────────┐ ┌─────────────────┐ ┌────────────────────────────┐
│ Obsidian │────▶│ Vault Watcher │────▶│ pi Session (Manager) │
│ @agent tags │ │ (auto-detect) │ │ dispatches subagents │
└──────────────┘ └─────────────────┘ └──────────┬─────────────────┘
│ context: "fork"
┌──────────────┼──────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Miner │ │Broadcaster│ │HeavyLifter│
│ research │ │ podcast │ │ deep │
└────┬─────┘ └────┬─────┘ └────┬─────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────┐
│ LanceDB (.lancedb/) + JSONL WAL │
│ + Obsidian Vault (synced markdown) │
└─────────────────────────────────────┘
Step 1: Install & Prerequisites¶
Required extensions¶
pi install npm:pi-subagents # sub-agent dispatch (forked contexts)
pi install npm:pi-context # session context management
pi install npm:pi-vault-mind # the vault-mind extension itself
Full details: EXTENSION_WIRING.md.
Pick your embedding provider¶
Option A — Zero setup (transformers.js):
No external services needed. Uses Xenova/all-MiniLM-L6-v2 (384 dims). Downloads model on first use, works offline after.
Option B — Higher quality (Ollama):
Step 2: Configure Your Vault¶
Run the interactive setup wizard from within any pi session:
This walks you through: 1. Vault path — absolute path to your Obsidian vault 2. Embedding provider — transformers (zero config) or ollama (higher quality) 3. Model selection — if using Ollama, pick from your available models
CLI mode (for scripting or headless setup):
Config is written to ~/.pi/agent/pi-vault-mind.config.json and applies globally
regardless of which project directory you open pi from.
Project config: ./pi-vault-mind.config.json¶
For project-specific settings (collections, injectors), scaffold inside a project:
This creates pi-vault-mind.config.json in the current directory with default
collections. The project config merges on top of the global config.
{
"collections": {
"main": {
"path": "collections/main.jsonl",
"schema": ["id", "domain", "source", "fact", "tag", "artifact"],
"dedupField": "fact"
}
}
}
You have two config files that merge together (global → project):
Global config: ~/.pi/agent/pi-vault-mind.config.json¶
Put shared settings here — vault paths, embedding, watcher. This applies no matter which project directory you open pi from.
{
"wiki": {
"dataDir": ".lancedb",
"embedding": {
"provider": "transformers"
},
"graph": {
"enabled": true,
"canvasSync": true
},
"vaults": {
"default": {
"path": "/home/you/Obsidian/MyVault",
"autoSync": true,
"autoSyncTags": ["decision", "insight", "requirement"],
"autoSyncMinLength": 200
}
}
}
}
Setup FAQ¶
Does it matter what folder I open pi in?
No. The global config at ~/.pi/agent/pi-vault-mind.config.json applies everywhere.
You can open pi from any project or any directory — the vault path, embedding
settings, and watcher all work globally. The /wiki setup and CLI flags
(--vault, --provider) write to this global file.
The only reason to open pi in a specific directory is if you've scaffolded a
project config with /wiki init, which creates a local pi-vault-mind.config.json
with project-specific collections and injectors.
What if my vault already exists?
Point to it with /wiki setup --vault /path/to/vault. It works immediately —
the watcher monitors existing vaults just fine. No special migration needed.
What if my vault doesn't exist yet?
Create the directory first:
Then open it in Obsidian once (File → Open vault → point to the directory). This initializes the.obsidian/ folder. After that, run /wiki setup
and point to the same path. The watcher won't start monitoring until the
vault path exists on disk.
Can I use multiple vaults?
Yes. Add multiple entries to wiki.vaults in the global config. The watcher
monitors all configured vaults simultaneously. Use wiki_sync(vault="name")
to target a specific one.
Do I need to keep pi running for the watcher to work?
Yes. The watcher runs inside pi. When pi is running, the watcher is active. When you close pi, the watcher stops. For continuous monitoring, keep a pi session open in a terminal or use the shellcommands bridge to trigger scans on explicit file saves.
Step 3: Start the Manager Session¶
Open pi in your project directory and start working with the Manager agent:
Inside pi, the Manager agent loads automatically from the skills/vault-mind/SKILL.md instructions. You'll see the wiki tools available.
Verify the watcher starts:
If it says STOPPED, your vaults may not be configured yet. Start manually:
Select your embedding provider:
Step 4: Work in Obsidian¶
Open your vault in Obsidian. Create or edit any markdown file and add an @agent marker:
Example: Research extraction¶
# Research Notes: RLHF Paper
@agent-miner Extract the key technical claims from this section and store them in LanceDB. Create entity links for any named models or techniques mentioned.
Reinforcement Learning from Human Feedback (RLHF) has become the dominant
alignment technique for large language models. The core approach involves
training a reward model on human preference data, then using PPO to
fine-tune the base model...
What happens:
1. You save the file
2. The watcher detects @agent-miner (within 1 second)
3. It sends a dispatch request to the Manager agent
4. The Manager forks a vault-mind-miner subagent in an isolated context
5. The Miner reads the file, extracts entities, appends to LanceDB, and writes an entity page to Vault/Agent/Inbox/
6. The original @agent-miner marker is replaced with a processing comment
Example: Generate a podcast¶
# Meeting Notes: Q2 Planning
@agent-broadcaster Generate a Deep Dive audio overview from these notes
## Key decisions
- We're moving to microservices architecture in Q3
- Budget approved for 3 new hires
...
Example: Multiple roles¶
# Architecture Review
@agent-miner Extract all technical decisions as entity-relation pairs
@agent-manager Review the architecture and suggest improvements based on the wiki knowledge graph
We're proposing a new event-driven architecture using Kafka as the message bus...
Same-role markers in one file are bundled into one task. Different roles dispatch to separate agents.
Named IDs for isolation¶
Use :customId to force separate subagent sessions:
@agent-miner:security-review Audit the auth flow
@agent-miner:perf-review Analyze the database query patterns
These dispatch as two separate subagents, each in their own forked context.
Step 5: See Results Flow Back¶
Results appear in several places:
In Obsidian¶
Vault/
├── Agent/
│ ├── Inbox/
│ │ ├── 2026-06-06-rlhf-claims.md ← Miner output
│ │ └── 2026-06-06-q2-decisions.md
│ └── Presentations/
│ └── q2-planning-deep-dive.wav ← Broadcaster output
├── Entities/
│ ├── RLHF.md
│ ├── PPO.md
│ └── Reward_Model.md
In LanceDB¶
In the terminal¶
Subagent results are logged to the Manager session. Use:
Day-to-Day Workflow¶
Here's what a typical session looks like:
Morning: Spin up¶
Inside pi:
/wiki watcher start # ensure watcher is running
/wiki validate # health check
wiki_status # see what's in the wiki
Throughout the day: Drop & Forget¶
- Research: Paste a paper abstract into Obsidian, add
@agent-miner extract entities - Meetings: Jot notes in a daily note, add
@agent-broadcaster generate a recap - Decisions: Document an architecture call, add
@agent-manager review against existing decisions
No need to switch to the terminal. The watcher handles it passively.
Evening: Review & Query¶
# See what the Miner found today
wiki_search(query="what did we learn about microservices?")
# Check entity relationships
wiki_graph_query(entity="Kafka", depth=2)
# Export decisions for a stakeholder
wiki_export(collection="main", format="markdown")
Manual chat (when you want deep interaction)¶
# Ask the Manager directly
"What are all the decisions we've made about authentication?"
# The Manager queries LanceDB and the graph, synthesizes an answer
# without needing to keep every research note in its context window
Troubleshooting¶
| Issue | Fix |
|---|---|
| Watcher not detecting markers | Check /wiki watcher status — are vaults configured? Is the watcher running? |
| "Unknown collection" | Run /wiki init to scaffold, or add collection to config |
| Ollama connection failed | Verify Ollama is installed: ollama list. Pull a model: ollama pull embeddinggemma |
| No search results | Append a fact first — LanceDB tables auto-create on first write |
| LanceDB error | Check wiki.dataDir is writable, not inside a read-only mount |
| Subagent not found | Ensure pi-subagents is loaded: pi install npm:pi-subagents |
| Ollama connection failed | Verify Ollama is installed: ollama list. Pull a model: ollama pull embeddinggemma |
| --- |
Config Reference¶
Vault auto-sync¶
Entries that are >200 chars OR tagged decision/insight/requirement are auto-synced to Vault/Agent/Inbox/. Configure thresholds:
"wiki": {
"vaults": {
"default": {
"path": "/home/you/Obsidian/MyVault",
"autoSync": true,
"autoSyncTags": ["decision", "insight", "requirement", "experiment"],
"autoSyncMinLength": 150
}
}
}
Multiple vaults¶
"wiki": {
"vaults": {
"personal": { "path": "/home/you/Obsidian/Personal" },
"work": { "path": "/home/you/Obsidian/Work" }
}
}
Use wiki_sync(vault="work", ...) to target specific vaults.