English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Sessions and memory

Mecanismo de memória QMD

QMD é um sidecar de busca que prioriza o local e roda junto com o OpenClaw. Ele combina BM25, busca vetorial e reclassificação em um único binário, e pode indexar conteúdo além dos arquivos de memória do seu workspace.

O que ele adiciona em relação ao integrado

  • Reclassificação e expansão de consulta para melhor recuperação.
  • Indexação de diretórios extras -- documentação do projeto, notas da equipe, qualquer coisa em disco.
  • Indexação de transcrições de sessões -- recupere conversas anteriores.
  • Totalmente local -- roda com o pacote de runtime opcional node-llama-cpp e baixa modelos GGUF automaticamente.
  • Fallback automático -- se o QMD estiver indisponível, o OpenClaw volta para o mecanismo integrado sem interrupção.

Primeiros passos

Pré-requisitos

  • Instale o QMD: npm install -g @tobilu/qmd ou bun install -g @tobilu/qmd
  • Build do SQLite que permite extensões (brew install sqlite no macOS).
  • O QMD deve estar no PATH do Gateway.
  • macOS e Linux funcionam sem configuração extra. No Windows, o melhor suporte é via WSL2.

Habilitar

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

O OpenClaw cria uma home autônoma do QMD em ~/.openclaw/agents/<agentId>/qmd/ e gerencia automaticamente o ciclo de vida do sidecar -- coleções, atualizações e execuções de embedding são tratadas por você. Ele prefere os formatos atuais de coleção do QMD e consulta MCP, mas ainda recorre a flags alternativas de padrão de coleção e nomes mais antigos de ferramentas MCP quando necessário. A reconciliação no boot também recria coleções gerenciadas obsoletas de volta para seus padrões canônicos quando uma coleção QMD mais antiga com o mesmo nome ainda está presente.

Como o sidecar funciona

  • O OpenClaw cria coleções a partir dos seus arquivos de memória do workspace e de quaisquer memory.qmd.paths configurados, depois executa qmd update quando o gerenciador QMD é aberto e periodicamente depois disso (padrão: a cada 5 minutos). Essas atualizações rodam por subprocessos do QMD, não por uma varredura de sistema de arquivos em processo. Modos semânticos também executam qmd embed.
  • A coleção padrão do workspace acompanha MEMORY.md mais a árvore memory/. memory.md em minúsculas não é indexado como arquivo de memória raiz.
  • O scanner do próprio QMD ignora caminhos ocultos e diretórios comuns de dependências/build, como .git, .cache, node_modules, vendor, dist e build. A inicialização do Gateway não inicializa o QMD por padrão, então o boot frio evita importar o runtime de memória ou criar o watcher de longa duração antes de a memória ser usada pela primeira vez.
  • Se você quiser uma atualização na inicialização do Gateway mesmo assim, defina memory.qmd.update.startup como idle ou immediate. A atualização de inicialização opcional usa um caminho de subprocesso QMD de execução única em vez de criar o watcher completo de longa duração em processo.
  • As buscas usam o searchMode configurado (padrão: search; também oferece suporte a vsearch e query). search é somente BM25, então o OpenClaw pula sondagens de prontidão vetorial semântica e manutenção de embeddings nesse modo. Se um modo falhar, o OpenClaw tenta novamente com qmd query.
  • Com versões do QMD que anunciam filtros de múltiplas coleções, o OpenClaw agrupa coleções da mesma origem em uma única invocação de busca do QMD. Versões mais antigas do QMD mantêm o fallback compatível por coleção.
  • Se o QMD falhar completamente, o OpenClaw volta para o mecanismo SQLite integrado. Tentativas repetidas em turnos de chat aguardam brevemente após uma falha de abertura para que um binário ausente ou dependência quebrada do sidecar não crie uma tempestade de retentativas; openclaw memory status e sondagens únicas da CLI ainda verificam o QMD diretamente.

Desempenho de busca e compatibilidade

O OpenClaw mantém o caminho de busca do QMD compatível com instalações atuais e antigas do QMD.

Na inicialização, o OpenClaw verifica uma vez por gerenciador o texto de ajuda do QMD instalado. Se o binário anunciar suporte a múltiplos filtros de coleção, o OpenClaw busca em todas as coleções da mesma origem com um comando:

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

Isso evita iniciar um subprocesso QMD para cada coleção de memória durável. Coleções de transcrições de sessão permanecem em seu próprio grupo de origem, então buscas mistas memory + sessions ainda fornecem ao diversificador de resultados entradas de ambas as origens.

Builds mais antigos do QMD aceitam apenas um filtro de coleção. Quando o OpenClaw detecta um desses builds, ele mantém o caminho de compatibilidade e busca em cada coleção separadamente antes de mesclar e deduplicar resultados.

