Extraímos o sistema de memória do OpenClaw e abrimo-lo (memsearch)

O OpenClaw (anteriormente clawdbot e moltbot) está a tornar-se viral - mais de 189 mil estrelas no GitHub em menos de duas semanas. É uma loucura. A maior parte do burburinho gira em torno de seus recursos autônomos e agênticos nos canais de bate-papo do dia a dia, incluindo iMessages, WhatsApp, Slack, Telegram e muito mais.

Mas como engenheiros a trabalhar num sistema de base de dados vetorial, o que realmente nos chamou a atenção foi a abordagem do OpenClaw à memória de longo prazo. Ao contrário da maioria dos sistemas de memória existentes, o OpenClaw faz com que a sua IA escreva automaticamente registos diários como ficheiros Markdown. Esses ficheiros são a fonte da verdade e o modelo apenas se "lembra" do que é escrito no disco. Os programadores humanos podem abrir esses ficheiros Markdown, editá-los diretamente, destilar princípios de longo prazo e ver exatamente aquilo de que a IA se lembra em qualquer momento. Sem caixas negras. Honestamente, é uma das arquitecturas de memória mais limpas e fáceis de desenvolver que já vimos.

Então, naturalmente, tivemos uma pergunta: por que isso só funcionaria dentro do OpenClaw? E se qualquer agente pudesse ter uma memória como essa? Pegamos a arquitetura de memória exata do OpenClaw e criamos o memsearch - uma biblioteca de memória de longo prazo independente, plug-and-play, que fornece a qualquer agente uma memória persistente, transparente e editável por humanos. Não há dependência do restante do OpenClaw. Basta inseri-la e o seu agente obtém memória duradoura com pesquisa alimentada por Milvus/Zilliz Cloud, além de registos Markdown como a fonte canónica da verdade.

• GitHub Repo: github.com/zilliztech/memsearch (código aberto, licença MIT)

• Documentação: https://zilliztech.github.io/memsearch/

• Plugin do código Claude: https://zilliztech.github.io/memsearch/claude-plugin/

O que torna a memória do OpenClaw diferente

Antes de mergulhar na arquitetura de memória do OpenClaw, vamos esclarecer dois conceitos: contexto e memória. Eles parecem semelhantes, mas funcionam de forma muito diferente na prática.

• O contexto é tudo o que o agente vê num único pedido - avisos do sistema, ficheiros de orientação ao nível do projeto como AGENTS.md e SOUL.md, histórico de conversação (mensagens, chamadas de ferramentas, resumos comprimidos) e a mensagem atual do utilizador. É limitado a uma sessão e é relativamente compacto.

• A memória é o que persiste ao longo das sessões. Está no disco local: o histórico completo das conversas anteriores, os ficheiros com que o agente trabalhou e as preferências do utilizador. Não é resumido. Não compactado. O material bruto.

Agora, aqui está a decisão de design que torna a abordagem do OpenClaw especial: toda a memória é armazenada como arquivos Markdown simples no sistema de arquivos local. Após cada sessão, a IA escreve automaticamente actualizações nesses registos Markdown. O utilizador - e qualquer programador - pode abri-los, editá-los, reorganizá-los, apagá-los ou refiná-los. Entretanto, a base de dados vetorial acompanha este sistema, criando e mantendo um índice para recuperação. Sempre que um ficheiro Markdown é alterado, o sistema detecta a alteração e volta a indexá-lo automaticamente.

Se já utilizou ferramentas como o Mem0 ou o Zep, notará imediatamente a diferença. Esses sistemas armazenam memórias como embeddings - essa é a única cópia. Não é possível ler o que o agente se lembra. Não é possível corrigir uma má memória editando uma linha. A abordagem do OpenClaw dá-lhe ambas: a transparência dos ficheiros simples e o poder de recuperação da pesquisa vetorial utilizando uma base de dados vetorial. Pode lê-lo, git diff, grepá-lo - são apenas ficheiros.

A única desvantagem? Neste momento, este sistema de memória Markdown-first está fortemente interligado com todo o ecossistema OpenClaw - o processo Gateway, conectores de plataforma, configuração do espaço de trabalho e infraestrutura de mensagens. Se você quer apenas o modelo de memória, é muita maquinaria para arrastar.

Foi exatamente por isso que construímos o memsearch: a mesma filosofia - Markdown como fonte de verdade, indexação automática de vectores, totalmente editável por humanos - mas fornecida como uma biblioteca leve e autónoma que pode ser inserida em qualquer arquitetura agêntica.

Como funciona o Memsearch

Como mencionado anteriormente, memsearch é uma biblioteca de memória de longo prazo totalmente independente que implementa a mesma arquitetura de memória usada no OpenClaw - sem trazer o resto da pilha do OpenClaw. Você pode conectá-la a qualquer estrutura de agente (Claude, GPT, Llama, agentes personalizados, mecanismos de fluxo de trabalho) e instantaneamente dar ao seu sistema uma memória persistente, transparente e editável por humanos.

Toda a memória do agente no memsearch é armazenada como Markdown de texto simples em um diretório local. A estrutura é intencionalmente simples para que os desenvolvedores possam entendê-la num piscar de olhos:

~/your-project/
└── memory/
    ├── MEMORY.md              # Hand-written long-term memory
    ├── 2026-02-09.md          # Today's work log
    ├── 2026-02-08.md
    └── 2026-02-07.md

O Memsearch usa o Milvus como base de dados vetorial para indexar estes ficheiros Markdown para uma rápida recuperação semântica. Mas, crucialmente, o índice vetorial não é a fonte da verdade - os arquivos são. Se eliminar totalmente o índice do Milvus, não perde nada. O Memsearch simplesmente reincorpora e reindexa os arquivos Markdown, reconstruindo a camada de recuperação completa em poucos minutos. Isso significa que a memória do seu agente é transparente, durável e totalmente reconstruível.

Aqui estão os principais recursos do memsearch:

Markdown legível torna a depuração tão simples quanto editar um arquivo

A depuração da memória da IA geralmente é dolorosa. Quando um agente produz uma resposta errada, a maioria dos sistemas de memória não oferece uma maneira clara de ver o que ele realmente armazenou. O fluxo de trabalho típico é escrever código personalizado para consultar uma API de memória e, em seguida, peneirar embeddings opacos ou blobs JSON detalhados - nenhum dos quais informa muito sobre o estado interno real da IA.

O memsearch elimina toda essa classe de problemas. Toda a memória vive na pasta memory/ como Markdown simples:

## Morning
- Fixed N+1 query issue — switched to selectinload()
- Query count dropped from 152 to 3

Se a IA se enganar em alguma coisa, corrigi-la é tão simples como editar o ficheiro. Actualize a entrada, guarde, e o memsearch reindexa automaticamente a alteração. Cinco segundos. Sem chamadas à API. Sem ferramentas. Nenhum mistério. Depura-se a memória de IA da mesma forma que se depura a documentação - editando um ficheiro.

Memória suportada por Git significa que as equipas podem acompanhar, rever e reverter alterações

A memória de IA que vive em um banco de dados é difícil de colaborar. Descobrir quem alterou o quê e quando significa vasculhar os registos de auditoria, e muitas soluções nem sequer os fornecem. As alterações acontecem silenciosamente e os desacordos sobre o que a IA deve lembrar não têm um caminho de resolução claro. As equipas acabam por se basear em mensagens do Slack e em suposições.

O Memsearch resolve este problema ao tornar a memória apenas ficheiros Markdown - o que significa que o Git trata automaticamente do controlo de versões. Um único comando mostra todo o histórico:

git log memory/MEMORY.md
git diff HEAD~1 memory/2026-02-09.md

Agora a memória de IA participa do mesmo fluxo de trabalho que o código. Decisões de arquitetura, actualizações de configuração e alterações de preferências aparecem em diffs que qualquer pessoa pode comentar, aprovar ou reverter:

+ ## Architecture Decision
+ - Use Kafka for event bus instead of RabbitMQ
+ - Reason: better horizontal scaling

A memória de texto simples torna a migração quase sem esforço

A migração é um dos maiores custos ocultos dos frameworks de memória. Mudar de uma ferramenta para outra geralmente significa exportar dados, converter formatos, reimportar e esperar que os campos sejam compatíveis. Esse tipo de trabalho pode facilmente consumir metade de um dia, e o resultado nunca é garantido.

O memsearch evita totalmente o problema porque a memória é Markdown em texto simples. Não há nenhum formato proprietário, nenhum esquema para traduzir, nada para migrar:

• Trocar de máquina: rsync a pasta de memória. Feito.

• Mudar os modelos de incorporação: Executar novamente o comando index. Demora cinco minutos, e os ficheiros markdown permanecem intactos.

• Mudar a implantação do banco de dados vetorial: Altere um valor de configuração. Por exemplo, passar do Milvus Lite em desenvolvimento para o Zilliz Cloud em produção:

# Development
ms = MemSearch(milvus_uri="~/.memsearch/milvus.db")
# Production (change only this line)
ms = MemSearch(milvus_uri=“https://xxx.zillizcloud.com”)

Os seus ficheiros de memória permanecem exatamente os mesmos. A infraestrutura em torno deles pode evoluir livremente. O resultado é a portabilidade a longo prazo - uma propriedade rara em sistemas de IA.

Ficheiros Markdown partilhados permitem que humanos e agentes sejam co-autores da memória

Na maioria das soluções de memória, editar o que a IA lembra requer escrever código em uma API. Isso significa que apenas os programadores podem manter a memória da IA e, mesmo para eles, é complicado.

O Memsearch permite uma divisão de responsabilidades mais natural:

• A IA trata: Registos diários automáticos (YYYY-MM-DD.md) com detalhes de execução como "implementado v2.3.1, 12% de melhoria de desempenho".

• Os humanos tratam: Princípios de longo prazo em MEMORY.md, como "Team stack: Python + FastAPI + PostgreSQL."

Ambos os lados editam os mesmos ficheiros Markdown com as ferramentas que já utilizam. Sem chamadas de API, sem ferramentas especiais, sem gatekeeper. Quando a memória está trancada dentro de um banco de dados, esse tipo de autoria compartilhada não é possível. memsearch torna isso o padrão.

Sob o capô: memsearch funciona em quatro fluxos de trabalho que mantêm a memória rápida, fresca e enxuta

O memsearch tem quatro fluxos de trabalho principais: Observar (monitorar) → Indexar (dividir e incorporar) → Pesquisar (recuperar) → Compactar (resumir). Eis o que cada um deles faz.

1. Observar: Re-Indexar automaticamente em cada ficheiro guardado

O fluxo de trabalho Watch monitoriza todos os ficheiros Markdown no diretório memory/ e desencadeia uma re-indexação sempre que um ficheiro é modificado e guardado. Um atraso de 1500ms garante que as actualizações são detectadas sem desperdiçar computação: se ocorrerem várias gravações numa sucessão rápida, o temporizador reinicia e dispara apenas quando as edições estabilizarem.

Esse atraso é ajustado empiricamente:

• 100ms → demasiado sensível; dispara em cada batida de tecla, queimando as chamadas de incorporação

• 10s → demasiado lento; os programadores notam um atraso

• 1500ms → equilíbrio ideal entre capacidade de resposta e eficiência de recursos

Na prática, isto significa que um programador pode escrever código numa janela e editar MEMORY.md noutra, adicionando um URL de documentação da API ou corrigindo uma entrada desactualizada. Guarde o ficheiro e a próxima consulta de IA recolhe a nova memória. Sem reiniciar, sem re-indexação manual.

2. Indexação: Chunking inteligente, desduplicação e incorporação com reconhecimento de versão

O Index é o fluxo de trabalho crítico para o desempenho. Ele lida com três coisas: chunking, deduplicação e IDs de chunk com versão.

A divisão em pedaços divide o texto ao longo de limites semânticos - títulos e seus corpos - para que o conteúdo relacionado permaneça junto. Isso evita casos em que uma frase como "configuração do Redis" é dividida em pedaços.

Por exemplo, este Markdown:

## Redis Caching
We use Redis for L1 cache with 5min TTL.
The connection pool is configured with max 100 connections.
## Database
PostgreSQL 16 is the primary database.

Torna-se dois pedaços:

• Fragmento 1: ## Redis Caching\nWe use Redis for L1 cache...

• Fragmento 2: ## Database\nPostgreSQL 16 is the primary database.

A deduplicação usa um hash SHA-256 de cada pedaço para evitar a incorporação do mesmo texto duas vezes. Se múltiplos arquivos mencionam "PostgreSQL 16", a API de embedding é chamada uma vez, não uma vez por arquivo. Para ~500KB de texto, isso economiza cerca de $0,15/mês. Em escala, isso representa centenas de dólares.

O design do ID do pedaço codifica tudo o que é necessário para saber se um pedaço é obsoleto. O formato é hash(source_path:start_line:end_line:content_hash:model_version). O campo model_version é a parte importante: quando um modelo de incorporação é atualizado de text-embedding-3-small para text-embedding-3-large, as incorporações antigas tornam-se inválidas. Uma vez que a versão do modelo é incorporada no ID, o sistema identifica automaticamente quais os pedaços que necessitam de ser incorporados de novo. Não é necessária uma limpeza manual.

3. Pesquisa: Recuperação híbrida de vetor + BM25 para máxima precisão

A recuperação utiliza uma abordagem de pesquisa híbrida: pesquisa vetorial ponderada a 70% e pesquisa de palavras-chave BM25 ponderada a 30%. Isto equilibra duas necessidades diferentes que surgem frequentemente na prática.

• A pesquisa vetorial lida com a correspondência semântica. Uma consulta para "Redis cache config" retorna um pedaço contendo "Redis L1 cache with 5min TTL" mesmo que o texto seja diferente. Isto é útil quando o programador se lembra do conceito mas não da frase exacta.

• BM25 lida com correspondência exata. Uma consulta para "PostgreSQL 16" não retorna resultados sobre "PostgreSQL 15". Isto é importante para códigos de erro, nomes de funções, e comportamentos específicos de versões, onde próximo não é suficiente.

A divisão padrão 70/30 funciona bem para a maioria dos casos de uso. Para fluxos de trabalho que se inclinam fortemente para correspondências exatas, aumentar o peso do BM25 para 50% é uma mudança de configuração de uma linha.

Os resultados são devolvidos como blocos top-K (padrão 3), cada um truncado para 200 caracteres. Quando o conteúdo completo é necessário, memsearch expand <chunk_hash> carrega-o. Esta divulgação progressiva mantém a utilização da janela de contexto do LLM reduzida sem sacrificar o acesso aos detalhes.

4. Compacto: Resumir a memória histórica para manter o contexto limpo

Memória acumulada eventualmente se torna um problema. Entradas antigas enchem a janela de contexto, aumentam os custos de token e adicionam ruído que degrada a qualidade da resposta. O Compact resolve este problema chamando um LLM para resumir a memória histórica numa forma condensada e, em seguida, eliminando ou arquivando os originais. Ele pode ser acionado manualmente ou programado para ser executado em um intervalo regular.

Como começar a usar o memsearch

O Memsearch fornece uma API Python e uma CLI, para que possa utilizá-lo dentro de estruturas de agentes ou como uma ferramenta de depuração autónoma. A configuração é mínima, e o sistema foi projetado para que o ambiente de desenvolvimento local e a implantação de produção sejam praticamente idênticos.

O Memsearch oferece suporte a três back-ends compatíveis com o Milvus, todos expostos por meio da mesma API:

• Milvus Lite (padrão): Arquivo local .db, configuração zero, adequado para uso individual.

• Milvus Standalone / Cluster: Auto-hospedado, suporta vários agentes que partilham dados, adequado para ambientes de equipa.

• Zilliz Cloud: Totalmente gerido, com escalonamento automático, cópias de segurança, alta disponibilidade e isolamento. Ideal para cargas de trabalho de produção.

Mudar do desenvolvimento local para a produção é tipicamente uma alteração de configuração de uma linha. O seu código permanece o mesmo.

Instalar

pip install memsearch

O memsearch também suporta vários fornecedores de incorporação, incluindo OpenAI, Google, Voyage, Ollama e modelos locais. Isso garante que sua arquitetura de memória permaneça portátil e independente de fornecedor.

Opção 1: API Python (integrada à sua estrutura de agente)

Aqui está um exemplo mínimo de um loop de agente completo usando memsearch. Você pode copiar/colar e modificar conforme necessário:

from openai import OpenAI
from memsearch import MemSearch
llm = OpenAI()
ms = MemSearch(paths=[“./memory/”])
async def agent_chat(user_input: str) -> str:
# 1. Recall — search relevant memories
memories = await ms.search(user_input, top_k=3)
context = “\n”.join(f"- {m[‘content’][:200]}" for m in memories)
<span class="hljs-comment"># 2. Think — call LLM</span>
resp = llm.chat.completions.create(
    model=<span class="hljs-string">&quot;gpt-4o-mini&quot;</span>,
    messages=[
        {<span class="hljs-string">&quot;role&quot;</span>: <span class="hljs-string">&quot;system&quot;</span>, <span class="hljs-string">&quot;content&quot;</span>: <span class="hljs-string">f&quot;Memories:\n<span class="hljs-subst">{context}</span>&quot;</span>},
        {<span class="hljs-string">&quot;role&quot;</span>: <span class="hljs-string">&quot;user&quot;</span>, <span class="hljs-string">&quot;content&quot;</span>: user_input},
    ],
)

<span class="hljs-comment"># 3. Remember — write to markdown, update index</span>
save_memory(<span class="hljs-string">f&quot;## <span class="hljs-subst">{user_input}</span>\n<span class="hljs-subst">{resp.choices[<span class="hljs-number">0</span>].message.content}</span>&quot;</span>)
<span class="hljs-keyword">await</span> ms.index()
<span class="hljs-keyword">return</span> resp.choices[<span class="hljs-number">0</span>].message.content

Isto mostra o ciclo principal:

• Lembre-se: o memsearch executa a recuperação híbrida de vetor + BM25

• Pense: o seu LLM processa a entrada do utilizador + memória recuperada

• Lembre-se: o agente escreve nova memória no Markdown e o memsearch actualiza o seu índice

Este padrão encaixa naturalmente em qualquer sistema de agentes - LangChain, AutoGPT, routers semânticos, LangGraph ou loops de agentes personalizados. É agnóstico em relação à estrutura por design.

Opção 2: CLI (operações rápidas, bom para depuração)

A CLI é ideal para fluxos de trabalho autónomos, verificações rápidas ou inspeção de memória durante o desenvolvimento:

memsearch index ./docs/              # Index files
memsearch search "Redis caching"     # Search
memsearch watch ./docs/              # Watch for file changes
memsearch compact                    # Compact old memory

A CLI espelha as capacidades da API Python mas funciona sem escrever qualquer código - ótimo para depuração, inspecções, migrações ou validação da sua estrutura de pastas de memória.

Como o memsearch se compara a outras soluções de memória

A pergunta mais comum que os desenvolvedores fazem é por que eles usariam o memsearch quando já existem opções estabelecidas. A resposta curta: o memsearch troca recursos avançados, como gráficos de conhecimento temporal, por transparência, portabilidade e simplicidade. Para a maioria dos casos de uso de memória de agente, essa é a troca certa.

Solução	Pontos fortes	Limitações	Melhor para
memsearch	Memória de texto simples transparente, coautoria humano-IA, fricção de migração zero, depuração fácil, Git-nativo	Sem gráficos temporais incorporados ou estruturas complexas de memória multiagente	Equipas que valorizam o controlo, a simplicidade e a portabilidade na memória de longo prazo
Mem0	Totalmente gerida, sem infra-estruturas para executar ou manter	Opaco - não é possível inspecionar ou editar manualmente a memória; os embeddings são a única representação	Equipas que pretendem um serviço gerido sem intervenção e que não se importam com menos visibilidade
Zep	Conjunto rico de funcionalidades: memória temporal, modelação multi-persona, gráficos de conhecimento complexos	Arquitetura pesada; mais peças móveis; mais difícil de aprender e operar	Agentes que necessitam efetivamente de estruturas de memória avançadas ou de raciocínio com conhecimento do tempo
LangMem / Letta	Integração profunda e sem falhas nos seus próprios ecossistemas	Bloqueio da estrutura; difícil de transferir para outras pilhas de agentes	Equipas já comprometidas com essas estruturas específicas

Experimente o memsearch e deixe-nos saber a sua opinião

O Memsearch é totalmente open source sob a licença MIT, e o repositório está pronto para experiências de produção hoje.

• Repositório: github.com/zilliztech/memsearch

• Documentos: zilliztech.github.io/memsearch

Se está a construir um agente que precisa de se lembrar de coisas através de sessões e quer ter controlo total sobre o que se lembra, vale a pena dar uma vista de olhos ao memsearch. A biblioteca é instalada com um único pip install, funciona com qualquer estrutura de agente e armazena tudo como Markdown que pode ser lido, editado e versionado com o Git.

Estamos desenvolvendo ativamente o memsearch e gostaríamos de receber contribuições da comunidade.

• Abra um problema se algo quebrar.

• Envie um PR se quiser estender a biblioteca.

• Dê uma estrela ao repositório se a filosofia Markdown-as-source-of-truth lhe agrada.

O sistema de memória do OpenClaw não está mais trancado dentro do OpenClaw. Agora, qualquer um pode usá-lo.

Continue lendo

• O que é o OpenClaw? Guia completo para o agente de IA de código aberto

• Tutorial do OpenClaw: Conectar ao Slack para Assistente de IA Local

• Construir agentes de IA do tipo Clawdbot com LangGraph e Milvus

• RAG vs. agentes de longa duração: O RAG é obsoleto?

• Crie uma habilidade antrópica personalizada para o Milvus para ativar rapidamente o RAG