Pular para o conteúdo principal
memory-lancedb é um plugin oficial externo de memória que armazena memória de longo prazo no LanceDB e usa embeddings para recuperação. Ele pode recuperar automaticamente memórias relevantes antes de uma rodada do modelo e capturar fatos importantes após uma resposta. Use-o quando quiser um banco de dados vetorial local para memória, precisar de um endpoint de embeddings compatível com OpenAI ou quiser manter um banco de dados de memória fora do armazenamento de memória integrado padrão.

​
Instalação

Instale memory-lancedb antes de definir plugins.slots.memory = "memory-lancedb": 
openclaw plugins install @openclaw/memory-lancedb
O plugin é publicado no npm e não é empacotado na imagem de runtime do OpenClaw. O instalador grava a entrada do plugin e troca o slot de memória quando nenhum outro plugin o possui.
memory-lancedb é um plugin de memória ativa. Habilite-o selecionando o slot de memória com plugins.slots.memory = "memory-lancedb". Plugins complementares, como memory-wiki, podem ser executados ao lado dele, mas apenas um plugin possui o slot de memória ativa.

​
Início rápido

{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}
Reinicie o Gateway depois de alterar a configuração do plugin: 
openclaw gateway restart
Em seguida, verifique se o plugin foi carregado: 
openclaw plugins list

​
Embeddings baseados em provedor

memory-lancedb pode usar os mesmos adaptadores de provedor de embeddings de memória que memory-core. Defina embedding.provider e omita embedding.apiKey para usar o perfil de autenticação configurado do provedor, a variável de ambiente ou models.providers.<provider>.apiKey. 
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
          },
          autoRecall: true,
        },
      },
    },
  },
}
Esse caminho funciona com perfis de autenticação de provedor que expõem credenciais de embeddings. Por exemplo, o GitHub Copilot pode ser usado quando o perfil/plano do Copilot oferece suporte a embeddings: 
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "github-copilot",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}
OAuth do OpenAI Codex / ChatGPT não é uma credencial de embeddings da OpenAI Platform. Para embeddings da OpenAI, use um perfil de autenticação com chave de API da OpenAI, OPENAI_API_KEY ou models.providers.openai.apiKey. Usuários somente com OAuth podem usar outro provedor compatível com embeddings, como GitHub Copilot ou Ollama.

​
Embeddings do Ollama

Para embeddings do Ollama, prefira o provedor de embeddings Ollama empacotado. Ele usa o endpoint nativo /api/embed do Ollama e segue as mesmas regras de autenticação/URL base que o provedor Ollama documentado em Ollama. 
{
  plugins: {
    slots: {
      memory: "memory-lancedb",
    },
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            provider: "ollama",
            baseUrl: "http://127.0.0.1:11434",
            model: "mxbai-embed-large",
            dimensions: 1024,
          },
          recallMaxChars: 400,
          autoRecall: true,
          autoCapture: false,
        },
      },
    },
  },
}
Defina dimensions para modelos de embeddings não padrão. O OpenClaw conhece as dimensões de text-embedding-3-small e text-embedding-3-large; modelos personalizados precisam do valor na configuração para que o LanceDB possa criar a coluna vetorial. Para modelos locais pequenos de embeddings, reduza recallMaxChars se vir erros de comprimento de contexto vindos do servidor local.

​
Provedores compatíveis com OpenAI

Alguns provedores de embeddings compatíveis com OpenAI rejeitam o parâmetro encoding_format, enquanto outros o ignoram e sempre retornam vetores number[]. Por isso, memory-lancedb omite encoding_format em solicitações de embeddings e aceita respostas como arrays de floats ou respostas float32 codificadas em base64. Se você tiver um endpoint bruto de embeddings compatível com OpenAI que não tenha um adaptador de provedor empacotado, omita embedding.provider (ou deixe-o como openai) e defina embedding.apiKey mais embedding.baseUrl. Isso preserva o caminho direto do cliente compatível com OpenAI. Defina embedding.dimensions para provedores cujas dimensões de modelo não estejam integradas. Por exemplo, o ZhiPu embedding-3 usa 2048 dimensões: 
{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          embedding: {
            apiKey: "${ZHIPU_API_KEY}",
            baseUrl: "https://open.bigmodel.cn/api/paas/v4",
            model: "embedding-3",
            dimensions: 2048,
          },
        },
      },
    },
  },
}

​
Limites de recuperação e captura