Para inspecionar manualmente o contrato instalado, execute:

qmd --help | grep -i collection

A ajuda atual do QMD diz que filtros de coleção podem mirar uma ou mais coleções. A ajuda mais antiga geralmente descreve uma única coleção.

Substituições de modelo

As variáveis de ambiente de modelo do QMD são repassadas sem alterações pelo processo do Gateway, então você pode ajustar o QMD globalmente sem adicionar nova configuração do OpenClaw:

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"

Depois de mudar o modelo de embedding, execute os embeddings novamente para que o índice corresponda ao novo espaço vetorial.

Indexação de caminhos extras

Aponte o QMD para diretórios adicionais para torná-los pesquisáveis:

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

Trechos de caminhos extras aparecem como qmd/<collection>/<relative-path> nos resultados de busca. memory_get entende esse prefixo e lê a partir da raiz correta da coleção.

Indexação de transcrições de sessão

Habilite a indexação de sessões para recuperar conversas anteriores:

{
  memory: {
    backend: "qmd",
    qmd: {
      sessions: { enabled: true },
    },
  },
}

As transcrições são exportadas como turnos sanitizados de User/Assistant para uma coleção QMD dedicada em ~/.openclaw/agents/<id>/qmd/sessions/.

Escopo de busca

Por padrão, os resultados de busca do QMD são exibidos em sessões diretas e de canal (não em grupos). Configure memory.qmd.scope para mudar isso:

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

Quando o escopo nega uma busca, o OpenClaw registra um aviso com o canal derivado e o tipo de chat para facilitar a depuração de resultados vazios.

Citações

Quando memory.citations é auto ou on, os trechos de busca incluem um rodapé Source: <path#line>. Defina memory.citations = "off" para omitir o rodapé enquanto ainda passa o caminho internamente para o agente.

Quando usar

Escolha o QMD quando você precisar de:

  • Reclassificação para resultados de maior qualidade.
  • Buscar documentação ou notas do projeto fora do workspace.
  • Recuperar conversas de sessões passadas.
  • Busca totalmente local sem chaves de API.

Para configurações mais simples, o mecanismo integrado funciona bem sem dependências extras.

Solução de problemas

QMD não encontrado? Garanta que o binário esteja no PATH do Gateway. Se o OpenClaw rodar como um serviço, crie um symlink: sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd.

Se qmd --version funcionar no seu shell, mas o OpenClaw ainda relatar spawn qmd ENOENT, o processo do Gateway provavelmente tem um PATH diferente do seu shell interativo. Fixe o binário explicitamente:

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

Use command -v qmd no ambiente em que o QMD está instalado e depois verifique novamente com openclaw memory status --deep.

Primeira busca muito lenta? O QMD baixa modelos GGUF no primeiro uso. Pré-aqueça com qmd query "test" usando os mesmos diretórios XDG que o OpenClaw usa.

Muitos subprocessos QMD durante a busca? Atualize o QMD se possível. O OpenClaw usa um processo para buscas de múltiplas coleções da mesma origem apenas quando o QMD instalado anuncia suporte a múltiplos filtros -c; caso contrário, mantém o fallback mais antigo por coleção para preservar a correção.

QMD somente BM25 ainda tentando compilar llama.cpp? Defina memory.qmd.searchMode = "search". O OpenClaw trata esse modo como apenas lexical, não executa sondagens de status vetorial do QMD nem manutenção de embeddings, e deixa as verificações de prontidão semântica para configurações vsearch ou query.

Busca expira? Aumente memory.qmd.limits.timeoutMs (padrão: 4000ms). Defina como 120000 para hardware mais lento.

Resultados vazios em chats de grupo? Verifique memory.qmd.scope -- o padrão só permite sessões diretas e de canal.

A busca de memória raiz ficou ampla demais de repente? Reinicie o Gateway ou aguarde a próxima reconciliação de inicialização. O OpenClaw recria coleções gerenciadas obsoletas de volta para os padrões canônicos MEMORY.md e memory/ quando detecta um conflito com o mesmo nome.

Repositórios temporários visíveis no workspace causando ENAMETOOLONG ou indexação quebrada? A travessia do QMD atualmente segue o comportamento do scanner QMD subjacente, em vez das regras de symlink integradas do OpenClaw. Mantenha checkouts temporários de monorepos em diretórios ocultos como .tmp/ ou fora das raízes QMD indexadas até que o QMD exponha travessia segura contra ciclos ou controles de exclusão explícitos.

Configuração

Para a superfície completa de configuração (memory.qmd.*), modos de busca, intervalos de atualização, regras de escopo e todos os outros ajustes, consulte a referência de configuração de memória.

Relacionado