Comment adicionar memória ao seu agente com Weaviate (Passo a passo)

“`html

Weaviate Adicionando Memória ao Seu Agente: Um Tutorial Prático de 2500 Palavras

Se você quer que seu agente inteligente realmente se lembre do contexto entre as conversas, você deve weaviate add memory to your agent da maneira certa, utilizando a pesquisa vetorial para armazenar e recuperar interações anteriores. Não estamos apenas fazendo fragmentos de código em um banco de dados; estamos construindo um verdadeiro grafo de conhecimento enriquecido com uma pesquisa semântica que mantém seu agente alerta.

O Que Você Está Construindo e Por Que Isso É Importante

Estamos construindo um agente que usa Weaviate para o armazenamento de memória, para que ele possa ter conversas significativas, não apenas perguntas e respostas sem estado. Esqueça essas demonstrações de chatbots superficiais que reinicializam a cada pergunta — aqui se trata de uma persistência contextual que seus usuários realmente sentirão.

Requisitos

• Python 3.11+
• Weaviate Community Edition (última versão estável, eu usei 1.19.0)
• Pacotes Pip: weaviate-client>=4.16.0, requests, dotenv
• Chave API OpenAI ou qualquer outra chave API de modelo de incorporação (GPT-4, Cohere ou Huggingface)
• Docker instalado (opcional, mas recomendado para rodar Weaviate localmente)
• Compreensão básica de bancos de dados vetoriais e geração de incorporações

Estatísticas Rápidas sobre Weaviate

Métrica	Valor
Estrelas no GitHub	15 839
Forks	1 227
Problemas Abertos	582 (em 20 de março de 2026)
Licença	BSD-3-Clause
Última Atualização	20 de março de 2026

Esses números mostram que o Weaviate é maduro, mas continua ativo; você não ficará preso esperando por uma biblioteca abandonada.

Passo a Passo: Weaviate Adicionando Memória ao Seu Agente

Passo 1: Configurar o Servidor Weaviate

# Execute o Weaviate com Docker para testes locais rápidos
docker run -d \
 -p 8080:8080 \
 -e AUTH_ANONYMOUS_ACCESS_ENABLED=true \
 -e QUERY_DEFAULTS_LIMIT=20 \
 -e PERSISTENCE_DATA_PATH=/var/lib/weaviate \
 -v $(pwd)/weaviate_data:/var/lib/weaviate \
 semitechnologies/weaviate:latest

Por que isso é importante: O Weaviate suporta a persistência e o acesso anônimo por padrão aqui, o que facilita o desenvolvimento local. Ajustando QUERY_DEFAULTS_LIMIT=20, você evita encontrar limites irritantes de 10 resultados nas consultas, o que irrita até mesmo desenvolvedores experientes. Não se esqueça, se você não quiser acesso anônimo, configure chaves API. Mas para testes, isso é aceitável.

Erros Comuns: Se o contêiner falhar, verifique se a porta 8080 está livre. Às vezes, o Docker Desktop ou contêineres anteriores ocupam. Além disso, se você gerar incorporações mais rápido do que o que a persistência do Weaviate pode lidar (raro localmente), espere um atraso.

Passo 2: Definir um Esquema para a Memória do Seu Agente

import weaviate

client = weaviate.Client("http://localhost:8080")

schema = {
 "classes": [
 {
 "class": "MemoryEntry",
 "description": "Armazena um segmento de memória único para o agente",
 "properties": [
 {
 "name": "text",
 "dataType": ["text"],
 "description": "O conteúdo textual da memória."
 },
 {
 "name": "embedding",
 "dataType": ["number[]"],
 "description": "Representação de incorporação vetorial."
 },
 {
 "name": "timestamp",
 "dataType": ["date"],
 "description": "Quando a memória foi armazenada."
 }
 ],
 "vectorizer": "none" # Iremos injetar as incorporações nós mesmos
 }
 ]
}

client.schema.delete_all() # Limpar o esquema
client.schema.create(schema)

Por que não usar um vetorizar? O principal erro que iniciantes cometem é usar cegamente os vetores de texto padrão do Weaviate. Isso é bom para uma pesquisa de texto simples, mas quando você quer um controle rigoroso sobre seu modelo de incorporação (por exemplo, OpenAI, Cohere), você deve carregar os vetores você mesmo. Isso evita a confusão de tutoriais concorrentes que abusam dos vetores incorporados do Weaviate para agentes.

Excluir o esquema antes de criar força um novo começo, o que o protege de erros estranhos como “o esquema já existe”. Certamente, isso apaga dados, mas é parte do desenvolvimento local.

“`

Passo 3: Gerar e Baixar as Incorporações de Memória

import os
import requests
from datetime import datetime

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

def get_openai_embedding(text):
 resp = requests.post(
 "https://api.openai.com/v1/embeddings",
 headers={"Authorization": f"Bearer {OPENAI_API_KEY}"},
 json={"input": text, "model": "text-embedding-ada-002"}
 )
 resp.raise_for_status()
 return resp.json()["data"][0]["embedding"]

