iopsystems/skills-mcp/vault-search

Vault search

You have three programmatic MCP tools available for reading the knowledge-iop vault. They are fast, deterministic, and query a SQLite index maintained by skills-mcp. Use them instead of grep or find whenever you can.

The tools

vault_search — find artifacts

// inputs (at least one filter required; empty filters return []):
{
  "type":    "design-brief",         // optional; see list below
  "status":  "draft",                 // optional
  "author":  "alex",                  // optional
  "topic":   "rate limiting",         // optional; FTS5 over title + body
  "limit":   50                       // optional; default 50, max 500
}

Artifact types: scope, arc, problem-brief, design-brief, decision, discussion, session-note, inquiry, exploration, synthesis, claim, schema.

Returns { count, matches: [{ id, type, status, author, created, path, title }] }.

vault_edges — walk the graph around an artifact

{
  "id":        "2026-04-17-vault-design",
  "kind":      "frames",               // optional; filter by edge kind
  "direction": "both"                  // outgoing | incoming | both (default both)
}

Edge kinds: frames, supersedes, superseded_by, relates_to, conflicts_with, depends_on, derived_from, arc, scopes, inquiry.

Returns { id, count, edges: [{ from_id, to_id, kind, neighbor }] }. Each edge carries the neighbor artifact's metadata, so one call is usually enough.

vault_check_transition — "can this be accepted?"

{ "id": "2026-04-17-vault-design", "new_status": "accepted" }

Returns { allowed, blockers: [...], warnings: [...] }. Use before proposing a status change, not as a general search.

When to use each

How to use this skill

When a phase skill (frame-problem, propose-design, record-decision, ...) or the user's request tells you to "check the vault first", do this:

1. Extract keywords from the topic or artifact the user is working on

(service names, problem nouns, technology names).

1. Call `vault_search` with `topic` first. If results are thin, try

with type to widen.

1. If you find a candidate match, call vault_edges on its id to see

what's already connected (does it have a design-brief? is it superseded? what arcs / scopes touch it?).

1. Report back concisely: matches + gaps. A phase skill will use the

result to decide whether to draft anew, supersede an old artifact, or redirect the user to an existing one.

Reporting format

When returning findings, use this structure so callers can parse it:

MATCHES (<n>)
- id: <artifact-id>
  type: <type>    status: <status>    created: <YYYY-MM-DD>
  path: <vault-relative path>
  title: <first heading>
  connected:
    - <kind> → <neighbor id> (<neighbor status>)
 
GAPS
- <what's missing that would matter here>
 
BLOCKERS (if vault_check_transition was called)
- <rule>: <message> — offenders: <ids>

Gaps are as important as matches. A phase skill deciding whether to chain to another skill needs to know what's missing, not just what exists.

Do not

• Do not modify the vault from this skill. Writes are the job of phase

skills (frame-problem, propose-design, ...).

• Do not call vault_reindex unless something is visibly stale — the

index auto-refreshes on each query when files change.

• Do not grep / find in the vault directory unless one of these tools

has failed. The index is the fast path.