# Estrategia de etiquetado de memoria

Las etiquetas son el secreto de la recuperación de memoria escalable. Esta
guía muestra cómo etiquetar memorias para que las correctas vuelvan en el
momento adecuado.

## Por qué importan las etiquetas

Sin etiquetas, tiene una búsqueda plana de texto completo. Con etiquetas, tiene
navegación estructurada:

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

Las etiquetas habilitan:

- **Filtrado rápido** — `GET /memory/by-tag?tag=production`
- **Búsqueda acotada** — `?q=auth&tag=project-x`
- **Agrupación** — encuentra todas las memorias "mistake" de un proyecto
- **Referencias cruzadas** — memorias que comparten etiquetas están relacionadas

## Esquema de etiquetado

### Etiquetas de proyecto

Use nombres de proyecto como etiquetas:

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

### Etiquetas de tecnología

Use nombres de tecnología:

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

### Etiquetas de tema

Use categorías de tema:

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

### Etiquetas de estado

Use indicadores de estado:

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

### Etiquetas de tipo

Use indicadores de tipo:

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

## Reglas de etiquetado

### Regla 1: 2-5 etiquetas por memoria

Muy pocas etiquetas = poca descubribilidad. Demasiadas = ruido.

```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"] }
```

### Regla 2: Minúsculas, con guiones

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

### Regla 3: Use vocabulario consistente

Establezca un vocabulario de etiquetado y manténgalo:

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

# NOT: synapse_project, synapseProject, SYNAPSE
```

### Regla 4: Etiquete con intención de búsqueda

Pregúntese: "¿Cómo buscaré esta memoria?"

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

## Patrones

### Patrón 1: Proyecto + Tema

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

Búsqueda: `?tag=synapse` (todas las memorias del proyecto Synapse)
Búsqueda: `?tag=synapse&q=deployment` (memorias de deployment en Synapse)

### Patrón 2: Tipo + Dominio

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

Búsqueda: `?tag=mistake` (todos los errores)
Búsqueda: `?tag=mistake&q=deployment` (errores de deployment)

### Patrón 3: Jerárquico

Para subproyectos dentro de un proyecto:

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

Búsqueda: `?tag=synapse` (todo Synapse)
Búsqueda: `?tag=synapse-docs` (solo el subproyecto de docs)

### Patrón 4: Seguimiento de estado

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

### Encontrar todas las decisiones de un proyecto

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

### Encontrar todos los errores de un dominio

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

### Encontrar trabajo activo

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

### Encontrar memorias sobre una tecnología

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

## Mantenimiento de etiquetas

### Revisión 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)")
```

### Fusionar etiquetas

Si tiene etiquetas inconsistentes (`docker` y `Docker`), fúndalas:

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

## Mejores prácticas

> [!TIP]
> - **Establezca el vocabulario temprano** — etiquetas consistentes desde el día 1
> - **Etiquete con intención de búsqueda** — ¿cómo encontrará esto después?
> - **2-5 etiquetas es el punto óptimo** — muy pocas o demasiadas es malo
> - **Minúsculas + guiones** — `ci-cd` no `CI/CD`
> - **Revise periódicamente** — fusione duplicados, elimine las no usadas

## Próximos pasos

- [Mejores prácticas de memoria](/docs/guides/memory-best-practices)
- [Búsqueda FTS5](/docs/concepts/fts5-search)
- [Workflow basado en tareas](/docs/llm-cookbook/task-driven-workflow)