pi-vault-mind

Passive Obsidian vault extension for the pi agent ecosystem. Watches @agent markers in your vault, dispatches forked subagents, and stores results in LanceDB with vector + FTS + graph. Multi-agent "Drop & Forget" workflow.

Looking for the legacy ledger-first extension (predecessor project)? See kylebrodeur/pi-qmd-ledger. This project was renamed twice: pi-qmd-ledger → pi-llm-wiki (intermediate) → pi-vault-mind (current).

Features

• Passive File Watcher — drop @agent-Miner, @agent-Broadcaster, etc. in any Obsidian note. Save the file. The watcher detects the marker, groups by role, and dispatches isolated subagent forks (vault-mind-{role} agents). No chat pollution, no manual triggers.
• Multi-Agent Architecture — five specialist agents under the vault-mind-{role} skill naming: Manager (interactive orchestrator), Miner (research + entity extraction), Broadcaster (NotebookLM artifacts), Heavy-Lifter (external delegation), Watcher (passive file observer).
• LanceDB Vector + FTS + Graph — hybrid semantic + keyword search with automatic entity extraction and BFS graph traversal. All local, no external binaries.
• JSONL Source-of-Truth + LanceDB Index — every fact lives in a durable, human-readable, version-control-friendly collections/*.jsonl file. The LanceDB index is derived and rebuildable via /wiki reindex --all --reembed.
• Bidirectional Obsidian Sync — substantial entries (>200 chars or tagged decision/insight/requirement) auto-write to Vault/Agent/Inbox/. Graph entities render as Obsidian Canvas files.
• Two-Layer Config — global (~/.pi/agent/vault-mind.config.json) for shared settings, project (./pi-vault-mind.config.json) for project-specific knowledge. Works across all projects from any directory.
• Interactive Setup Wizard — /wiki setup walks through vault path, embedding provider, and model selection. CLI mode: --vault, --provider, --model flags for scripting.

Architecture

┌─────────────────────────────────────────┐
│  User prompt                             │
│  e.g. "draft login"                      │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Injector regex match                    │
│  → matches "draft\s+(\S+)"              │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  query collections/main.jsonl            │
│  where tag="login" + inject artifact.md  │
└──────┬──────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────┐
│  Appended to system prompt               │
│  → LLM now has pre-fetched context       │
└─────────────────────────────────────────┘

Data Layer:
┌─────────────────────────────────────────┐
│  JSONL WAL (collections/*.jsonl)        │
│  ─ durable, human-readable, versionable │
│       │                                  │
│       ▼ (auto-embed on append)           │
│  LanceDB (.lancedb/)                    │
│  ─ vector search + FTS + graph          │
│       │                                  │
│       ▼ (graph extraction)               │
│  Graph Tables (entities + relations)     │
│  ─ entity linking + traversal            │
└─────────────────────────────────────────┘

See docs/architecture/index.md for the full agent flow.

Obsidian Counterparts & Requirements

pi-vault-mind works on any directory, but for the full Obsidian experience, you need a few things in Obsidian itself:

Required: An Obsidian vault

Just point /wiki setup at any directory used as an Obsidian vault. pi-vault-mind auto-detects .obsidian/ and respects .obsidian/, .git/, .trash/.

Recommended: Official Obsidian CLI (1.12+)

The official Obsidian CLI lets you install plugins, themes, and manage vault state from the terminal. This is the safest, most direct install path for pi-vault-mind's required plugins.

Install: Open Obsidian → Settings → General → Command line interface → enable. Follow the prompt to register the CLI to your system PATH. Restart your terminal. Test: obsidian help.

Then run:

obsidian plugin:install id=obsidian-git enable
obsidian plugin:install id=obsidian-breadcrumbs enable
obsidian plugin:install id=graph-analysis enable
obsidian plugin:install id=actions-uri enable
obsidian plugin:install id=shellcommands enable

Full walkthrough: see docs/OBSIDIAN_SETUP.md.

Recommended: Obsidian Community Plugins

Plugin	Install ID	Why	Status
obsidian-git	obsidian-git	Auto-commits vault changes for backup & conflict resolution. Heavy-Lifter uses git worktrees for isolated refactors.	Essential
Breadcrumbs	obsidian-breadcrumbs	Parses typed edges (agent:related-to, agent:derived-from) in YAML frontmatter. The recommended way to display the agent-extracted knowledge graph in Obsidian's UI.	Highly recommended
Graph Analysis	graph-analysis	Co-citation discovery, Jaccard similarity on the native Obsidian graph. Surfaces "always cited together but not yet linked" notes — a key agent discovery signal.	Highly recommended
Actions URI	actions-uri	x-callback-url endpoints so the Manager agent can trigger Obsidian UI commands (open notes, run commands) from pi.	Recommended
obsidian-shellcommands	shellcommands	Bridge from Obsidian events (e.g., file save) to pi agent workflows. Configure a curl to http://127.0.0.1:11435/vault-mind/scan on file save.	Recommended

Recommended: notesmd-cli (headless alternative)

For headless operations, CI, or when Obsidian isn't running, use Yakitrak/notesmd-cli. It does everything the official CLI does but doesn't require Obsidian to be open.

brew tap yakitrak/yakitrak && brew install yakitrak/yakitrak/notesmd-cli
# or scoop, AUR, etc.

notesmd-cli add-vault /path/to/vault
notesmd-cli create "Note.md" --content "..." --append

Use the official obsidian CLI when Obsidian is running; use notesmd-cli when it isn't.

Beta plugins via BRAT

For beta plugins not in the official store:

# Install BRAT first
obsidian plugin:install id=obsidian42-brat enable

# Then add beta plugin URLs via BRAT's interface, or:
# In Obsidian: Settings → BRAT → Beta Plugin List → Add

Recommended: kepano/obsidian-skills (pi skills)

Install via the official skills CLI (pi is a first-class target agent — auto-detected):

# Non-interactive: install all 5 globally for pi
DISABLE_TELEMETRY=1 yes y | npx -y skills add https://github.com/kepano/obsidian-skills \
  --skill obsidian-markdown --skill obsidian-bases \
  --skill json-canvas --skill obsidian-cli --skill defuddle \
  -g -a pi --copy -y

This puts them at ~/.pi/agent/skills/<name>/SKILL.md where pi auto-discovers them. The CLI handles agent detection, symlink/copy, and security risk confirmations.

Verify they're discoverable:

for s in obsidian-markdown obsidian-bases json-canvas obsidian-cli defuddle; do
  [ -f ~/.pi/agent/skills/$s/SKILL.md ] && echo "✅ $s" || echo "❌ $s"
done

• obsidian-markdown — agent learns Obsidian-flavored markdown syntax
• obsidian-bases — agent learns to generate valid .base files (database views)
• json-canvas — agent learns Canvas JSON format (used for our graph sync)
• obsidian-cli — agent learns to use the Obsidian CLI
• defuddle — cleaner markdown extraction from web pages

These skills let the Miner, Broadcaster, and Heavy-Lifter agents produce valid Obsidian content.

Built-in Obsidian features used

Feature	How pi-vault-mind uses it
YAML frontmatter properties	Strict schema for typed edges (agent:related-to, status: needs-podcast, domain:, tag:)
Callouts	> [!info], > [!warning] for syntheses and contradictions
Embeds	![[Note]] to transclude summaries into synthesis docs
Obsidian Bases (.base)	Agent-generated dynamic tables/boards/kanbans in Agent/Tasks/
JSON Canvas (.canvas)	wiki_sync(format="canvas") writes entity graph as Canvas JSON
Obsidian Sync	Primary sync mechanism across devices

Optional: NotebookLM integration (Broadcaster)

The Broadcaster agent can generate podcasts, study guides, and slide decks from vault content via the notebooklm-mcp-cli MCP server. Requires Google account login.

---

Quick Start

Prerequisites

• Node.js 20+ (matches engines in package.json)
• Embedding Provider — choose one:
  • @xenova/transformers — built-in, no external deps (uses all-MiniLM-L6-v2, offline-capable)
  • ollama — requires Ollama running locally with embeddinggemma (higher quality)

1. Install with pi

pi install npm:pi-vault-mind              # latest
pi install npm:pi-vault-mind@0.7.0        # pinned
pi -e npm:pi-vault-mind                   # try without installing

Or from git:

pi install git:git@github.com:kylebrodeur/pi-vault-mind

2. Configure (interactive wizard)

/wiki setup

This walks you through: vault path → embedding provider → Ollama model (if applicable).

Or via CLI for scripting:

/wiki setup --vault /home/you/Obsidian/MyVault --provider transformers
/wiki setup --vault /home/you/Obsidian/MyVault --provider ollama --model embeddinggemma

Config is written to ~/.pi/agent/vault-mind.config.json — it applies globally no matter which project directory you open pi from.

You can re-run /wiki setup anytime to view or change settings.

3. Start using

append_wiki(collection="main", mode="autopilot", entry={"id":"1","domain":"auth","fact":"JWT tokens expire after 1 hour","tag":"security"})
wiki_search(collection="main", query="token expiry")

Entries are automatically embedded and stored in LanceDB. If graph is enabled, entities and relations are also extracted.

4. Adapt the config

Edit pi-vault-mind.config.json to match your domain:

{
  "version": 2,
  "collections": {
    "main": {
      "path": "collections/main.jsonl",
      "schema": ["id", "domain", "source", "fact", "tag", "artifact"],
      "dedupField": "fact"
    }
  },
  "injectors": [
    {
      "name": "draft-context",
      "regex": "draft\\s+(\\S+)",
      "collection": "main",
      "filterField": "tag"
    }
  ],
  "wiki": {
    "dataDir": ".lancedb",
    "embedding": {
      "provider": "transformers",
      "ollamaModel": "embeddinggemma",
      "ollamaHost": "http://127.0.0.1:11434"
    },
    "ftsEnabled": true,
    "graph": { "enabled": true, "canvasSync": false }
  }
}

Example domains

Research project

{
  "collections": {
    "findings": {
      "path": "research/findings.jsonl",
      "schema": ["id", "paper", "claim", "evidence", "confidence", "tag"],
      "dedupField": "claim"
    }
  },
  "injectors": [
    {
      "name": "lit-review",
      "regex": "review\\s+(\\S+)",
      "collection": "findings",
      "filterField": "tag",
      "artifactPath": "research/synthesis.md"
    }
  ]
}

Decision log

{
  "collections": {
    "decisions": {
      "path": "decisions/log.jsonl",
      "schema": [
        "id",
        "date",
        "context",
        "decision",
        "rationale",
        "status",
        "owner"
      ],
      "dedupField": "decision"
    }
  },
  "injectors": [
    {
      "name": "decide",
      "regex": "decide\\s+(\\S+)",
      "collection": "decisions",
      "filterField": "context"
    }
  ]
}

Tools

Tool	Purpose
wiki_search	Semantic search via LanceDB (vector + FTS)
wiki_fts_search	Exact keyword full-text search (Tantivy BM25)
wiki_graph_query	Traverse entity connections in the graph layer
wiki_status	Show LanceDB table sizes and health
query_wiki	Deterministic JSONL search by collection name
append_wiki	Append with strict/gated/autopilot modes + dual-write
configure_wiki	Read or update config at runtime
describe_wiki	Introspect schema, count, and sample entries
wiki_stats	Dashboard: counts, sizes, LanceDB status
wiki_export	Export to JSON, CSV, or Markdown
promote_wiki	Promote entries between collections via pending queue

Commands

Command	Purpose
/wiki help	Show usage help
/wiki setup	Interactive global config wizard (vault, embedding)
/wiki init	Scaffold project config + collections
/wiki validate	Health check LanceDB, config, and all collection paths
/wiki approve [collection]	Batch-review pending entries
/wiki settings	Open interactive settings dashboard
/wiki audit	Audit config for missing defaults
/wiki reindex [--all] [--reembed]	Rebuild FTS + vector indexes
/wiki collection select	Select active collection (shortcut: ctrl+alt+l)
/wiki collection create	Interactive wizard to create a new collection
/wiki injector create	Interactive wizard to create a new injector
/wiki context enable | disable | status	Manage pi-context integration
/wiki embedding status | use | model | models | pull	Manage embedding provider
/wiki watcher start | stop | status	Manage the passive file watcher
/wiki server status	Show HTTP server status, port, and uptime

Documentation

Full docs site: kylebrodeur.github.io/pi-vault-mind (GH Pages, built from docs/). The links below point to the source files in this repository.

Getting started

Doc	Description
docs/QUICKSTART.md	Fastest path — 60-second install, setup, first append
docs/INSTALL.md	Canonical install playbook — all 5 layers (pi ext, skills, Obsidian, config, external CLIs)
docs/GETTING_STARTED.md	End-to-end workflow + daily "drop & forget" usage
docs/WALKTHROUGH_PROMPT.md	Paste-into-pi guided setup with checkpoints between phases

Architecture & design

Doc	Description
docs/AGENTS.md	Agent Roster and Multi-Agent Architecture ("Fork & Review" model)
docs/EXTENSION_WIRING.md	Extension dependencies, runtime wiring, auto-install patterns
docs/DISPATCHER_SPEC.md	Technical spec for the passive file-watcher and subagent routing
docs/PASSIVE_INTERACTION_MODEL.md	"Fork & Dispatch" model — why we don't pollute the main chat session
docs/PASSIVE_INGESTION_WORKFLOW.md	The "Drop & Forget" document ingestion pipeline
docs/NOTEBOOKLM_PIPELINE.md	NotebookLM automated podcast and study guide generation
docs/OBSIDIAN_SETUP.md	Recommended Obsidian vault structure, plugins, and CLI

Reference

Doc	Description
skills/vault-mind/SKILL.md	The Manager skill — what pi auto-loads about this extension
docs/CHANGELOG.md	Version history (rename from pi-llm-wiki to pi-vault-mind was v0.7.0)
docs/reference/tools.md	The 11 wiki_* and query_wiki/append_wiki/etc. tools — parameters, return shapes
docs/reference/commands.md	Full /wiki slash command tree
docs/reference/configuration.md	The complete pi-vault-mind.config.json schema
docs/reference/skill.md	Manifest of all bundled skills and their trigger phrases

Testing

Doc	Description
docs/TESTING.md	Test plan for agent / human / HITL personas, regression suite
docs/E2E_MANUAL_TEST.md	Manual end-to-end verification procedure (watcher → dispatch → vault)

Development

Doc	Description
docs/CONTRIBUTING.md	Dev setup, testing, and commit conventions
docs/dev/PUBLISHING.md	How to publish this extension to npm
docs/dev/FUTURE_WORK.md	Roadmap — codegraph integration, pagination, TUI rendering, etc.

Research

Doc	Description
docs/COMPETITOR_COMPARISON.md	Tier 1/2/3 comparison vs. other Obsidian-LLM tools (22 competitors)
docs/research/naming-decisions.md	Historical record of the 2026-06-06 decision to name the project pi-vault-mind
docs/research/obsidian-links-reviewed.csv	Curated subset of starred Obsidian repos with adoption verdicts

Archive

Doc	Description
docs/_archive/	Historical docs kept for context (e.g. the pi-llm-wiki → pi-vault-mind rename audit)
docs/plans/legacy-audit.md	The 2026-06-08 legacy-terminology audit (139 findings, 13 blockers) and its resolution log (in the repo, not on the docs site)

Contributing

See docs/CONTRIBUTING.md for dev setup, testing, and commit conventions.

License

MIT — see LICENSE (or package.json).