Home
Blog
Adicionando memória persistente ao código Claude com o plugin leve memsearch

Adicionando memória persistente ao código Claude com o plugin leve memsearch

Engineering

February 13, 2026

Cheney Zhang

Recentemente construímos e abrimos o memsearch, uma biblioteca de memória de longo prazo autónoma e plug-and-play que dá a qualquer agente uma memória persistente, transparente e editável por humanos. Ela usa a mesma arquitetura de memória subjacente do OpenClaw - mas sem o resto da pilha do OpenClaw. Isso significa que é possível colocá-la em qualquer estrutura de agente (Claude, GPT, Llama, agentes personalizados, mecanismos de fluxo de trabalho) e adicionar instantaneamente memória durável e consultável. (Se quiser se aprofundar em como o memsearch funciona, escrevemos um post separado aqui).

Na maioria dos fluxos de trabalho de agentes, o memsearch funciona exatamente como pretendido. Mas a codificação agêntica é uma história diferente. As sessões de codificação são longas, as mudanças de contexto são constantes e a informação que vale a pena guardar acumula-se ao longo de dias ou semanas. Esse volume e volatilidade expõem as fraquezas dos sistemas de memória típicos dos agentes - incluindo o memsearch. Nos cenários de codificação, os padrões de recuperação diferem o suficiente para não podermos simplesmente reutilizar a ferramenta existente tal como está.

Para resolver isso, criamos um plug-in de memória persistente projetado especificamente para o Claude Code. Ele fica em cima do CLI do memsearch, e nós o chamamos de memsearch ccplugin.

GitHub Repo: https://zilliztech.github.io/memsearch/claude-plugin/ (código aberto, licença MIT)

Com o leve memsearch ccplugin gerenciando a memória nos bastidores, o Claude Code ganha a capacidade de lembrar cada conversa, cada decisão, cada preferência de estilo e cada thread de vários dias - indexado automaticamente, totalmente pesquisável e persistente entre as sessões.

Para maior clareza neste post: "ccplugin" refere-se à camada superior ou ao próprio plug-in do Claude Code. "memsearch" refere-se à camada inferior, a ferramenta CLI autónoma que lhe está subjacente.

Então, porque é que a codificação precisa do seu próprio plugin e porque é que construímos algo tão leve? Resume-se a dois problemas que quase de certeza já encontrou: A falta de memória persistente do Claude Code e a complexidade das soluções existentes, como o claude-mem.

Então, por que construir um plugin dedicado? Porque os agentes de codificação esbarram em dois pontos de dor que você quase certamente já experimentou:

Claude O código não tem memória persistente.
Muitas soluções existentes na comunidade - como o claude-mem - sãopoderosas, mas pesadas, desajeitadas ou excessivamente complexas para o trabalho diário de codificação.

O ccplugin tem como objetivo resolver ambos os problemas com uma camada mínima, transparente e amigável ao desenvolvedor sobre o memsearch.

O problema de memória do código do Claude: ele esquece tudo quando uma sessão termina

Vamos começar com um cenário que os usuários do Claude Code com certeza já encontraram.

Você abre o Claude Code pela manhã. "Continue o refactor de autenticação de ontem", você digita. O Claude responde: "Não tenho certeza no que você estava trabalhando ontem". Então, passas os dez minutos seguintes a copiar e colar os registos de ontem. Não é um grande problema, mas torna-se irritante rapidamente porque aparece com muita frequência.

Mesmo que o Claude Code tenha seus próprios mecanismos de memória, eles estão longe de serem satisfatórios. O ficheiro CLAUDE.md pode armazenar diretivas de projeto e preferências, mas funciona melhor para regras estáticas e comandos curtos, não para acumular conhecimento a longo prazo.

O Claude Code oferece os comandos resume e fork, mas eles estão longe de serem fáceis de usar. Para os comandos fork, é necessário lembrar-se dos IDs de sessão, digitar comandos manualmente e gerir uma árvore de históricos de conversação ramificados. Quando você executa /resume, você obtém uma parede de títulos de sessão. Se você só se lembra de alguns detalhes sobre o que você fez e foi há mais de alguns dias, boa sorte para encontrar a sessão certa.

Para a acumulação de conhecimentos a longo prazo, entre projectos, toda esta abordagem é impossível.

Para cumprir essa idéia, claude-mem usa um sistema de memória de três camadas. A primeira camada pesquisa resumos de alto nível. O segundo nível procura numa linha de tempo para obter mais detalhes. O terceiro nível extrai observações completas para conversas em bruto. Além disso, existem etiquetas de privacidade, controlo de custos e uma interface de visualização na Web.

Eis como funciona por baixo do capô:

Camada de tempo de execução. Um serviço Node.js Worker é executado na porta 37777. Os metadados da sessão residem numa base de dados SQLite leve. Uma base de dados vetorial trata da recuperação semântica precisa do conteúdo da memória.
Camada de interação. Uma IU Web baseada em React permite-lhe ver as memórias capturadas em tempo real: resumos, linhas de tempo e registos em bruto.
Camada de interface. Um servidor MCP (Model Context Protocol) expõe interfaces de ferramentas padronizadas. O Claude pode chamar search (consultar resumos de alto nível), timeline (ver linhas de tempo detalhadas) e get_observations (recuperar registos de interação em bruto) para recuperar e utilizar memórias diretamente.

Para ser justo, este é um produto sólido que resolve o problema de memória do Claude Code. Mas é desajeitado e complexo em aspectos que importam no dia a dia.

Camada	Tecnologia
Linguagem	TypeScript (ES2022, módulos ESNext)
Tempo de execução	Node.js 18+
Base de dados	SQLite 3 com driver bun:sqlite
Armazenamento vetorial	ChromaDB (opcional, para pesquisa semântica)
Servidor HTTP	Express.js 4.18
Em tempo real	Eventos enviados pelo servidor (SSE)
Estrutura de IU	React + TypeScript
SDK DE IA	@anthropic-ai/claude-agent-sdk
Ferramenta de construção	esbuild (inclui TypeScript)
Gerenciador de processos	Bun
Testes	Executor de testes embutido no Node.js

Para começar, a configuração é pesada. Fazer o claude-mem rodar significa instalar o Node.js, Bun e o runtime do MCP, e então montar um serviço Worker, servidor Express, React UI, SQLite e um vetor store em cima disso. São muitas partes móveis para implantar, manter e depurar quando algo quebra.

Todos esses componentes também queimam tokens que você não pediu para gastar. As definições de ferramentas do MCP são carregadas permanentemente na janela de contexto do Claude, e cada chamada de ferramenta consome tokens na solicitação e na resposta. Em sessões longas, essa sobrecarga aumenta rapidamente e pode levar os custos de tokens para fora de controle.

A recuperação de memória não é confiável porque depende inteiramente da escolha do Claude em pesquisar. O Claude tem de decidir por si próprio chamar ferramentas como search para despoletar a recuperação. Se ele não percebe que precisa de uma memória, o conteúdo relevante nunca aparece. E cada um dos três níveis de memória requer a sua própria invocação explícita de ferramentas, por isso não há recurso se o Claude não se lembrar de procurar.

Finalmente, o armazenamento de dados é opaco, o que torna a depuração e a migração desagradáveis. As memórias são divididas entre o SQLite para metadados de sessão e o Chroma para dados vetoriais binários, sem nenhum formato aberto que as una. Migrar significa escrever scripts de exportação. Para ver o que a IA realmente lembra, é necessário passar pela IU da Web ou por uma interface de consulta dedicada. Não há forma de ver apenas os dados em bruto.

Por que o plug-in memsearch para o Claude Code é melhor?

Queríamos uma camada de memória que fosse realmente leve - sem serviços extras, sem arquitetura emaranhada, sem sobrecarga operacional. Foi isso que nos motivou a construir o memsearch ccplugin. No fundo, tratava-se de uma experiência: poderia um sistema de memória focado na codificação ser radicalmente mais simples?

Sim, e nós provámos isso.

O ccplugin inteiro é composto por quatro hooks de shell mais um processo de vigilância em segundo plano. Sem Node.js, sem servidor MCP, sem interface Web. São apenas scripts de shell que chamam a CLI do memsearch, o que reduz drasticamente a barra de configuração e manutenção.

O ccplugin pode ser tão fino por causa dos limites estritos de responsabilidade. Ele não lida com armazenamento de memória, recuperação de vetor ou incorporação de texto. Tudo isso é delegado à CLI do memsearch que está por baixo. O ccplugin tem uma função: fazer a ponte entre os eventos do ciclo de vida do Claude Code (início da sessão, envio de prompt, parada de resposta, fim da sessão) e as funções correspondentes da CLI do memsearch.

Este design desacoplado torna o sistema flexível para além do Código Claude. A CLI do memsearch funciona de forma independente com outros IDEs, outras estruturas de agentes ou até mesmo invocação manual simples. Ela não está presa a um único caso de uso.

Na prática, esse design oferece três vantagens principais.

1. Todas as memórias vivem em ficheiros Markdown simples

Cada memória que o ccplugin cria vive em .memsearch/memory/ como um ficheiro Markdown.

.memsearch/memory/
├── 2026-02-09.md
├── 2026-02-10.md
└── 2026-02-11.md

É um ficheiro por dia. Cada ficheiro contém os resumos das sessões desse dia em texto simples, totalmente legível por humanos. Aqui está uma captura de ecrã dos ficheiros de memória diários do próprio projeto memsearch:

Pode ver o formato imediatamente: carimbo de data/hora, ID da sessão, ID do turno e um resumo da sessão. Nada está escondido.

Quer saber do que a IA se lembra? Abra o ficheiro Markdown. Quer editar uma memória? Utilize o seu editor de texto. Quer migrar os seus dados? Copie a pasta .memsearch/memory/.

O índice vetorial Milvus é uma cache para acelerar a pesquisa semântica. É reconstruído a partir do Markdown em qualquer altura. Não há bases de dados opacas, nem caixas negras binárias. Todos os dados são rastreáveis e totalmente reconstruíveis.

