Melhores práticas de memória
Como estruturar memórias para recall eficaz — categorias, keys, tags, prioridades.
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" |
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_nameproject_synapse_statuspreference_communication_stylemistake_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:
{
"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
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% |
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
contextcom prioridade baixa)
Atualizando memórias
POST /memory com a mesma category + key atualiza a memória existente:
# 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")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
# 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):
# 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:
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:
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")