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:

# 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.

// 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?"

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

{ "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

{ "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:

{ "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

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

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

Encontrar todos los errores de un dominio

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

Encontrar trabajo activo

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

Encontrar memorias sobre una tecnología

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

Mantenimiento de etiquetas

Revisión periódica

# 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:

# 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

Próximos pasos

• Mejores prácticas de memoria
• Búsqueda FTS5
• Workflow basado en tareas