Tutorial Supermemory: adicione memória persistente a agentes de IA

O que é Supermemory?

O Supermemory pode ser descrito como uma API de memória de IA para agentes. Quando você envia strings sobre seu usuário ao Supermemory, ele depois retorna uma visão compacta de quem é esse usuário e o que ele tem feito recentemente. Embedding, indexação e busca rodam dentro do Supermemory, então seu código de agente fica pequeno.

O benchmark LongMemEval testa o quão bem um sistema de memória responde a perguntas ao longo de um histórico longo de conversa. O Supermemory relembra 81,6% dos fatos corretos. O Zep, o próximo melhor sistema, marca 71,2% — uma diferença de 10 pontos que se traduz em aproximadamente 1 resposta correta extra a cada 10 perguntas do usuário. O repositório open-source tem mais de 22k estrelas no GitHub, outro sinal de uso real.

Memória vs. RAG

A maioria dos leitores que procuram uma ferramenta de memória para agentes já usou RAG antes. Ajuda colocar o Supermemory lado a lado com ela. RAG e memória resolvem problemas diferentes e muitas vezes convivem no mesmo agente.

Um sistema RAG aponta para um corpus de documentos que o desenvolvedor prepara uma vez. Manuais de produto, artigos de suporte, docs internos. O corpus é carregado no deploy, consultado em runtime e raramente muda. O agente o usa para responder perguntas cujas respostas o próprio produto já conhece.

Um sistema de memória aponta para o usuário. O Supermemory grava fatos específicos do usuário conforme o agente conversa com ele, e o acervo cresce a cada interação. O agente usa isso para responder perguntas que só o usuário pode responder, como preferências, histórico e atividade recente.

Em um produto real, os dois rodam lado a lado. RAG sobre a base de conhecimento da empresa responde "qual é nossa política de reembolso?". O Supermemory sobre o usuário responde "quanto foi meu supino na semana passada?". Mesmo agente, dois repositórios de dados, dois trabalhos.

Perfis de usuário: fatos estáticos e dinâmicos

A ideia central do Supermemory é o perfil do usuário. Cada log é classificado em dois blocos: fatos estáticos, que raramente mudam, e fatos dinâmicos sobre a atividade atual. Padrões recorrentes sobem para o estático. Atividade recente fica no dinâmico.

Quando o agente lê o perfil, uma chamada retorna os dois blocos mais os trechos de memória correspondentes.

A divisão importa porque fatos estáticos e dinâmicos respondem a perguntas diferentes sobre o mesmo usuário:

Leia a primeira linha. O lado estático diz como o usuário treina: em casa, com o equipamento que tem. Isso não muda de semana a semana. O lado dinâmico diz no que ele está trabalhando agora: membros superiores, neste ciclo.

Um gerador de treinos precisa de ambos. O estático elimina exercícios exclusivos de academia; o dinâmico escolhe a sessão de hoje.

Por trás desse perfil, o Supermemory faz quatro trabalhos que você teria que construir. Ele armazena memórias brutas, gera embeddings de cada trecho, roda busca por similaridade na leitura e extrai fatos de perfil a partir do conteúdo registrado. Nada disso aparece no seu código.

Cada memória é etiquetada com uma string escolhida pelo desenvolvedor. Cada leitura envia a mesma string de volta para limitar o que sai. O treinador fixa uma tag porque um usuário basta para mostrar o que o perfil faz. Apps reais calculam a tag a partir do usuário autenticado, como o JWT dele.

Configurando seu ambiente Supermemory

O treinador precisa de duas chaves de API (Supermemory e OpenAI) e um projeto Python com três dependências. Um script rápido de ida e volta comprova que as duas chaves funcionam antes de qualquer código de agente chegar perto delas.

Obtendo suas chaves de API

A chave de API do Supermemory fica em console.supermemory.ai, NÃO em app.supermemory.ai. O subdomínio app é o produto de memória para consumidores (para salvar notas e navegar seu espaço). Ele não tem página de chave de API. Ignore-o e vá direto para o console.

No console.supermemory.ai:

