Give your agent searchable memory
Your agent can miss something it already knows simply because you asked about it using different words. QMD gives it fast, private search across its memory, notes, instructions, and knowledge base.
For humans
Your agent's workspace may contain months of memory, daily notes, decisions, people, projects, and instructions. Without good search, it can overlook a file that contains the answer and wrongly tell you it does not know.
It can find the idea, not just the exact words
Ordinary text search works best when your question uses the same words as the note. QMD also looks for related meaning.
For example, you might ask about difficulty starting tasks while the useful note calls it executive dysfunction. QMD can connect those ideas, while still finding exact names, phrases, and details when those matter.
QMD builds a private search index on your computer. When you send your agent this link, it will install QMD, make the agent workspace searchable, schedule regular updates, connect search to Claude Code or Codex, and prove the setup with a real query.
You can simply send the page to your agent and let it handle the setup. We encourage you to read through the guide too, so you understand what your agent will install, which files it will index, and what will run in the background. You do not need to memorize the commands.
Send this guide to your agent
Copy the page link, paste it into a conversation opened at the root of your agent workspace, and say: “Read this guide and follow the For agents section.”
Local and private
QMD downloads about 2 GB of search models the first time it runs. Searches and embeddings stay on this machine. The first embedding pass is real work: expect roughly 5–15 minutes for a substantial workspace. One 6,712-chunk vault took 6 minutes 26 seconds.
For agents
Your task
Set up QMD search for the current AI agent workspace. Follow every step below in order. Detect the operating system and current harness rather than asking the human to translate instructions. Preserve existing configuration, do not create duplicate collections or scheduled jobs, and verify the complete search path before reporting success. Pause only when an action requires approval or a choice that cannot be safely inferred.
Execution steps
Install Node.js and one shared copy of QMD
QMD requires Node.js 22 or newer. Check node --version and npm --version first. If either command is missing or Node is too old, install a current version from the official Node.js download page. npm comes with Node.js; do not install it separately.
Install QMD globally rather than hiding it inside one harness's plugin cache. That gives Claude Code, Codex, your terminal, and the scheduled updater the same executable.
npm install -g @tobilu/qmdAfter installation, verify QMD by locating the command itself: use command -v qmd on Mac or (Get-Command qmd).Source in Windows PowerShell. Record the absolute paths for both QMD and Node. If QMD is not found, use npm prefix -g to diagnose where npm installed it; do not use the removed npm bin -g command.
Node version managers need extra care
With nvm, a “global” npm package belongs to one Node version. Switching or removing that Node version can break QMD, the Codex MCP connection, and the scheduled updater. Record the active Node version and paths. After changing Node versions, reinstall QMD and update both integrations.
Index the agent vault without duplicating it
QMD configuration can survive even when its executable disappears. Inspect existing collections before creating anything. Compare their resolved paths with the current workspace folder containing AGENTS.md. If one already points there, reuse its existing name. Only create a new, uniquely named collection when no path matches.
qmd collection list
qmd collection show <existing-name>
# Only when no existing collection points at this workspace:
qmd collection add "<agent-workspace>" --name "<unique-vault-name>" --mask "**/*.md"
qmd context add qmd://<collection-name> "The agent's workspace, memory, daily notes, instructions, and structured knowledge base."
qmd update
qmd embedLet the first embedding pass finish. Early time estimates may jump around. Do not interrupt it merely because it estimates ten minutes.
Keep the index fresh
New and changed files need to enter the text index, then receive embeddings for semantic search. The scheduled job should run both commands, in that order, once an hour.
Mac: create a wrapper and user LaunchAgent
LaunchAgents do not load your normal shell setup. Create ~/.local/bin/qmd-refresh with the resolved Node and QMD directories in PATH. Replace every placeholder with an absolute value; do not leave angle-bracket placeholders in the finished files.
#!/bin/zsh
export PATH="<NODE_DIR>:<QMD_DIR>:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
"<ABSOLUTE_QMD_PATH>" update &&
"<ABSOLUTE_QMD_PATH>" embedMake it executable, then create ~/Library/LaunchAgents/systems.divergent.qmd-refresh.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>systems.divergent.qmd-refresh</string>
<key>ProgramArguments</key>
<array>
<string>/Users/<USER>/.local/bin/qmd-refresh</string>
</array>
<key>StartInterval</key>
<integer>3600</integer>
<key>RunAtLoad</key>
<true/>
<key>StandardOutPath</key>
<string>/Users/<USER>/Library/Logs/qmd-update.log</string>
<key>StandardErrorPath</key>
<string>/Users/<USER>/Library/Logs/qmd-update.log</string>
</dict>
</plist>Validate, load, trigger, and inspect it. If the label already exists, update the existing files and use bootout before loading it again rather than creating a second job.
chmod +x "$HOME/.local/bin/qmd-refresh"
plutil -lint "$HOME/Library/LaunchAgents/systems.divergent.qmd-refresh.plist"
launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/systems.divergent.qmd-refresh.plist" 2>/dev/null || true
launchctl bootstrap "gui/$(id -u)" "$HOME/Library/LaunchAgents/systems.divergent.qmd-refresh.plist"
launchctl kickstart -k "gui/$(id -u)/systems.divergent.qmd-refresh"
tail -n 50 "$HOME/Library/Logs/qmd-update.log"The explicit PATH is required even when QMD itself is absolute because its launcher may use /usr/bin/env node.
Windows: use Task Scheduler
Create a current-user PowerShell script that calls the absolute QMD command, runs update and then embed, and appends output to %USERPROFILE%\qmd-update.log. Register it in Task Scheduler to repeat hourly after sign-in. Run the task immediately once and inspect both its exit status and log.
Connect your agent harness
Claude Code has an official QMD plugin that bundles the MCP connection and QMD search skill.
claude plugin marketplace add tobi/qmd
claude plugin install qmd@qmdCodex connects directly to QMD's built-in MCP server. Register the absolute QMD path found in step 1, not a bare qmd command. Also give the MCP process an explicit PATH containing the resolved Node and QMD directories.
codex mcp add --env PATH="<NODE_DIR>:<QMD_DIR>:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin" qmd -- "<ABSOLUTE_QMD_PATH>" mcpUse the platform's normal PATH separator on Windows. If Node came from nvm, recreate this MCP entry after switching Node versions.
The current task will not gain newly installed MCP tools dynamically. Claude Code users should start a fresh session. Codex desktop users must fully quit the app with Command+Q, reopen it, and then start a fresh task. Closing a task or window alone may reuse the old MCP configuration.
Teach the agent when to search
Tools do not help if the agent forgets to use them. Add a durable instruction to the workspace's AGENTS.md:
Before saying you cannot find or remember workspace information, search QMD. Use QMD for questions about memory, daily notes, the knowledge base, people, projects, decisions, and prior work.Prove the CLI works
First verify the local index. Read USER.md, choose the human's actual name and one specific fact, then form a query likely to return that file. Avoid broad prompts such as “What does this agent know about its human?” because another person's document may rank first.
qmd status
qmd query "What are <HUMAN'S FULL NAME>'s communication preferences?"Confirm the expected file appears near the top, retrieve it, and check that the passage actually answers the question. This proves QMD's CLI and index, but it does not prove the harness connection.
Prove the MCP connection in a fresh task
After restarting the harness as described above, ask the human to open a fresh task in the same workspace and send:
Verify QMD search using the QMD MCP tools only, not shell commands.
Call each QMD tool sequentially and wait for it to return before calling the next one.
First call status. Confirm that documents are indexed and the documents are vectorized.
Then choose 2–3 natural test questions of your own about people, projects, decisions, or topics you already know are documented in this workspace. Do not copy wording from filenames or known documents. Run each question through query using semantic/vector search. For promising results, call get to retrieve the relevant passage.
Report which QMD tools you called, the index health, each test question, which expected documents appeared, any missing or irrelevant results, and whether QMD search is working.QMD's MCP exposes status, query, and get. Do not require tools literally named vector_search or deep_search. Run semantic queries sequentially because several simultaneous local model calls can stall or contend for memory. A shell command such as qmd query is not sufficient. Report the QMD version, absolute Node and QMD paths, reused or created collection, document and embedding counts, scheduled-job test result, CLI result, and fresh-task MCP result. If the fresh-task test has not happened yet, report the setup as awaiting MCP verification rather than complete.
If search results feel stale
Check the updater's log first. qmd update refreshes keyword search; qmd embed catches semantic search up afterward. If one runs without the other, the two search modes can disagree.
Stuck or need help?
Send a message and it comes straight to me. Tell me where you got stuck and I'll write back.
Rather have it done for you?
If following the steps yourself isn't how your brain works today, that's fine. On a Zoom call you share your screen and hand me control, and I set it up for you, right there on your own computer. You watch it come together and end the call with a working setup, nothing left on your plate.
Pick a time below. No pitch, no pressure, no homework beforehand.