RAG Híbrido para Memória de Agente Local com OpenClaw, Ollama e nomic-embed-text

Problema: Recuperação, Não Armazenamento

O desenvolvedor tinha meses de registros de memória diários armazenados em arquivos markdown, o que funcionava para salvar informações, mas não para encontrá-las novamente. Quando o agente precisava de contexto passado, ele voltava a executar ls, abrindo arquivos um por um, gastando tokens e às vezes perdendo informações relevantes. O problema era a recuperação por significado, não o armazenamento.

Solução: RAG Híbrido com Embeddings Locais

O desenvolvedor habilitou memorySearch no OpenClaw usando Ollama como provedor e nomic-embed-text para embeddings locais, rodando em modo híbrido. Híbrido significa 70% de similaridade vetorial (cosseno via nomic-embed-text) combinado com 30% de correspondência de palavras-chave BM25. O vetor lida com proximidade semântica enquanto o BM25 lida com nomes exatos, versões e IDs. O MMR reduz resultados redundantes, e o decaimento temporal dá mais peso aos registros recentes. Tudo roda localmente sem APIs externas.

Configuração

"memorySearch": {
  "provider": "ollama",
  "query": {
    "hybrid": {
      "enabled": true,
      "vectorWeight": 0.7,
      "textWeight": 0.3,
      "mmr": {
        "enabled": true,
        "lambda": 0.7
      },
      "temporalDecay": {
        "enabled": true,
        "halfLifeDays": 30
      }
    }
  }
}

Instruções de Configuração

• OpenClaw detecta Ollama automaticamente em localhost:11434
• Não é necessário especificar baseUrl ou modelo - ele pega nomic-embed-text se baixado
• Execute ollama pull nomic-embed-text primeiro, depois reinicie o gateway
• Evite definir provider: "openai" e apontar baseUrl para Ollama - use provider: "ollama" diretamente

Mudança Comportamental Necessária

Habilitar a ferramenta não foi suficiente. Sem instruções explícitas para usar memorySearch antes de ler arquivos diretamente, o agente pulava isso e tomava a rota mais lenta e pesada em tokens. O desenvolvedor escreveu uma regra tanto no AGENTS.md quanto no MEMORY.md no workspace para tornar a busca de memória parte do fluxo de trabalho normal do agente.

Resultados Antes vs Depois

• Antes: Navegar pastas, abrir arquivos às cegas, torcer para a redação corresponder, desperdiçar tokens, perder contexto
• Depois: Executar memory_search com consulta semântica, recuperar resultados classificados com pontuações de similaridade, abrir a melhor correspondência, responder a partir de notas passadas reais
• Pontuações de similaridade para resultados relevantes normalmente variam de 0,45 a 0,48 para nomic-embed-text em registros de prosa

Notas Práticas

• nomic-embed-text tem um limite de contexto de 2048 tokens por padrão, não 8192 - arquivos grandes podem ser truncados na indexação
• Arquivos de memória em espanhol funcionam bem - nomic-embed-text lida com espanhol sem problemas
• A qualidade da recuperação depende da qualidade das notas - registros vagos ainda causam dificuldades na busca semântica

Stack Tecnológico

• OpenClaw (local, auto-hospedado)
• Ollama + nomic-embed-text:latest
• SQLite com sqlite-vec e FTS5 (criado automaticamente pelo OpenClaw no primeiro uso)
• Mac mini M4, 16GB de memória unificada