1. Faça login.

2. Clique em API Keys na barra lateral.

3. Clique em Create API Key.

4. Dê um nome (o demo usa datacamp-tutorial).

5. Copie a chave gerada. Ela começa com sm_.

Você também precisa de uma chave da OpenAI para as chamadas de LLM do agente. Pegue uma em platform.openai.com/api-keys se ainda não tiver.

Crie um arquivo .env na raiz do projeto com as duas chaves. Não faça commit dele.

SUPERMEMORY_API_KEY=sm_your_key_here
OPENAI_API_KEY=sk-your_key_here

O plano gratuito do Supermemory cobre este tutorial sem informar pagamento. Limites exatos estão na página de preços.

Instalando dependências

O tutorial usa uv para configuração e execução do projeto. Se você não tiver o uv, instale-o uma vez com o one-liner de astral.sh/uv.

Inicialize o projeto:

uv init supermemory-trainer
cd supermemory-trainer

Apague o README.md gerado automaticamente pelo uv init. O hello.py gerado será sobrescrito no próximo passo, então deixe como está por enquanto.

Adicione três dependências:

• supermemory==3.37.0 é o cliente de memória, fixado na versão verificada para este tutorial.

• openai-agents é o OpenAI Agents SDK. O nome do pacote tem hífen; o caminho de import é agents.

• python-dotenv lê o arquivo .env que você acabou de criar.

uv add supermemory==3.37.0 openai-agents python-dotenv

O pyproject.toml resultante:

[project]
name = "supermemory-trainer"
version = "0.1.0"
description = "Personal exercise trainer agent built with Supermemory and the OpenAI Agents SDK."
requires-python = ">>=3.10"
dependencies = [
	"openai-agents>=0.10.2",
	"python-dotenv>=1.2.1",
	"supermemory==3.37.0",
]

Verificando sua configuração

Antes de escrever qualquer código de agente, veja o Supermemory fazer seu trabalho uma vez com uma única frase. O script abaixo envia um fato ao Supermemory, espera o pipeline e depois lê o perfil de volta. Se isso rodar sem erros, as chaves funcionam e o SDK está acessível. A saída também dá um primeiro olhar sobre o que o Supermemory faz com texto bruto.

Abra o hello.py na raiz do projeto e substitua o corpo gerado pelos imports e uma chamada de escrita:

import time
 
from dotenv import load_dotenv
from supermemory import Supermemory
 
load_dotenv()
 
client = Supermemory()
USER_ID = "demo_warmup"
 
response = client.add(
	content="The user is learning Supermemory by building a personal trainer agent.",
	container_tag=USER_ID,
)
print(f"client.add() -> id={response.id} status={response.status}")

load_dotenv() lê a chave de API do .env para o ambiente antes de construir Supermemory(). O cliente capta SUPERMEMORY_API_KEY automaticamente. O valor container_tag="demo_warmup" delimita esse único fato a um usuário descartável.

Agora adicione a espera e a leitura ao final do mesmo arquivo:

print("Waiting 20 seconds for processing...")
time.sleep(20)
 
prof = client.profile(container_tag=USER_ID, q="learning")
print(f"profile.static  ({len(prof.profile.static)}): {prof.profile.static}")
print(f"profile.dynamic ({len(prof.profile.dynamic)}): {prof.profile.dynamic}")
print(f"search_results.results ({len(prof.search_results.results)}):")
for r in prof.search_results.results[:3]:
	print(f"  - {r['memory']} (similarity={r['similarity']:.3f})")

Os 20 segundos de espera dão tempo para o pipeline de embedding e extração do Supermemory processar a nova memória. Sem isso, a leitura não retorna nada e o script parece quebrado quando não está.

Execute o arquivo:

uv run python hello.py

Saída esperada:

client.add() -> id=zNLsJBrY1PZupAeZ3Qn6EL status=queued
Waiting 20 seconds for processing...
profile.static  (0): []
profile.dynamic (1): ['Building a personal trainer agent to learn Supermemory.']
search_results.results (1):
  - Building a personal trainer agent to learn Supermemory. (similarity=0.650)

