{"title":"API de Memória","slug":"memory","category":"api","summary":"Referência completa dos 22 endpoints de memória: armazenar, recall, busca, busca semântica, sincronização, auditoria e mais.","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":558,"read_minutes":3,"llm_context":"Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)\nALWAYS call GET /memory/recall at session start.\nPOST /memory with same category+key updates the existing memory.\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nSearch: GET /memory/search?q=... (FTS5 syntax: AND, OR, \"phrases\", prefix*)\nSemantic: GET /memory/semantic-search?q=... (slower, conceptual)\nSync: GET /memory/diff?since=TIMESTAMP (incremental sync)\nExport: GET /memory/mind-export (full JSON dump)\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# API de Memória\n\nA API de Memória é o coração do Synapse. Ela oferece 22 endpoints para\narmazenar, recuperar, buscar e gerenciar memórias estruturadas. Todos os\nendpoints requerem uma Mind Key para autenticação.\n\n> [!CRITICAL]\n> **Sempre chame `GET /memory/recall` no início de cada sessão.** Esta é a\n> única forma de reconstruir o contexto de sessões anteriores.\n\n## Categorias\n\nAs memórias estão organizadas em 8 categorias:\n\n| Categoria | Caso de uso |\n|-----------|-------------|\n| `identity` | Nome do usuário, papel, contato, preferências sobre si mesmo |\n| `preference` | Gostos, desgostos, estilo de trabalho, preferências de comunicação |\n| `fact` | Fatos verificáveis (detalhes de projeto, datas, URLs) |\n| `project` | Status de projeto, marcos, arquitetura |\n| `skill` | Coisas em que o usuário é bom |\n| `mistake` | Erros passados — evitar repetir |\n| `context` | Contexto relevante para a sessão |\n| `note` | Notas diversas |\n\n## Prioridades\n\n- `low` — bom saber\n- `normal` — padrão\n- `high` — importante\n- `critical` — nunca esquecer (identidade do usuário, info jurídica)\n\n## Endpoints principais\n\n### GET /memory/recall\n\nRetorna TODAS as memórias como texto puro otimizado para LLMs. Chame isso no\ninício de cada sessão.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\nResposta (text/plain):\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n...\n```\n\n### POST /memory\n\nArmazena uma nova memória ou atualiza uma existente (mesma categoria + key = atualização).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n }'\n```\n\nResposta: `{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\nLista memórias com filtros opcionais.\n\n```bash\n# All memories (JSON)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?limit=50&offset=0\"\n\n# Filter by category\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?category=project\"\n\n# Filter by tag\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?tag=docker\"\n```\n\n### PUT /memory/:id\n\nAtualiza uma memória específica por ID.\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Updated content\", \"priority\": \"high\"}'\n```\n\n### DELETE /memory/:id\n\nExclui uma única memória.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Endpoints de busca\n\n### GET /memory/search\n\nBusca em texto completo usando FTS5.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nSintaxe FTS5:\n\n- Múltiplas palavras = AND: `docker swarm`\n- Frase: `\"docker swarm\"`\n- Prefixo: `docker*`\n- Booleano: `docker OR kubernetes`\n- Excluir: `docker -swarm`\n\n### GET /memory/semantic-search\n\nBusca conceitual usando embeddings (mais lenta que FTS5, mas entende significado).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nRetorna memórias semanticamente similares à consulta, mesmo que nenhuma palavra-\n-chave corresponda. Útil para \"encontrar memórias sobre X\" quando X é descrito\nde outra forma.\n\n### GET /memory/by-tag\n\nLista memórias por tag.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/by-tag?tag=docker\"\n```\n\n### GET /memory/related/:id\n\nEncontra memórias relacionadas a uma memória específica (via tags compartilhadas).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## Sync & Diff\n\n### GET /memory/diff\n\nSincronização incremental — retorna memórias alteradas desde um timestamp.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\nResposta: `{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\nAplica um diff de outra instância (para sync auto-hospedado).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/sync \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"added\": [...], \"updated\": [...], \"deleted\": [...]}'\n```\n\n## Operações em massa\n\n### POST /memory/bulk-delete\n\nExclui várias memórias por ID.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n### POST /memory/embed-batch\n\nGera embeddings para memórias que ainda não os têm (para busca semântica).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n```\n\n### GET /memory/embed-batch-status\n\nVerifica o progresso da geração de embeddings.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Verificação\n\nMemórias têm um flag `verified`. Memórias armazenadas pelo agente vêm como não\nverificadas por padrão (`source=agent`); memórias armazenadas por humanos são\nverificadas (`source=user`).\n\n### POST /memory/verify\n\nMarca uma memória como verificada (requer JWT, não Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### POST /memory/unverify\n\nMarca uma memória como não verificada (requer JWT).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### GET /memory/unverified\n\nLista memórias aguardando verificação humana.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## Estatísticas e auditoria\n\n### GET /memory/stats\n\nEstatísticas agregadas para o mind atual.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\nRetorna: `{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\nLog de auditoria de todas as operações que alteram estado.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/audit?limit=100&action=store\"\n```\n\n### GET /memory/contradictions\n\nDetecta potenciais contradições nas memórias armazenadas.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\nLista memórias com datas de expiração se aproximando.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## Health e exportação\n\n### GET /memory/health\n\nHealth check rápido do sistema de memória.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/health\n```\n\n### GET /memory/mind-export\n\nExportação JSON completa de todas as memórias (para backup).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mind-export > backup.json\n```\n\n### POST /memory/compact\n\nCompacta memórias similares (auto-resumo).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/compact \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": true}'\n```\n\n## Próximos passos\n\n- [Quick Start para LLMs](/docs/getting-started/quick-start-llm)\n- [Melhores práticas de memória](/docs/guides/memory-best-practices)\n- [Busca FTS5](/docs/concepts/fts5-search)\n- [Busca semântica](/docs/concepts/semantic-search)\n","content_html":"

