Extension Wiring & Dependencies¶

Where this fits: This is the technical reference for what extensions pi-vault-mind depends on, what each one provides, and the runtime wiring between them. For the user-facing install procedure (5 layers, scripts, verification), see INSTALL.md. For the agent-facing multi-agent architecture, see AGENTS.md.

This document describes every pi extension and external tool that pi-vault-mind integrates with, what each provides, and how to install them.

Required Extensions¶

These are hard dependencies — pi-vault-mind will not function without them.

Auto-install at setup: pi-vault-mind's /wiki setup wizard does not automatically install the required extensions (pi-subagents, pi-context) into the user's pi. This is intentional — pi extensions are global, and silent installs would surprise users. However, the wizard detects missing dependencies and prints the exact pi install commands for the user to copy-paste. See Auto-installing required extensions below for the canonical one-liner.

pi-subagents¶

What it provides: The subagent() tool — used by the Manager agent to fork isolated worker sessions for the Miner, Broadcaster, and Heavy-Lifter.

pi install npm:pi-subagents

How we use it: - Vault Watcher detects @agent-miner → sends task to Manager - Manager calls subagent({ agent: "vault-mind-miner", context: "fork", async: true }) - Miner runs in isolated session, writes results to LanceDB + Vault, terminates - No chat pollution, clean context per task

Configuration: None required. Works out of the box.

pi-context¶

What it provides: Context management tools (context_tag, context_log, context_checkout) for clean session hygiene during long orchestration sessions.

pi install npm:pi-context

How we use it: - Manager tags milestones (watcher-build-start, research-phase) to create rollback points - Before risky operations, checks context_log to understand current session state - After noisy research: squashes history with context_checkout to keep context window clean

Configuration in pi-vault-mind.config.json:

{
  "extensionCompatibility": {
    "pi-context": {
      "enabled": true,
      "tagPatterns": [],
      "enhanceInjectors": false,
      "autoEnableAcm": true,
      "indexContextEvents": true
    }
  }
}

Enable/disable via:

/wiki context enable
/wiki context disable
/wiki context status

Optional Extensions¶

These enhance specific agent workflows but are not required for basic wiki operation.

NotebookLM CLI (`nlm`)¶

What it provides: Command-line interface to Google NotebookLM for programmatic podcast generation, study guides, quizzes, and audio overviews.

# Install globally (not a pi extension):
npm install -g notebooklm-cli

# Or use the MCP server (preferred):
# Add to ~/.pi/agent/mcp.json:
# { "notebooklm-mcp": { "command": "npx", "args": ["-y", "notebooklm-mcp-cli"] } }

How we use it (Broadcaster agent): - User drops @agent-broadcaster on meeting notes - Broadcaster creates NotebookLM notebook from vault markdown files - Generates "Deep Dive" audio overview - Downloads .wav to Vault/Agent/Presentations/

Required skill: nlm-skill — auto-loaded by pi when nlm or notebooklm keywords are detected.

# Pi auto-discovers this skill, no manual install needed.
# It lives at: ~/.pi/agent/skills/nlm-skill/SKILL.md

Authentication: Requires Google account login. Run once:

nlm login

any2md¶

What it provides: Converts URLs, PDFs, and other formats to clean markdown. Used by the Miner for passive document ingestion.

# Available via npx (no global install needed):
npx any2md https://arxiv.org/abs/... > paper.md

# Or install globally:
npm install -g any2md

How we use it (Miner agent): - User drops a PDF URL or file reference with @agent-miner ingest - Miner calls npx any2md <source> to convert to markdown - Extracts entities and appends to LanceDB - Writes converted markdown to Vault/Agent/Inbox/

Future: We may wrap this as a pi tool (e.g., wiki_ingest) for direct invocation.

Extension Dependency Graph¶

pi-vault-mind
├── REQUIRED: pi-subagents        → subagent() tool for forked dispatch
├── REQUIRED: pi-context          → context_tag/log/checkout for session hygiene
├── OPTIONAL: notebooklm-mcp-cli  → Broadcaster audio generation (nlm-skill)
├── OPTIONAL: any2md              → Miner passive document ingestion
└── OPTIONAL: pi-intercom         → inter-agent coordination channel

Quick Install¶

# Core (required)
pi install npm:pi-subagents
pi install npm:pi-context

# Wiki (the main extension)
pi install npm:pi-vault-mind

# Optional quality-of-life
npm install -g notebooklm-cli    # or configure MCP server
npm install -g any2md             # or use npx any2md

# Verify
pi -e npm:pi-vault-mind
/wiki validate
/wiki watcher status

Auto-installing required extensions¶

