Estratégia de tagueamento de memória
Como taguear memórias para busca e filtragem eficazes — o sistema de tagueamento que escala.
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:
# Without tags: search everything
GET /memory/search?q=docker
# With tags: filter by project + technology
GET /memory/search?q=deployment&tag=synapse&tag=dockerTags 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-sdkTags de tecnologia
Use nomes de tecnologia:
docker, kubernetes, postgres, fastify, react, typescriptTags de tópico
Use categorias de tópico:
deployment, ci-cd, auth, database, frontend, backend, securityTags de status
Use indicadores de status:
active, completed, blocked, deprecatedTags de tipo
Use indicadores de tipo:
decision, mistake, pattern, reference, todoRegras de tagueamento
Regra 1: 2-5 tags por memória
Poucas tags = descoberta ruim. Muitas = ruído.
// 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, MindKeyRegra 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, SYNAPSERegra 4: tagueie com intenção de busca
Pergunte: "Como vou buscar por essa memória?"
// 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=deploymentPadrões
Padrão 1: projeto + tópico
{ "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
{ "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:
{ "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
// 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
curl -H "Authorization: Bearer $KEY" \
".../memory/search?q=decision&tag=synapse"Encontrar todos os erros em um domínio
curl -H "Authorization: Bearer $KEY" \
".../memory/search?q=mistake&tag=deployment"Encontrar trabalho ativo
curl -H "Authorization: Bearer $KEY" \
".../memory/by-tag?tag=active"Encontrar memórias sobre uma tecnologia
curl -H "Authorization: Bearer $KEY" \
".../memory/search?q=postgres+performance&tag=database"Manutenção de tags
Revisão 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)")Mesclando tags
Se você tem tags inconsistentes (docker e Docker), mescle-as:
# 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)))