Skip to main content
Glama

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"| 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:

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:

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:

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:

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" .-> TOPK

See 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 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 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 memory

A 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

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 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 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):

uv run qmx serve                       # HTTP on 127.0.0.1:8765/mcp by default

Register 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 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.

Available Tools

17 tools
add_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

    A3.5/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      17
      6
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Provides 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -