README.md

---
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](https://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:

```bash
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

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

### 2. Instalar dependências

```bash
cd agent_memory
pip install -r requirements.txt
```

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

### 3. Configurar API key

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

### 4. Rodar

```bash
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