pi-vault-mind does not automatically pi install its required extensions (pi-subagents, pi-context). Pi extensions are global to the user's ~/.pi/agent/ and silent installs would surprise users. Instead, the setup wizard detects missing dependencies and prints the exact commands to run.

One-liner: install everything pi-vault-mind needs¶

If you want to install all required extensions in one command (e.g., during provisioning, CI, or a fresh dev container), use:

pi install npm:pi-vault-mind npm:pi-subagents npm:pi-context

pi install accepts multiple packages in a single invocation and installs them in order. After this one command, run /wiki setup to configure the vault and embedding provider.

What the setup wizard does¶

When you run /wiki setup, the wizard will:

Check whether pi-subagents and pi-context are loadable in the current pi session.
If a required extension is missing, print a banner with the install command for the user to copy-paste (or run manually).
Continue with the vault path / embedding provider prompts after the user confirms they've installed the missing dependencies.

This pattern keeps the user in control while removing the most common "watcher doesn't dispatch" failure mode (missing pi-subagents).

Optional: install from a script¶

For provisioning or CI, drop this in your bootstrap script:

#!/usr/bin/env bash
# Idempotent: skips packages that are already installed.
set -e

for pkg in pi-vault-mind pi-subagents pi-context; do
  if pi list 2>/dev/null | grep -q "$pkg"; then
    echo "✅ $pkg already installed"
  else
    echo "→ Installing $pkg..."
    pi install "npm:$pkg"
  fi
done

echo "→ Verifying..."
pi list

Run with chmod +x install-vault-mind.sh && ./install-vault-mind.sh.

Global Config Template¶

After installing all extensions, create ~/.pi/agent/pi-vault-mind.config.json:

{
  "version": 2,
  "wiki": {
    "dataDir": ".lancedb",
    "embedding": {
      "provider": "transformers",
      "ollamaModel": "embeddinggemma",
      "ollamaHost": "http://127.0.0.1:11434"
    },
    "graph": {
      "enabled": true,
      "canvasSync": true
    },
    "vaults": {
      "default": {
        "path": "/home/YOU/Obsidian/YOUR_VAULT",
        "autoSync": true,
        "autoSyncTags": ["decision", "insight", "requirement"],
        "autoSyncMinLength": 200
      }
    }
  },
  "extensionCompatibility": {
    "pi-context": {
      "enabled": true,
      "tagPatterns": [],
      "autoEnableAcm": true
    }
  },
  "collections": {},
  "injectors": []
}

How Extensions Wire Together at Runtime¶

1. pi starts with pi-vault-mind loaded
   ├── Discovers skills/ directory → Manager, Miner, Broadcaster, Heavy-Lifter prompts
   ├── Registers 12 wiki tools (wiki_search, append_wiki, wiki_sync, etc.)
   ├── Registers /wiki commands (init, validate, watcher, etc.)
   └── Auto-starts Vault Watcher if wiki.vaults is configured

2. User saves @agent-miner in Obsidian
   ├── Vault Watcher (src/watcher.ts) detects marker via fs.watch
   ├── Groups markers, debounces 1s
   └── Calls pi.sendUserMessage() with dispatch instruction

3. Manager agent receives message
   ├── Recognizes dispatch request
   ├── Calls subagent({ agent: "vault-mind-miner", context: "fork", async: true })
   │   └── pi-subagents extension handles forking, session isolation
   └── pi-context tools available for session hygiene (context_tag, etc.)

4. Miner subagent executes in isolation
   ├── Reads the vault file (instruction + context)
   ├── If URL/PDF detected: calls npx any2md to convert
   ├── Extracts entities via regex (src/graph.ts)
   ├── Calls append_wiki() → JSONL WAL + LanceDB
   ├── Calls wiki_sync() → markdown in Vault/Agent/Inbox/
   └── Terminates — context doesn't pollute Manager session

5. (Optional) User drops @agent-broadcaster
   ├── Broadcaster subagent forks
   ├── Uses nlm-skill to interact with NotebookLM CLI/MCP
   ├── Uploads vault sources to NotebookLM
   ├── Generates audio overview
   └── Downloads to Vault/Agent/Presentations/

Troubleshooting¶

Symptom	Check
`subagent is not defined`	Install pi-subagents: `pi install npm:pi-subagents`
`context_tag is not defined`	Install pi-context: `pi install npm:pi-context`
Watcher doesn't start	Vaults not configured: add `wiki.vaults` to config
Subagent doesn't run	Check `/wiki watcher status` — is it RUNNING? Check vault path
NotebookLM fails	`nlm login` to authenticate Google account
any2md fails	Use `npx any2md` or install globally: `npm install -g any2md`