Três detalhes importam nessa saída. client.add() retorna imediatamente com status="queued", já que o Supermemory processa documentos assincronamente. A espera de 20 segundos cobre o pipeline de embedding e extração. Quando a leitura roda, a frase bruta já virou um trecho de memória pesquisável.

A linha interessante é profile.dynamic. A entrada foi a frase "The user is learning Supermemory by building a personal trainer agent.". A saída é o fato dinâmico 'Building a personal trainer agent to learn Supermemory.'. O Supermemory reescreveu uma frase em terceira pessoa em um fato em primeira pessoa sobre o usuário. É o extrator de perfil fazendo seu trabalho.

profile.static é uma lista vazia. Fatos estáticos se consolidam lentamente, depois que um punhado de logs relacionados se acumula, então uma única escrita de aquecimento não produz um. A ferramenta de sugestão do treinador considera static como bônus, não garantia.

Construindo um agente com Supermemory: treinador pessoal de exercícios em Python

O treinador encapsula client.add() e client.profile() em duas ferramentas do agente, para que leituras e gravações aconteçam automaticamente conforme o usuário conversa. Histórico de treinos combina bem com memória. Equipamentos, lesões e cargas recentes não vivem nos dados de treinamento do LLM e se acumulam sessão a sessão.

Estrutura do projeto e o agente

O treinador é pequeno o suficiente para que todo o projeto caiba em dois arquivos Python mais o pyproject.toml que você já tem:

supermemory-trainer/
├── .env            	# suas chaves reais (gitignored)
├── .env.example    	# placeholders, no repositório
├── .gitignore
├── .python-version
├── main.py         	# definição do agente, prompt de sistema, loop REPL
├── pyproject.toml
└── tools.py        	# log_workout e suggest_next_session

tools.py guarda as duas ferramentas com memória que você vai escrever a seguir. log_workout grava um treino no Supermemory via client.add(). suggest_next_session lê o perfil do usuário via client.profile(). O main.py importa ambas e conecta o agente.

A maior parte do main.py é boilerplate do OpenAI Agents SDK. Uma frase no prompt de sistema faz o trabalho do Supermemory: todo fato sobre o usuário deve vir por meio de chamadas de ferramenta. O agente é instruído de que não tem memória própria. Essa única regra é o que torna o treinador suportado por memória.

Abra o main.py e comece com os imports e o prompt de sistema:

import asyncio
 
from agents import Agent, Runner, SQLiteSession
 
from tools import log_workout, suggest_next_session
 
SYSTEM_PROMPT = """You are a personal exercise trainer who logs the user's
workouts and recommends what to do next.
 
You have no memory of the user's history on your own. Every fact about the
user lives in Supermemory and reaches you only through tool calls.
 
Two rules, no exceptions:
 
1. Whenever the user reports completing a workout, call log_workout immediately, before responding. Extract the exercise, sets, reps, weight, and any notes from what they said. If a value is missing, ask one short follow-up question instead of guessing. After logging, confirm in one short sentence and stop. Do NOT recommend the next session unless the user asks for one.
 
2. When the user explicitly asks what to do next (or asks for a recommendation, suggestion, or plan), call suggest_next_session first. Never recommend from your own training data. The tool returns the user's
 recent activity, stable preferences, and matching past sessions. Reference those facts directly in your reply.
 
Keep replies concise (2-4 sentences). Be specific: name the exercise, sets, reps, and weight. Honor any injuries or equipment constraints the tool surfaces.
"""

Ambas as regras no prompt de sistema encaminham o modelo pelo Supermemory.

A Regra 1 força uma escrita com log_workout sempre que o usuário relata um treino, para que cada treino chegue ao repositório de memória. A Regra 2 força uma leitura com suggest_next_session antes de qualquer recomendação, para que toda sugestão seja fundamentada no que o Supermemory sabe.

Sem essas regras, o agente responde do seu próprio conjunto de treinamento, o que anula o propósito da camada de memória.

Agora defina o agente e o loop de chat no mesmo arquivo:

