{"title":"O modelo de memória","slug":"memory-model","category":"concepts","summary":"Como as memórias são estruturadas — categorias, keys, tags, prioridades, fontes, verificação.","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":737,"read_minutes":4,"lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# O modelo de memória\n\nO modelo de memória do Synapse é projetado para agentes LLM — estruturado o\nsuficiente para recall confiável, flexível o suficiente para qualquer domínio.\n\n## Anatomia de uma memória\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## Campos\n\n| Campo | Tipo | Obrigatório | Descrição |\n|-------|------|-------------|-----------|\n| `id` | string | auto | ID único (mem_xxx) |\n| `category` | enum | ✅ | Uma das 8 categorias |\n| `key` | string | ✅ | Identificador estável (usado para updates) |\n| `content` | string | ✅ | O conteúdo da memória (qualquer texto) |\n| `tags` | string[] | – | Para busca e filtragem |\n| `priority` | enum | – | low, normal, high, critical (padrão: normal) |\n| `source` | enum | auto | user, agent (quem armazenou) |\n| `verified` | bool | auto | Um humano verificou isso? |\n| `confidence` | float | – | 0.0 a 1.0 (padrão: 1.0 para user, 0.7 para agent) |\n| `expires_at` | timestamp | – | Quando esquecer esta memória |\n| `mind_id` | string | auto | Qual mind é dono disso |\n| `created_at` | timestamp | auto | Quando foi armazenada |\n| `updated_at` | timestamp | auto | Última modificação |\n\n## Categorias\n\nOito categorias cobrem os casos de uso comuns de agentes LLM:\n\n| Categoria | Finalidade | Exemplo de conteúdo |\n|-----------|------------|---------------------|\n| `identity` | Quem é o usuário | \"User is Michael Schäfer, software engineer in Berlin\" |\n| `preference` | Preferências do usuário | \"Prefers concise technical responses\" |\n| `fact` | Fatos verificáveis | \"Office is in Berlin, timezone Europe/Berlin\" |\n| `project` | Status de projeto | \"Synapse v1.5.0 deployed, working on v1.6.0 docs\" |\n| `skill` | Habilidades do usuário | \"Advanced Python, 10+ years\" |\n| `mistake` | Erros passados | \"Forgot to bump npm version — CI failed\" |\n| `context` | Contexto de sessão | \"Currently reviewing PR #42\" |\n| `note` | Notas diversas | \"Try Redis for caching next sprint\" |\n\n## Keys: identificadores estáveis\n\nO campo `key` é crítico — é como você atualiza memórias sem criar duplicatas.\n\n```python\n# First store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**Regras de key:**\n\n- Deve ser única dentro de (category, mind)\n- Use `snake_case`\n- Prefixe com a categoria para clareza: `preference_communication`, `mistake_npm_version`\n- Mantenha estável — não mude keys após a criação\n\n## Tags: para busca\n\nTags permitem filtragem e busca rápidas:\n\n```bash\n# Find all memories with tag \"docker\"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker\n```\n\n**Melhores práticas de tags:**\n\n- 2-5 tags por memória (não exagere)\n- Minúsculas para consistência\n- Use nomes de projeto, tópicos, tecnologias\n- Tags são case-insensitive\n\n## Níveis de prioridade\n\n| Prioridade | Quando usar | Comportamento de recall |\n|------------|-------------|-------------------------|\n| `critical` | Identidade, jurídico, irreversível | Sempre no topo do recall |\n| `high` | Projetos ativos, preferências-chave | Em destaque no recall |\n| `normal` | Maioria das memórias (padrão) | Ordem padrão de recall |\n| `low` | Efêmero, bom saber | Pode ser resumido |\n\n`/memory/recall` ordena por prioridade (critical primeiro), depois por\nrecenticidade.\n\n## Source: User vs Agent\n\nMemórias são marcadas com `source`:\n\n- `user` — armazenada por um humano (via JWT ou interface humana)\n- `agent` — armazenada por um agente LLM (via Mind Key)\n\nIsso afeta:\n\n- **Verificação:** memórias `user` são auto-verificadas, memórias `agent` não\n- **Confiança:** `user` padrão 1.0, `agent` padrão 0.7\n- **Recall:** `/memory/recall` marca memórias não verificadas com \"(unverified)\"\n\n> [!NOTE]\n> Trate memórias de source `agent` com ceticismo apropriado. Elas podem ser\n> inferidas ou presumidas em vez de diretamente declaradas pelo usuário.\n\n## Verificação\n\nO flag `verified` indica que um humano confirmou a memória:\n\n- Memórias `user`: auto-verificadas (`true`)\n- Memórias `agent`: padrão não verificadas (`false`)\n\nVerifique memórias via:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> Verificação requer JWT (auth humana), não Mind Key (auth de agente). Isso\n> garante que apenas humanos possam marcar memórias como verificadas.\n\n## Confiança\n\nO campo `confidence` (0.0 a 1.0) indica quão confiável é a memória:\n\n- 1.0 — diretamente declarada pelo usuário\n- 0.7 — inferida pelo agente\n- 0.5 — incerta, precisa verificação\n- 0.0 — explicitamente duvidosa\n\nDefina a confiança ao armazenar:\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## Expiração\n\nDefina `expires_at` para memórias sensíveis ao tempo:\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\nMemórias expiradas não são retornadas por `/memory/recall` (mas ainda existem\nno DB). Use `/memory/expiring?within=7d` para ver memórias expirando em breve.\n\n## Ciclo de vida da memória\n\n```\n ┌─────────────────┐\n │ Create │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Active │ ◀──── PUT /memory/:id (update)\n │ (in recall) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ Expired │ │ Verified │ │ Deleted │\n │ (in DB) │ │ (flag) │ │ (gone) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## Comportamento de recall\n\n`GET /memory/recall` retorna um resumo em texto puro otimizado para contexto de\nLLM:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- Ordenado por prioridade (critical → low), depois por recenticidade\n- Memórias não verificadas marcadas com `[unverified]`\n- Tags incluídas para contexto\n- Texto puro (sem necessidade de parsing JSON)\n\n## Próximos passos\n\n- [API de Memória](/docs/api/memory)\n- [Melhores práticas de memória](/docs/guides/memory-best-practices)\n- [Busca FTS5](/docs/concepts/fts5-search)\n","content_html":"

O modelo de memória

\n

O modelo de memória do Synapse é projetado para agentes LLM — estruturado o\nsuficiente para recall confiável, flexível o suficiente para qualquer domínio.

\n

Anatomia de uma memória

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

Campos

\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\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
CampoTipoObrigatórioDescrição
idstringautoID único (mem_xxx)
categoryenum✅Uma das 8 categorias
keystring✅Identificador estável (usado para updates)
contentstring✅O conteúdo da memória (qualquer texto)
tagsstring[]–Para busca e filtragem
priorityenum–low, normal, high, critical (padrão: normal)
sourceenumautouser, agent (quem armazenou)
verifiedboolautoUm humano verificou isso?
confidencefloat–0.0 a 1.0 (padrão: 1.0 para user, 0.7 para agent)
expires_attimestamp–Quando esquecer esta memória
mind_idstringautoQual mind é dono disso
created_attimestampautoQuando foi armazenada
updated_attimestampautoÚltima modificação
\n

Categorias

\n

Oito categorias cobrem os casos de uso comuns de agentes LLM:

\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
CategoriaFinalidadeExemplo de conteúdo
identityQuem é o usuário"User is Michael Schäfer, software engineer in Berlin"
preferencePreferências do usuário"Prefers concise technical responses"
factFatos verificáveis"Office is in Berlin, timezone Europe/Berlin"
projectStatus de projeto"Synapse v1.5.0 deployed, working on v1.6.0 docs"
skillHabilidades do usuário"Advanced Python, 10+ years"
mistakeErros passados"Forgot to bump npm version — CI failed"
contextContexto de sessão"Currently reviewing PR #42"
noteNotas diversas"Try Redis for caching next sprint"
\n

Keys: identificadores estáveis

\n

O campo key é crítico — é como você atualiza memórias sem criar duplicatas.

\n
# First store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

Regras de key:

\n\n

Tags: para busca

\n

Tags permitem filtragem e busca rápidas:

\n
# Find all memories with tag "docker"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker

Melhores práticas de tags:

\n\n

Níveis de prioridade

\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
PrioridadeQuando usarComportamento de recall
criticalIdentidade, jurídico, irreversívelSempre no topo do recall
highProjetos ativos, preferências-chaveEm destaque no recall
normalMaioria das memórias (padrão)Ordem padrão de recall
lowEfêmero, bom saberPode ser resumido
\n

/memory/recall ordena por prioridade (critical primeiro), depois por\nrecenticidade.

\n

Source: User vs Agent

\n

Memórias são marcadas com source:

\n\n

Isso afeta:

\n\n
Trate memórias de source `agent` com ceticismo apropriado. Elas podem ser\ninferidas ou presumidas em vez de diretamente declaradas pelo usuário.

Verificação

\n

O flag verified indica que um humano confirmou a memória:

\n\n

Verifique memórias via:

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
Verificação requer JWT (auth humana), não Mind Key (auth de agente). Isso\ngarante que apenas humanos possam marcar memórias como verificadas.

Confiança

\n

O campo confidence (0.0 a 1.0) indica quão confiável é a memória:

\n\n

Defina a confiança ao armazenar:

\n
{\n  "category": "preference",\n  "key": "prefers_dark_mode",\n  "content": "User seems to prefer dark mode (based on their IDE screenshots)",\n  "confidence": 0.5,\n  "source": "agent"\n}

Expiração

\n

Defina expires_at para memórias sensíveis ao tempo:

\n
{\n  "category": "context",\n  "key": "current_meeting_topic",\n  "content": "Discussing Q3 roadmap",\n  "expires_at": "2026-06-28T00:00:00Z"\n}

Memórias expiradas não são retornadas por /memory/recall (mas ainda existem\nno DB). Use /memory/expiring?within=7d para ver memórias expirando em breve.

\n

Ciclo de vida da memória

\n
                  ┌─────────────────┐\n                  │     Create      │\n                  │  POST /memory   │\n                  └────────┬────────┘\n                           │\n                           ▼\n                  ┌─────────────────┐\n                  │     Active      │ ◀──── PUT /memory/:id (update)\n                  │  (in recall)    │\n                  └────────┬────────┘\n                           │\n              ┌────────────┼────────────┐\n              │            │            │\n              ▼            ▼            ▼\n        ┌──────────┐ ┌──────────┐ ┌──────────┐\n        │ Expired  │ │ Verified │ │ Deleted  │\n        │ (in DB)  │ │ (flag)   │ │ (gone)   │\n        └──────────┘ └──────────┘ └──────────┘

Comportamento de recall

\n

GET /memory/recall retorna um resumo em texto puro otimizado para contexto de\nLLM:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

Próximos passos

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