def add_memory_entry(client, text):
 embedding = get_openai_embedding(text)
 memory_obj = {
 "text": text,
 "embedding": embedding,
 "timestamp": datetime.utcnow().isoformat()
 }
 client.data_object.create(memory_obj, "MemoryEntry", vector=embedding)

# Exemplo de uso
add_memory_entry(client, "Eu me lembro que o céu é azul.")
add_memory_entry(client, "O sentido da vida é 42.")

Por que gerar as incorporações você mesmo? Porque é extremamente valioso desacoplar a geração de incorporações e o armazenamento de vetores. Você pode precisar mudar seu modelo de incorporação mais tarde ou agregar vetores de diferentes fontes. Esses outros tutoriais misturam tudo e você fica preso.

Erro comum aqui: esquecer de passar a incorporação como parâmetro de vetor vector=embedding na chamada data_object.create. Se você esquecer isso, o Weaviate tentará vetorizá-lo automaticamente (e falhará porque configuramos vectorizer: none).

Passo 4: Consultar a Memória com uma Pesquisa Semântica

def query_memory(client, question, top_k=3):
 question_embedding = get_openai_embedding(question)
 near_vector = {"vector": question_embedding}
 response = client.query.get("MemoryEntry", ["text", "timestamp"])\
 .with_near_vector(near_vector)\
 .with_limit(top_k)\
 .do()
 results = response.get("data", {}).get("Get", {}).get("MemoryEntry", [])
 return results

# Teste isso
results = query_memory(client, "Qual é a cor do céu?")
for res in results:
 print(f"Memória: {res['text']} (armazenada em {res['timestamp']})")

Por que a pesquisa semântica? A pesquisa por palavras-chave na memória é inútil para agentes que precisam gerenciar conversas de múltiplas rodadas com consultas nuançadas. A verdadeira mágica reside na pesquisa de incorporação por “pensamentos semelhantes” sem sobreposição exata de palavras-chave.

A característica chave é como você mistura e associa essas consultas dinamicamente em tempo de execução para manter seu agente ciente do contexto sem ser sobrecarregado por memórias irrelevantes.

Passo 5: Conectar Seu Agente à Memória Weaviate

class MemoryAgent:
 def __init__(self, weaviate_client):
 self.client = weaviate_client

 def remember(self, text):
 add_memory_entry(self.client, text)

 def recall(self, question):
 return query_memory(self.client, question, top_k=5)

 def chat(self, question):
 memories = self.recall(question)
 # Concatenar simples para o prompt — substitua pelo seu modelo de prompt
 prompt_context = "\n".join([m["text"] for m in memories])
 prompt = f"Contexto:\n{prompt_context}\n\nPergunta: {question}\nResposta:"
 
 # Envie o prompt para o LLM (não coberto aqui)
 # Simulação:
 return f"Resposta simulada baseada nas memórias:\n{prompt}"

agent = MemoryAgent(client)
agent.remember("O agente foi criado em 20 de março de 2026.")
agent.remember("Python é a linguagem de programação reconhecida para IA.")

print(agent.chat("Quando o agente foi criado?"))

Por que esse design? Separar a gestão da memória da lógica de “chat” do agente é crucial. Eu odeio o código fortemente acoplado onde a gestão do contexto torna sua chamada de geração desordenada. Com este modelo, você acompanha, armazena e recorda de forma independente. Se você quiser mudar para um LLM melhor ou adicionar caching, isso é trivial.

Os Armadilhas Que Você Não Oirá em Outros Tutoriais

1. Confusão com o esquema. Muitos tutoriais passam rapidamente pelo design do esquema, mas se seu esquema estiver incorreto, seus vetores e metadados serão lixo. Você vai se arrepender de não ter incluído timestamps ou metadados como IDs de usuário para filtrar sua memória.
2. Os custos das incorporações contam. As incorporações OpenAI não são gratuitas. Se você adicionar milhares de memórias, espere uma conta alta. Agrupe sua geração para reduzir os custos e faça caching das incorporações de forma agressiva.
3. A memória excessiva mata o desempenho. Consultar um banco de dados vetorial com dezenas de milhares de entradas? Você verá picos de latência e resultados de recall ruidosos. Uma poda regular é necessária – uma dura, mas inevitável realidade.
4. Incompatibilidades de dimensões vetoriais. Se você trocar acidentalmente modelos de incorporação ou versões, seus vetores armazenados não corresponderão aos vetores de consulta. Você não obterá resultados ou corresponderá de forma enganosa. Sempre fixe a versão do seu modelo de incorporação no seu pipeline.
5. A consistência dos dados é um problema. Sem suporte a transações, gravações ou atualizações parciais podem deixar memórias pendentes sem contexto. Esse bug sutil pode assombrá-lo em produção, especialmente se você atualizar as memórias.

