qmd Memory Stack — RAG Local com GPU para Agentes de Código
mairp/qmd-memory-stack
Memória RAG privada e acelerada por GPU para agentes de codificação
Ver no GitHubServidor MCP que fornece memória hierárquica acelerada por GPU para agentes de código (Claude Code, OpenClaw) usando embeddings GGUF locais (Qwen3) e recuperação híbrida semântica+keyword sem dependências em cloud. Implementa 3 camadas: índice sempre carregado (MEMORY.md), tópicos sob demanda e sessões opcionais, com injeção automática de contexto via hooks e ferramentas MCP.
Instalação
npx convez-ai mairp/qmd-memory-stack1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Agentes de IA com contexto persistente offline (Claude Code, OpenClaw)
- Recuperação de conhecimento em projetos de codificação sem nuvem
- Aceleração GPU de busca semântica (19× via Intel/NVIDIA/AMD Vulkan)
Veredito

Solução técnica sólida para teams que precisam de RAG privado e low-latency em agentes de código; arquitetura clara com 3 tiers e suporte GPU maturo. Curva de aprendizado íngreme (Shell, embeddings locais, GPU tunning) mas bem documentada; não é ferramenta plug-and-play.
README
A tradução para o português deste README ainda está na fila.
qmd-memory-stack
Local, GPU-accelerated RAG memory for coding agents — Claude Code
and OpenClaw — built on qmd
with fully local Qwen3 GGUF models (no cloud embeddings) and optional Intel/NVIDIA GPU offload.
It gives an agent a hierarchical, retrieval-augmented memory:
- L1 —
MEMORY.md: a lean always-loaded index of one-line facts. - L2 — topic leaf files (
infra/,projects/, …): retrieved on demand via semantic + keyword search. - L3 — sessions (optional): long-form transcripts.
Recall is wired into Claude Code through hooks (auto-injected on every prompt) and an MCP server (on-demand deep recall), and can share OpenClaw's memory read-only so both agents see the same facts.
Why
- Private & offline: embeddings/expansion/reranking run on local GGUF models (Qwen3-Embedding-0.6B, a 1.7B query-expansion model, Qwen3-Reranker-0.6B). Nothing leaves the box. Works with providers that have no embeddings endpoint (e.g. Core42 Compass).
- Fast where it matters: the always-on auto-inject path is pure BM25 (~0.4s, no model load); heavier semantic/hybrid recall is on-demand. On an Intel Arc iGPU via Vulkan, full hybrid query went 110.7s → 5.7s (~19×) — see docs/OPTIMIZATIONS.md.
- Fail-open: memory recall never blocks or breaks a turn (hard timeouts, swallow errors,
exit 0).
Quickstart
git clone https://github.com/mairp/qmd-memory-stack.git
cd qmd-memory-stack
./install.sh # auto-detects OS, qmd, GPU, memory dir, OpenClaw
# then start a NEW Claude Code session (loads the hooks + MCP server)
Prerequisites on the target machine: node and the qmd binary on PATH
(npm i -g @tobilu/qmd), and Claude Code. OpenClaw is optional (auto-detected for the read-only share).
Useful flags:
./install.sh --dry-run # show everything it would do, change nothing
./install.sh --no-gpu # force CPU mode
./install.sh --memory-dir DIR # override the Claude auto-memory dir
./install.sh --with-openclaw # also let OpenClaw recall Claude's memory (symmetric share)
./uninstall.sh # clean revert (your memory notes are NOT deleted)
Support matrix
| Memory stack | GPU offload | |
|---|---|---|
| OS | Debian/Ubuntu (apt), Fedora (dnf), Arch (pacman), openSUSE (zypper) | same |
| Intel iGPU (Arc/Xe) | ✅ | ✅ Vulkan (Mesa ANV) — tested |
| NVIDIA | ✅ | ⚠️ CUDA via node-llama-cpp — implemented, untested |
| AMD | ✅ | ✅ Vulkan (Mesa RADV) — best-effort |
| CPU-only | ✅ | n/a (QMD_FORCE_CPU=1) |
Docs
- docs/ARCHITECTURE.md — how the memory layers, RAG modes, and hooks fit together.
- docs/TUTORIAL.md — understand it, install it, verify it, troubleshoot it.
- docs/GPU-VULKAN.md — GPU offload (Intel/NVIDIA/AMD), the shared-RAM model, reverting.
- docs/OPTIMIZATIONS.md — the full tuning changelog + benchmark numbers.
How it works (one diagram)
user prompt ──► UserPromptSubmit hook ──► claude-recall.sh -m fast ──► qmd search (BM25, ~0.4s)
└─► <memory-recall> injected
on demand ──► MCP "qmd" tools / claude-recall.sh -m deep|query ─────► qmd vector / hybrid (+GPU)
memory write ─► PostToolUse hook ───────► reindex.sh (flock) ─────────► qmd update && embed
session start ► SessionStart hook ──────► refresh GPU flag + background reindex
qmd index (sqlite, FTS5 + sqlite-vec) ◄── collections: claude-memory + openclaw-memory (read-only)
models: Qwen3-Embedding-0.6B · qmd-query-expansion-1.7B · Qwen3-Reranker-0.6B (local GGUF, CPU/GPU)
License
MIT — see LICENSE. No secrets or host-specific credentials are included; configure via flags
or a local .env (see .env.example).