pi-vault-mind Quickstart¶

Passive Obsidian vault extension with multi-agent subagent dispatch.

Install¶

pi install npm:pi-vault-mind
# or try without installing:
pi -e npm:pi-vault-mind

Scaffold¶

/wiki setup                 # interactive wizard: vault path, embedding, Ollama model

Or CLI mode:

/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/pi-vault-mind.config.json — global, shared across all projects. You can open pi from any directory — the config applies everywhere.

Note: The vault path must exist before you can watch it. If you haven't created a vault yet:
mkdir -p /home/you/Obsidian/MyVault
# Then open it in Obsidian once to initialize the .obsidian/ directory

For project-specific scaffolding:

/wiki init          # creates config + collection files + .lancedb/
/wiki validate      # verify LanceDB connection and health

Embedding (choose one)¶

Default (zero-setup):

/wiki embedding use transformers    # all-MiniLM-L6-v2, 384d, downloads once

Ollama (higher quality):

ollama pull embeddinggemma

/wiki embedding use ollama
/wiki embedding model embeddinggemma
/wiki embedding status             # verify connection

Pull other models:

/wiki embedding models             # list available
/wiki embedding pull all-minilm    # smaller/faster alternative

Usage¶

# Append a fact (auto-embedded into LanceDB)
append_wiki(collection="main", mode="autopilot", entry={
  "id": "1", "domain": "auth",
  "fact": "JWT tokens expire after 1 hour",
  "tag": "security"
})

# Semantic search
wiki_search(collection="main", query="token expiry")

# Keyword search
wiki_fts_search(collection="main", query="JWT")

# Graph traversal
wiki_graph_query(entity="Authentication", depth=2)

# Check health
wiki_status

Agents & Workflows¶

To see how to utilize the multi-agent "Fork & Review" architecture with passive dispatching, see AGENTS.md.

Commands¶

Command	Purpose
`/wiki setup`	Interactive global config wizard
`/wiki init`	Scaffold project config + collections
`/wiki validate`	Health check
`/wiki reindex [--all]`	Rebuild indexes
`/wiki approve [collection]`	Review pending entries
`/wiki watcher start \\| stop \\| status`	Manage passive file watcher
`/wiki server status`	Show HTTP server health + port
`/wiki embedding status`	Embedding config
`/wiki embedding use <provider>`	Switch provider
`/wiki embedding pull <model>`	Pull Ollama model
`/wiki collection create`	Create new collection
`/wiki help`	Full command list

Architecture¶

append_wiki()
  ├── JSONL WAL (collections/main.jsonl)   ← durable, versionable
  └── LanceDB (.lancedb/)              ← auto-embedded, searchable

wiki_search()        → vector (semantic)
wiki_fts_search()    → Tantivy BM25 (keyword)
wiki_graph_query()   → BFS entity traversal

Troubleshooting¶

Issue	Fix
LanceDB connection failed	Check `lancedb.dataDir` is writable
Ollama not reachable	Verify `ollama list` works, then `/wiki embedding status`
No search results	Append a fact first — tables create on first write
Model not found	`/wiki embedding pull embeddinggemma`