README.md

metadata

title: Agent Memory
emoji: 🧠
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false

Agent Memory — Fase 1 (Baseline)

PoC de memória observável: chat à esquerda, armazém de memórias à direita.

Use case: bot de atendimento de provedor de internet/TV/telefonia que armazena falas de clientes (como foram ditas) para extrair aprendizados bons ou ruins e ajudar em conversas futuras — sem CRM, RAG ou integrações externas.

Estrutura

agent_memory/
├── main.py           # FastAPI app
├── agent.py          # Lógica do agente + OpenRouter API
├── memory_store.py   # ChromaDB + decay heurístico
├── models.py         # Pydantic models
├── seeds.py          # Memórias seed (falas de clientes fictícios)
├── requirements.txt
├── Dockerfile        # Deploy em Hugging Face Spaces
├── .env.example
└── static/
    └── index.html    # UI do armazém

Deploy no Hugging Face Spaces

1. Criar o Space

1. Acesse huggingface.co/new-space
2. Space name: ex. agent-memory
3. SDK: Docker
4. Hardware: CPU basic (grátis)
5. Visibility: Public ou Private

2. Conectar ao GitHub (recomendado)

Na aba Settings do Space:

1. Repository → conecte EriqueSouza/agent_memory (branch claude_agent ou main)
2. Faça push deste repositório com o Dockerfile e o frontmatter YAML no README.md

Ou faça push direto para o git do Space:

git remote add space https://huggingface.co/spaces/SEU_USUARIO/agent-memory
git push space claude_agent:main

3. Configurar secrets

Em Settings → Repository secrets do Space, adicione:

Secret	Valor
OPENROUTER_API_KEY	sua chave OpenRouter
OPENROUTER_MODEL	ex. nvidia/nemotron-3-super-120b-a12b
OPENROUTER_API_URL	https://openrouter.ai/api/v1

O Space reinicia automaticamente após salvar os secrets.

4. Acessar

URL pública: https://huggingface.co/spaces/SEU_USUARIO/agent-memory

A UI abre na raiz (/). O build inicial pode levar alguns minutos (download do modelo de embedding do ChromaDB).

Limitações no tier gratuito: disco efêmero — memórias criadas no chat somem se o Space reiniciar; os seeds são recarregados automaticamente.

---

Setup

1. Criar ambiente

conda create -n agent_memory python=3.11 -y
conda activate agent_memory

2. Instalar dependências

cd agent_memory
pip install -r requirements.txt

ChromaDB vai baixar um modelo de embedding (~80MB) na primeira execução.

3. Configurar API key

cp .env.example .env
# editar .env com sua OPENROUTER_API_KEY e OPENROUTER_MODEL

4. Rodar

python main.py

Abrir: http://localhost:8000

Se o armazém já foi populado com seeds de outro domínio, use o botão RESET na UI (ou POST /api/memories/reset) para recarregar os seeds de atendimento ISP.

---

Tipos de memória

Tipo	Cor	Decay/dia	Uso (neste use case)
episódica	azul	0.03	Situação específica que um cliente relatou
semântica	roxo	0.005	Padrão recorrente inferido de várias falas
estado	laranja	0.15	Algo que clientes disseram sobre condição atual (volátil)
procedimental	verde	0.002	Lição sobre o que ajudou ou irritou no atendimento

As memórias seed em seeds.py incluem de propósito relatos bons, ruins, contraditórios e desatualizados para exercitar o armazém observável.

Features da UI

• Chat com o agente em português (atendimento ISP)
• Armazém mostra todas as memórias como cards com barra de relevância
• Cards piscam (dourado) quando a memória foi usada na última resposta
• Cards novos entram com animação verde
• Clique no pill mem:id no chat para ir direto ao card no armazém
• Filtros por tipo + ordenação por data/relevância/acessos
• Botão ✕ para arquivar memórias individuais
• Botão RESET para voltar ao estado seed

---

Fase 2 (próximo)

• Scoring por Information Gain (Shannon entropy)
• Shannon Surprise para detecção de obsolescência
• Decay functions substituídas por cálculo entrópico
• Logits do modelo para distribuição de decisão
• Comparação experimental Fase 1 vs Fase 2