Skip to content

Tools Reference

pi-vault-mind registers 12 tools with the pi agent. They cover the full lifecycle: search, append, configure, introspect, and sync.

Search & traversal

Semantic vector search across indexed wiki collections using LanceDB.

Parameters:

Parameter Type Required Description
collection string yes Collection name (e.g. main)
query string yes Natural-language search query
limit number no Max results (default 5)

When to use: Natural-language queries, "find me facts about X" questions.

Full-text keyword search (Tantivy BM25) across indexed wiki collections.

Parameters: same as wiki_search.

When to use: Exact keyword/phrase matching, code symbols, specific terms that semantic search might miss.

wiki_graph_query

Traverse entity connections in the LanceDB graph tables.

Parameters:

Parameter Type Required Description
entity string yes Entity to search for relations
depth number no Depth of traversal (default 1)

When to use: "What is X related to?" or "show me the neighborhood around entity Y."

query_wiki

Deterministic JSONL search by collection name. Use for exact lookups and filtered retrieval.

Parameters:

Parameter Type Required Description
collection string yes Collection name (e.g. main, pending)
query string no Free-text substring search across all text fields
filters object no Exact {field: value} matches

When to use: When you need exact, deterministic results rather than semantic similarity.

Append & promote

append_wiki

Append to a wiki collection. Autopilot dual-writes to JSONL + LanceDB with optional auto-sync to vault.

Parameters:

Parameter Type Required Description
collection string yes Target collection name (call describe_wiki if unsure)
entry object yes Field-key → value map matching the collection schema
sync enum no Vault sync mode: auto (default), manual, none
vault string no Specific vault to sync to (default: all configured)

Modes:

  • autopilot (default) — appends immediately, dual-writes, auto-embeds, optionally syncs to vault.
  • strict — fires a ctx.ui.confirm prompt for human-in-the-loop approval.
  • gated — stages to pending collection for batch review via /wiki approve.

promote_wiki

Promote entries from one collection to another via the pending queue for human approval.

Parameters:

Parameter Type Required Description
sourceCollection string yes Collection where entries currently reside
targetCollection string yes Collection where entries should be moved
entryIds string[] yes List of entry IDs to promote
reason string yes Reason for promoting these entries

Stages entries in pending for human review. Does not append directly to target. Use /wiki approve to finalize.

Configuration & introspection

configure_wiki

Read or update the pi-vault-mind.config.json at runtime.

Parameters: config (object, optional) — partial config object to merge.

describe_wiki

Introspect a named collection: schema, entry count, and sample entries.

Parameters: collection (string, required) — collection name to inspect.

wiki_stats

Dashboard of all collections: counts, sizes, pending queue size, and LanceDB health.

Parameters: none.

wiki_status

Show LanceDB status: data directory and tables.

Parameters: none.

Sync & export

wiki_sync

Push matching wiki entries to an Obsidian vault as markdown pages or canvas graph files.

Parameters:

Parameter Type Required Description
vault string no Vault name (defaults to "default"). Use "*" for all configured vaults.
query string no Free-text search to select entries to sync
tag string no Sync entries matching this tag
collection string no Collection to sync from (default: main)
format enum no markdown (default) or canvas
limit number no Max entries (default 20)

wiki_export

Export a collection to JSON, CSV, or Markdown.

Parameters:

Parameter Type Required Description
collection string yes Collection name to export
format enum yes json (default), csv, or markdown

wiki_ingest

Ingest documents (URLs, HTML, PDFs) into the wiki. Converts to clean markdown via any2md, then returns the text for entity extraction and append_wiki.

Parameters:

Parameter Type Required Description
source string yes URL, file path, or raw text to ingest
sourceType enum no url, file, or text (auto-detected if omitted)

See also