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)
  • modal — optional: offload embedding + bulk re-index to a cloud GPU service and sync vectors down for offline search (see docs/MODAL_EMBEDDING.md). Default behavior is unchanged until you opt in.

1. Install with pi

pi install npm:pi-vault-mind              # latest
pi install npm:[email protected]        # pinned
pi -e npm:pi-vault-mind                   # try without installing

Or from git:

pi install git:[email protected]: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] [--remote] | Rebuild FTS + vector indexes; --remote offloads to Modal | | /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 modal status \| config \| sync \| jobs \| migrate | Manage Modal embedding + vector sync | | /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/NEW_VAULT_WALKTHROUGH.md | Fresh Mac → new vault → Modal → sync → verified, one linear path (incl. multi-vault storage isolation) | | 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 |

Modal embedding service (local integration done)

The local extension now integrates the Modal embedding service as a fully configurable embedding provider: on-demand /embed for search (with an offline fallback that degrades to FTS, never crashes), a sync-down path that pulls server-side vectors into the local LanceDB with a monotonic seq watermark, remote bulk re-index (/wiki reindex --all --reembed --remote), and debounced + batched append embedding via the coalescer. Existing non-modal users see no behavior change. See docs/MODAL_EMBEDDING.md for the full design.

| Doc | Description | |---|---| | docs/MODAL_EMBEDDING.md | Design of record: ADRs, HTTP contract, sync protocol, roadmap for the cloud embedding service | | docs/plans/modal-embedding-plan.md | Consolidated plan & next steps — phases, owners, status, decision gate (in repo, not on the docs site) | | docs/plans/embedding-open-questions.md | Embedding-strategy decision log (decided + open questions) | | modal/ | The deployable Modal app: embedding service + bulk worker + sync + dataset generator | | eval/ | Retrieval eval harness + labeled benchmark datasets for picking the canonical model |

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/_archive/legacy-audit.md | The 2026-06-08 legacy-terminology audit (139 findings, 13 blockers) and its resolution log. Resolved 2026-06-09; archived 2026-06-16 (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).