Exemplo Completo Funcional

import os
import requests
from datetime import datetime
import weaviate

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
WEAVIATE_URL = "http://localhost:8080"

def get_openai_embedding(text):
 r = requests.post(
 "https://api.openai.com/v1/embeddings",
 headers={"Authorization": f"Bearer {OPENAI_API_KEY}"},
 json={"input": text, "model": "text-embedding-ada-002"},
 )
 r.raise_for_status()
 return r.json()["data"][0]["embedding"]

client = weaviate.Client(WEAVIATE_URL)
client.schema.delete_all()

schema = {
 "classes": [
 {
 "class": "MemoryEntry",
 "description": "Armazena a memória do agente",
 "properties": [
 {"name": "text", "dataType": ["text"]},
 {"name": "embedding", "dataType": ["number[]"]},
 {"name": "timestamp", "dataType": ["date"]}
 ],
 "vectorizer": "none"
 }
 ]
}
client.schema.create(schema)

def add_memory(text):
 embedding = get_openai_embedding(text)
 data = {"text": text, "embedding": embedding, "timestamp": datetime.utcnow().isoformat()}
 client.data_object.create(data, "MemoryEntry", vector=embedding)

def query_memories(question, top_k=5):
 q_emb = get_openai_embedding(question)
 near_vector = {"vector": q_emb}
 res = client.query.get("MemoryEntry", ["text", "timestamp"])\
 .with_near_vector(near_vector).with_limit(top_k).do()
 return res.get("data", {}).get("Get", {}).get("MemoryEntry", [])

class Agent:
 def __init__(self, client):
 self.client = client

 def remember(self, text):
 add_memory(text)

 def chat(self, question):
 memories = query_memories(question)
 context = "\n".join([m["text"] for m in memories])
 prompt = f"Contexto:\n{context}\n\nPergunta: {question}\nResposta:"
 # Resposta fictícia
 return prompt

agent = Agent(client)
agent.remember("O céu é azul.")
agent.remember("A água ferve a 100 graus Celsius.")
print(agent.chat("Qual é a cor do céu?"))

O que fazer a seguir?

Após dominar a integração da memória Weaviate, seu próximo passo concreto é construir um pipeline de dimensionamento e atualização de memória. Isso significa avaliar periodicamente quais memórias estão obsoletas ou não relevantes e removê-las ou atualizá-las. Se você deixar a memória crescer descontroladamente, as respostas do seu agente vão desacelerar e se tornar inconsistentes.

Considere implementar um sistema de obsolescência baseado no tempo ou um ranking de importância das memórias para manter seu banco de dados enxuto. Isso afinará o foco do agente no que realmente importa.

FAQ

Por que devo desativar o vetorizar padrão do Weaviate?

Os vetorizadores integrados são adequados para demos simples, mas o vinculam ao seu modelo de incorporação específico e tornam as atualizações impossíveis. Você quer injetar suas próprias incorporações geradas a partir de modelos como o text-embedding-ada-002 da OpenAI, para controlar a qualidade dos vetores e os custos da API.

O que fazer se minhas consultas não retornam resultados?

Primeiro, confirme que as dimensões de seus embeddings correspondem. Os embeddings ada-002 da OpenAI são vetores de 1536 dimensões. Se seus vetores armazenados e seus vetores de consulta diferirem em dimensão, a busca por similaridade não retornará nada. Verifique também se o vetor de seu esquema é ‘none’ e que você está enviando explicitamente seus próprios vetores ao criar objetos.

Como gerenciar os custos de embedding com milhares de entradas de memória?

Batch embed seus dados em vez de chamadas únicas e armazene em cache os embeddings no disco ou Redis. O pré-processamento das novas informações offline também pode ajudar. Seja também estratégico sobre o que você armazena — armazene resumos, não conversas completas. Por fim, explore modelos open-source mais baratos, mas atenção à precisão.

Recomendações para Personas Desenvolvedores

Tipo de Desenvolvedor	Passos Recomendados
Pesquisador em IA	Integre Weaviate com embeddings de transformador personalizados e explore a busca híbrida combinando texto e similaridade de vetor.
Engenheiro Backend	Implemente a gestão do ciclo de vida da memória com tamanho automático, reconstrução de índice e rastreamento de durabilidade.
Desenvolvedor Full-Stack	Construa um painel UI para visualizar e gerenciar entradas de memória e conecte a memória Weaviate com sua interface de chat frontend.

Dados em 21 de março de 2026. Fontes: https://github.com/weaviate/weaviate, https://weaviate.io/product/integrations/mem0

Artigos Relacionados

• Melhore os LLM com Grafo de Conhecimentos Confiáveis: A Inovação de Qinggang Zhang
• Desbloqueie Sua Marca: Criando o Logo Perfeito de uma Rede Neural Convolucional
• Por Que Usar a Arquitetura de Agente IA

🕒 Published: April 5, 2026