Skip to main content

API de Memória

intermediate 🤖 Compatível com LLM 3 min · 558 palavras Atualizado: 2026-06-27 Português

Referência completa dos 22 endpoints de memória: armazenar, recall, busca, busca semântica, sincronização, auditoria e mais.

Ler este artigo como: 📄 Texto simples ⚡ JSON 🤖 Formato LLM
Idioma: English中文हिन्दीEspañolFrançaisالعربيةPortuguêsРусский日本語DeutschItaliano한국어NederlandsPolskiTürkçeSvenskaTiếng ViệtไทยBahasa IndonesiaУкраїнська

API de Memória

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

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

Categorias

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

Categoria Caso de uso
identity Nome do usuário, papel, contato, preferências sobre si mesmo
preference Gostos, desgostos, estilo de trabalho, preferências de comunicação
fact Fatos verificáveis (detalhes de projeto, datas, URLs)
project Status de projeto, marcos, arquitetura
skill Coisas em que o usuário é bom
mistake Erros passados — evitar repetir
context Contexto relevante para a sessão
note Notas diversas

Prioridades

  • low — bom saber
  • normal — padrão
  • high — importante
  • critical — nunca esquecer (identidade do usuário, info jurídica)

Endpoints principais

GET /memory/recall

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

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

Resposta (text/plain):

Mind: Michael's Mind
Memories: 12 total (10 verified)

[001] identity (CRITICAL)
  user_name
  Michael Schäfer
  Tags: person, identity

...

POST /memory

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

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

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

GET /memory

Lista memórias com filtros opcionais.

# All memories (JSON)
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?limit=50&offset=0"

# Filter by category
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory?category=project"

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

PUT /memory/:id

Atualiza uma memória específica por ID.

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

DELETE /memory/:id

Exclui uma única memória.

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

Endpoints de busca

GET /memory/search

Busca em texto completo usando FTS5.

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

Sintaxe FTS5:

  • Múltiplas palavras = AND: docker swarm
  • Frase: "docker swarm"
  • Prefixo: docker*
  • Booleano: docker OR kubernetes
  • Excluir: docker -swarm

GET /memory/semantic-search

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

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

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

GET /memory/by-tag

Lista memórias por tag.

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

GET /memory/related/:id

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

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

Sync & Diff

GET /memory/diff

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

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

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

POST /memory/sync

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

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

Operações em massa

POST /memory/bulk-delete

Exclui várias memórias por ID.

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

POST /memory/embed-batch

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

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

GET /memory/embed-batch-status

Verifica o progresso da geração de embeddings.

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

Verificação

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

POST /memory/verify

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

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

POST /memory/unverify

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

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

GET /memory/unverified

Lista memórias aguardando verificação humana.

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

Estatísticas e auditoria

GET /memory/stats

Estatísticas agregadas para o mind atual.

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

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

GET /memory/audit

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

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

GET /memory/contradictions

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

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

GET /memory/expiring

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

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

Health e exportação

GET /memory/health

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

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

GET /memory/mind-export

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

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

POST /memory/compact

Compacta memórias similares (auto-resumo).

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

Próximos passos

← Voltar a Referência da API