def build_agent() -> Agent:
	return Agent(
    	name="Trainer",
    	instructions=SYSTEM_PROMPT,
    	tools=[log_workout, suggest_next_session],
    	model="gpt-5",
	)
 
 
async def chat() -> None:
	agent = build_agent()
	session = SQLiteSession(session_id="trainer-cli")
 
	print("Trainer ready. Type a message, or 'exit' to quit.\n")
	while True:
    	try:
        	message = input("You: ").strip()
    	except (EOFError, KeyboardInterrupt):
        	print()
        	break
    	if not message:
        	continue
    	if message.lower() in {"exit", "quit"}:
        	break
 
    	result = await Runner.run(agent, message, session=session)
    	print(f"\nTrainer: {result.final_output}\n")
 
 
if __name__ == "__main__":
	asyncio.run(chat())

Duas linhas merecem destaque. tools=[log_workout, suggest_next_session] registra as duas ferramentas com memória. O decorator @function_tool em cada uma (em tools.py) informa ao SDK que são chamáveis. Sem o decorator, o agente fica sem ferramentas em runtime, mesmo que a construção tenha sido bem-sucedida.

SQLiteSession(session_id="trainer-cli") mantém o histórico de curto prazo dentro do processo Python em execução. O Supermemory guarda os fatos de longo prazo do usuário entre processos. Encerrar o processo Python derruba a sessão SQLite, mas os dados do Supermemory permanecem.

Importante: execute o main.py como script, não em uma célula do Jupyter, pois o loop de eventos do Jupyter entra em conflito com asyncio.run(). O cliente síncrono Supermemory() funciona dentro de funções de ferramenta assíncronas porque o Agents SDK executa ferramentas em um thread pool. Para saber mais sobre o SDK, veja o tutorial do OpenAI Agents SDK.

Escrevendo a ferramenta de registro de treinos

log_workout é o lado de escrita da memória do agente. A função recebe argumentos estruturados do agente: nome do exercício, séries, repetições, carga e notas opcionais. Ela transforma isso em uma frase curta em inglês e entrega a frase ao Supermemory via client.add(). O pipeline de embedding e extração roda dentro do Supermemory depois disso e não precisa de nada do treinador.

Abra o tools.py e comece com os imports e um cliente compartilhado:

from agents import function_tool
from dotenv import load_dotenv
from supermemory import Supermemory
 
load_dotenv()
 
USER_ID = "demo_user"
 
client = Supermemory()

load_dotenv() roda no import para que SUPERMEMORY_API_KEY esteja no ambiente antes de construir Supermemory(). Se você construir o cliente antes de carregar o env, terá um cliente não autenticado. A primeira chamada então retorna um 401 confuso. As duas funções de ferramenta neste arquivo compartilham esse único cliente e a mesma constante USER_ID.

Adicione a ferramenta de log abaixo do cliente:

@function_tool
def log_workout(
	exercise: str,
	sets: int,
	reps: int,
	weight: float,
	notes: str = "",
) -> str:
	"""Log a completed workout to the user's memory.
 
	Args:
    	exercise: Name of the exercise.
    	sets: Number of sets performed.
    	reps: Number of reps per set.
    	weight: Weight in pounds. Pass 0 for bodyweight or cardio.
    	notes: Optional notes about the session.
	"""
	print(f"[log_workout] {exercise=} {sets=} {reps=} {weight=} {notes=}")
 
	content = f"Performed {exercise}: {sets} sets of {reps} reps at {weight} lbs."
	if notes:
    	content += f" Notes: {notes}"
 
	response = client.add(content=content, container_tag=USER_ID)
	print(f"[log_workout] -> id={response.id} status={response.status}")
	return f"Logged {exercise} ({sets}x{reps} @ {weight} lb)."

A docstring do @function_tool é o que o LLM vê ao decidir chamar a ferramenta. O bloco Args: mapeia para descrições por parâmetro. Ambos fazem parte do contrato do agente com a função.

