How to Ingest and Search a MIF Doc Corpus

Build a local semantic index over a tree of MIF documents and query it by meaning. This guide assumes MIF-conformant docs exist (see the authoring how-to) and that you want discovery over them — coverage checks, cross-link candidates, “which doc covers X?”.

Prerequisites

The optional mif-rs tooling: either the mif-mcp MCP server connected in your session, or the mif-cli binary on PATH. The install how-to covers both routes — attested release binaries verified with gh attestation verify, or cargo install mif-cli mif-mcp.
Network access for the first run only — the embedding model downloads into the local hf-hub cache once.

Ingest the documents

Ingest each document; the store .mif/vectors.db (gitignored) is created on first use:

find docs -name '*.md' -not -path 'docs/adr/*' | while read -r f; do
  mif-cli ingest "$f" || echo "FAILED: $f"
done

Each successful line reports lint=ok validate=ok roundtrip=lossless plus the stored id. Ingest is fail-closed — a doc that fails validation or the round-trip stores nothing and renders a problem+json envelope explaining why, so treat any FAILED line as a real failure to investigate. The ADR documents under docs/adr/ are excluded up front and deliberately: they carry a top-level description: frontmatter key, which currently drifts through the Rust round-trip (dropped on re-serialization, tracked in the engine-convergence epic). Excluding them by path keeps known drift out of the failure signal.

Search by meaning

mif-cli search "how do I validate a document against the MIF schema" --limit 5

The output is ranked (score, id) pairs, most similar first. Useful matches on this suite’s corpus typically score about 0.55-0.78. An empty store returns (no matches).

Find cross-link candidates

mif-cli find-similar "urn:mif:reference-corpus-layer" --limit 5

The anchor id must already be ingested (a 404 problem envelope tells you it is not). The anchor itself is excluded from results. Offer the top matches as candidate relationships[] targets — the author, or the doc-set-planner reconcile step, decides which to accept.

Check corpus health

mif-cli corpus-stats

Reports count, embedding dim (384), and the db path. To rebuild from scratch, delete .mif/vectors.db and re-ingest — the store is a derived index, never an authority.

Result

You have a queryable semantic index over your MIF docs and a repeatable way to refresh it. For the full operation-by-operation contract (MCP tool names, error envelopes, the ADR exclusion), see the corpus-layer reference linked in this guide’s relationships[].