QMD-Speicher-Engine

QMD ist ein Local-first-Such-Sidecar, der neben OpenClaw läuft. Es kombiniert BM25, Vektorsuche und Reranking in einer einzelnen Binärdatei und kann Inhalte über Ihre Workspace-Speicherdateien hinaus indexieren.

Was es gegenüber der integrierten Lösung hinzufügt

• Reranking und Abfrageerweiterung für bessere Trefferquote.
• Zusätzliche Verzeichnisse indexieren -- Projektdokumentation, Teamnotizen, alles auf der Festplatte.
• Sitzungstranskripte indexieren -- frühere Unterhaltungen wiederfinden.
• Vollständig lokal -- läuft mit dem offiziellen llama.cpp-Provider-Plugin und lädt GGUF-Modelle automatisch herunter.
• Automatischer Fallback -- wenn QMD nicht verfügbar ist, fällt OpenClaw nahtlos auf die integrierte Engine zurück.

Erste Schritte

Voraussetzungen

• Installieren Sie QMD: npm install -g @tobilu/qmd oder bun install -g @tobilu/qmd
• SQLite-Build, der Erweiterungen erlaubt (brew install sqlite unter macOS).
• QMD muss im PATH des Gateways liegen.
• macOS und Linux funktionieren ohne zusätzliche Einrichtung. Windows wird am besten über WSL2 unterstützt.

Aktivieren

{  memory: {    backend: "qmd",  },}

OpenClaw erstellt ein eigenständiges QMD-Home unter ~/.openclaw/agents/<agentId>/qmd/ und verwaltet den Sidecar-Lebenszyklus automatisch -- Collections, Updates und Embedding-Läufe werden für Sie übernommen. Es bevorzugt aktuelle QMD-Collection- und MCP-Abfrageformen, fällt bei Bedarf aber weiterhin auf alternative Collection-Pattern-Flags und ältere MCP-Tool-Namen zurück. Die Abstimmung beim Start erstellt außerdem veraltete verwaltete Collections wieder mit ihren kanonischen Patterns, wenn noch eine ältere QMD-Collection mit demselben Namen vorhanden ist.

Funktionsweise des Sidecars

• OpenClaw erstellt Collections aus Ihren Workspace-Speicherdateien und allen konfigurierten memory.qmd.paths und führt dann qmd update aus, wenn der QMD-Manager geöffnet wird, sowie danach regelmäßig (standardmäßig alle 5 Minuten). Diese Aktualisierungen laufen über QMD-Subprozesse, nicht über ein dateisystemweites Crawling im Prozess. Semantische Modi führen außerdem qmd embed aus.
• Die standardmäßige Workspace-Collection verfolgt MEMORY.md plus den Baum memory/. Kleingeschriebenes memory.md wird nicht als Root-Speicherdatei indexiert.
• Der eigene Scanner von QMD ignoriert versteckte Pfade und übliche Abhängigkeits- oder Build- Verzeichnisse wie .git, .cache, node_modules, vendor, dist und build. Der Gateway-Start initialisiert QMD standardmäßig nicht, sodass ein Kaltstart weder die Speicherlaufzeit importiert noch den langlebigen Watcher erstellt, bevor Speicher erstmals verwendet wird.
• Wenn Sie QMD trotzdem beim Gateway-Start initialisieren möchten, setzen Sie memory.qmd.update.startup auf idle oder immediate. Mit memory.qmd.update.onBoot: true führt der Start die anfängliche Aktualisierung aus. Mit onBoot: false überspringt der Start diese sofortige Aktualisierung, öffnet aber dennoch den langlebigen Manager, wenn Update- oder Embed-Intervalle konfiguriert sind, damit QMD seinen regulären Watcher und seine Timer besitzen kann.
• Suchen verwenden den konfigurierten searchMode (Standard: search; unterstützt auch vsearch und query). search ist nur BM25, daher überspringt OpenClaw in diesem Modus semantische Vektor-Bereitschaftsprüfungen und Embedding-Wartung. Wenn ein Modus fehlschlägt, versucht OpenClaw es erneut mit qmd query.
• Wenn searchMode auf query steht, setzen Sie memory.qmd.rerank auf false, um QMDs hybriden Abfragepfad ohne Reranker zu verwenden. OpenClaw übergibt --no-rerank an den direkten QMD-CLI-Pfad und rerank: false an QMDs MCP-Abfragetool. Diese Option erfordert QMD 2.1 oder neuer.
• Bei QMD-Versionen, die Multi-Collection-Filter ausweisen, fasst OpenClaw Collections aus derselben Quelle in einem QMD-Suchaufruf zusammen. Ältere QMD-Versionen behalten den kompatiblen Fallback pro Collection.
• Wenn QMD vollständig fehlschlägt, fällt OpenClaw auf die integrierte SQLite-Engine zurück. Wiederholte Versuche in Chat-Turns legen nach einem Öffnungsfehler kurz eine Pause ein, damit eine fehlende Binärdatei oder beschädigte Sidecar-Abhängigkeit keinen Wiederholungssturm erzeugt; openclaw memory status und einmalige CLI-Prüfungen prüfen QMD weiterhin direkt erneut.

