| name | qmd |
| description | FlowState-QMD gives coding agents anticipatory project memory over docs, notes, ADRs, changelogs, and runbooks. |
| license | MIT |
| compatibility | Requires the qmd CLI or MCP server. Install with qmd or npm, then connect agents via MCP. |
| metadata | {"author":"Adam Manning and Tobi Lutke","version":"2.0.1-flowstate"} |
| allowed-tools | Bash(qmd:*), mcp__qmd__* |
QMD for Coding Agents
FlowState-QMD is a local-first memory layer for coding agents. It turns markdown knowledge bases into project memory that is fast enough to feel built in.
What It Is Good At
- Repo memory: design docs, specs, ADRs, RFCs, changelogs
- Team memory: meeting notes, incident reviews, migration summaries
- Agent memory: anticipatory context before a reactive search step
- Trustworthy recall: inspectable snippets, doc IDs, and explain traces
Status
!qmd status 2>/dev/null || echo "Not installed: run 'qmd skill install --global' or 'npm install -g @tobilu/qmd'"
Start Here
- Call
fetch_anticipatory_context at the beginning of a coding turn when recent conversation context is available.
- Use
query when you need deeper retrieval or want to inspect the evidence directly.
- Use
get or multi_get to pull exact docs, ADRs, changelogs, or notes once you know what matters.
MCP Tool: fetch_anticipatory_context
Use this first when you want the agent to feel like it already knows the project context.
{
"recent_conversation": "What changed in the auth rollback plan and why did we revert the migration?",
"refresh": false,
"lite_mode": false
}
Returns:
- cached anticipatory memories from FlowState when available
- or a fresh live query over the current project memory
MCP Tool: query
{
"searches": [
{ "type": "lex", "query": "\"auth rollback\" migration changelog" },
{ "type": "vec", "query": "why did we revert the authentication migration?" }
],
"collections": ["docs", "notes"],
"intent": "coding agent project memory for a migration debugging task",
"limit": 8
}
Query Types
| Type | Method | Best for |
|---|
lex | BM25 | exact names, code terms, filenames, changelog phrases |
vec | Vector | natural-language engineering questions |
hyde | Vector | nuanced answers when you know what the result should sound like |
Writing Better Coding-Agent Queries
- Start with
lex when you know a filename, subsystem, ADR title, or error string
- Add
vec when you know the problem but not the vocabulary
- Add
intent for ambiguous queries like "performance", "memory", or "rollback"
- Use
--explain in the CLI when you need to understand why a memory was selected
Other MCP Tools
| Tool | Use |
|---|
get | Retrieve a single document by path or #docid |
multi_get | Pull several related documents by glob or list |
status | Check collection health, embedding status, and defaults |
CLI
qmd collection add . --name repo-memory
qmd embed
qmd flow ~/.codex/sessions/current.log --lite
qmd query "why was the rollout reverted"
qmd query --json --explain "performance regression in auth service"
qmd get "#abc123"
qmd multi-get "docs/**/*.md,CHANGELOG.md"
Memory Model
- Durable knowledge: indexed markdown files in collections
- Working memory: FlowState anticipatory cache in
~/.cache/qmd/intuition.json
- Context overlays: human-authored collection and path summaries via
qmd context add
Setup
qmd skill install --global --yes
qmd collection add ~/projects/my-repo/docs --name docs
qmd collection add ~/projects/my-repo/notes --name notes
qmd embed
qmd mcp
