qmx
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@qmx where does the launcher logic live in my codebase?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 embeddings, the
Qwen reranker/judge models and
sqlite-vec. Derived from
tobi/qmd (MIT).
Start here: QUICKSTART.md (install → index → use from Claude Code) · INFRA.md (the model backends — Ollama, vLLM, llama.cpp — + services) · 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.
Related MCP server: memento
Architecture
The big picture — three pieces:
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"| CDGX 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-vecvectors + 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:
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" --> DBQuerying — only the query string is embedded on the backend; vector + keyword search and ranking are entirely local:
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" --> SRChat 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:
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 --> RCKeeping 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:
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).
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:
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" .-> TOPKSee plan/qmx-ml-notes.md (TD-1) for how the reranker is built and served.
Meetings (Memoir calls)
qmx also indexes 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.
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 toolA 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 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:
# ~/.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"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 memoryA lesson can also be wrong, so it can be corrected or retired rather than only buried under a lower weight:
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
importanceis a ranking weight in 0..1, not a 1–5 rating: it enters the blend as0.3 × importanceagainst 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 --applyrepairs 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
drops 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 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):
{ "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):
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, which
points at 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.
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.
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). See 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.
Development
Python 3.12 + 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 and INFRA.md.
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 integrationUse 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):
uv run qmx serve # HTTP on 127.0.0.1:8765/mcp by defaultRegister it with Claude Code — either the CLI:
claude mcp add --transport http qmx http://127.0.0.1:8765/mcp…or in settings.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). Bind it to the
LAN and point each client at the Spark instead:
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 clientThe 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.
Available Tools
17 toolsadd_learningA
Record a durable lesson so future sessions recall it. type: decision|mistake|howto.
``statement`` is the lesson in one crisp sentence; ``detail`` the why/correction/better-way;
``scope`` the repo it applies to as its git remote ``owner/repo`` (e.g. ``the-dsvolk/qmx``)
— omit it for a global lesson. A bare repo name is mapped to the one known ``owner/repo``
it matches, and rejected with the options if it matches none or several.
Inputs: type (required), statement (required), scope, topic, +2 more.
deprecate_learningA
Soft-retire a lesson: it stops being recalled, but is kept with a breadcrumb.
The right tool when a lesson turned out to be wrong or went stale — reversible, and
preferable to leaving it firing at a lower weight. ``reason`` records why; ``superseded_by``
points at the lesson that replaces it (omit when nothing does). Retired lessons are visible
again via ``lessons(..., include_retired=True)`` and revivable with ``restore_learning``.
Inputs: learning_id (required), reason, superseded_by. Returns: result
getA
Fetch a single chunk's full text + location by chunk_id (from a prior result).
Inputs: chunk_id (required). Returns: result
learning_historyA
A lesson's earlier versions, newest first — every in-place update keeps the old text.
Use it when a lesson looks wrong or off-topic (e.g. a bad consolidation merge overwrote it),
then ``revert_learning`` to put a previous version back. ``None`` if the lesson is unknown.
Inputs: learning_id (required). Returns: result
lessonsA
Recall distilled lessons — decisions, mistakes+corrections, how-tos learned before.
Higher-signal than raw chat recall: ranked by relevance × importance × recency, each with
citations. ``type`` filters ``decision`` | ``mistake`` | ``howto``. ``include_retired`` also
returns deprecated/superseded lessons (hidden by default) with their ``deprecated_reason``
and ``superseded_by`` breadcrumb — use it to check *why* something was retired.
Inputs: text (required), k, type, include_retired. Returns: result
list_parkedA
List parked items — only call when the user asks ("what did I park?", "parked items").
Scoped to ``cwd``'s repo (or ``scope``) plus global items; with neither, every scope.
``status``: ``open`` (default) | ``done`` | ``dropped`` | ``closed`` | ``all``. ``query``
ranks by meaning. ``stale_only`` keeps items untouched long enough to need a keep-or-drop
review (each item also carries a ``stale`` flag).
Inputs: k, cwd, query, scope, +3 more. Returns: result
meetingsB
Search recorded meetings (Memoir calls) — transcripts, summaries, notes and prep.
Each hit names its call: ``meeting`` (folder ``YYYY-MM-DD_<name>``), ``date``, ``file``
(``transcript.txt`` | ``summary.md`` | ``notes.md`` | ``prep.md``), plus ``symbol``
(transcript speakers + time range, or the summary section) and the snippet.
Inputs: text (required), k. Returns: result
parkA
Park an idea to come back to later — when the user says "park this", "remind me later", "let's come back to that", or mid-task surfaces a side idea not worth derailing for.
``text`` is the idea in one line; ``why`` the context needed to pick it up cold (what
prompted it, what to check). Pass ``cwd`` (your working directory) so the item is scoped
to that repo, or ``scope`` (``owner/repo``) directly; omit both for a global item.
``session`` optionally records the transcript it came from. Returns the stored item;
``similar`` lists open items that look alike (mention them — it may be a duplicate).
Inputs: text (required), cwd, why, scope, +1 more.
queryB
Semantic + keyword search over the qmx knowledge base (code, docs, chats, learnings).
Returns ranked hits with ``path``, ``start_line``/``end_line``, ``symbol``, ``score`` and a
text snippet. Optional ``kind`` filters to ``code`` | ``doc`` | ``chat`` | ``learning`` |
``meeting``.
Inputs: text (required), k, kind. Returns: result
recallB
Recall past Claude Code conversations — semantic search over indexed chat turns.
Returns matching turns with their transcript path, line, and role (user/assistant).
Inputs: text (required), k. Returns: result
restore_learningA
Un-retire a lesson deprecated by mistake — clears the retire/supersede markers.
Inputs: learning_id (required). Returns: result
resume_parkedB
Pick a parked item back up: the item plus the past chat turns that best match it, so the original context is restored, not just the one-line note.
Inputs: item_id (required), k.
revert_learningA
Restore a lesson from its history; revision_id defaults to the latest revision.
The current text is saved as a new revision first, so a revert can itself be reverted.
Returns the restored lesson, or ``None`` if ``learning_id`` does not exist.
Inputs: learning_id (required), revision_id. Returns: result
search_codeB
Search only code by meaning; returns file:line locations with snippets.
Inputs: text (required), k. Returns: result
statusB
Index stats (documents/chunks/mentions) and Ollama backend health.
Inputs: no named parameters.
unparkA
Close a parked item once the work is done (done) or abandoned (dropped).
``note`` records the resolution (what was done, or why it was dropped). The item is
archived, not deleted — ``qmx reopen <id>`` brings it back.
Inputs: item_id (required), note, status.
update_learningA
Fix an existing lesson in place — correct its wording or lower its importance.
Prefer this over adding a near-duplicate when a lesson is merely wrong, stale in detail, or
over-weighted; use ``deprecate_learning`` when it should stop firing altogether. Omitted
fields are left unchanged (to *clear* one: ``qmx update-learning --clear-detail``).
Returns the updated lesson, or ``None`` if ``learning_id`` does not exist.
Inputs: learning_id (required), type, scope, topic, +3 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Related MCP Servers
- AlicenseAqualityDmaintenanceA universal, local-first MCP hub that indexes personal files (documents, code, etc.) and provides private semantic search via hybrid dense+BM25 retrieval, enabling agents like Claude Desktop to query your data without sending it to the cloud.176MIT
- AlicenseNot gradedqualityAmaintenanceProvides persistent memory for AI coding agents via MCP, enabling agents to store and semantically recall facts, events, and lessons across sessions, all running locally without cloud dependencies.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides local-first, cross-session memory for Claude Code, enabling semantic search across past sessions to retrieve procedures, decisions, or answers without exposing secrets.Apache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables AI agents to query a local, hybrid-searchable second brain over scattered notes, documents, and chat logs with section-level citations. It exposes retrieval tools, resources, and prompts through MCP so hosts like Claude Desktop, Cursor, and Cline can use the indexed knowledge.-