{"title":"Melhores práticas de memória","slug":"memory-best-practices","category":"guides","summary":"Como estruturar memórias para recall eficaz — categorias, keys, tags, prioridades.","audience":["human","llm"],"tags":["guide","memory","best-practices","patterns"],"difficulty":"intermediate","updated":"2026-06-27","word_count":661,"read_minutes":3,"lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Melhores práticas de memória\n\nA forma como você estrutura memórias determina quão úteis elas são. Este guia\ncobre padrões para categorizar, taguear e priorizar memórias para que o LLM\npossa recuperar a informação certa na hora certa.\n\n## Categorias: escolha a mais específica\n\n| Categoria | Usar para | Exemplo |\n|-----------|-----------|---------|\n| `identity` | Nome, papel, contato do usuário | `\"user_name\": \"Michael Schäfer\"` |\n| `preference` | Gostos, desgostos, estilo de trabalho | `\"communication\": \"Prefers concise responses\"` |\n| `fact` | Fatos verificáveis | `\"office_location\": \"Berlin, Germany\"` |\n| `project` | Status de projeto, decisões | `\"project_synapse\": \"v1.5.0 deployed\"` |\n| `skill` | Habilidades do usuário | `\"skill_python\": \"Advanced, 10+ years\"` |\n| `mistake` | Erros passados a evitar | `\"mistake_npm_version\": \"Always bump version\"` |\n| `context` | Contexto relevante para a sessão | `\"current_focus\": \"Working on docs system\"` |\n| `note` | Notas diversas | `\"note_idea\": \"Try Redis for caching\"` |\n\n> [!TIP]\n> Em caso de dúvida, use `fact` para info verificável e `note` para todo o\n> resto. Não categorize em excesso — melhor ter um `fact` claro do que um\n> `context` confuso.\n\n## Keys: identificadores significativos\n\nO campo `key` é o identificador da memória. Use keys significativas e estáveis:\n\n**Keys boas:**\n- `user_name`\n- `project_synapse_status`\n- `preference_communication_style`\n- `mistake_npm_version_bump`\n\n**Keys ruins:**\n- `mem_001` (não significativa)\n- `temp` (não descritiva)\n- `2026-06-27-note` (data não ajuda o recall)\n\n### Convenções de nomenclatura de keys\n\n- `snake_case` (minúsculas com underscores)\n- Prefixe com a categoria: `preference_*`, `project_*`, `mistake_*`\n- Use substantivos descritivos, não verbos\n- Mantenha abaixo de 50 caracteres\n\n## Tags: para busca e filtragem\n\nTags permitem filtragem e busca rápidas. Adicione 2-5 tags por memória:\n\n```json\n{\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.\",\n \"tags\": [\"synapse\", \"deployment\", \"status\", \"v1.5.0\"]\n}\n```\n\n### Padrões de tags\n\n- **Nomes de projeto**: `synapse`, `synapse-mcp`, `synapse-chat`\n- **Tópicos**: `deployment`, `ci`, `database`, `auth`\n- **Status**: `active`, `completed`, `blocked`\n- **Indicadores de prioridade**: `urgent`, `long-term`\n\n> [!NOTE]\n> Tags são case-insensitive. Use minúsculas para consistência.\n\n## Prioridades: seja realista\n\n| Prioridade | Usar para | % das memórias |\n|------------|-----------|-----------------|\n| `critical` | Identidade do usuário, info jurídica, decisões irreversíveis | ~5% |\n| `high` | Projetos ativos, preferências importantes | ~20% |\n| `normal` | Maioria dos fatos, notas, contexto | ~65% |\n| `low` | Efêmero, bom saber | ~10% |\n\n> [!WARNING]\n> Não marque tudo como `critical`. Se tudo é crítico, nada é. Reserve\n> `critical` para coisas que causariam dano real se esquecidas.\n\n## Quando armazenar vs não armazenar\n\n### Sempre armazene\n\n- Identidade do usuário (nome, email, papel)\n- Preferências de longo prazo\n- Decisões de projeto e racional\n- Erros passados e lições aprendidas\n- Compromissos assumidos com o usuário\n\n### Não armazene\n\n- Estado transitório (use variáveis em vez disso)\n- Histórico literal de conversa (o sistema de chat cuida disso)\n- Dados sensíveis (senhas, API keys)\n- Fatos facilmente deriváveis (data atual, conteúdo de arquivos)\n- Contexto efêmero (use categoria `context` com prioridade baixa)\n\n## Atualizando memórias\n\nPOST `/memory` com a mesma `category` + `key` atualiza a memória existente:\n\n```python\n# Initial store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Later: update with same key\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed. CI green.\", priority=\"high\")\n```\n\n> [!TIP]\n> Use keys estáveis para poder atualizar sem criar duplicatas. O LLM deve\n> refazer POST da mesma key conforme a info muda, não criar novas memórias.\n\n## Ciclo de vida da memória\n\n```\nCreate → Active → Stale → Archive → Delete\n```\n\n- **Create**: POST /memory com contexto completo\n- **Active**: Recall frequente, atualize conforme necessário\n- **Stale**: Ainda relevante, mas não usado ativamente (prioridade mais baixa?)\n- **Archive**: Defina prioridade como `low`, mantenha para referência histórica\n- **Delete**: DELETE /memory/:id quando não for mais relevante\n\n### Limpeza periódica\n\n```python\n# Find memories not updated in 90 days\nold_memories = requests.get(\n f\"{URL}/memory/search?q=*\",\n headers={\"Authorization\": f\"Bearer {KEY}\"}\n)\n\nfor mem in old_memories[\"results\"]:\n if is_stale(mem, days=90):\n # Either delete or lower priority\n if is_obsolete(mem):\n delete_memory(mem[\"id\"])\n else:\n update_memory(mem[\"id\"], priority=\"low\")\n```\n\n## Padrão: herança de memória\n\nPara contexto hierárquico (projeto → subprojeto → tarefa):\n\n```python\n# Parent project\nstore(\"project\", \"project_synapse\", \"Main Synapse project\", \n tags=[\"synapse\", \"parent\"], priority=\"high\")\n\n# Sub-project (tags link to parent)\nstore(\"project\", \"project_synapse_docs\", \"Docs system for Synapse\",\n tags=[\"synapse\", \"docs\", \"synapse-parent\"], priority=\"high\")\n\n# Specific task (tags link to sub-project)\nstore(\"project\", \"task_docs_loader\", \"Implement docs-loader.ts\",\n tags=[\"synapse\", \"docs\", \"task\"], priority=\"normal\")\n```\n\nO LLM pode então buscar `q=synapse+docs` para encontrar todas as memórias\nrelacionadas.\n\n## Padrão: log de decisões\n\nArmazene decisões com racional para que o LLM não as rediscuta:\n\n```python\nstore(\"fact\", \"decision_postgres_over_sqlite\",\n \"Chose PostgreSQL over SQLite for production. Reason: concurrent writes, \"\n \"FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.\",\n tags=[\"decision\", \"database\", \"postgres\", \"sqlite\"],\n priority=\"high\")\n```\n\n## Padrão: evitar erros\n\nArmazene erros com instruções específicas de evitação:\n\n```python\nstore(\"mistake\", \"mistake_forget_version_bump\",\n \"Forgot to bump package.json version after changes. npm publish failed. \"\n \"FIX: Always run `npm version patch` before pushing. \"\n \"CI fails with 'version already exists' if you forget.\",\n tags=[\"npm\", \"ci\", \"publish\", \"version\"],\n priority=\"high\")\n```\n\n## Antipadrões a evitar\n\n> [!WARNING]\n> - **Armazenar logs de conversa** — o sistema de chat cuida disso\n> - **Armazenar arquivos inteiros** — use script store ou armazenamento externo\n> - **Armazenar estado efêmero** — use variáveis\n> - **Armazenar segredos** — use variáveis de ambiente\n> - **Duplicar memórias** — use keys estáveis\n> - **Taguear em excesso** — 2-5 tags por memória é o ideal\n> - **Tudo é crítico** — seja realista com prioridades\n\n## Próximos passos\n\n- [API de Memória](/docs/api/memory)\n- [Agente LLM persistente](/docs/guides/persistent-llm-agent)\n- [Estratégia de tagueamento de memória](/docs/llm-cookbook/memory-tagging-strategy)\n","content_html":"

Melhores práticas de memória

\n

A forma como você estrutura memórias determina quão úteis elas são. Este guia\ncobre padrões para categorizar, taguear e priorizar memórias para que o LLM\npossa recuperar a informação certa na hora certa.

\n

Categorias: escolha a mais específica

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CategoriaUsar paraExemplo
identityNome, papel, contato do usuário"user_name": "Michael Schäfer"
preferenceGostos, desgostos, estilo de trabalho"communication": "Prefers concise responses"
factFatos verificáveis"office_location": "Berlin, Germany"
projectStatus de projeto, decisões"project_synapse": "v1.5.0 deployed"
skillHabilidades do usuário"skill_python": "Advanced, 10+ years"
mistakeErros passados a evitar"mistake_npm_version": "Always bump version"
contextContexto relevante para a sessão"current_focus": "Working on docs system"
noteNotas diversas"note_idea": "Try Redis for caching"
\n
Em caso de dúvida, use `fact` para info verificável e `note` para todo o\nresto. Não categorize em excesso — melhor ter um `fact` claro do que um\n`context` confuso.

Keys: identificadores significativos

\n

O campo key é o identificador da memória. Use keys significativas e estáveis:

\n

Keys boas:

\n\n

Keys ruins:

\n\n

Convenções de nomenclatura de keys

\n\n

Tags: para busca e filtragem

\n

Tags permitem filtragem e busca rápidas. Adicione 2-5 tags por memória:

\n
{\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system.",\n  "tags": ["synapse", "deployment", "status", "v1.5.0"]\n}

Padrões de tags

\n\n
Tags são case-insensitive. Use minúsculas para consistência.

Prioridades: seja realista

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
PrioridadeUsar para% das memórias
criticalIdentidade do usuário, info jurídica, decisões irreversíveis~5%
highProjetos ativos, preferências importantes~20%
normalMaioria dos fatos, notas, contexto~65%
lowEfêmero, bom saber~10%
\n
Não marque tudo como `critical`. Se tudo é crítico, nada é. Reserve\n`critical` para coisas que causariam dano real se esquecidas.

Quando armazenar vs não armazenar

\n

Sempre armazene

\n\n

Não armazene

\n\n

Atualizando memórias

\n

POST /memory com a mesma category + key atualiza a memória existente:

\n
# Initial store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Later: update with same key\nstore("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\nrefazer POST da mesma key conforme a info muda, não criar novas memórias.

Ciclo de vida da memória

\n
Create → Active → Stale → Archive → Delete
\n

Limpeza periódica

\n
# Find memories not updated in 90 days\nold_memories = requests.get(\n    f"{URL}/memory/search?q=*",\n    headers={"Authorization": f"Bearer {KEY}"}\n)\n\nfor mem in old_memories["results"]:\n    if is_stale(mem, days=90):\n        # Either delete or lower priority\n        if is_obsolete(mem):\n            delete_memory(mem["id"])\n        else:\n            update_memory(mem["id"], priority="low")

Padrão: herança de memória

\n

Para contexto hierárquico (projeto → subprojeto → tarefa):

\n
# Parent project\nstore("project", "project_synapse", "Main Synapse project", \n      tags=["synapse", "parent"], priority="high")\n\n# Sub-project (tags link to parent)\nstore("project", "project_synapse_docs", "Docs system for Synapse",\n      tags=["synapse", "docs", "synapse-parent"], priority="high")\n\n# Specific task (tags link to sub-project)\nstore("project", "task_docs_loader", "Implement docs-loader.ts",\n      tags=["synapse", "docs", "task"], priority="normal")

O LLM pode então buscar q=synapse+docs para encontrar todas as memórias\nrelacionadas.

\n

Padrão: log de decisões

\n

Armazene decisões com racional para que o LLM não as rediscuta:

\n
store("fact", "decision_postgres_over_sqlite",\n      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "\n      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",\n      tags=["decision", "database", "postgres", "sqlite"],\n      priority="high")

Padrão: evitar erros

\n

Armazene erros com instruções específicas de evitação:

\n
store("mistake", "mistake_forget_version_bump",\n      "Forgot to bump package.json version after changes. npm publish failed. "\n      "FIX: Always run `npm version patch` before pushing. "\n      "CI fails with 'version already exists' if you forget.",\n      tags=["npm", "ci", "publish", "version"],\n      priority="high")

Antipadrões a evitar

\n

Próximos passos

\n\n","urls":{"html":"/docs/guides/memory-best-practices","text":"/docs/guides/memory-best-practices?format=text","json":"/docs/guides/memory-best-practices?format=json","llm":"/docs/guides/memory-best-practices?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}