A ferramenta envia uma frase em linguagem natural para client.add(), não JSON. O extrator de perfil do Supermemory lê linguagem natural e infere fatos a partir dela. JSON tecnicamente funciona, mas a qualidade da extração cai porque o modelo não tem uma narrativa para resumir. "Performed bench press: 4 sets of 5 reps at 185.0 lbs" dá ao extrator uma frase limpa para trabalhar.

As duas chamadas print() escrevem cada invocação da ferramenta no terminal: primeiro os argumentos parseados, depois a resposta.

[log_workout] exercise='bench press' sets=4 reps=5 weight=185.0 notes=''
[log_workout] -> id=xY7AK3qLzBPx5Vd2HnRf1M status=queued

O valor status="queued" bate com o que o script de aquecimento retornou. O log bruto está armazenado, mas client.profile() não o retornará como resultado de busca até o pipeline terminar. Você vai adicionar depois uma etapa de verificação que espera isso se estabilizar.

Escrevendo a ferramenta de sugestão de treino

suggest_next_session é o lado de leitura, e é onde a divisão estático-dinâmico se paga. Uma chamada client.profile(container_tag=USER_ID, q=focus) retorna três visões do usuário em uma única ida e volta.

Preferências estáveis vêm como profile.static, atividade atual como profile.dynamic e os trechos de memória mais próximos como search_results.results. O trabalho da ferramenta é achatar essas três visões em um bloco de contexto que o agente possa citar.

Após alguns treinos, a ferramenta produz algo assim:

Recent activity:
- Trains at home instead of a gym
- Performed deadlift: 3 sets of 5 reps at 225.0 lbs
- Performed 5k run in 26 minutes
- Reports no knee pain during bench press
- Performed bench press: 4 sets of 5 reps at 185.0 lbs
Closest matching past entries:
- Trains at home instead of a gym
- Performed deadlift: 3 sets of 5 reps at 225.0 lbs
- Performed bench press: 4 sets of 5 reps at 185.0 lbs
- Performed 5k run in 26 minutes
- Reports no knee pain during bench press

O agente lê esse bloco e escreve uma recomendação baseada no histórico real do usuário. Sem o perfil do Supermemory, você teria que montar o mesmo contexto. Isso significaria uma busca semântica separada, seu próprio store de perfil e a fusão dos resultados. A única chamada client.profile() substitui os três.

Adicione isto ao tools.py abaixo de log_workout:

@function_tool
def suggest_next_session(focus: str) -> str:
	"""Fetch the user's training history and preferences for a given focus.
 
	Returns a context string the agent can use to recommend the next session.
	The agent is responsible for the actual recommendation. This tool only
	surfaces what Supermemory knows about the user.
 
	Args:
    	focus: What the user wants to train next (e.g. "upper body", "legs",
        	"cardio", "today"). Drives semantic search against past logs.
	"""
	print(f"[suggest_next_session] focus={focus!r}")
	profile = client.profile(container_tag=USER_ID, q=focus)
 
	static_facts = profile.profile.static
	dynamic_facts = profile.profile.dynamic
	matches = profile.search_results.results
 
	print(
    	f"[suggest_next_session] static={len(static_facts)} "
    	f"dynamic={len(dynamic_facts)} matches={len(matches)}"
	)
 
	sections = []
	if static_facts:
    	sections.append("Stable preferences and constraints:")
    	sections.extend(f"- {fact}" for fact in static_facts)
	if dynamic_facts:
    	sections.append("Recent activity:")
    	sections.extend(f"- {fact}" for fact in dynamic_facts)
	if matches:
    	sections.append("Closest matching past entries:")
    	for r in matches[:5]:
        	sections.append(f"- {r['memory']}")
 
	if not sections:
    	return (
        	"No prior training history found for this user. "
        	"Ask the user about their goals, equipment, and recent training."
    	)
	return "\n".join(sections)

client.profile(container_tag=USER_ID, q=focus) retorna um objeto ProfileResponse. Depois de 5 logs curtos, os três campos que a ferramenta lê ficam assim:

profile.profile.static        	# [] (list[str])
profile.profile.dynamic       	# ["Performed bench press: 4 sets of 5 reps at 185.0 lbs", ...]
profile.search_results.results	# [{"memory": "...", "similarity": 0.631, ...}, ...] (list[dict])

Cada resultado de busca é um dict Python, não um objeto Pydantic. Use r["memory"] para o texto e r["similarity"] para a pontuação. O dict completo tem as seguintes chaves:

• id

• memory

• rootMemoryId

• metadata

• updatedAt

• version

• similarity

• filepath

• documents

O snippet r.memory or r.chunk da página de integração do Supermemory com o OpenAI Agents SDK levanta AttributeError na versão supermemory==3.37.0. Use acesso por colchetes.

static está vazio aqui, por isso a ferramenta ramifica com if static_facts:. Os blocos dynamic e search_results fazem o trabalho real nos primeiros registros.

O Supermemory também aplica um threshold de similaridade padrão. Um fato que você mencionou uma vez pode não voltar em toda consulta. Os 5 logs acima retornaram para q="today", mas uma query mais específica pode retornar menos. O if matches: lida com isso sem falhar.

Executando a sessão 1: registrando treinos

Inicie a sessão 1 e registre alguns treinos para preencher o Supermemory com algo para ler depois. Rode o script:

uv run python main.py

Registre supino, depois uma corrida de 5k, depois levantamento terra, além de uma preferência: "Eu só treino em casa, nada de academia." O agente dispara log_workout uma vez por treino, e as linhas de print() da ferramenta deixam cada chamada visível no terminal.

Saída de exemplo. A redação exata do seu agente pode variar porque o modelo é não determinístico.

As três linhas status=queued são o momento em que o Supermemory assume. Cada uma corresponde a um documento passando pelo pipeline de embedding e extração no lado do Supermemory. Para logs curtos como estes, o documento se torna pesquisável via client.profile() em cerca de 12 segundos.

Nada no código do treinador espera por isso. O agente segue, e o Supermemory termina o trabalho em background.

Cada log dispara exatamente uma chamada a log_workout, e o agente para. Nada de recomendações proativas, chamadas extras de ferramenta ou sugestões de acompanhamento. A primeira regra do prompt de sistema garante isso. Sem a regra, o agente sugeriria a próxima sessão após cada log, dobrando as chamadas.

Digite exit para fechar a sessão 1. O processo Python termina e a SQLiteSession vai junto. Os logs de treino e a declaração de preferência agora vivem no Supermemory sob container_tag="demo_user", separados do script que os escreveu.

Verificando o recall e executando a sessão 2

Antes da sessão 2, confirme que os fatos da sessão 1 são consultáveis. Abra um REPL Python novo ou salve isto como um script curto:

from dotenv import load_dotenv
from supermemory import Supermemory
 
load_dotenv()
client = Supermemory()
 
prof = client.profile(container_tag="demo_user", q="training")
print(f"static  ({len(prof.profile.static)}): {prof.profile.static}")
print(f"dynamic ({len(prof.profile.dynamic)}):")
for fact in prof.profile.dynamic:
	print(f"  - {fact}")
print(f"matches ({len(prof.search_results.results)}):")
for r in prof.search_results.results[:5]:
	print(f"  - {r['memory']} (similarity={r['similarity']:.3f})")

Saída real capturada entre as duas sessões:

static  (0): []
dynamic (5):
  - Trains at home instead of a gym
  - Performed deadlift: 3 sets of 5 reps at 225.0 lbs
  - Performed 5k run in 26 minutes
  - Reports no knee pain during bench press
  - Performed bench press: 4 sets of 5 reps at 185.0 lbs
matches (5):
  - Trains at home instead of a gym (similarity=0.682)
  - Performed deadlift: 3 sets of 5 reps at 225.0 lbs (similarity=0.643)
  - Performed bench press: 4 sets of 5 reps at 185.0 lbs (similarity=0.631)
  - Performed 5k run in 26 minutes (similarity=0.585)
  - Reports no knee pain during bench press (similarity=0.585)

Veja o que o extrator do Supermemory produziu. O usuário disse uma vez: "Eu só treino em casa, nada de academia". O extrator transformou isso no fato dinâmico "Trains at home instead of a gym".