memory-lancedb tem dois limites de texto separados:
ConfiguraçãoPadrãoIntervaloAplica-se a
recallMaxChars1000100-10000texto enviado à API de embeddings para recuperação
captureMaxChars500100-10000tamanho de mensagem qualificado para captura automática
customTriggers[]0-50frases literais que fazem a captura automática considerar uma mensagem
recallMaxChars controla a recuperação automática, a ferramenta memory_recall, o caminho de consulta memory_forget e openclaw ltm search. A recuperação automática prefere a mensagem mais recente do usuário na rodada e recorre ao prompt completo somente quando nenhuma mensagem do usuário está disponível. Isso mantém metadados de canal e grandes blocos de prompt fora da solicitação de embeddings. captureMaxChars controla se uma resposta é curta o suficiente para ser considerada para captura automática. Ele não limita embeddings de consulta de recuperação. customTriggers permite adicionar frases literais de captura automática sem escrever expressões regulares. Os gatilhos integrados incluem frases comuns de memória em inglês, tcheco, chinês, japonês e coreano.

​
Comandos

Quando memory-lancedb é o plugin de memória ativa, ele registra o namespace de CLI ltm: 
openclaw ltm list
openclaw ltm search "project preferences"
openclaw ltm stats
O subcomando query executa uma consulta não vetorial diretamente contra a tabela do LanceDB: 
openclaw ltm query --cols id,text,createdAt --limit 20
openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc
  • --cols <columns>: lista permitida de colunas separadas por vírgulas (o padrão é id, text, importance, category, createdAt).
  • --filter <condition>: cláusula WHERE em estilo SQL; limitada a 200 caracteres e restrita a alfanuméricos, operadores de comparação, aspas, parênteses e um pequeno conjunto de pontuação segura.
  • --limit <n>: inteiro positivo; padrão 10.
  • --order-by <column>:<asc|desc>: ordenação em memória aplicada após o filtro; a coluna de ordenação é incluída automaticamente na projeção.
Os agentes também recebem ferramentas de memória do LanceDB do plugin de memória ativa:
  • memory_recall para recuperação baseada no LanceDB
  • memory_store para salvar fatos, preferências, decisões e entidades importantes
  • memory_forget para remover memórias correspondentes

​
Armazenamento

Por padrão, os dados do LanceDB ficam em ~/.openclaw/memory/lancedb. Substitua o caminho com dbPath: 
{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "~/.openclaw/memory/lancedb",
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}
storageOptions aceita pares chave/valor de string para backends de armazenamento do LanceDB e oferece suporte à expansão ${ENV_VAR}: 
{
  plugins: {
    entries: {
      "memory-lancedb": {
        enabled: true,
        config: {
          dbPath: "s3://memory-bucket/openclaw",
          storageOptions: {
            access_key: "${AWS_ACCESS_KEY_ID}",
            secret_key: "${AWS_SECRET_ACCESS_KEY}",
            endpoint: "${AWS_ENDPOINT_URL}",
          },
          embedding: {
            apiKey: "${OPENAI_API_KEY}",
            model: "text-embedding-3-small",
          },
        },
      },
    },
  },
}

​
Dependências de runtime

memory-lancedb depende do pacote nativo @lancedb/lancedb. O OpenClaw empacotado trata esse pacote como parte do pacote do plugin. A inicialização do Gateway não repara dependências de plugins; se a dependência estiver ausente, reinstale ou atualize o pacote do plugin e reinicie o Gateway. Se uma instalação mais antiga registrar um erro de dist/package.json ausente ou @lancedb/lancedb ausente durante o carregamento do plugin, atualize o OpenClaw e reinicie o Gateway. Se o plugin registrar que o LanceDB está indisponível em darwin-x64, use o backend de memória padrão nessa máquina, mova o Gateway para uma plataforma compatível ou desabilite memory-lancedb.

​
Solução de problemas

​
O comprimento da entrada excede o comprimento de contexto

Isso geralmente significa que o modelo de embeddings rejeitou a consulta de recuperação: 
memory-lancedb: recall failed: Error: 400 the input length exceeds the context length
Defina um recallMaxChars menor e reinicie o Gateway: 
{
  plugins: {
    entries: {
      "memory-lancedb": {
        config: {
          recallMaxChars: 400,
        },
      },
    },
  },
}
Para Ollama, verifique também se o servidor de embeddings está acessível pelo host do Gateway: 
curl http://127.0.0.1:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"mxbai-embed-large","input":"hello"}'

​
Modelo de embeddings não compatível

Sem dimensions, somente as dimensões integradas de embeddings da OpenAI são conhecidas. Para modelos locais ou personalizados de embeddings, defina embedding.dimensions como o tamanho do vetor informado por esse modelo.

​
O plugin carrega, mas nenhuma memória aparece

Verifique se plugins.slots.memory aponta para memory-lancedb e execute: 
openclaw ltm stats
openclaw ltm search "recent preference"
Se autoCapture estiver desabilitado, o plugin recuperará memórias existentes, mas não armazenará novas automaticamente. Use a ferramenta memory_store ou habilite autoCapture se quiser captura automática.

​
Relacionado