qmx
# qmx — Query Memory indeX
Local, private semantic search over your **code and chats**.
qmx indexes source repositories (AST-aware) and your Claude Code conversation history into an
on-device vector + full-text index, and serves them by *meaning* to agents via MCP — or to you on
the command line. Everything runs on hardware you control — no cloud service.
Powered by [Nemotron](https://huggingface.co/nvidia/Nemotron-3-Embed-1B-BF16) embeddings, the
[Qwen](https://github.com/QwenLM) reranker/judge models and
[`sqlite-vec`](https://github.com/asg017/sqlite-vec). Derived from
[`tobi/qmd`](https://github.com/tobi/qmd) (MIT).
**Start here:** [QUICKSTART.md](./QUICKSTART.md) (install → index → use from Claude Code) ·
[INFRA.md](./INFRA.md) (the model backends — Ollama, vLLM, llama.cpp — + services) ·
[plan/](./plan) (design).
## Why
- **Find by meaning, not grep** — "where's the launcher logic" instead of guessing symbol names.
- **Remember conversations** — semantic recall across every past Claude Code session.
- **Private by construction** — code and chats are embedded (Ollama) and distilled (vLLM) by model
servers you control and stored in a local index — never sent to a cloud service.
## Architecture
**The big picture — three pieces:**
```mermaid
flowchart LR
U["Claude Code / you"]
subgraph MAC["Your Mac — the client (answers here)"]
S["qmx MCP server"]
DB[("local index<br/>SQLite: vectors + BM25")]
CON["qmx consolidate<br/>(SessionEnd hook · nightly)"]
S <--> DB
CON --> DB
end
subgraph SPARK["DGX Spark — GPU (models only)"]
E["Nemotron embeddings<br/>(vLLM)"]
C["Qwen3.8 judge · vLLM<br/>(learnings / consolidation)"]
R["Qwen reranker<br/>(llama.cpp)"]
end
U -->|"MCP: query · recall · lessons"| S
S -->|"embed · rerank"| E
S -.->|"rerank top-k"| R
CON -->|"consolidate chats → lessons"| C
```
- **DGX Spark (GPU)** — runs the **models only**: **embeddings** (Nemotron-3-Embed-1B on vLLM), the
**reranker** (Qwen3-Reranker on llama.cpp), and the **judge** that distils chats into *learnings* (Qwen3.8 on vLLM). Text is sent
for compute; **nothing is stored there**.
- **Your Mac (the client)** — holds the **local index** (SQLite: `sqlite-vec` vectors + FTS5/BM25)
and runs the **MCP server** and **consolidation** (`qmx consolidate`). It does the actual
searching and **answers from the local DB**, calling the Spark only for model compute.
- **Claude Code (you)** — talks to the Mac's MCP server (`query` / `recall` / `lessons` / …); it
never touches the Spark directly.
A few config knobs point the Mac at the Spark: `embed_url` (embeddings), `chat_url` (the
judge) and, optionally, `rerank_url`. In more detail, qmx is two cooperating pieces:
- **qmx** (this tool) — the **index and search**: chunking, the SQLite store (`sqlite-vec` + FTS5),
hybrid ranking, the CLI, and the MCP server all run **on your machine**.
- **Model servers** — an **embedding server** produces the **embeddings**: vLLM serving
Nemotron-3-Embed-1B in production (`embed_backend = "openai"`), or Ollama (the default). For
the learnings tier, the **judge** (a Qwen chat model) runs on an OpenAI-compatible server — vLLM
in production (`chat_backend = "openai"`); optionally a llama.cpp **reranker**. They can be the
*same* machine, or a GPU box on your LAN (e.g. a DGX Spark). The only thing that crosses to them
is the text being embedded, reranked or consolidated; the index and all search stay local.
So you can run everything on one laptop, or keep the index local and offload embeddings to a GPU box.
**Indexing** — files → chunks → vectors (on the backend) → local SQLite index:
```mermaid
flowchart LR
subgraph M["your machine — qmx"]
F["repo files"] --> C["chunk<br/>(tree-sitter)"]
DB[("SQLite index<br/>sqlite-vec · FTS5 · hashes")]
end
subgraph B["Ollama backend · GPU"]
E["Nemotron-3-Embed-1B<br/>(vLLM)"]
end
C -- "chunk text" --> E
E -- "vectors" --> DB
```
**Querying** — only the query string is embedded on the backend; vector + keyword search and
ranking are entirely local:
```mermaid
flowchart LR
subgraph M["your machine — qmx"]
QT["query text"]
SR["search<br/>vector (cosine) + BM25 → RRF"]
DB[("SQLite index")]
H["ranked hits<br/>file:line + snippet"]
DB --> SR --> H
end
subgraph B["Ollama backend · GPU"]
E["Nemotron-3-Embed-1B<br/>(vLLM)"]
end
QT -- "query text" --> E
E -- "1 vector" --> SR
```
**Chat memory** — Claude Code transcripts feed the *same* flat KB two ways: `qmx backfill-chats`
imports past sessions once, and a Claude Code `Stop` hook runs `qmx capture` on every finished turn.
Both clean the JSONL to plain turns and reuse the incremental pipeline, so only *new* turns embed;
`recall` (or `query --kind chat`) reads them back:
```mermaid
flowchart LR
H["Claude Code<br/>Stop hook (per turn)"]
subgraph SRC["~/.claude/projects/*.jsonl"]
T["session transcripts"]
end
subgraph M["your machine — qmx"]
BF["qmx backfill-chats<br/>(all past sessions)"]
CAP["qmx capture<br/>(new turn, live)"]
CLEAN["clean turns<br/>drop thinking / tools / side-chains"]
DB[("flat KB · SQLite<br/>code + chats")]
RC["recall<br/>(query --kind chat)"]
end
subgraph B["Ollama backend · GPU"]
E["Nemotron-3-Embed-1B<br/>(vLLM)"]
end
H -- "transcript path (stdin)" --> CAP
T --> BF --> CLEAN
T --> CAP --> CLEAN
CLEAN -- "turn text" --> E
E -- "vectors — only NEW turns" --> DB
DB --> RC
```
**Keeping code current (`watch`)** — the code counterpart to chat capture. `qmx watch` subscribes to
OS filesystem events (**macOS FSEvents** via `watchdog`): the kernel *pushes the changed path* — no
polling, no tree scan. Recognised **code** (tree-sitter) and **markdown** (`.md`, indexed as
`kind=doc`) files are (re)indexed, and only the *changed chunks* re-embed (content-hash diff);
other files (data, binaries) are ignored:
```mermaid
flowchart LR
SAVE["edit / save a file<br/>under code_roots"]
subgraph OS["macOS kernel"]
FSE["FSEvents<br/>pushes the changed path"]
end
subgraph W["qmx watch (launchd)"]
H{"code or .md?"}
RI["reindex that one file<br/>chunk → hash → embed only NEW chunks"]
IGN["ignore"]
DB[("flat KB · SQLite")]
end
SAVE --> FSE
FSE -- "changed path" --> H
H -- "yes (.py/.ts/.md/…)" --> RI --> DB
H -- "no (data / binaries)" --> IGN
```
(Delete → the file's chunks are dropped; move → drop old + index new. `busy_timeout` lets watch,
the capture hook, and `refresh` write the flat KB concurrently.)
Choose where the embedding backend lives with `embed_backend` + `embed_url` (or `QMX_OLLAMA_URL`
for Ollama) and which model embeds with `embed_model` (see [QUICKSTART.md](./QUICKSTART.md)).
**Reranking (optional)** — when `rerank_url` is set, the RRF top candidates are re-scored by a
cross-encoder (**Qwen3-Reranker** via llama.cpp `--reranking` on the Spark GPU) and trimmed to `k`.
Off by default; if the rerank server is unreachable it **fails soft** back to RRF order:
```mermaid
flowchart LR
subgraph M["your machine — qmx"]
RRF["vector + BM25 → RRF"]
POOL["top-N candidates<br/>(rerank_pool, default 40)"]
TOPK["reordered top-k<br/>(cross-encoder scores)"]
RRF --> POOL
end
subgraph B["Spark · GPU"]
RR["llama-server --reranking<br/>Qwen3-Reranker (llama.cpp)"]
end
POOL -- "query + candidate texts" --> RR
RR -- "relevance scores" --> TOPK
POOL -. "server down → keep RRF order" .-> TOPK
```
See [plan/qmx-ml-notes.md](./plan/qmx-ml-notes.md) (TD-1) for how the reranker is built and served.
## Meetings (Memoir calls)
qmx also indexes [Memoir](https://github.com/the-dsvolk/memoir) call folders
(`~/memoir/YYYY-MM-DD_<name>/`) as `kind=meeting`. Each of `transcript.txt`, `summary.md`,
`notes.md` and `prep.md` is its own document, with `repo` set to the call folder. The transcript is
chunked into ~60–90 s windows (breaking only between lines, one-line overlap) that cite their
`transcript.txt` line range, with speakers and time range as the `symbol`. Every chunk starts with
`name · date start · attendees` (attendees from an `Attendees:` line in `prep.md`). Meetings are
searchable only — they are never distilled into lessons.
```bash
qmx index-meeting ~/memoir/2026-10-22_design-review # one call (Memoir's after-the-call step)
qmx backfill-meetings # every call under ~/memoir
qmx query --kind meeting "release plan options" # or the `meetings` MCP tool
```
A call still in progress (no `ended_at` in `meeting.json`) is skipped. Renamed or deleted call
folders are not tracked automatically.
## Learnings (distilled lessons)
Beyond raw recall, qmx distils past chats into a **learnings** tier (`kind=learning`) — reusable
*decisions*, *mistakes+corrections*, and *how-tos* — deduped/superseded so they self-correct, and
**proactively injected at session start** so an agent begins already knowing. See
[`plan/qmx-learnings.md`](./plan/qmx-learnings.md) for the design. The judge model is config-driven
(`chat_backend` / `chat_url` / `chat_model`), never hardcoded. In production it is **Qwen3.8-27B**
(NVFP4, DFlash2 speculative decoding) served by **vLLM** through its OpenAI-compatible API on the
Spark, with thinking off, a reasoning-first JSON field and temperature 0:
```toml
# ~/.qmx/config.toml — these are also the code defaults; set them to point at another judge
chat_backend = "openai"
chat_url = "http://spark-1.local:8000/v1"
chat_model = "qwen3.8-judge"
```
```bash
qmx add-learning "raise IAM PRs at project level" --type mistake \
--detail "bucket-level failed; ask the platform team" --scope the-dsvolk/qmx
qmx lessons "how to raise an IAM PR" # recall, ranked by relevance × importance × recency
qmx consolidate --session <transcript> # Qwen distils a chat into lessons (new/update/supersede/retire)
qmx lessons --review # list promotion-eligible lessons
qmx promote <id> # graduate one into per-repo curated memory
```
A lesson can also be **wrong**, so it can be corrected or retired rather than only buried under a
lower weight:
```bash
qmx update-learning 42 --importance 0.1 # re-weight (no re-embed, works backend-down)
qmx update-learning 42 --statement "…" --clear-detail # fix the wording in place, same id
qmx deprecate-learning 42 --reason "renegotiated" --superseded-by 57 # soft-retire + breadcrumb
qmx lessons --deprecated # what's retired, why, and what replaced it
qmx restore-learning 42 # undo
qmx learning-history 42 # earlier versions (every update keeps the old text)
qmx revert-learning 42 # undo the last in-place update (--revision N)
qmx fix-importance # report lessons whose importance escaped 0..1
```
> `importance` is a ranking **weight** in 0..1, not a 1–5 rating: it enters the blend as
> `0.3 × importance` against a relevance term capped at 0.5, so a lesson stored at 9.0 outranks
> everything relevant. Writes are normalised and clamped; `qmx fix-importance --apply` repairs rows
> written before that guard existed.
`deprecate` needs **no** replacement — that is the case `superseded_by` alone could not express.
Retired lessons stop firing everywhere (`lessons`, `query --kind learning`, session-start injection)
and come back with `--include-retired`; nothing is destroyed, so restore is free. Hard delete is
intentionally **not** an MCP tool: it is irreversible and reserved for a wrong-with-no-history or
confidentiality call a human makes.
Consolidation retires too, so the loop closes: the judge's actions are
**new / update / supersede / deprecate / drop** — it can retire a lesson a session proved wrong with
nothing to replace it, and, because retired lessons are shown to it flagged `[RETIRED: why]`, it
`drop`s a candidate that merely re-learns one instead of quietly resurrecting it next session. Both
counts are reported by `qmx consolidate`, never silent. Long sessions are read in several passes
(≤200 turns / ≤100K characters each), and sessions below a one-off gate (`consolidate_min_turns` 8,
`consolidate_min_chars` 4000) are skipped and left to accumulate.
**Merge guardrails.** `update` is the only destructive action (supersede/deprecate keep the old row),
and the judge sometimes "merges" a candidate into an *unrelated* neighbour, replacing that lesson's
point — e.g. a pinning rule rewritten as a lockfile rule. So before any `update` the
judge answers a second question: *does the merged text still state the target's core claim?* — and
must quote, verbatim, where that claim survives in the merged text (checked in code). If not (or the
answer is unusable), the update is refused, the target is left intact and the candidate is stored as
a new lesson in its own words; `qmx consolidate` reports the count. Every in-place update —
consolidation or manual — also snapshots the previous text (`learning_revisions`, schema v6), so
`qmx learning-history` / `qmx revert-learning` (and the matching MCP tools) can undo a bad edit.
**Retirement guardrail.** `supersede` and `deprecate` both hide a live lesson, so both need a
verified contradiction: the judge quotes the span of the candidate that contradicts the old lesson,
and code checks the quote is really in the candidate. A refused `deprecate` stores the candidate as
new; a refused `supersede` keeps the old lesson live and sends the candidate through the
near-duplicate check below.
**What the judge is shown.** The decision call lists the candidate's nearest live lessons, up to
`judge_match_pool` (10; was 5 until 2026-11-07, when one known missed merge turned out to have its
lesson at rank 8), plus up to 3 retired ones.
**Near-duplicate check.** A `new` candidate whose nearest live lesson is at least
`dedup_min_similarity` similar gets one more question — *same lesson?* — about that one lesson, and
is dropped, merged into it, or kept as new. The cut-off depends on the embedder: 0.65 (default) for
qwen3-embedding, 0.50 for Nemotron-3-Embed (both send about two thirds of true duplicates to the
check); 0 disables it. With `judge_merge_steps = true` (opt-in) that one question is split into
steps: the judge only *quotes* — where the stored lesson already states the candidate's main rule,
and which candidate facts it lacks — and code decides. No verifiable quote → kept as new; nothing
missing → dropped; otherwise the candidate's own sentences carrying the missing facts are appended
to the stored lesson's detail, so its statement and detail survive byte for byte and no merge check
is needed. Aimed at the known missed merges, where the judge files a lesson the store already holds
(often in its detail) as new.
**When the judge misbehaves.** Each call has an output cap — 3072 tokens for the short decision and
check calls (`chat_short_max_tokens`), 8192 for extraction (`chat_max_tokens`). A reply that is cut
off, runs away past the timeout, or is not JSON fails safe for that one decision (decision → stored
as new, merge/retirement check → refused, near-duplicate check → kept, extract → that pass stays
queued) instead of failing the run. Three unusable replies in a row, or an unreachable judge,
**defer** the run: there is no fallback judge, and a pass is marked consolidated only once it
finishes, so its turns stay queued for the next session end or the nightly `qmx consolidate --all`.
`chat_json_layout = "indent"` (opt-in; default `"schema"`) constrains vLLM to a fixed JSON layout
that rules out runaway whitespace.
**Judge client settings (opt-in).** `chat_temperature` (0.0), `chat_top_p` (0 = not sent),
`chat_template_kwargs` (a JSON object merged into vLLM's chat-template kwargs),
`chat_short_max_tokens` (3072), `judge_reasoning_field` (true), `judge_filing_rules`
(`"current"` | `"v2"`), `judge_offrule_block` (false), `judge_match_pool` (10), `judge_merge_steps` (false) and `judge_listing` (`"inline"` |
`"labelled"`: the decision call shows each existing lesson's code-computed main rule, statement and
detail on labelled lines) let a different judge model run from config alone. The defaults are the validated Qwen3.8 judge's request exactly (`"current"` rules). Since
2026-11-05 production runs a trial of `judge_filing_rules = "v2"` with `chat_short_max_tokens = 6144`
(set in config; rollback = delete the two lines); v2 becomes the code default only after a blind
review. See [`INFRA.md`](./INFRA.md) for details.
**Lesson template (always on).** Every save and merge (judge, CLI, MCP) stores a lesson's
`statement` as one sentence, the reusable rule, without a `[type]` tag; any further sentences move
to the front of `detail` (`qmx/lesson_text.py`). Rows saved earlier keep their text until their next
update, and `revert-learning` restores a revision exactly.
**Hooks** (optional, wire in `settings.json` like the `Stop`/capture hook) — inject at start,
consolidate at end (the latter runs detached so it never blocks session close):
```json
{ "hooks": {
"SessionStart": [{ "matcher": "startup", "hooks": [{ "type": "command", "command": "qmx session-start" }] }],
"SessionEnd": [{ "hooks": [{ "type": "command", "command": "qmx session-end" }] }]
} }
```
Injection is **scope-keyed** (the current repo, resolved from `cwd` via `git remote`, + global) and
budgeted to the 10k-char `additionalContext` cap — so one repo's lessons never leak into another's
session. Promoted lessons live in an **isolated per-repo store** (`~/.qmx/memory/<owner__repo>/`).
**Excluding automated sessions** — agents that run headless in a known folder (e.g. Memoir's
after-the-call Summary agent, which runs in `~/memoir/<call>/`) still fire the user's hooks. List
those folders in `~/.qmx/config.toml` and `qmx capture` / `qmx session-end` ignore any session whose
workspace folder is inside one (env override: `QMX_CAPTURE_EXCLUDE_ROOTS`, comma-separated):
```toml
capture_exclude_roots = ["~/memoir"]
```
**Setting it up** — point qmx at the judge (the `chat_*` lines above), wire the hooks, and
(optionally) schedule the nightly sweep: see step 8 of [`QUICKSTART.md`](./QUICKSTART.md), which
points at [`INFRA.md`](./INFRA.md) for the running services (the vLLM judge on the Spark + the
launchd agents).
## Parked items ("park this, come back later")
Mid-chat ideas you want to set aside without derailing the current task. Tell Claude *"park this"*
(→ `mcp__qmx__park`) or use the CLI; each item is a markdown file under `~/.qmx/parked/`, scoped to
the current repo (or global). Items are surfaced **only when you ask** — there is no session-start
nudge.
```bash
qmx park "auto-suggest closing items from commits" --why "Stop hook could match commits"
qmx park --global "try qwen3-embedding 4b"
qmx parked # open items for this repo + global (--all: every repo)
qmx parked "embedding" # rank by meaning
qmx unpark 3 --note "landed in #30" # done -> archived, never deleted (--drop: abandoned)
qmx reopen 3
qmx parked --stale # untouched > 30 days: `qmx keep <id>` or `qmx unpark <id> --drop`
```
The files are the source of truth; open items are also embedded (`kind=parked`) for semantic
listing and a "similar item" hint on park. Parking works with the Spark off — `qmx refresh` (or
`qmx parked --sync`) indexes anything saved meanwhile. Design: [`plan/qmx-parked.md`](./plan/qmx-parked.md).
## Status
Capabilities #1–#3 implemented: code search, chat recall, and the **learnings/consolidation** tier
(schema v6; `add-learning`/`lessons`/`promote`, in-place `update-learning` with revision
history + `revert-learning`, `deprecate-learning`/`restore-learning`, a `consolidate` judge (Qwen3.8
on vLLM) that can new/update/supersede/deprecate/drop behind merge, retirement and near-duplicate
guardrails, and SessionStart/SessionEnd hooks). qmx
indexes your Claude Code **conversation history** alongside code — `qmx backfill-chats` for past
transcripts and a `Stop` hook (`qmx capture`) for live turns, recalled via `mcp__qmx__recall`. Built
on the resident **MCP server**, tree-sitter chunking, incremental indexing, and hybrid **vector +
BM25 → RRF** search — with an optional **Qwen3-Reranker** stage (llama.cpp on the Spark GPU; see
[`plan/qmx-ml-notes.md`](./plan/qmx-ml-notes.md)). See [`plan/`](./plan) for the design.
Because the index is local, **search keeps working when the embedding backend is off** — qmx
degrades to keyword-only (BM25) results and flags them, rather than failing. See *When the Spark is
off* in [`QUICKSTART.md`](./QUICKSTART.md).
## Development
Python 3.12 + [`uv`](https://docs.astral.sh/uv/). The model backends run on the DGX Spark in prod —
Ollama for embeddings (`QMX_OLLAMA_URL`), vLLM for the judge (`chat_url`); see
[`plan/qmx-deployment.md`](./plan/qmx-deployment.md) and [`INFRA.md`](./INFRA.md).
```bash
uv sync # create the venv, install qmx + dev tools
uv run pytest # unit tests (live-Ollama tests skip when unreachable)
uv run ruff check . && uv run ruff format --check .
uv run qmx status # resolved config + index stats
# index code and search it (needs a running Ollama backend):
export QMX_OLLAMA_URL=http://spark-1.local:11434
uv run qmx index ~/some/repo
uv run qmx query "where is the retry logic" -k 5
uv run qmx watch ~/some/repo # keep the index live as files change
uv run qmx gc # purge tombstoned chunks
# run the live embed round-trip against the Spark:
uv run pytest -m integration
```
## Use from Claude Code (MCP)
Run the resident server (it owns the index + background loops). In the **primary setup** it runs
**on your Mac**, serving the Mac's `~/.qmx/index.db` — kept up by the launchd agent `com.qmx.serve`,
next to `com.qmx.watch` and the nightly `com.qmx.consolidate` (see [`INFRA.md`](./INFRA.md)):
```bash
uv run qmx serve # HTTP on 127.0.0.1:8765/mcp by default
```
Register it with Claude Code — either the CLI:
```bash
claude mcp add --transport http qmx http://127.0.0.1:8765/mcp
```
…or in `settings.json`:
```json
{ "mcpServers": { "qmx": { "type": "http", "url": "http://127.0.0.1:8765/mcp" } } }
```
**Alternative: a Spark-hosted server** — one shared index served to several machines (on the Spark
it runs as the `qmx-mcp.service` systemd user unit; see [`INFRA.md`](./INFRA.md)). Bind it to the
LAN and point each client at the Spark instead:
```bash
QMX_MCP_HOST=0.0.0.0 uv run qmx serve # on the Spark
claude mcp add --transport http qmx http://spark-1.local:8765/mcp # on each client
```
The tools then appear as `mcp__qmx__query`, `mcp__qmx__search_code`, `mcp__qmx__recall`,
`mcp__qmx__meetings`, `mcp__qmx__lessons`, `mcp__qmx__add_learning`, `mcp__qmx__update_learning`,
`mcp__qmx__deprecate_learning`, `mcp__qmx__restore_learning`, `mcp__qmx__learning_history`,
`mcp__qmx__revert_learning`, `mcp__qmx__park`,
`mcp__qmx__list_parked`, `mcp__qmx__unpark`, `mcp__qmx__resume_parked`, `mcp__qmx__get`,
`mcp__qmx__status`.
(`qmx serve --transport stdio` is available for a local, single-client setup.)
## License
MIT — see [LICENSE](./LICENSE).
TDQS
Scored across 17 tools
The learning lifecycle tools (add/update/deprecate/restore/history/revert) and the parking tools (park/list_parked/unpark/resume_parked) are cleanly separated by distinct verbs. The main overlap is that `query` is a superset covering code, chats, meetings and lessons, so `search_code`, `recall`, `meetings` and `lessons` can look redundant against it, and `lessons(include_retired=True)` versus `learning_history` needs the descriptions to disambiguate. Descriptions do carry enough signal to pick correctly in practice.
Most learning and parking tools follow a clean verb_noun pattern (add_learning, deprecate_learning, list_parked, resume_parked), but the retrieval tools break it with bare nouns and vague verbs (query, recall, lessons, meetings, get, status). `search_code` mixes noun-then-verb, adding a second convention to the set. Still readable, but not a single predictable pattern.
17 tools is at the upper edge of comfortable but each one maps to a real operation; the seven-tool learning lifecycle is granular yet all roles are distinct. The surface is scoped to three coherent areas (search/retrieval, learnings, parking) rather than sprawling. Slightly heavy but nothing feels gratuitous.
Learnings have full lifecycle coverage (create, update, deprecate, restore, history, revert) and parking has create/list/resolve/resume, plus retrieval has `get` and `status` to close the loop on results. Minor gaps: archived parked items can only be reopened via the CLI (`qmx reopen`, referenced but not exposed as a tool), and there is no tool to index new content, only to search it.