# Melhores práticas de memória

A forma como você estrutura memórias determina quão úteis elas são. Este guia
cobre padrões para categorizar, taguear e priorizar memórias para que o LLM
possa recuperar a informação certa na hora certa.

## Categorias: escolha a mais específica

| Categoria | Usar para | Exemplo |
|-----------|-----------|---------|
| `identity` | Nome, papel, contato do usuário | `"user_name": "Michael Schäfer"` |
| `preference` | Gostos, desgostos, estilo de trabalho | `"communication": "Prefers concise responses"` |
| `fact` | Fatos verificáveis | `"office_location": "Berlin, Germany"` |
| `project` | Status de projeto, decisões | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Habilidades do usuário | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Erros passados a evitar | `"mistake_npm_version": "Always bump version"` |
| `context` | Contexto relevante para a sessão | `"current_focus": "Working on docs system"` |
| `note` | Notas diversas | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> Em caso de dúvida, use `fact` para info verificável e `note` para todo o
> resto. Não categorize em excesso — melhor ter um `fact` claro do que um
> `context` confuso.

## Keys: identificadores significativos

O campo `key` é o identificador da memória. Use keys significativas e estáveis:

**Keys boas:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Keys ruins:**
- `mem_001` (não significativa)
- `temp` (não descritiva)
- `2026-06-27-note` (data não ajuda o recall)

### Convenções de nomenclatura de keys

- `snake_case` (minúsculas com underscores)
- Prefixe com a categoria: `preference_*`, `project_*`, `mistake_*`
- Use substantivos descritivos, não verbos
- Mantenha abaixo de 50 caracteres

## Tags: para busca e filtragem

Tags permitem filtragem e busca rápidas. Adicione 2-5 tags por memória:

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",
  "tags": ["synapse", "deployment", "status", "v1.5.0"]
}
```

### Padrões de tags

- **Nomes de projeto**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Tópicos**: `deployment`, `ci`, `database`, `auth`
- **Status**: `active`, `completed`, `blocked`
- **Indicadores de prioridade**: `urgent`, `long-term`

> [!NOTE]
> Tags são case-insensitive. Use minúsculas para consistência.

## Prioridades: seja realista

| Prioridade | Usar para | % das memórias |
|------------|-----------|-----------------|
| `critical` | Identidade do usuário, info jurídica, decisões irreversíveis | ~5% |
| `high` | Projetos ativos, preferências importantes | ~20% |
| `normal` | Maioria dos fatos, notas, contexto | ~65% |
| `low` | Efêmero, bom saber | ~10% |

> [!WARNING]
> Não marque tudo como `critical`. Se tudo é crítico, nada é. Reserve
> `critical` para coisas que causariam dano real se esquecidas.

## Quando armazenar vs não armazenar

### Sempre armazene

- Identidade do usuário (nome, email, papel)
- Preferências de longo prazo
- Decisões de projeto e racional
- Erros passados e lições aprendidas
- Compromissos assumidos com o usuário

### Não armazene

- Estado transitório (use variáveis em vez disso)
- Histórico literal de conversa (o sistema de chat cuida disso)
- Dados sensíveis (senhas, API keys)
- Fatos facilmente deriváveis (data atual, conteúdo de arquivos)
- Contexto efêmero (use categoria `context` com prioridade baixa)

## Atualizando memórias

POST `/memory` com a mesma `category` + `key` atualiza a memória existente:

```python
# Initial store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Later: update with same key
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Use keys estáveis para poder atualizar sem criar duplicatas. O LLM deve
> refazer POST da mesma key conforme a info muda, não criar novas memórias.

## Ciclo de vida da memória

```
Create → Active → Stale → Archive → Delete
```

- **Create**: POST /memory com contexto completo
- **Active**: Recall frequente, atualize conforme necessário
- **Stale**: Ainda relevante, mas não usado ativamente (prioridade mais baixa?)
- **Archive**: Defina prioridade como `low`, mantenha para referência histórica
- **Delete**: DELETE /memory/:id quando não for mais relevante

### Limpeza periódica

```python
# Find memories not updated in 90 days
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Padrão: herança de memória

Para contexto hierárquico (projeto → subprojeto → tarefa):

```python
# Parent project
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

O LLM pode então buscar `q=synapse+docs` para encontrar todas as memórias
relacionadas.

## Padrão: log de decisões

Armazene decisões com racional para que o LLM não as rediscuta:

```python
store("fact", "decision_postgres_over_sqlite",
      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "
      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",
      tags=["decision", "database", "postgres", "sqlite"],
      priority="high")
```

## Padrão: evitar erros

Armazene erros com instruções específicas de evitação:

```python
store("mistake", "mistake_forget_version_bump",
      "Forgot to bump package.json version after changes. npm publish failed. "
      "FIX: Always run `npm version patch` before pushing. "
      "CI fails with 'version already exists' if you forget.",
      tags=["npm", "ci", "publish", "version"],
      priority="high")
```

## Antipadrões a evitar

> [!WARNING]
> - **Armazenar logs de conversa** — o sistema de chat cuida disso
> - **Armazenar arquivos inteiros** — use script store ou armazenamento externo
> - **Armazenar estado efêmero** — use variáveis
> - **Armazenar segredos** — use variáveis de ambiente
> - **Duplicar memórias** — use keys estáveis
> - **Taguear em excesso** — 2-5 tags por memória é o ideal
> - **Tudo é crítico** — seja realista com prioridades

## Próximos passos

- [API de Memória](/docs/api/memory)
- [Agente LLM persistente](/docs/guides/persistent-llm-agent)
- [Estratégia de tagueamento de memória](/docs/llm-cookbook/memory-tagging-strategy)