Suchleistung und Kompatibilität

OpenClaw hält den QMD-Suchpfad mit aktuellen und älteren QMD-Installationen kompatibel.

Beim Start prüft OpenClaw den Hilfetext des installierten QMD einmal pro Manager. Wenn die Binärdatei Unterstützung für mehrere Collection-Filter ausweist, durchsucht OpenClaw alle Collections derselben Quelle mit einem Befehl:

qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main

Das vermeidet, für jede Durable-Memory-Collection einen eigenen QMD-Subprozess zu starten. Sitzungstranskript-Collections bleiben in ihrer eigenen Quellgruppe, sodass gemischte Suchen über memory + sessions dem Ergebnis-Diversifizierer weiterhin Eingaben aus beiden Quellen liefern.

Ältere QMD-Builds akzeptieren nur einen Collection-Filter. Wenn OpenClaw einen dieser Builds erkennt, behält es den Kompatibilitätspfad bei und durchsucht jede Collection separat, bevor Ergebnisse zusammengeführt und dedupliziert werden.

Um den installierten Vertrag manuell zu prüfen, führen Sie aus:

qmd --help | grep -i collection

Die aktuelle QMD-Hilfe sagt, dass Collection-Filter eine oder mehrere Collections adressieren können. Ältere Hilfe beschreibt üblicherweise eine einzelne Collection.

Modellüberschreibungen

QMD-Modellumgebungsvariablen werden unverändert aus dem Gateway-Prozess durchgereicht, sodass Sie QMD global abstimmen können, ohne neue OpenClaw-Konfiguration hinzuzufügen:

export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"

Nachdem Sie das Embedding-Modell geändert haben, führen Sie die Embeddings erneut aus, damit der Index zum neuen Vektorraum passt.

Zusätzliche Pfade indexieren

Richten Sie QMD auf zusätzliche Verzeichnisse aus, um sie durchsuchbar zu machen:

{  memory: {    backend: "qmd",    qmd: {      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],    },  },}

Snippets aus zusätzlichen Pfaden erscheinen in Suchergebnissen als qmd/<collection>/<relative-path>. memory_get versteht dieses Präfix und liest aus dem richtigen Collection-Root.

Sitzungstranskripte indexieren

Aktivieren Sie die Sitzungsindexierung, um frühere Unterhaltungen wiederzufinden. QMD benötigt sowohl die allgemeine memorySearch-Sitzungsquelle als auch den QMD-Transkriptexporter:

{  agents: {    defaults: {      memorySearch: {        experimental: { sessionMemory: true },        sources: ["memory", "sessions"],      },    },  },  memory: {    backend: "qmd",    qmd: {      sessions: { enabled: true },    },  },}

Transkripte werden als bereinigte User/Assistant-Turns in eine dedizierte QMD-Collection unter ~/.openclaw/agents/<id>/qmd/sessions/ exportiert. Nur memorySearch.experimental.sessionMemory zu setzen, exportiert keine Transkripte nach QMD.

Sitzungstreffer werden weiterhin nach tools.sessions.visibility gefiltert. Die standardmäßige Sichtbarkeit tree legt keine unzusammenhängenden Sitzungen desselben Agenten offen. Wenn eine vom Gateway disponierte Sitzung aus einer separaten DM-Sitzung wiederauffindbar sein soll, setzen Sie tools.sessions.visibility: "agent" bewusst.

Suchumfang

Standardmäßig werden QMD-Suchergebnisse in direkten Sitzungen und Kanalsitzungen angezeigt (nicht in Gruppen). Konfigurieren Sie memory.qmd.scope, um dies zu ändern:

