# Estratégia de tagueamento de memória

Tags são o segredo para recuperação de memória escalável. Este guia mostra como
taguear memórias para que as certas voltem no momento certo.

## Por que tags importam

Sem tags, você tem busca em texto completo plana. Com tags, você tem navegação
estruturada:

```bash
# Without tags: search everything
GET /memory/search?q=docker

# With tags: filter by project + technology
GET /memory/search?q=deployment&tag=synapse&tag=docker
```

Tags permitem:

- **Filtragem rápida** — `GET /memory/by-tag?tag=production`
- **Busca com escopo** — `?q=auth&tag=project-x`
- **Agrupamento** — encontre todas as memórias "mistake" de um projeto
- **Referência cruzada** — memórias que compartilham tags são relacionadas

## Esquema de tagueamento

### Tags de projeto

Use nomes de projeto como tags:

```
synapse, synapse-mcp, synapse-chat, synapse-sdk
```

### Tags de tecnologia

Use nomes de tecnologia:

```
docker, kubernetes, postgres, fastify, react, typescript
```

### Tags de tópico

Use categorias de tópico:

```
deployment, ci-cd, auth, database, frontend, backend, security
```

### Tags de status

Use indicadores de status:

```
active, completed, blocked, deprecated
```

### Tags de tipo

Use indicadores de tipo:

```
decision, mistake, pattern, reference, todo
```

## Regras de tagueamento

### Regra 1: 2-5 tags por memória

Poucas tags = descoberta ruim. Muitas = ruído.

```json
// Good: 3 relevant tags
{ "tags": ["synapse", "deployment", "docker"] }

// Bad: 1 tag (too narrow)
{ "tags": ["synapse"] }

// Bad: 10 tags (noise)
{ "tags": ["synapse", "deployment", "docker", "vps1", "2026", "june", "ssh", "git", "main", "production"] }
```

### Regra 2: minúsculas, hifenizadas

```
✅ ci-cd, api-key, mind-key
❌ CI-CD, APIKey, MindKey
```

### Regra 3: use vocabulário consistente

Estabeleça um vocabulário de tagueamento e mantenha-se nele:

```
# Project vocabulary
synapse, synapse-mcp, synapse-chat

# NOT: synapse_project, synapseProject, SYNAPSE
```

### Regra 4: tagueie com intenção de busca

Pergunte: "Como vou buscar por essa memória?"

```json
// Storing a deployment decision
{
  "content": "Decided to use Docker Swarm for Synapse deployment",
  "tags": ["synapse", "deployment", "docker", "swarm", "decision"]
}

// You'll likely search: ?q=docker+swarm or ?tag=deployment
```

## Padrões

### Padrão 1: projeto + tópico

```json
{ "tags": ["synapse", "deployment"] }
{ "tags": ["synapse", "auth"] }
{ "tags": ["synapse-mcp", "tools"] }
```

Busca: `?tag=synapse` (todas as memórias do projeto Synapse)
Busca: `?tag=synapse&q=deployment` (memórias de deployment no Synapse)

### Padrão 2: tipo + domínio

```json
{ "tags": ["mistake", "deployment"] }
{ "tags": ["decision", "database"] }
{ "tags": ["pattern", "auth"] }
```

Busca: `?tag=mistake` (todos os erros)
Busca: `?tag=mistake&q=deployment` (erros de deployment)

### Padrão 3: hierárquico

Para subprojetos dentro de um projeto:

```json
{ "tags": ["synapse", "synapse-docs", "markdown"] }
{ "tags": ["synapse", "synapse-mcp", "mcp"] }
{ "tags": ["synapse", "synapse-admin", "ui"] }
```

Busca: `?tag=synapse` (todo Synapse)
Busca: `?tag=synapse-docs` (apenas subprojeto de docs)

### Padrão 4: rastreamento de status

```json
// Active project
{ "tags": ["synapse", "active"], "priority": "high" }

// Completed project
{ "tags": ["synapse-v1", "completed"], "priority": "low" }

// Blocked
{ "tags": ["synapse-v2", "blocked"], "priority": "high" }
```

## Casos de uso comuns

### Encontrar todas as decisões sobre um projeto

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=decision&tag=synapse"
```

### Encontrar todos os erros em um domínio

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=mistake&tag=deployment"
```

### Encontrar trabalho ativo

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/by-tag?tag=active"
```

### Encontrar memórias sobre uma tecnologia

```bash
curl -H "Authorization: Bearer $KEY" \
     ".../memory/search?q=postgres+performance&tag=database"
```

## Manutenção de tags

### Revisão periódica

```python
# Find rarely-used tags (candidates for cleanup)
tags = requests.get(f"{URL}/memory/tags",
    headers={"Authorization": f"Bearer {KEY}"}).json()

for tag, count in tags.items():
    if count < 2:
        print(f"Rare tag: {tag} ({count} memories)")
```

### Mesclando tags

Se você tem tags inconsistentes (`docker` e `Docker`), mescle-as:

```python
# Find all memories with "Docker" tag
mems = requests.get(f"{URL}/memory/by-tag?tag=Docker",
    headers={"Authorization": f"Bearer {KEY}"}).json()

# Update each to use "docker" instead
for mem in mems["results"]:
    tags = [t.lower() for t in mem["tags"]]
    update_memory(mem["id"], tags=list(set(tags)))
```

## Melhores práticas

> [!TIP]
> - **Estabeleça vocabulário cedo** — tags consistentes desde o dia 1
> - **Tagueie com intenção de busca** — como você vai encontrar isso depois?
> - **2-5 tags é o ponto ideal** — poucas ou muitas é ruim
> - **Minúsculas + hífens** — `ci-cd` não `CI/CD`
> - **Revise periodicamente** — mescle duplicatas, remova não usadas

## Próximos passos

- [Melhores práticas de memória](/docs/guides/memory-best-practices)
- [Busca FTS5](/docs/concepts/fts5-search)
- [Workflow orientado por tarefas](/docs/llm-cookbook/task-driven-workflow)