05-04-01 — Memória: short-term, long-term, episodic, semantic

Mapa dos 4 tipos de memória

Short-term: a context window

É a memória ativa do agente — tudo que está no contexto da chamada atual ao LLM. Inclui o system prompt, histórico da conversa, resultados de ferramentas, e o estado atual.

• Capacidade: varia por modelo — GPT-4o: 128k tokens, Claude: até 200k tokens, Gemini: até 1M tokens.
• Custo: cada token no contexto é cobrado na chamada. Context window longa = custo mais alto.
• Limite prático: mesmo com 128k tokens disponíveis, modelos perdem qualidade com contextos muito longos ("lost in the middle" problem).

Long-term: persistência além do contexto

Armazenamento que persiste entre sessões. Recuperado via busca e injetado no contexto quando relevante.

from openai import OpenAI
import chromadb  # Vector DB local

client = OpenAI()
chroma = chromadb.Client()
collection = chroma.create_collection("agent_memory")

def remember(fact: str, metadata: dict):
    """Salva um fato na memória long-term"""
    embedding = client.embeddings.create(
        input=fact, model="text-embedding-3-small"
    ).data[0].embedding
    
    collection.add(
        embeddings=[embedding],
        documents=[fact],
        metadatas=[metadata],
        ids=[f"mem_{hash(fact)}"]
    )

def recall(query: str, n_results: int = 5) -> list[str]:
    """Recupera memórias relevantes para a query"""
    embedding = client.embeddings.create(
        input=query, model="text-embedding-3-small"
    ).data[0].embedding
    
    results = collection.query(
        query_embeddings=[embedding],
        n_results=n_results
    )
    return results["documents"][0]

# Uso no agente
relevant_memories = recall("preferências do cliente Vale")
context = f"Memórias relevantes:\n{chr(10).join(relevant_memories)}"

Episodic: histórico de sessões

Registro de interações passadas. Diferente de long-term por ser organizado cronologicamente e representar "o que aconteceu" (episódios), não apenas fatos.

import json
from datetime import datetime

class EpisodicMemory:
    def __init__(self, storage_path: str):
        self.path = storage_path
    
    def save_episode(self, session_id: str, conversation: list, outcome: str):
        episode = {
            "session_id": session_id,
            "timestamp": datetime.now().isoformat(),
            "conversation": conversation,
            "outcome": outcome,
            "tags": self._extract_tags(conversation)
        }
        # Salva em DB ou arquivo
        with open(f"{self.path}/{session_id}.json", "w") as f:
            json.dump(episode, f)
    
    def get_similar_episodes(self, current_task: str) -> list:
        # Busca episódios anteriores similares para aprender com eles
        # Na prática, usa embedding search no storage
        pass

Semantic: conhecimento estruturado

Fatos e relações sobre o domínio do agente. Pode ser um knowledge graph, um banco de fatos, ou regras de negócio estruturadas.

# Semantic memory como knowledge base estruturada
semantic_memory = {
    "clients": {
        "Vale": {
            "sector": "mineração",
            "erp": "SAP S/4HANA",
            "key_contacts": ["João Silva (CTO)", "Maria Santos (PMO)"],
            "contract_value": "R$ 2M/ano",
            "pain_points": ["integração legacy", "latência relatórios"]
        }
    },
    "products": {
        "SystemX": {
            "target_sectors": ["mineração", "siderurgia"],
            "integrations": ["SAP", "Oracle", "TOTVS"]
        }
    }
}

# O agente consulta isso como contexto fixo
# sem precisar buscar na web a cada vez

Estratégia de memória por caso de uso