2. A injeção automática de contexto não custa nenhum token adicional

O armazenamento transparente é a base deste sistema. A verdadeira recompensa vem da forma como estas memórias são utilizadas e, no ccplugin, a recuperação de memórias é totalmente automática.

Sempre que uma solicitação é enviada, o gancho UserPromptSubmit dispara uma pesquisa semântica e injeta as três principais memórias relevantes no contexto. O Claude não decide se deve pesquisar. Ele apenas obtém o contexto.

Durante este processo, o Claude nunca vê as definições da ferramenta MCP, por isso nada mais ocupa a janela de contexto. O gancho é executado na camada CLI e injeta resultados de pesquisa de texto simples. Sem sobrecarga de IPC, sem custos de token de chamada de ferramenta. O inchaço da janela de contexto que vem com as definições de ferramentas MCP desapareceu completamente.

Para os casos em que o top-3 automático não é suficiente, também construímos três níveis de recuperação progressiva. Todos os três são comandos CLI, não ferramentas MCP.

L1 (automático): Cada prompt retorna os três principais resultados de pesquisa semântica com uma visualização de chunk_hash e 200 caracteres. Isso cobre a maior parte do uso diário.
L2 (a pedido): Quando é necessário um contexto completo, memsearch expand <chunk_hash> devolve a secção Markdown completa e os metadados.
L3 (profundo): Quando é necessária a conversa original, memsearch transcript <jsonl_path> --turn <uuid> extrai o registo JSONL em bruto do Claude Code.

3. Os resumos das sessões são gerados em segundo plano a um custo quase nulo

A recuperação abrange a forma como as memórias são utilizadas. Mas as memórias têm que ser escritas primeiro. Como é que todos esses ficheiros Markdown são criados?

O ccplugin os gera por meio de um pipeline em segundo plano que é executado de forma assíncrona e não custa quase nada. Sempre que você interrompe uma resposta do Claude, o gancho Stop é acionado: ele analisa a transcrição da conversa, chama o Claude Haiku (claude -p --model haiku) para gerar um resumo e o anexa ao arquivo Markdown do dia atual. As chamadas à API do Haiku são extremamente baratas, quase insignificantes por invocação.

A partir daí, o processo de observação detecta a alteração do ficheiro e indexa automaticamente o novo conteúdo no Milvus para que esteja disponível para recuperação imediata. Todo o processo decorre em segundo plano, sem interromper o seu trabalho, e os custos mantêm-se controlados.

Início rápido do plugin memsearch com o Claude Code

Primeiro, instale a partir do mercado de plug-ins do Claude Code:


bash
# Run in Claude Code terminal
/plugin marketplace add zilliztech/memsearch
/plugin install memsearch

Em segundo lugar, reinicie o Claude Code.

O plugin inicializa a sua configuração automaticamente.

Terceiro, depois de uma conversa, verifique o ficheiro de memória do dia:

bash
cat .memsearch/memory/$(date +%Y-%m-%d).md

Quarto, aproveite.

Da próxima vez que o Claude Code for iniciado, o sistema recupera e injecta automaticamente as memórias relevantes. Não são necessários passos adicionais.

Conclusão

Voltemos à questão original: como é que se dá memória persistente à IA? claude-mem e memsearch ccplugin adoptam abordagens diferentes, cada uma com diferentes pontos fortes. Resumimos um guia rápido para escolher entre eles:

Categoria	pesquisa de memória	claude-mem
Arquitetura	4 ganchos de shell + 1 processo de observação	Node.js Worker + Express + React UI
Método de integração	Ganchos nativos + CLI	Servidor MCP (stdio)
Recuperação	Automática (injeção de ganchos)	Orientada para o agente (requer invocação de ferramenta)
Consumo de contexto	Zero (injetar apenas o texto do resultado)	As definições da ferramenta MCP persistem
Resumo da sessão	Uma chamada CLI assíncrona do Haiku	Várias chamadas API + compressão de observação
Formato de armazenamento	Ficheiros Markdown simples	SQLite + incorporação de Chroma
Migração de dados	Ficheiros Markdown simples	SQLite + incorporação Chroma
Método de migração	Copiar ficheiros .md	Exportar da base de dados
Tempo de execução	Python + CLI do Claude	Node.js + Bun + tempo de execução MCP

O claude-mem oferece recursos mais ricos, uma interface de usuário refinada e um controle mais refinado. Para equipas que precisam de colaboração, visualização na Web ou gestão detalhada da memória, é uma escolha forte.

O memsearch ccplugin oferece um design mínimo, zero sobrecarga de janela de contexto e armazenamento totalmente transparente. Para engenheiros que desejam uma camada de memória leve sem complexidade adicional, é a melhor opção. Qual é o melhor depende do que você precisa.

Quer se aprofundar ou obter ajuda para criar com memsearch ou Milvus?

Junte-se à comunidade Milvus Slack para se conectar com outros desenvolvedores e compartilhar o que você está construindo.
Reserve o nosso Milvus Office Hoursparaperguntas e respostas ao vivo e apoio direto da equipa.