API de Memória

\n

A API de Memória é o coração do Synapse. Ela oferece 22 endpoints para\narmazenar, recuperar, buscar e gerenciar memórias estruturadas. Todos os\nendpoints requerem uma Mind Key para autenticação.

\n
**Sempre chame `GET /memory/recall` no início de cada sessão.** Esta é a\núnica forma de reconstruir o contexto de sessões anteriores.

Categorias

\n

As memórias estão organizadas em 8 categorias:

\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
CategoriaCaso de uso
identityNome do usuário, papel, contato, preferências sobre si mesmo
preferenceGostos, desgostos, estilo de trabalho, preferências de comunicação
factFatos verificáveis (detalhes de projeto, datas, URLs)
projectStatus de projeto, marcos, arquitetura
skillCoisas em que o usuário é bom
mistakeErros passados — evitar repetir
contextContexto relevante para a sessão
noteNotas diversas
\n

Prioridades

\n\n

Endpoints principais

\n

GET /memory/recall

\n

Retorna TODAS as memórias como texto puro otimizado para LLMs. Chame isso no\ninício de cada sessão.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/recall

Resposta (text/plain):

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n...

POST /memory

\n

Armazena uma nova memória ou atualiza uma existente (mesma categoria + key = atualização).

\n
curl -X POST https://synapse.schaefer.zone/memory \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n    "category": "fact",\n    "key": "user_name",\n    "content": "The user's name is Michael Schäfer",\n    "tags": ["person", "identity"],\n    "priority": "critical"\n  }'

Resposta: { "id": "mem_001", "status": "stored" }

\n

GET /memory

\n

Lista memórias com filtros opcionais.

\n
# All memories (JSON)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?limit=50&offset=0"\n\n# Filter by category\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?category=project"\n\n# Filter by tag\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

\n

Atualiza uma memória específica por ID.

\n
curl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"content": "Updated content", "priority": "high"}'

DELETE /memory/:id

\n

Exclui uma única memória.

\n
curl -X DELETE -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/mem_001

Endpoints de busca

\n

GET /memory/search

\n

Busca em texto completo usando FTS5.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/search?q=docker+swarm"

Sintaxe FTS5:

\n\n

GET /memory/semantic-search

\n

Busca conceitual usando embeddings (mais lenta que FTS5, mas entende significado).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration"

Retorna memórias semanticamente similares à consulta, mesmo que nenhuma palavra-\n-chave corresponda. Útil para "encontrar memórias sobre X" quando X é descrito\nde outra forma.

\n

GET /memory/by-tag

\n

Lista memórias por tag.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/by-tag?tag=docker"

GET /memory/related/:id

\n

Encontra memórias relacionadas a uma memória específica (via tags compartilhadas).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/related/mem_001

Sync & Diff

\n

GET /memory/diff

\n

Sincronização incremental — retorna memórias alteradas desde um timestamp.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/diff?since=1700000000"

Resposta: { "added": [...], "updated": [...], "deleted": [...] }

\n

POST /memory/sync

\n

Aplica um diff de outra instância (para sync auto-hospedado).

\n
curl -X POST https://synapse.schaefer.zone/memory/sync \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"added": [...], "updated": [...], "deleted": [...]}'

Operações em massa

\n

POST /memory/bulk-delete

\n

Exclui várias memórias por ID.

\n
curl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"ids": ["mem_001", "mem_002", "mem_003"]}'

POST /memory/embed-batch

\n

Gera embeddings para memórias que ainda não os têm (para busca semântica).

\n
curl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"limit": 100}'

GET /memory/embed-batch-status

\n

Verifica o progresso da geração de embeddings.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/embed-batch-status

Verificação

\n

Memórias têm um flag verified. Memórias armazenadas pelo agente vêm como não\nverificadas por padrão (source=agent); memórias armazenadas por humanos são\nverificadas (source=user).

\n

POST /memory/verify

\n

Marca uma memória como verificada (requer JWT, não Mind Key).

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"

POST /memory/unverify

\n

Marca uma memória como não verificada (requer JWT).

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n  -H "Authorization: Bearer YOUR_JWT"

GET /memory/unverified

\n

Lista memórias aguardando verificação humana.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/unverified?limit=100"

Estatísticas e auditoria

\n

GET /memory/stats

\n

Estatísticas agregadas para o mind atual.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/stats

Retorna: { "total": 12, "verified": 10, "unverified": 2, "by_category": {...}, "by_priority": {...} }

\n

GET /memory/audit

\n

Log de auditoria de todas as operações que alteram estado.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/audit?limit=100&action=store"

GET /memory/contradictions

\n

Detecta potenciais contradições nas memórias armazenadas.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/contradictions

GET /memory/expiring

\n

Lista memórias com datas de expiração se aproximando.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory/expiring?within=7d"

Health e exportação

\n

GET /memory/health

\n

Health check rápido do sistema de memória.

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/health

GET /memory/mind-export

\n

Exportação JSON completa de todas as memórias (para backup).

\n
curl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     https://synapse.schaefer.zone/memory/mind-export > backup.json

POST /memory/compact

\n

Compacta memórias similares (auto-resumo).

\n
curl -X POST https://synapse.schaefer.zone/memory/compact \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{"dry_run": true}'

Próximos passos

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