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-knowledge-store (intermediate) → pi-vault-mind (current).

Features

• Passive File Watcher — drop @agent:<role> (or @agent-<role>) markers in any Obsidian note. Save. The watcher detects the marker, groups by role, and dispatches isolated subagent forks. The original request block is preserved in the note; only the running-status line is updated with the result summary. @agent:main is reserved for the current interactive session and is never auto-dispatched — sweep it manually with /vm main sweep. 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 /vm 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.
• Vault-Scoped Configuration Surface — Vault Mind setup/config now lives under <vault>/.vault-mind/, with the Obsidian setup wizard and /vm setup both writing the vault-local surface instead of a shared global config.
• Audio Transcription Lane — vm_transcribe handles audio/video separately from vm_ingest, preferring a vault-configured Modal HTTP endpoint for high-quality jobs when vaultMind.transcription.remoteUrl is set, while keeping a safe local faster-whisper fallback and /vm transcribe status|config|use|local ops surface for switching lanes and managing the local server.

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 /vm 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=obsidian42-brat enable
obsidian plugin:install id=obsidian-pi-vault-mind enable

Full walkthrough: see [`docs/integrations/OBSIDIAN_SETUP.md`](docs/integrations/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 |
| **Vault Mind plugin** | `obsidian-pi-vault-mind` | Native setup/status/chat UI and HTTP bridge integration. | Recommended |

### Recommended: `notesmd-cli` (headless alternative)

For headless operations, CI, or when Obsidian isn't running, use [Yakitrak/notesmd-cli](https://github.com/Yakitrak/notesmd-cli). It does everything the official CLI does but doesn't require Obsidian to be open.

```bash
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

Curated vault-local skills

pvm setup installs the supported Obsidian and NotebookLM skills into the vault-local Pi agent directory:

pvm setup /path/to/your/vault

The skills live under <vault>/.vault-mind/.pi/agent/skills/<name>/SKILL.md. pvm run disables Pi's implicit global/project skill discovery and explicitly loads only these curated skills plus skills provided by packages installed in the same vault-local agent directory. Do not install these skills globally for a Vault Mind session; global copies defeat vault isolation and can create skill-name conflicts.

• obsidian-markdown — Obsidian-flavored Markdown syntax
• obsidian-bases — valid .base database views
• json-canvas — Canvas JSON used by graph sync
• obsidian-cli — Obsidian CLI operation
• nlm-skill — NotebookLM CLI and MCP workflows

These skills let the Miner, Broadcaster, and Heavy-Lifter agents produce valid Obsidian content without changing the identity of the interactive main agent.

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) | vm_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 24.19.0+ (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, bring-your-own deploy: offload embedding + bulk re-index to a cloud GPU service and sync vectors down for offline search (see docs/integrations/MODAL_EMBEDDING.md). Default behavior is unchanged until you opt in.

On the Modal transcription path: this is bring-your-own deploy. You deploy your own Modal HTTP endpoint from the audio-transcription repo, store its URL under vaultMind.transcription.remoteUrl, and Vault Mind can prefer that remote high-quality path by default. If no remote transcription URL is configured, vm_transcribe falls back to the local faster-whisper lane.

1. Install and set up the vault-local runtime

Install the first-class pvm CLI once, then run setup against a vault:

npm install --global pi-vault-mind
pvm setup /path/to/your/vault
pvm run /path/to/your/vault

pvm setup is safe to repeat. It installs or updates the required Vault Mind, context, model-routing, task, and subagent extensions inside <vault>/.vault-mind/.pi/agent/; installs the curated obsidian-cli, obsidian-markdown, obsidian-bases, and json-canvas skills; and merge-safely scaffolds Vault Mind, model-router, and main-agent configuration. On first run it also creates stock .pi/agent/system.md and vault-root AGENTS.md baseline regions. All of these are preserved on repeat runs — existing user configuration, collections, model choices, and personalizations are never overwritten.

Refresh only extensions, tools, and skills without touching vault configuration:

pvm setup --resources-only /path/to/your/vault

Audit the isolated runtime without changing it, or repair it in place:

pvm check-deps /path/to/your/vault
pvm check-deps --fix /path/to/your/vault

Add --strict to fail when optional tools are missing and --obsidian to include recommended Obsidian plugin checks.

Run either mode without a global installation:

npx --yes pi-vault-mind setup /path/to/your/vault
npx --yes pi-vault-mind run /path/to/your/vault

Installing only the Pi extension remains supported:

pi install npm:pi-vault-mind
pi -e npm:pi-vault-mind

2. Configure interactively when needed

Inside Pi, use the wizard to choose or change embedding providers, folder layout, and other user-facing settings:

/vm setup

For a non-interactive repair inside Pi:

/vm setup --vault /home/you/Obsidian/MyVault --remoteUrl https://your-embedding-service-url.example.com --model embeddinggemma

Config is written to the vault-local Vault Mind surface under <vault>/.vault-mind/ rather than a shared global config file.

You can re-run /vm setup anytime to view or change settings, and the Obsidian plugin's setup wizard uses the same extension-owned routes.

3. Start using

vm_append(collection="main", mode="autopilot", entry={"id":"1","domain":"auth","fact":"JWT tokens expire after 1 hour","tag":"security"})
vm_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 <vault>/.vault-mind/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"
    }
  ],
  "vaultMind": {
    "dataDir": ".lancedb",
    "embedding": {
      "remoteUrl": "http://127.0.0.1:11434",
      "model": "embeddinggemma",
      "dim": 768
    },
    "ftsEnabled": true,
    "graph": { "enabled": true, "canvasSync": false }
  }
}

Using Vault Mind agent identities

Vault Mind keeps the interactive Pi session on the unrestricted main persona unless you explicitly select a specialist boundary. Bundled specialist skills are available resources; merely loading them does not change the active persona.

Start the vault-local main agent

From the vault directory, start Pi in the current terminal:

pvm run

You can launch a different vault from anywhere or use the package without a global install:

pvm run /path/to/your/vault
npx --yes pi-vault-mind run /path/to/your/vault

pvm run defaults to the current terminal. This is the recommended Obsidian Terminal profile command. Use a vault-path placeholder supplied by the plugin, or provide the vault's absolute path. Override the launch mode when needed:

pvm run --same-terminal /path/to/your/vault
pvm run --new-window /path/to/your/vault
pvm run --auto /path/to/your/vault

--new-window opens a dedicated Terminal/iTerm window. --auto uses the current terminal when attached to a TTY and falls back to a new window otherwise. The packaged shell launcher remains available for direct use as scripts/vault-pi.sh.

In every mode, the launcher runs Pi inside the target vault with its configuration isolated under <vault>/.vault-mind/.pi/agent/. It also prevents two launcher-managed Pi processes from running for the same vault and removes the PID file when an inline session exits.

Check the active persona after startup:

/vm identity status

A normal main-agent session reports:

Persona: main
Effective boundary: none (main agent)

Injection may report enabled or disabled. An enabled injector still applies no boundary while the persona is main.

Use specialist agents without changing the main session

Normally, leave the interactive session on main and dispatch specialist work through the passive watcher. Both marker forms are equivalent:

@agent:miner
Research and extract the durable facts from this note.

or

@agent-miner
Research and extract the durable facts from this note.

The watcher runs that work as an isolated specialist job, preserving the request block in the source note and replacing only the running-status line with a result summary. It does not turn the interactive terminal into the Miner persona. The same applies to @agent:broadcaster, @agent:manager, and @agent:heavy-lifter.

@agent:main is reserved for the current interactive session and is never auto-dispatched. To sweep reserved markers into the active session:

/vm main sweep
/vm main sweep path/to/note.md

Explicitly change the interactive persona

Use an identity boundary only when the current interactive session itself should follow a specialist capability contract:

/vm identity set miner
/vm identity set broadcaster
/vm identity set manager
/vm identity set heavy-lifter

| Persona | Intended interactive boundary | |---|---| | main | Unrestricted primary agent with the full configured toolset | | manager | Orchestrates collections, publishing, and subagents; does not run Bash | | miner | Extracts and stores knowledge; does not run Bash or publish | | broadcaster | Produces presentation artifacts; does not run Bash or write durable knowledge | | heavy-lifter | Performs file and Bash work in isolation; does not write durable knowledge or publish |

/vm identity set <role> persists the selected persona, enables boundary injection, and applies on the next agent turn.

Use the remaining controls to inspect or suspend that selection:

/vm identity status
/vm identity off
/vm identity on

• off disables boundary injection without discarding the selected persona.
• on re-enables the configured persona boundary on the next agent turn.
• status shows the configured persona, injection switch, effective boundary, and any environment overrides.

Restore the safe main-agent default with:

/vm identity set main
/vm identity off
/vm identity status

The final status should show Effective boundary: none (main agent).

Configuration and environment overrides

Identity controls are stored in the vault-local configuration:

{
  "vaultMind": {
    "identities": {
      "activeRole": "main",
      "injectBoundaries": false
    }
  }
}

The canonical path is <vault>/.vault-mind/vault-mind.config.json under vaultMind.identities. Identity commands preserve any existing vaultMind.identities.roles allowlists.

Launch automation and explicit specialist forks can override the saved values for one process:

VAULT_MIND_AGENT_ROLE=miner VAULT_MIND_IDENTITY_INJECTION=on pi
VAULT_MIND_IDENTITY_INJECTION=off pi

VAULT_MIND_AGENT_ROLE takes precedence over activeRole. VAULT_MIND_IDENTITY_INJECTION=off suppresses every boundary, while on enables the explicitly selected role. Missing, main, none, and unknown roles all resolve safely to the unrestricted main agent.

Troubleshoot an unexpected specialist boundary

1. Run /vm identity status and check both the configured persona and any reported environment overrides.
2. If an environment override is present, exit Pi, unset VAULT_MIND_AGENT_ROLE and VAULT_MIND_IDENTITY_INJECTION, then relaunch.
3. Run /vm identity set main, followed by /vm identity off.
4. Send the next agent turn and re-run /vm identity status; boundary changes take effect on the next turn.
5. Confirm Pi was started for the intended vault and uses <vault>/.vault-mind/.pi/agent/ as PI_CODING_AGENT_DIR.

Do not edit SYSTEM.md or an agent skill to change the interactive identity. Those files provide operating instructions and resources; persona selection belongs in vaultMind.identities or an explicit environment override.

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 | | ------------------ | ------------------------------------------------------- | | vm_search | Semantic search via LanceDB (vector + FTS) | | vm_fts_search | Exact keyword full-text search (Tantivy BM25) | | vm_graph_query | Traverse entity connections in the graph layer | | vm_status | Show LanceDB table sizes and health | | vm_query | Deterministic JSONL search by collection name | | vm_append | Append with strict/gated/autopilot modes + dual-write | | vm_configure | Read or update config at runtime | | vm_describe | Introspect schema, count, and sample entries | | vm_stats | Dashboard: counts, sizes, LanceDB status | | vm_export | Export to JSON, CSV, or Markdown | | vm_ingest | Convert URLs and documents to markdown via docling | | vm_transcribe | Transcribe audio/video, generate transcript notes + raw artifacts | | vm_script | Execute sandboxed JS/TS with vm., vault.read, log. |

Commands

| Command | Purpose | | ------------------------------ | -------------------------------------------------------- | | /vm help | Show usage help | | /vm setup | Interactive vault-local setup/config wizard (runtime, embedding, scaffold) | | /vm validate | Health check LanceDB, config, and all collection paths | | /vm approve [collection] | Batch-review pending entries | | /vm settings | Open interactive settings dashboard | | /vm audit | Audit config for missing defaults | | /vm reindex [--all] [--reembed] [--remote] | Rebuild FTS + vector indexes; --remote offloads to Modal | | /vm collection select | Select active collection (shortcut: ctrl+alt+l) | | /vm collection create | Interactive wizard to create a new collection | | /vm injector create | Interactive wizard to create a new injector | | /vm context enable \| disable \| status | Manage pi-context integration | | /vm embedding status \| use \| model \| models \| pull | Manage embedding provider | | /vm identity status \| set <role> \| on \| off | Inspect or explicitly control the interactive agent persona boundary | | /vm remote status \| config \| sync \| jobs \| migrate | Manage remote embedding + vector sync | | /vm watcher start \| stop \| status | Manage the passive file watcher | | /vm main sweep [file] | Sweep @agent:main markers into the current interactive session | | /vm server status | Show HTTP server status, port, and uptime |

Documentation

Documentation is maintained directly in this repository.

Getting started

| Doc | Description | |---|---| | Install playbook | Canonical install procedure for the extension, skills, Obsidian plugin, configuration, and external CLIs | | Getting started | End-to-end setup and daily “drop and forget” workflow | | CLI-only walkthrough | Setup and daily commands without the Obsidian plugin | | ReturnVape walkthrough | Current guided Obsidian test-vault procedure |

Architecture & design

| Doc | Description | |---|---| | docs/architecture/AGENTS.md | Agent Roster and Multi-Agent Architecture ("Fork & Review" model) | | docs/architecture/EXTENSION_WIRING.md | Extension dependencies, runtime wiring, auto-install patterns | | docs/architecture/DISPATCHER_SPEC.md | Technical spec for the passive file-watcher and subagent routing — incl. the "Fork & Dispatch" rationale and thread resume |

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 (/vm reindex --all --reembed --remote), and debounced + batched append embedding via the coalescer. Existing non-modal users see no behavior change. See docs/integrations/MODAL_EMBEDDING.md for the full design.

| Doc | Description | |---|---| | docs/integrations/MODAL_EMBEDDING.md | Design of record: ADRs, HTTP contract, sync protocol, roadmap for the cloud embedding service | | 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-knowledge-store to pi-vault-mind was v0.7.0) | | Tools reference | Registered Vault Mind tools, parameters, and return shapes | | Commands reference | Full /vm slash command tree | | Setup and configuration | Current integrated setup/configuration surface, ownership, routes, and live gaps | | Skill manifest | Bundled skills and their trigger phrases |

Development

| Doc | Description | |---|---| | docs/development/CONTRIBUTING.md | Dev setup, testing, and commit conventions | | docs/development/PUBLISHING.md | How to publish this extension to npm |

Archive

| Doc | Description | |---|---| | docs/_archive/ | Historical docs kept for context (e.g. the pi-knowledge-store → 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 and archived 2026-06-16. |

Contributing

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

License

MIT — see LICENSE (or package.json).