{  memory: {    qmd: {      scope: {        default: "deny",        rules: [{ action: "allow", match: { chatType: "direct" } }],      },    },  },}

Wenn der Scope eine Suche verweigert, protokolliert OpenClaw eine Warnung mit dem abgeleiteten Kanal und Chattyp, damit leere Ergebnisse leichter zu debuggen sind.

Zitationen

Wenn memory.citations auf auto oder on steht, enthalten Such-Snippets eine Fußzeile Source: <path#line>. Setzen Sie memory.citations = "off", um die Fußzeile wegzulassen und den Pfad intern dennoch an den Agenten zu übergeben.

Einsatzempfehlung

Wählen Sie QMD, wenn Sie Folgendes benötigen:

• Reranking für höherwertige Ergebnisse.
• Suche in Projektdokumentation oder Notizen außerhalb des Workspace.
• Wiederfinden früherer Sitzungsunterhaltungen.
• Vollständig lokale Suche ohne API-Schlüssel.

Für einfachere Setups funktioniert die integrierte Engine gut ohne zusätzliche Abhängigkeiten.

Fehlerbehebung

QMD nicht gefunden? Stellen Sie sicher, dass die Binärdatei im PATH des Gateways liegt. Wenn OpenClaw als Dienst läuft, erstellen Sie einen Symlink: sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd.

Wenn qmd --version in Ihrer Shell funktioniert, OpenClaw aber weiterhin spawn qmd ENOENT meldet, hat der Gateway-Prozess wahrscheinlich einen anderen PATH als Ihre interaktive Shell. Legen Sie die Binärdatei explizit fest:

{  memory: {    backend: "qmd",    qmd: {      command: "/absolute/path/to/qmd",    },  },}

Verwenden Sie command -v qmd in der Umgebung, in der QMD installiert ist, und prüfen Sie dann erneut mit openclaw memory status --deep.

Erste Suche sehr langsam? QMD lädt GGUF-Modelle bei der ersten Verwendung herunter. Wärmen Sie mit qmd query "test" unter Verwendung derselben XDG-Verzeichnisse vor, die OpenClaw nutzt.

Viele QMD-Subprozesse während der Suche? Aktualisieren Sie QMD, wenn möglich. OpenClaw verwendet nur dann einen Prozess für Multi-Collection-Suchen derselben Quelle, wenn das installierte QMD Unterstützung für mehrere -c-Filter ausweist; andernfalls behält es aus Korrektheitsgründen den älteren Fallback pro Collection bei.

Nur-BM25-QMD versucht trotzdem, llama.cpp zu bauen? Setzen Sie memory.qmd.searchMode = "search". OpenClaw behandelt diesen Modus als rein lexikalisch, führt keine QMD-Vektorstatusprüfungen oder Embedding-Wartung aus und überlässt semantische Bereitschaftsprüfungen vsearch- oder query-Setups.

Suche läuft in ein Timeout? Erhöhen Sie memory.qmd.limits.timeoutMs (Standard: 4000 ms). Setzen Sie den Wert für langsamere Hardware auf 120000.

Leere Ergebnisse in Gruppenchats? Prüfen Sie memory.qmd.scope -- die Standardeinstellung erlaubt nur direkte Sitzungen und Kanalsitzungen.

Root-Speichersuche wurde plötzlich zu breit? Starten Sie das Gateway neu oder warten Sie auf die nächste Abstimmung beim Start. OpenClaw erstellt veraltete verwaltete Collections wieder mit den kanonischen Patterns MEMORY.md und memory/, wenn es einen gleichnamigen Konflikt erkennt.

Workspace-sichtbare temporäre Repos verursachen ENAMETOOLONG oder defekte Indexierung? Die QMD-Traversierung folgt derzeit dem Verhalten des zugrunde liegenden QMD-Scanners statt den integrierten Symlink-Regeln von OpenClaw. Legen Sie temporäre Monorepo-Checkouts in versteckten Verzeichnissen wie .tmp/ oder außerhalb indexierter QMD-Roots ab, bis QMD zyklussichere Traversierung oder explizite Ausschlusssteuerungen bereitstellt.

Konfiguration

Die vollständige Konfigurationsoberfläche (memory.qmd.*), Suchmodi, Aktualisierungsintervalle, Scope-Regeln und alle weiteren Stellschrauben finden Sie in der Referenz zur Speicherkonfiguration.

Verwandte Themen

• Speicherübersicht
• Integrierte Speicher-Engine
• Honcho-Speicher