QMD Embed Workflow

Keep local hybrid search current after wiki edits: lexical update first, semantic embedding second.

qmd update && qmd embed

Both commands are incremental: only changed files re-index. Source: AGENTS.md Search, 2026-05-31

Role in the stack

qmd provides BM25 keyword, vector semantic, and LLM reranking on-device. It implements the retrieval layer for The Brain-Agent Loop and Brain-First Lookup.

The wiki has two indexes:

Run both. A page can exist in _index.md and still be invisible to qmd query until the qmd pass runs.

qmd is a retrieval projection. The source of truth remains wiki markdown plus generated graph surfaces. If qmd returns stale results after a successful update/embed, debug qmd config or source frontmatter rather than rewriting prose to game search. Source: Generated Surface Contract, 2026-07-01

When to run

After every substantive wiki write, same pass as Build Index Workflow. Agents with MCP can use qmd's query, get, and multi_get tools via .cursor/mcp.json.

Also run after:

• large frontmatter changes that affect search labels
• category README rewrites
• resolver or meta-protocol edits
• skill page updates
• project/person page refreshes that future agents will query

Verification

After embedding, query for one changed concept and confirm the edited page appears:

qmd search "changed phrase" --limit 5

For large ingests, run one semantic query too:

qmd query "what changed about <topic>?"

If search misses an edited page, rerun qmd update, then qmd embed. If it still misses, inspect qmd config and page frontmatter before assuming the content is fine.

For broad rewrites, verify at least one new page title and one updated phrase. The workflow is not complete if qmd failed and the final answer says the brain is updated.

Remote access

For HTTP MCP: npx tsx scripts/serve-mcp.ts with bearer token auth (see integration recipes).

Run Contract

This workflow follows Workflow Run Contract: name the sources, write output or no-op proof, promote only durable facts, update state only when the run really completed, refresh generated surfaces when durable pages or skills change, and log user-visible work.

---

Timeline

• 2026-07-01 | Aligned qmd with the generated-surface model and added broad-rewrite verification expectations for title and phrase retrieval. Source: User request, 2026-07-01
• 2026-06-18 | Clarified the two-index model, expanded run triggers, and added post-embed verification queries. Source: User request, 2026-06-18
• 2026-05-31 | Workflow page created from qmd maintenance protocol in AGENTS.md. Source: AGENTS.md, 2026-05-31