O log do supino incluía uma nota sobre ausência de dor no joelho. O extrator dividiu esse único log em dois fatos dinâmicos: um para o treino, outro para a ausência de dor.

Quatro logs viraram cinco fatos dinâmicos normalizados mais cinco trechos de memória correspondentes, com scores de similaridade entre 0,585 e 0,682. Nenhuma dessa divisão, normalização ou correspondência rodou no código do treinador. Se o dynamic estiver vazio para você, espere mais 10 segundos e rode o snippet novamente. A fila de processamento às vezes sobe.

Agora inicie a sessão 2 em um processo novinho:

uv run python main.py

Este é um interpretador Python novo. Sem memória compartilhada com a sessão 1. Sem cache aquecido. Qualquer coisa que o agente lembrar vem do Supermemory.

Envie uma mensagem: "What should I do for my workout today?"

Saída de exemplo. Mesmo repositório de memória, processo Python novo.

O agente chama suggest_next_session("today"). A ferramenta imprime static=0 dynamic=5 matches=5. A execução capturada respondeu com uma sessão de membros inferiores em casa (agachamentos, avanços, step-ups).

A recomendação bateu com os logs anteriores porque o perfil do Supermemory contou ao agente quais foram. Supino, terra e um 5k foram membros superiores ou cardio, e o usuário só treinava em casa. Ambos os fatos vieram da mesma chamada client.profile(). Sua execução pode redigir diferente porque o modelo é não determinístico, mas o caminho de recall é o mesmo.

Próximos passos para seu agente com Supermemory

O demo é um usuário, duas ferramentas e uma CLI. Uma versão real do treinador se estende em três direções com a cara do Supermemory antes mesmo de tocar o loop do agente.

Delimite a memória por usuário real. A constante USER_ID = "demo_user" funciona para uma pessoa. Apps em produção calculam a tag a partir do ID do usuário autenticado, como container_tag="user_sarah" ou container_tag=customer_id. A memória entre usuários fica separada porque toda leitura envia a tag de volta. Uma mudança em tools.py, sem mexer no resto.

Adicione mais ferramentas apoiadas por memória. Semanas de deload, rastreamento de PR e lembretes semanais de mobilidade. Cada uma é outra função com @function_tool que chama client.add() para escrita e client.profile() para leitura contra o mesmo container_tag. O formato da ferramenta permanece. Só muda o que o agente registra e pede.

Trate falhas do Supermemory. Envolva client.add() e client.profile() em try/except supermemory.APIError para que falhas transitórias do Supermemory não derrubem o agente. Defina timeouts por requisição se seu agente rodar em ambiente restrito.

O lado do loop do agente é independente do Supermemory e pode mudar depois. Coloque a CLI na frente de Telegram, Discord ou Slack, para o usuário mandar o treino por texto e o bot chamar Runner.run(). Ou troque o framework. O Supermemory tem uma integração com LangChain se sua stack já usa agentes LangChain, e o código de memória não muda.

A divisão entre estático e dinâmico também se encaixa em outros domínios.

• Agente de suporte ao cliente: estático = problemas conhecidos e preferências de conta; dinâmico = tickets em aberto e contatos recentes.
• Agente de código: estático = linguagens e frameworks preferidos; dinâmico = tarefa atual e arquivos tocados recentemente.

A divisão funciona sempre que o usuário é a fonte da verdade.

Conclusão

Você acabou de construir um treinador em Python com duas ferramentas e memória persistente entre processos. client.add() grava treinos. client.profile() lê o usuário como fatos estáticos, fatos dinâmicos e correspondências semânticas em uma chamada, tudo delimitado por container_tag. O Supermemory faz o chunking, embedding, busca e extração de perfil que o demo não precisou escrever.

Combine com RAG, e o mesmo agente responde perguntas sobre o usuário e sobre o produto. LLM Agents Explained cobre padrões de agente mais amplos, e a trilha Associate AI Engineer for Developers aprofunda ainda mais em agentes com memória.