# DOCUMENTAÇÃO DO SYNAPSE — Referência completa
# Gerado em: 2026-07-18T06:14:48.771Z
# Total de artigos: 47
Este documento contém a documentação completa da API do Synapse.
Base URL: https://synapse.schaefer.zone
Language: pt
========================================================================
## CATEGORIA: INTRODUÇÃO
Tudo o que você precisa para começar com o Synapse.
────────────────────────────────────────────────────────────
# Autenticação e Mind Keys
SUMMARY: Como funciona a autenticação do Synapse: Mind Keys para agentes, JWTs para humanos, ?key= para ferramentas somente-URL.
KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.
Autenticação e Mind Keys
O Synapse usa dois métodos de autenticação, cada um otimizado para um caso de
uso diferente. Entender a diferença é essencial para construir integrações
confiáveis.
Dois métodos de auth
| Método | Caso de uso | Limite de taxa | Expiração |
|--------|-------------|----------------|-----------|
| Mind Key | Agentes LLM, ferramentas automatizadas | Nenhum (header) / 60 min (query) | Nunca |
| JWT | Interface humana, operações de conta | Nenhum | 7 dias |
Mind Key (para agentes)
Uma Mind Key é um token de API com escopo de tenant. Ele autentica os dados de
um único mind (memórias, tarefas, chat, scripts, etc.). Use para:
- Agentes LLM chamando a API
- Scripts de automação em background
- Configuração do servidor MCP
- Qualquer integração de longa duração
Autenticação por cabeçalho (recomendada)
[CODE BLOCK]
Parâmetro de consulta (para ferramentas somente-URL)
[CODE BLOCK]
> [!WARNING]
> O parâmetro de consulta é limitado a 60 requisições por minuto.
> O cabeçalho Bearer não tem limite de taxa. Use o cabeçalho sempre que seu
> cliente suportar cabeçalhos personalizados.
Criando uma Mind Key
[CODE BLOCK]
A resposta inclui — salve-a imediatamente, ela é exibida apenas
uma vez.
Listando seus minds
[CODE BLOCK]
Excluindo um mind (irreversível!)
[CODE BLOCK]
JWT (para humanos)
JWTs autenticam a conta do usuário, não um mind específico. Use-os para:
- Registro e login de conta
- Criar / listar / excluir minds
- Compartilhar minds com outros usuários
- Gerenciamento de assinaturas Web Push
Registrar
[CODE BLOCK]
Retorna:
Login
[CODE BLOCK]
Retorna:
Expiração do JWT
JWTs expiram após 7 dias. Quando um JWT expira, basta chamar
novamente para obter um novo. A Mind Key nunca expira, então integrações de
agentes existentes continuam funcionando.
Melhores práticas de segurança
> [!CRITICAL]
> - Nunca faça commit de Mind Keys no git. Use variáveis de ambiente.
> - Nunca registre Mind Keys em logs. Mascarie-as em logs ().
> - Faça rotação de keys se suspeitar de vazamento (exclua o mind, crie um novo).
> - Use um mind por projeto para limitar o raio de explosão se uma key vazar.
Padrão de variável de ambiente
[CODE BLOCK]
[CODE BLOCK]
Configuração do servidor MCP
[CODE BLOCK]
Padrão multi-mind
Cada usuário pode ter múltiplos minds. Padrões comuns:
| Nome do mind | Finalidade |
|--------------|------------|
| | Memórias relacionadas ao trabalho |
| | Preferências pessoais, família |
| | Contexto de projeto específico |
| | Progresso de aprendizado |
| | Fallback de propósito geral |
Use Mind Keys diferentes para sessões LLM diferentes para manter contextos
isolados.
Limites de taxa
| Método de auth | Limite | Escopo |
|----------------|--------|--------|
| Mind Key (header) | Nenhum | Por mind |
| Mind Key (?key=) | 60/min | Por IP |
| JWT (header) | Nenhum | Por usuário |
| Endpoints públicos | Nenhum | Global |
Cabeçalhos de limite de taxa (, ,
) são incluídos nas respostas quando aplicável.
Próximos passos
- Mind Key vs JWT — quando usar qual
- API de Memória — o que você pode fazer com uma Mind Key
- API de Usuário — gerenciamento de conta com JWTs
────────────────────────────────────────────────────────────
# Mind Key vs JWT — qual usar quando?
SUMMARY: Guia de decisão: Mind Key para acesso a dados do agente, JWT para gerenciamento de conta.
KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).
Mind Key vs JWT — qual usar quando?
O Synapse tem dois tokens de autenticação. Escolher o errado leva a erros 401.
Este guia oferece uma estrutura clara de decisão.
Tabela de decisão rápida
| Você quer... | Use |
|--------------|-----|
| Armazenar / recuperar memórias | Mind Key |
| Enviar / fazer poll de mensagens de chat | Mind Key |
| Gerenciar tarefas | Mind Key |
| Armazenar scripts | Mind Key |
| Registrar webhooks | Mind Key |
| Controlar computadores | Mind Key (lado do usuário) / Computer Token (lado do agente) |
| Registrar uma conta de usuário | Nenhum (público) |
| Fazer login | Nenhum (público) |
| Criar / listar / excluir minds | JWT |
| Compartilhar um mind com outro usuário | JWT |
| Inscrever-se em notificações web push | JWT |
| Ver log de auditoria | Mind Key |
A regra simples
> [!TIP]
> Se toca os dados de um único mind → Mind Key.
> Se gerencia a conta ou metadados de mind → JWT.
Mind Key — token de acesso a dados
Uma Mind Key concede acesso aos dados de um mind. É um token de longa
duração que nunca expira (até o mind ser excluído). Perfeita para:
- Agentes LLM persistindo memórias entre sessões
- Cron jobs em background
- Configuração de servidor MCP
- Integrações de webhook
- Apps mobile lendo memória
O que a Mind Key pode fazer
- — ler todas as memórias neste mind
- — armazenar/atualizar memórias
- — ler mensagens de chat
- — enviar mensagens de chat
- — listar tarefas
- — criar tarefas
- — armazenar scripts
- — registrar webhooks
- — enfileirar comandos de computador
O que a Mind Key NÃO pode fazer
- Criar / listar / excluir minds (precisa de JWT)
- Compartilhar mind com outro usuário (precisa de JWT)
- Ver informações da conta do usuário (precisa de JWT)
- Inscrever-se em web push (precisa de JWT)
JWT — token de gerenciamento de conta
Um JWT autentica a conta do usuário. Ele expira após 7 dias e é usado para
operações em nível de conta que abrangem múltiplos minds ou envolvem outros
usuários.
O que o JWT pode fazer
- — criar um novo mind (retorna uma nova Mind Key)
- — listar todos os minds deste usuário
- — excluir um mind
- — compartilhar um mind com outro usuário
- — inscrever em notificações web push
- — listar compartilhamentos de mind
O que o JWT NÃO pode fazer
- Ler / escrever memórias (precisa de Mind Key)
- Enviar mensagens de chat (precisa de Mind Key)
- Gerenciar tarefas (precisa de Mind Key)
- Registrar webhooks (precisa de Mind Key)
Caso especial: Computer Token
Os endpoints (voltados ao agente, para o screen-remote-agent)
usam um terceiro tipo de token: o Computer Token. Esse token é retornado por
ao resgatar um código de instalação, e é específico
para um computador registrado.
| Endpoint | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key ou JWT |
| | Mind Key ou JWT |
Padrões comuns
Padrão 1: agente LLM único
1. Registre uma vez → obtenha JWT
2. Crie um mind → obtenha Mind Key
3. LLM usa a Mind Key para tudo
Padrão 2: agente multi-projeto
1. Registre uma vez → obtenha JWT
2. Crie múltiplos minds (work, personal, project-x) → obtenha múltiplas Mind Keys
3. LLM carrega Mind Key diferente com base no contexto
Padrão 3: compartilhamento em equipe
1. Usuário A cria um mind → obtém Mind Key A
2. Usuário A compartilha com Usuário B via JWT ()
3. Usuário B agora pode acessar via seu próprio JWT
4. Para acesso LLM, Usuário B precisa criar sua própria Mind Key (ou usar a de A)
Padrão 4: servidor MCP
Servidores MCP sempre usam Mind Key (definida via variável de ambiente
). Uma instância de servidor MCP = um mind. Para acesso
multi-mind, rode múltiplas instâncias MCP ou implemente troca de mind no cliente.
Tabela de formato de tokens
| Token | Formato | Exemplo |
|-------|---------|---------|
| Mind Key | + 36 chars | |
| JWT | + base64 | |
| Computer Token | + 36 chars | |
Próximos passos
- Autenticação — guia completo de auth
- API de Usuário e Minds — endpoints protegidos por JWT
- API de Memória — endpoints protegidos por Mind Key
────────────────────────────────────────────────────────────
# Quick Start para agentes LLM
SUMMARY: Em 3 chamadas de API: recupere todas as memórias, armazene uma nova, busque. O workflow essencial de LLM.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)
ALWAYS call /memory/recall at the start of every session.
Wichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
FTS5 search: multiple words = AND, "phrases" in quotes, prefix* for prefix search
Quick Start para agentes LLM
Você perde toda a memória entre sessões. O Synapse é seu cérebro externo. Este
guia mostra as três chamadas de API essenciais que todo agente LLM precisa
conhecer.
> [!CRITICAL]
> Chame no INÍCIO de CADA sessão.
> Sem essa chamada, você não tem memória de quem é o usuário, do que prometeu
> ou no que estava trabalhando da última vez.
Passo 1: recuperar todas as memórias (SEMPRE PRIMEIRO)
[CODE BLOCK]
Retorna um resumo estruturado em texto puro de todas as memórias armazenadas.
Faça parse disso para reconstruir seu modelo mental do usuário, seus projetos e
interações passadas.
Exemplo de resposta:
[CODE BLOCK]
Passo 2: armazenar uma nova memória
Quando você aprender algo que vale a pena lembrar:
[CODE BLOCK]
Categorias: , , , , , , , ,
Prioridades: , , ,
> [!TIP]
> Sempre inclua um campo — um identificador curto para a memória. Isso
> permite atualizar a mesma memória depois refazendo POST com a mesma key.
Passo 3: buscar uma memória específica
[CODE BLOCK]
> [!TIP]
> Sintaxe FTS5: múltiplas palavras = busca AND. Frases em aspas: .
> Busca por prefixo: . Booleano: .
Ferramentas abertas (sem cabeçalhos de auth)
Se sua ferramenta só consegue abrir URLs (sem cabeçalhos personalizados), use o
parâmetro :
[CODE BLOCK]
> [!WARNING]
> é limitado a 60 requisições/minuto. O cabeçalho Bearer não tem limite
> de taxa. Use o cabeçalho Bearer sempre que possível.
Workflow completo de sessão
1. Início da sessão: — carregar todas as memórias
2. Durante o trabalho: — encontrar fatos específicos
3. Em nova informação: — armazenar (com category, key, tags, priority)
4. Periodicamente: — verificar mensagens humanas
5. Fim da sessão: Armazenar quaisquer aprendizados finais via
Padrões comuns
Atualizar uma memória existente
Faça POST com a mesma e — a memória existente é
atualizada, não duplicada.
Armazenar status de projeto
[CODE BLOCK]
Registrar um erro (para não repeti-lo)
[CODE BLOCK]
Verificar mensagens humanas
[CODE BLOCK]
Retorna mensagens não lidas do humano. Responda com:
[CODE BLOCK]
Próximos passos
- Autenticação — Mind Key vs JWT
- Referência da API de Memória — todos os 22 endpoints de memória
- API de Chat — comunicação assíncrona com humanos
- Cookbook de LLM — padrões práticos
────────────────────────────────────────────────────────────
# Quick Start (Humano)
SUMMARY: Registre uma conta, crie seu primeiro mind, armazene uma memória — tudo em 5 minutos.
Quick Start (Humano)
Este guia conduz você pela criação de uma conta no Synapse, sua primeira Mind
Key e o armazenamento de sua primeira memória. Tempo total: 5 minutos.
Passo 1: registre uma conta
Abra a API do Synapse e crie uma conta:
[CODE BLOCK]
Resposta:
[CODE BLOCK]
> [!TIP]
> Salve o JWT em algum lugar seguro — você precisará dele para criar minds. O
> JWT expira após 7 dias; refaça login com o mesmo endpoint para renovar.
Passo 2: crie seu primeiro mind
Um "mind" é um escopo de memória isolado. A maioria dos usuários começa com um
mind, mas você pode ter múltiplos (ex.: "work", "personal", "project-x"). Cada
mind tem sua própria Mind Key única.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
> [!CRITICAL]
> Salve a imediatamente. Ela é exibida apenas uma vez e não
> pode ser recuperada depois. Se você a perder, precisará criar um novo mind.
Passo 3: armazene sua primeira memória
Agora use a Mind Key para armazenar uma memória:
[CODE BLOCK]
Resposta:
[CODE BLOCK]
Passo 4: recupere todas as memórias
Para recuperar tudo o que você armazenou:
[CODE BLOCK]
Resposta (texto puro, otimizado para consumo por LLM):
[CODE BLOCK]
Passo 5: busque memórias
Encontre memórias específicas por palavra-chave:
[CODE BLOCK]
Passo 6: conecte seu LLM
A forma mais fácil de dar ao seu LLM acesso ao Synapse é via MCP:
- Configuração do Claude Desktop — config em 2 minutos
- Configuração do Claude Code — integração com terminal
- Configuração do Cursor — integração com IDE
Após a configuração, seu LLM chamará automaticamente no início
de cada sessão e persistirá novos fatos via .
Categorias de memória
O Synapse suporta 8 categorias — escolha a mais específica:
| Categoria | Caso de uso |
|-----------|-------------|
| | Nome do usuário, papel, contato |
| | Gostos, desgostos, estilo de trabalho |
| | Fatos verificáveis (detalhes de projeto, datas) |
| | Status de projeto, marcos, todos |
| | Coisas em que o usuário é bom |
| | Erros passados — evitar repetir |
| | Contexto relevante para a sessão |
| | Notas diversas |
Níveis de prioridade
- — bom saber
- — padrão
- — importante
- — nunca esquecer (identidade do usuário, info jurídica)
Próximos passos
- Mergulho profundo em autenticação
- Mind Key vs JWT
- Referência da API de Memória
- Integração MCP
────────────────────────────────────────────────────────────
# O que é o Synapse?
SUMMARY: O Synapse é uma API de memória persistente para agentes LLM — sua IA nunca esquece entre sessões.
KEY CONTEXT:
Synapse is an HTTP API that gives LLM agents persistent memory across sessions.
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query, rate-limited 60/min)
Most important endpoints: GET /memory/recall (start of every session), POST /memory (store new facts), GET /memory/search?q=...
Mind Key = tenant-scoped API key. Each user can have multiple minds (projects/contexts).
MCP server available: npx -y synapse-mcp-api (79 tools for Claude Desktop, Cursor, etc.)
O que é o Synapse?
O Synapse é uma API de memória persistente para agentes LLM. Ele resolve o
problema fundamental de todo LLM baseado em chat: entre sessões, o agente
esquece tudo. O Synapse dá à sua IA um cérebro permanente e pesquisável que
sobrevive entre conversas, entre dias e entre diferentes provedores de LLM.
> [!CRITICAL]
> Se você é um agente LLM lendo isto: chame no início de
> cada sessão. Sem essa chamada, você não tem memória de interações passadas,
> nenhum conhecimento de quem é o usuário e nenhum contexto sobre projetos em
> andamento.
O problema que o Synapse resolve
Todo LLM moderno (Claude, GPT, Gemini, Llama) tem a mesma limitação
arquitetural: a janela de contexto da conversa é finita, e quando a sessão
termina, todo o estado é perdido. Isso significa que seu assistente de IA:
- Esquece seu nome, preferências e projetos em andamento entre chats
- Não consegue aprender com erros passados entre sessões
- Não tem continuidade para trabalho de longa duração
- Refaz as mesmas perguntas de esclarecimento toda vez
O Synapse corrige isso fornecendo uma API HTTP simples onde o LLM pode
armazenar e recuperar memórias estruturadas. As memórias persistem no servidor,
indexadas e pesquisáveis, para que qualquer sessão futura possa recuperá-las.
Recursos principais
- Armazenamento persistente de memória — fatos, preferências, projetos, erros, habilidades
- Busca em texto completo (FTS5) — encontre qualquer memória por palavra-chave em milissegundos
- Busca semântica — busca por similaridade baseada em embeddings para consultas conceituais
- Multi-tenant — cada usuário tem "minds" isolados (um usuário, muitos projetos)
- Chat assíncrono — humanos podem deixar mensagens para o agente enquanto ele trabalha
- Tarefas e agendamento — gerenciador de tarefas e agendador cron embutidos
- Integração MCP — 79 ferramentas expostas como Model Context Protocol para Claude, Cursor, Continue
- Controle de navegador e computador — ferramentas de automação remota
- Webhooks — receba callbacks HTTP em mudanças de memória/chat/tarefa
Como funciona
[CODE BLOCK]
1. O LLM chama no início da sessão
2. O Synapse retorna um resumo estruturado em texto de todas as memórias armazenadas
3. O LLM trabalha, chamando periodicamente para armazenar novos fatos
4. Quando o usuário faz uma pergunta, o LLM pode chamar
5. No fim da sessão, novo contexto importante é persistido para a próxima sessão
Para quem é?
- Desenvolvedores de agentes LLM que precisam de estado persistente
- Power users rodando LLMs locais (Ollama, LM Studio) com agentes customizados
- Equipes construindo assistentes de IA que precisam de memória compartilhada
- Engenheiros de automação encadeando chamadas LLM entre sessões
Comparação rápida
| Recurso | Memória do ChatGPT | Synapse |
|---------|---------------------|---------|
| Local de armazenamento | Servidores OpenAI | Seu servidor |
| Acesso por API | Não (fechado) | Sim (REST + MCP) |
| Multi-tenant | Não | Sim (minds) |
| Categorias personalizadas | Não | Sim (8 categorias) |
| Busca | Limitada | FTS5 + semântica |
| Auto-hospedável | Não | Sim (Docker) |
Próximos passos
- Quick Start para humanos — obtenha uma Mind Key em 5 minutos
- Quick Start para LLMs — primeiras chamadas de API
- Autenticação — Mind Keys vs JWTs
- Visão geral da arquitetura — como o Synapse é construído
## CATEGORIA: REFERÊNCIA DA API
Referência completa de todos os endpoints da API.
────────────────────────────────────────────────────────────
# Proxy de navegador
SUMMARY: Serviço de automação de navegador — container Docker separado na porta 13000 para controle de navegador headless.
KEY CONTEXT:
Browser Proxy is a SEPARATE Docker service (port 13000), NOT a Synapse endpoint.
Synapse endpoints do NOT include /browser/* paths.
For browser automation, use the MCP browser_new tool OR connect to the browser-proxy service directly.
Synapse MCP exposes browser tools (browser_new, browser_navigate, browser_click, etc.)
Proxy de navegador
O Browser Proxy é um serviço Docker separado que oferece automação de
navegador headless via Playwright. Ele não faz parte diretamente da API do
Synapse — os endpoints do Synapse não incluem caminhos .
Arquitetura
[CODE BLOCK]
Métodos de acesso
Método 1: Via servidor MCP do Synapse (recomendado)
O servidor MCP do Synapse expõe ferramentas de navegador como ferramentas MCP.
Use isto para automação de navegador orientada por LLM:
[CODE BLOCK]
Ferramentas MCP de navegador disponíveis:
- — abre uma nova aba do navegador
- — navega para uma URL
- — clica em um elemento
- — digita texto em um campo
- — captura uma screenshot
- — fecha a aba
- (e mais — consulte Integração MCP)
Método 2: Acesso direto ao Browser Proxy
Para integrações não-MCP, conecte-se diretamente ao serviço browser-proxy:
[CODE BLOCK]
Casos de uso comuns
Web scraping
[CODE BLOCK]
Automação de formulário
[CODE BLOCK]
Captura de screenshot
[CODE BLOCK]
Serviços relacionados
| Serviço | Porta | Finalidade |
|---------|-------|------------|
| Synapse API | 12800 | Memória, chat, tarefas |
| Synapse MCP | 13100 | Servidor MCP (79 ferramentas) |
| Browser Proxy | 13000 | Automação de navegador headless |
| SSH Proxy | 12900 | Acesso SSH a máquinas remotas |
Próximos passos
- Integração MCP — como usar ferramentas de navegador via MCP
- API de Controle de Computadores — para automação de GUI em máquinas registradas
────────────────────────────────────────────────────────────
# API de Chat
SUMMARY: Chat assíncrono entre humanos e agentes LLM — poll, resposta, histórico, contagem de não lidas, envio de arquivos.
KEY CONTEXT:
Auth: Mind Key (agent side, ?role=agent) or JWT (human side, ?role=human)
Poll: GET /chat/poll (returns unread messages, marks them as read)
Reply: POST /chat/reply { content }
History: GET /chat/history?limit=50
Unread count: GET /chat/unread?role=agent (or ?role=human)
Upload: POST /chat/upload (multipart, file attachment)
Pattern: poll between tool calls, reply when human asks questions
API de Chat
A API de Chat permite mensagens assíncronas entre humanos e agentes LLM.
Diferente do chat síncrono (estilo ChatGPT), o humano pode deixar mensagens
enquanto o agente está trabalhando — o agente faz poll entre chamadas de
ferramenta.
Como funciona
[CODE BLOCK]
1. O humano envia uma mensagem pela interface web (usa JWT)
2. A mensagem é armazenada, marcada como não lida
3. O agente faz poll em entre chamadas de ferramenta
4. O poll retorna todas as mensagens não lidas e as marca como lidas
5. O agente processa a mensagem e, opcionalmente, responde via
Endpoints
GET /chat/poll
Faz poll por novas mensagens do humano. Retorna mensagens não lidas e as marca
como lidas. Use isto entre chamadas de ferramenta.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
POST /chat/reply
Envia uma mensagem como agente.
[CODE BLOCK]
POST /chat/send
Envia uma mensagem como humano (requer JWT, não Mind Key).
[CODE BLOCK]
GET /chat/history
Obtém o histórico recente de chat (ambos os papéis).
[CODE BLOCK]
GET /chat/unread
Obtém a contagem de mensagens não lidas.
[CODE BLOCK]
GET /chat/status
Obtém o status da sessão de chat (timestamps da última mensagem, contagens de não lidas).
[CODE BLOCK]
POST /chat/upload
Faz upload de um anexo de arquivo para uma mensagem específica (form multipart).
[CODE BLOCK]
GET /chat/files/:messageid
Lista os anexos de uma mensagem.
[CODE BLOCK]
GET /chat/file/:fileid
Baixa um anexo de arquivo.
[CODE BLOCK]
Padrão de poll
> [!TIP]
> Faça poll a cada 30-60 segundos entre chamadas de ferramenta. Não faça poll
> com mais frequência — isso desperdiça cota da API e não traz benefício.
[CODE BLOCK]
Próximos passos
- API de Tarefas
- Padrão de poll de chat
────────────────────────────────────────────────────────────
# API de Controle de Computadores
SUMMARY: Controle remoto de computadores registrados — enfileirar comandos, capturar screenshots, executar scripts em máquinas remotas.
KEY CONTEXT:
Two sides: user-facing (Mind Key/JWT) and agent-facing (Computer Token)
Register agent: POST /computers/register { install_code } → returns computer_token
List: GET /computers/list (Mind Key or JWT)
Queue command: POST /computers/:id/commands { type, payload }
Command types: screenshot, click, move, type, key, scroll, drag
Agent poll: GET /computers/me/poll?wait=5 (Computer Token)
Agent result: POST /computers/me/commands/:cid/result (Computer Token)
One-shot screenshot: GET /computers/:id/screenshot (waits 30s for result)
Pattern: register agent on remote machine → user queues commands → agent polls and executes
API de Controle de Computadores
A API de Controle de Computadores permite controlar remotamente computadores
registrados. Um pequeno agente () roda na máquina-alvo,
faz poll por comandos, executa-os e envia os resultados de volta. Isso permite
automação de GUI orientada por LLM.
Arquitetura
[CODE BLOCK]
Endpoints voltados ao usuário (Mind Key ou JWT)
GET /computers/list
Lista todos os computadores registrados.
[CODE BLOCK]
GET /computers/:id
Obtém detalhes de um único computador.
[CODE BLOCK]
POST /computers/install-code
Gera um código de instalação para registrar um novo computador.
[CODE BLOCK]
Resposta:
POST /computers/:id/commands
Enfileira um comando para o agente remoto executar.
[CODE BLOCK]
Resposta:
GET /computers/:id/command (via query)
Enfileira um comando via GET (para casos simples).
[CODE BLOCK]
GET /computers/:id/commands
Lista comandos recentes de um computador.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Obtém o status + resultado de um comando específico.
[CODE BLOCK]
GET /computers/:id/screenshot
One-shot: enfileira um comando de screenshot e aguarda até 30s pelo resultado.
[CODE BLOCK]
POST /computers/:id/disable
Desativa um computador (revoga seu token, mantém o registro para auditoria).
[CODE BLOCK]
DELETE /computers/:id
Exclui um computador permanentemente.
[CODE BLOCK]
Endpoints voltados ao agente (Computer Token)
Esses endpoints são usados pelo em execução na
máquina-alvo. Eles usam um Computer Token (retornado por ),
não uma Mind Key.
POST /computers/register
Resgata um código de instalação e obtém um Computer Token.
[CODE BLOCK]
Resposta:
> [!CRITICAL]
> Salve o — ele é exibido apenas uma vez e é necessário para
> todos os endpoints do lado do agente.
GET /computers/me/poll
Long-poll por novos comandos. O agente chama isso em loop.
[CODE BLOCK]
Retorna imediatamente se houver comandos pendentes, ou após segundos se
não houver.
POST /computers/me/commands/:cid/result
Envia o resultado da execução de um comando.
[CODE BLOCK]
Tipos de comando
| Tipo | Payload | Descrição |
|------|---------|-----------|
| | | Captura a tela como PNG (base64) |
| | | Clica nas coordenadas |
| | | Move o mouse para as coordenadas |
| | | Digita texto no cursor |
| | | Pressiona combinação de teclas |
| | | Rola a roda do mouse |
| | | Arrasta e solta |
Padrão comum: automação de GUI orientada por LLM
[CODE BLOCK]
Próximos passos
- Proxy de navegador — serviço separado para automação de navegador
- Guia de agentes auto-hospedados
────────────────────────────────────────────────────────────
# Cron & Agendador
SUMMARY: Agende chamadas recorrentes de API — cron jobs que disparam em horários programados, perfeitos para sincronização periódica e lembretes.
KEY CONTEXT:
Auth: Mind Key
Create: POST /cron { schedule, endpoint, method?, body?, headers?, enabled? }
List: GET /cron
Delete: DELETE /cron/:id
Toggle: PUT /cron/:id/toggle
Schedule: 5-field cron (minute hour day month day-of-week) OR integer interval (seconds)
Endpoint: must be http(s) URL, same Synapse instance OR public HTTPS (no private IPs)
Pattern: schedule /memory/recall every hour, /chat/poll every 5 min, etc.
Cron & Agendador
A API de Cron permite agendar chamadas HTTP recorrentes para endpoints do
Synapse (ou endpoints HTTPS externos). Perfeita para sincronização periódica,
lembretes e tarefas de manutenção.
Endpoints
POST /cron
Cria uma tarefa agendada.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
GET /cron
Lista todas as tarefas agendadas.
[CODE BLOCK]
DELETE /cron/:id
Exclui uma tarefa agendada.
[CODE BLOCK]
PUT /cron/:id/toggle
Ativa ou desativa uma tarefa sem excluí-la.
[CODE BLOCK]
Sintaxe de agendamento
Cron padrão (5 campos)
[CODE BLOCK]
Exemplos:
| Agendamento | Significado |
|-------------|-------------|
| | A cada hora |
| | A cada 15 minutos |
| | Dias úteis às 9h |
| | Todo domingo à meia-noite |
| | Primeiro dia de cada mês à meia-noite |
Intervalo inteiro (segundos)
Para intervalos simples, passe um inteiro:
[CODE BLOCK]
Restrições de endpoint
> [!WARNING]
> Endpoints devem ser URLs ou apontando para:
> - A mesma instância do Synapse (ex.: )
> - URLs HTTPS públicas (sem IPs privados, sem localhost, sem IPs de metadata)
Isso evita ataques SSRF onde um mind comprometido pudesse agendar requisições
para serviços internos.
Padrões comuns
Recall de memória por hora (para agentes LLM)
[CODE BLOCK]
Backup diário
[CODE BLOCK]
Poll de chat periódico (a cada 5 minutos)
[CODE BLOCK]
Gatilho de relatório semanal
[CODE BLOCK]
Próximos passos
- API de Variáveis
- API de Webhooks
────────────────────────────────────────────────────────────
# Erros e tratamento de erros
SUMMARY: Códigos de status HTTP, formato de resposta de erro e como se recuperar de erros comuns.
KEY CONTEXT:
Error format: { statusCode, error, message, docs? }
Common errors: 401 (auth), 404 (wrong path), 429 (rate limit), 500 (server)
401 → check Mind Key/JWT, see /docs/getting-started/authentication
404 → wrong path, GET /endpoints for valid list, do NOT guess paths
429 → rate limited (?key= is 60/min), use Bearer header instead
500 → server error, retry with backoff, check /health
docs field in error response links to relevant documentation.
Erros e tratamento de erros
O Synapse usa códigos de status HTTP padrão com um formato consistente de
resposta de erro. Esta página explica como interpretar e se recuperar de erros.
Formato de resposta de erro
Todos os erros retornam JSON com esta estrutura:
[CODE BLOCK]
| Campo | Descrição |
|-------|-----------|
| | Código de status HTTP |
| | Nome do status HTTP |
| | Descrição do erro legível para humanos |
| | URL para a documentação relevante (quando aplicável) |
Códigos de status HTTP
200 OK
Sucesso. A requisição foi processada corretamente.
201 Created
Sucesso. Um novo recurso foi criado (ex.: ).
204 No Content
Sucesso. Sem corpo retornado (ex.: ).
400 Bad Request
A requisição estava malformada. Causas comuns:
- Campos JSON obrigatórios ausentes
- Sintaxe JSON inválida
- Valor de enum inválido (ex.: categoria errada)
[CODE BLOCK]
Correção: Confira o corpo da requisição com a documentação da API. Garanta
que todos os campos obrigatórios estão presentes e têm valores válidos.
401 Unauthorized
A autenticação falhou. Causas comuns:
- Cabeçalho ausente
- Mind Key ou JWT inválido
- Uso de Mind Key onde JWT é necessário (ou vice-versa)
[CODE BLOCK]
Correção: Verifique seu token. Consulte Autenticação.
403 Forbidden
Você está autenticado, mas não tem permissão para realizar esta ação. Causas
comuns:
- Tentativa de excluir o mind de outro usuário
- Tentativa de verificar uma memória com Mind Key (requer JWT)
- Mind desativado
Correção: Verifique se você está usando o tipo correto de token para este
endpoint.
404 Not Found
O caminho ou recurso solicitado não existe.
> [!CRITICAL]
> NÃO tente adivinhar caminhos de endpoint. Apenas os caminhos listados em
> existem. Se você recebeu um 404, usou um caminho errado.
[CODE BLOCK]
Correção: Chame para ver a lista de endpoints válidos.
Compare sua URL com a lista caractere por caractere.
409 Conflict
A requisição conflita com o estado existente. Causas comuns:
- Tentativa de registrar com um email que já existe
- URL de webhook duplicada
Correção: Use um valor diferente, ou use para atualizar o recurso
existente.
429 Too Many Requests
Você atingiu um limite de taxa. Aplica-se apenas à auth via parâmetro de
consulta (60/min).
[CODE BLOCK]
Cabeçalhos da resposta:
[CODE BLOCK]
Correção: Mude para o cabeçalho (sem limite de
taxa), ou aguarde segundos.
500 Internal Server Error
Erro de servidor. Isso não deveria acontecer — se acontecer, é um bug.
Correção:
1. Faça retry com backoff exponencial (1s, 2s, 4s, 8s)
2. Verifique para ver se o servidor está no ar
3. Se persistir, relate o erro
503 Service Unavailable
Servidor temporariamente indisponível (ex.: durante deploy, migração de banco).
Correção: Aguarde e tente novamente. Verifique .
Padrões de recuperação
Retry com backoff exponencial
[CODE BLOCK]
Tratamento de erro de auth
[CODE BLOCK]
Cenários comuns de erro
"Mind Key fehlt oder ungültig"
- Você esqueceu o cabeçalho
- Você usou mas a chave está errada
- Você está usando um JWT onde uma Mind Key é necessária
"Route not found"
- Você tentou adivinhar um caminho que não existe
- Você usou um verbo errado (ex.: vs )
- Confira para caminhos válidos
"Rate limit exceeded"
- Você está usando e excedeu 60 req/min
- Mude para o cabeçalho
Próximos passos
- Autenticação
- Visão geral da API
- Limites de taxa
────────────────────────────────────────────────────────────
# API de Memória
SUMMARY: Referência completa dos 22 endpoints de memória: armazenar, recall, busca, busca semântica, sincronização, auditoria e mais.
KEY CONTEXT:
Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)
ALWAYS call GET /memory/recall at session start.
POST /memory with same category+key updates the existing memory.
Categories: identity, preference, fact, project, skill, mistake, context, note, credentials
Priorities: low, normal, high, critical
Search: GET /memory/search?q=... (FTS5 syntax: AND, OR, "phrases", prefix*)
Semantic: GET /memory/semantic-search?q=... (slower, conceptual)
Sync: GET /memory/diff?since=TIMESTAMP (incremental sync)
Export: GET /memory/mind-export (full JSON dump)
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.
> [!CRITICAL]
> Sempre chame 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 |
|-----------|-------------|
| | Nome do usuário, papel, contato, preferências sobre si mesmo |
| | Gostos, desgostos, estilo de trabalho, preferências de comunicação |
| | Fatos verificáveis (detalhes de projeto, datas, URLs) |
| | Status de projeto, marcos, arquitetura |
| | Coisas em que o usuário é bom |
| | Erros passados — evitar repetir |
| | Contexto relevante para a sessão |
| | Notas diversas |
Prioridades
- — bom saber
- — padrão
- — importante
- — 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.
[CODE BLOCK]
Resposta (text/plain):
[CODE BLOCK]
POST /memory
Armazena uma nova memória ou atualiza uma existente (mesma categoria + key = atualização).
[CODE BLOCK]
Resposta:
GET /memory
Lista memórias com filtros opcionais.
[CODE BLOCK]
PUT /memory/:id
Atualiza uma memória específica por ID.
[CODE BLOCK]
DELETE /memory/:id
Exclui uma única memória.
[CODE BLOCK]
Endpoints de busca
GET /memory/search
Busca em texto completo usando FTS5.
[CODE BLOCK]
Sintaxe FTS5:
- Múltiplas palavras = AND:
- Frase:
- Prefixo:
- Booleano:
- Excluir:
GET /memory/semantic-search
Busca conceitual usando embeddings (mais lenta que FTS5, mas entende significado).
[CODE BLOCK]
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.
[CODE BLOCK]
GET /memory/related/:id
Encontra memórias relacionadas a uma memória específica (via tags compartilhadas).
[CODE BLOCK]
Sync & Diff
GET /memory/diff
Sincronização incremental — retorna memórias alteradas desde um timestamp.
[CODE BLOCK]
Resposta:
POST /memory/sync
Aplica um diff de outra instância (para sync auto-hospedado).
[CODE BLOCK]
Operações em massa
POST /memory/bulk-delete
Exclui várias memórias por ID.
[CODE BLOCK]
POST /memory/embed-batch
Gera embeddings para memórias que ainda não os têm (para busca semântica).
[CODE BLOCK]
GET /memory/embed-batch-status
Verifica o progresso da geração de embeddings.
[CODE BLOCK]
Verificação
Memórias têm um flag . Memórias armazenadas pelo agente vêm como não
verificadas por padrão (); memórias armazenadas por humanos são
verificadas ().
POST /memory/verify
Marca uma memória como verificada (requer JWT, não Mind Key).
[CODE BLOCK]
POST /memory/unverify
Marca uma memória como não verificada (requer JWT).
[CODE BLOCK]
GET /memory/unverified
Lista memórias aguardando verificação humana.
[CODE BLOCK]
Estatísticas e auditoria
GET /memory/stats
Estatísticas agregadas para o mind atual.
[CODE BLOCK]
Retorna:
GET /memory/audit
Log de auditoria de todas as operações que alteram estado.
[CODE BLOCK]
GET /memory/contradictions
Detecta potenciais contradições nas memórias armazenadas.
[CODE BLOCK]
GET /memory/expiring
Lista memórias com datas de expiração se aproximando.
[CODE BLOCK]
Health e exportação
GET /memory/health
Health check rápido do sistema de memória.
[CODE BLOCK]
GET /memory/mind-export
Exportação JSON completa de todas as memórias (para backup).
[CODE BLOCK]
POST /memory/compact
Compacta memórias similares (auto-resumo).
[CODE BLOCK]
Próximos passos
- Quick Start para LLMs
- Melhores práticas de memória
- Busca FTS5
- Busca semântica
────────────────────────────────────────────────────────────
# Visão geral da API e URL base
SUMMARY: Todos os endpoints da API do Synapse, URL base, padrões de autenticação e formatos de resposta em um só lugar.
KEY CONTEXT:
Base URL: https://synapse.schaefer.zone
Auth: Authorization: Bearer YOUR_MIND_KEY (header, no rate limit)
OR ?key=YOUR_MIND_KEY (query, 60 req/min)
All responses are JSON except /memory/recall (text/plain) and /docs (HTML/text/json)
All 404 responses mean the path does not exist — do NOT guess paths.
GET /endpoints returns machine-readable list of all valid endpoints.
Visão geral da API e URL base
A API do Synapse é uma API HTTP RESTful. Todos os endpoints retornam JSON (exceto
quando indicado de outra forma). Esta página cobre o essencial que você precisa
antes de explorar endpoints específicos.
URL base
[CODE BLOCK]
Todos os caminhos nesta documentação são relativos a esta URL base. Para
instâncias auto-hospedadas, substitua pela sua própria URL.
Autenticação
Dois métodos, ambos enviados via cabeçalho :
[CODE BLOCK]
Ou via parâmetro de consulta (limitado a 60/min):
[CODE BLOCK]
Consulte Autenticação para detalhes.
Grupos de endpoints
| Grupo | Auth | Descrição |
|-------|------|-----------|
| Público | Nenhuma | Página inicial, health, OpenAPI, docs |
| Memória | Mind Key | CRUD, busca, sincronização, embeddings |
| Chat | Mind Key / JWT | Mensagens assíncronas entre humano e agente |
| Tarefas | Mind Key | Gerenciamento de tarefas |
| Scripts | Mind Key / JWT | Armazenamento persistente de scripts |
| Agendador | Mind Key | Cron jobs + variáveis |
| Webhooks | Mind Key | Callbacks HTTP em eventos |
| Computadores | Mind Key / JWT | Controle de computadores remotos |
| Usuário/Minds | JWT | Conta + gerenciamento de minds |
| Compartilhamento | JWT | Compartilhamento de minds entre usuários |
| Push | JWT | Assinaturas Web Push |
| Ferramentas | Nenhuma | Hora, calc, aleatório (utilidades públicas) |
Formatos de resposta
- JSON (padrão):
- Texto puro: retorna texto otimizado para LLMs
- HTML: , , , ,
Envelope de resposta padrão
Respostas de sucesso retornam os dados diretamente:
[CODE BLOCK]
Respostas de erro usam este formato:
[CODE BLOCK]
> [!NOTE]
> O campo aponta para a documentação relevante dos erros comuns.
Códigos de status HTTP
| Código | Significado |
|--------|-------------|
| 200 | Sucesso (GET, PUT) |
| 201 | Criado (POST) |
| 204 | Sem conteúdo (DELETE) |
| 400 | Requisição inválida (erro de validação) |
| 401 | Não autorizado (token ausente/inválido) |
| 403 | Proibido (tipo de token incorreto) |
| 404 | Não encontrado (caminho não existe) |
| 409 | Conflito (duplicado) |
| 429 | Muitas requisições (rate limit) |
| 500 | Erro de servidor |
Endpoints de descoberta
| Endpoint | Finalidade |
|----------|------------|
| | Página inicial (otimizada para LLMs) |
| | Lista legível por máquina de todos os endpoints |
| | Lista de endpoints em texto puro |
| | Especificação OpenAPI 3.0 |
| | Documentação completa da API (HTML) |
| | Docs da API em JSON |
| | Sistema de documentação (HTML) |
| | Índice da documentação (JSON) |
| | Todas as docs em um único bloco de texto |
| | Playground interativo da API |
Limites de taxa (rate limits)
| Método de auth | Limite |
|----------------|--------|
| Mind Key (header) | Nenhum |
| Mind Key (?key=) | 60/min por IP |
| JWT (header) | Nenhum |
| Endpoints públicos | Nenhum |
Respostas com limite de taxa incluem:
[CODE BLOCK]
Paginação
Endpoints de listagem suportam e :
[CODE BLOCK]
Limite padrão: 100. Limite máximo: 500.
CORS
Todos os endpoints suportam CORS para clientes baseados em navegador:
[CODE BLOCK]
SDKs e clientes
- SDK Node.js: (repo)
- Servidor MCP: (repo)
- Cliente HTTP: qualquer biblioteca HTTP (curl, fetch, axios, etc.)
Próximos passos
- API de Memória — os endpoints mais importantes
- API de Chat — comunicação assíncrona humano-agente
- Erros e tratamento de erros
────────────────────────────────────────────────────────────
# Limites de taxa e cotas
SUMMARY: Política de limites de taxa da API do Synapse — cabeçalho Bearer (ilimitado), ?key= (60/min), endpoints públicos.
KEY CONTEXT:
Mind Key (Authorization: Bearer header) → NO rate limit
Mind Key (?key= query param) → 60 req/min per IP
JWT (Authorization: Bearer header) → NO rate limit
Public endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit
Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After
Recommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.
Limites de taxa e cotas
O Synapse tem uma política de limite de taxa simples e previsível, projetada
para evitar abuso sem atrapalhar o uso legítimo.
Política de limite de taxa
| Método de auth | Limite | Escopo |
|----------------|--------|--------|
| Mind Key () | Nenhum | Por mind |
| Mind Key () | 60 req/min | Por IP |
| JWT () | Nenhum | Por usuário |
| Endpoints públicos | Nenhum | Global |
> [!TIP]
> Sempre use o cabeçalho quando possível. Ele não
> tem limite de taxa. Use apenas para ferramentas que não conseguem
> definir cabeçalhos personalizados.
Cabeçalhos de limite de taxa
Quando você usa auth via , as respostas incluem cabeçalhos de limite:
[CODE BLOCK]
Quando você excede o limite:
[CODE BLOCK]
Quando você atinge um limite de taxa
Se você recebe um 429:
1. Mude para o cabeçalho Authorization (recomendado):
[CODE BLOCK]
2. Ou aguarde segundos e tente novamente.
Por que o limite de ?key= existe
O parâmetro de consulta é conveniente para ferramentas somente-URL
(navegadores, comandos ), mas tem implicações de segurança e desempenho:
- Segurança: Parâmetros de consulta são registrados em logs de acesso do
servidor, histórico do navegador e cabeçalhos Referer. Limitar o uso reduz a
exposição.
- Desempenho: Auth por parâmetro de consulta requer um limitador de taxa
baseado em IP (lookup Redis por requisição), o que adiciona latência. Auth
por cabeçalho pula isso.
- Prevenção de abuso: Uma URL vazada poderia ser compartilhada e
bombardeada. O limite por IP contém o raio de explosão.
Padrões recomendados
Agentes LLM
[CODE BLOCK]
Ferramentas baseadas em navegador
Se sua ferramenta só consegue abrir URLs:
[CODE BLOCK]
Servidor MCP
Servidores MCP sempre usam auth por cabeçalho via variável de ambiente
— nenhum limite de taxa se aplica.
Importações em massa
Para operações em massa (ex.: importar 1000 memórias), sempre use auth por
cabeçalho. Importações em massa via atingirão o limite de taxa em menos
de 1 minuto.
Cotas (nível de mind)
Atualmente não há cotas por mind em tamanho de armazenamento ou contagem de
memórias. Todos os limites são em nível de auth/IP, não de dados. Isso pode
mudar no futuro para justiça multi-tenant.
Monitorando seu uso
[CODE BLOCK]
Próximos passos
- Autenticação
- Erros e tratamento de erros
────────────────────────────────────────────────────────────
# API de Scripts
SUMMARY: Armazenamento persistente de scripts — salve scripts shell, Python ou Node reutilizáveis e os obtenha via curl | bash.
KEY CONTEXT:
Auth: Mind Key or JWT
Store: POST /script { name, content, description?, language? }
Fetch as text: GET /script/:name (returns text/plain, curl | bash ready)
Info: GET /script/:name/info (metadata without content)
List: GET /scripts (JSON array)
Delete: DELETE /script/:name
Use case: store deployment scripts, config generators, troubleshooting snippets
API de Scripts
A API de Scripts oferece um armazenamento persistente para scripts reutilizáveis.
Scripts são nomeados e versionados dentro de um mind, e podem ser obtidos como
texto puro — perfeitos para padrões .
Endpoints
POST /script
Armazena ou atualiza um script.
[CODE BLOCK]
GET /script/:name
Obtém o conteúdo do script como . Perfeito para pipe para o bash.
[CODE BLOCK]
GET /script/:name/info
Obtém metadados do script sem o conteúdo.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
GET /scripts
Lista todos os scripts no mind atual.
[CODE BLOCK]
DELETE /script/:name
Exclui um script.
[CODE BLOCK]
Casos de uso comuns
Scripts de deploy
Armazene procedimentos padrão de deploy para que o LLM possa executá-los sem
rederivar os passos a cada vez:
[CODE BLOCK]
Snippets de troubleshooting
Armazene comandos de diagnóstico para problemas comuns:
[CODE BLOCK]
Geradores de configuração
Armazene scripts que geram configurações:
[CODE BLOCK]
Próximos passos
- API de Variáveis
- Cron & Agendador
────────────────────────────────────────────────────────────
# API de Tarefas
SUMMARY: Gerenciamento de tarefas para agentes LLM — criar, listar, atualizar, concluir e excluir tarefas com prioridades.
KEY CONTEXT:
Auth: Mind Key
List: GET /mind/tasks?status=pending|in_progress|done|cancelled|all
Create: POST /mind/task { title, description?, priority?, due_at? }
Update: PUT /mind/task/:id { title?, description?, priority?, status?, due_at? }
Complete: GET /mind/task/:id/complete
Delete: GET /mind/task/:id/delete
Priorities: low, normal, high, critical
Statuses: pending, in_progress, done, cancelled
Pattern: create tasks for multi-step work, update status as you progress
API de Tarefas
A API de Tarefas oferece aos agentes LLM uma forma estruturada de acompanhar
trabalhos em várias etapas. As tarefas têm escopo no mind atual e persistem
entre sessões, para que o agente possa retomar o trabalho de onde parou.
Endpoints
GET /mind/tasks
Lista todas as tarefas do mind atual.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
POST /mind/task
Cria uma nova tarefa.
[CODE BLOCK]
GET /mind/task (parâmetros de consulta)
Cria uma tarefa via GET (para ferramentas somente-URL).
[CODE BLOCK]
PUT /mind/task/:id
Atualiza uma tarefa existente.
[CODE BLOCK]
GET /mind/task/:id/complete
Marca uma tarefa como concluída.
[CODE BLOCK]
GET /mind/task/:id/delete
Exclui uma tarefa permanentemente.
[CODE BLOCK]
Prioridades
- — sem urgência
- — padrão
- — importante
- — deve fazer imediatamente
Status
- — criada, não iniciada
- — sendo trabalhada no momento
- — concluída
- — abandonada
Padrão: workflow orientado por tarefas
[CODE BLOCK]
Próximos passos
- Workflow orientado por tarefas
- Cron & Agendador
────────────────────────────────────────────────────────────
# Ferramentas utilitárias (time, calc, random)
SUMMARY: Endpoints utilitários públicos — hora do servidor, calculadora segura, gerador de valores aleatórios. Sem auth necessária.
KEY CONTEXT:
No auth required for any /tools/* endpoint.
GET /tools/time → { time, timezone, offset }
GET /tools/calc?expr=(10+5)*3 → { result, expr } (safe, no eval, arithmetic only)
GET /tools/random?type=uuid → { value, type } (types: uuid, int, float, hex, alpha)
Use case: LLM agents that need current time, safe math, or random values.
Ferramentas utilitárias
Os endpoints são utilitários públicos — sem autenticação necessária.
São úteis para agentes LLM que precisam de hora do servidor, matemática segura
ou valores aleatórios.
GET /tools/time
Obtém a hora atual do servidor, fuso horário e offset UTC.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
Caso de uso: agentes LLM que precisam saber "que horas são agora" para
agendamento, timestamps ou cálculos de datas relativas.
GET /tools/calc
Calculadora segura — apenas aritmética, sem . Suporta , , ,
, , , e números.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
> [!TIP]
> Use isso em vez de tentar fazer matemática mentalmente ou via parsing de
> strings. É seguro (sem possibilidade de injeção de código) e preciso.
Operadores suportados
- adição
- subtração
- multiplicação
- divisão
- módulo
- parênteses
- Números (inteiros e decimais)
Exemplos
[CODE BLOCK]
GET /tools/random
Gera valores aleatórios.
[CODE BLOCK]
Parâmetros por tipo
| Tipo | Parâmetros | Saída |
|------|-----------|-------|
| | nenhum | String UUID v4 |
| | , (padrão 0-100) | Inteiro |
| | , (padrão 0-100) | Float |
| | , (intervalo de comprimento, padrão 8-16) | String hex |
| | , (intervalo de comprimento, padrão 8-16) | String alfabética |
Casos de uso para agentes LLM
Gerar IDs únicos
[CODE BLOCK]
Calcular porcentagens
[CODE BLOCK]
Obter timestamp atual
[CODE BLOCK]
Gerar dados de teste
[CODE BLOCK]
Próximos passos
- Visão geral da API — todos os grupos de endpoints
- Erros e tratamento de erros
────────────────────────────────────────────────────────────
# API de Usuário e Minds
SUMMARY: Gerenciamento de conta — registrar, login, criar minds, listar minds, excluir minds. Protegido por JWT.
KEY CONTEXT:
Auth: JWT (from /register or /login)
Register: POST /register { email, password, display_name? } → returns JWT
Login: POST /login { email, password } → returns JWT
Create mind: POST /minds { name, description? } → returns mind_key (shown once!)
List minds: GET /minds
Delete mind: DELETE /minds/:id (irreversible — deletes all memories!)
JWT expires after 7 days. Mind Key never expires.
Mind Key is shown only once at creation — save it permanently.
API de Usuário e Minds
A API de Usuário e Minds cuida do gerenciamento de conta. Esses endpoints usam
autenticação JWT (não Mind Keys) porque operam em nível de conta, não em nível
de mind.
Endpoints de autenticação
POST /register
Cria uma nova conta de usuário.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
POST /login
Faz login em uma conta existente.
[CODE BLOCK]
Resposta: mesma de .
Endpoints de minds
POST /minds
Cria um novo mind. Retorna a Mind Key — salve-a imediatamente, ela é
exibida apenas uma vez.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
> [!CRITICAL]
> A é exibida apenas uma vez. Se você a perder, não poderá recuperá-
> -la — será necessário excluir o mind e criar um novo (o que apaga todas as
> memórias armazenadas).
GET /minds
Lista todos os minds do usuário atual.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
DELETE /minds/:id
Exclui um mind permanentemente.
[CODE BLOCK]
> [!WARNING]
> Excluir um mind é irreversível. Todas as memórias, tarefas, histórico de
> chat e scripts desse mind são perdidos permanentemente. Exporte antes via
> se precisar de backup.
Padrão multi-mind
A maioria dos usuários se beneficia de múltiplos minds para manter contextos
isolados:
[CODE BLOCK]
Use Mind Keys diferentes em sessões LLM diferentes para manter contextos
isolados.
Segurança da conta
Requisitos de senha
- Mínimo de 6 caracteres
- Sem máximo (use um gerenciador de senhas)
- Armazenada como hash bcrypt (nunca em texto puro)
Expiração do JWT
JWTs expiram após 7 dias. Quando expirar, basta chamar novamente.
Segurança da Mind Key
Mind Keys nunca expiram. Se uma Mind Key for comprometida:
1. Crie um novo mind via
2. Atualize sua configuração de LLM com a nova Mind Key
3. Exclua o mind comprometido via
Próximos passos
- Autenticação — guia completo de auth
- Mind Key vs JWT — guia de decisão
- API de Compartilhamento — compartilhe minds com outros usuários
────────────────────────────────────────────────────────────
# API de Variáveis
SUMMARY: Armazenamento key-value rápido para estado de LLM — contadores, flags, timestamps de última atividade, progresso parcial.
KEY CONTEXT:
Auth: Mind Key
Set: POST /var { key, value }
Get: GET /var/:key
List: GET /var
Delete: DELETE /var/:key
Use case: store last-seen timestamps, counters, flags, partial workflow state
Faster than memory (PostgreSQL direct, no FTS5 indexing)
Not for: structured facts (use /memory), long content (use /script)
API de Variáveis
A API de Variáveis é um armazenamento key-value rápido para estado efêmero.
Diferente das memórias (que são indexadas, pesquisáveis e estruturadas), as
variáveis são otimizadas para acesso rápido de leitura/escrita — perfeitas para
contadores, flags e estado de sessão.
Endpoints
POST /var
Define ou atualiza uma variável.
[CODE BLOCK]
GET /var/:key
Obtém uma única variável.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
GET /var
Lista todas as variáveis.
[CODE BLOCK]
DELETE /var/:key
Exclui uma variável.
[CODE BLOCK]
Quando usar Variáveis vs Memória
| Caso de uso | Use |
|-------------|-----|
| Nome do usuário, preferências | Memória (pesquisável, estruturada) |
| Timestamp da última sessão | Variável (estado efêmero) |
| Contador (ex.: mensagens enviadas) | Variável (atualizações frequentes) |
| Estado de workflow ("passo 3 de 5 concluído") | Variável (transitório) |
| Notas longas de projeto | Memória (indexada em texto completo) |
| Scripts reutilizáveis | Armazenamento de scripts (nomeados, versionados) |
Padrões comuns
Rastrear última sessão
[CODE BLOCK]
Padrão de contador
[CODE BLOCK]
Feature flags
[CODE BLOCK]
Próximos passos
- API de Memória — para dados estruturados e pesquisáveis
- Cron & Agendador
────────────────────────────────────────────────────────────
# API de Webhooks
SUMMARY: Registre callbacks HTTP para eventos de memória, chat e tarefa — seja notificado quando os dados mudarem.
KEY CONTEXT:
Auth: Mind Key
Register: POST /webhooks { url, events, secret? }
List: GET /webhooks
Get: GET /webhooks/:id
Update: PUT /webhooks/:id { url?, events?, secret?, enabled? }
Delete: DELETE /webhooks/:id
Events: memory.*, memory.store, memory.update, memory.delete, chat.*, chat.message_received, task.*, task.created, task.completed
Secret: HMAC-SHA256 signed payload, sent in X-Synapse-Signature header
Pattern: register webhook → receive POST → process event → call Synapse API
API de Webhooks
Webhooks permitem receber callbacks HTTP quando eventos acontecem no Synapse.
Perfeitos para disparar automação externa, enviar notificações ou sincronizar
com outros sistemas.
Endpoints
POST /webhooks
Registra um novo webhook.
[CODE BLOCK]
Resposta:
[CODE BLOCK]
GET /webhooks
Lista todos os webhooks do mind atual.
[CODE BLOCK]
GET /webhooks/:id
Obtém um único webhook.
[CODE BLOCK]
PUT /webhooks/:id
Atualiza um webhook (URL, eventos, secret ou flag enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Exclui um webhook.
[CODE BLOCK]
Tipos de evento
| Padrão | Dispara quando |
|--------|----------------|
| | Qualquer evento de memória |
| | Nova memória armazenada |
| | Memória atualizada |
| | Memória excluída |
| | Qualquer evento de chat |
| | Nova mensagem do humano |
| | Qualquer evento de tarefa |
| | Nova tarefa criada |
| | Tarefa marcada como concluída |
| | Todos os eventos |
Payload do webhook
Quando um evento dispara, o Synapse faz POST para sua URL:
[CODE BLOCK]
Verificação de assinatura
Se você definir um , o Synapse assina cada payload com HMAC-SHA256:
[CODE BLOCK]
Verifique no seu handler:
[CODE BLOCK]
Padrão: sincronização em tempo real
[CODE BLOCK]
Próximos passos
- Cron & Agendador
- Guia de automação com webhooks
## CATEGORIA: INTEGRAÇÃO MCP
Integração com Claude, Cursor e outros clientes MCP.
────────────────────────────────────────────────────────────
# MCP no Claude Code
SUMMARY: Use ferramentas do Synapse no agente de terminal Claude Code — memória persistente para sessões de codificação.
KEY CONTEXT:
Claude Code config: ~/.claude/config.json (or via `claude mcp add` command)
Command: npx -y synapse-mcp-api@latest
Env: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional)
Alternative: `claude mcp add synapse -- npx -y synapse-mcp-api@latest`
Then: set SYNAPSE_MIND_KEY env var in your shell
Test: in claude code, type "recall all my memories"
MCP no Claude Code
Claude Code é o agente de codificação baseado em terminal da Anthropic. Com o
MCP do Synapse, o Claude Code ganha memória persistente entre sessões de
codificação — ele lembra seu contexto de projeto, decisões passadas e padrões
de codebase.
Configuração
Método 1: comando CLI (recomendado)
[CODE BLOCK]
Método 2: editar arquivo de config
Edite :
[CODE BLOCK]
Verifique se funciona
Inicie o Claude Code:
[CODE BLOCK]
No prompt do Claude Code, digite:
[CODE BLOCK]
Claude deve chamar e responder com suas memórias armazenadas.
Padrões comuns
Persistência de contexto de projeto
No início de uma sessão de codificação:
[CODE BLOCK]
Claude chama , vê sua lista de projetos e continua o trabalho de
onde você parou.
Decisões de codebase
Quando você toma uma decisão arquitetural:
[CODE BLOCK]
Claude chama com categoria , prioridade .
Evitar erros passados
[CODE BLOCK]
Claude busca memórias com categoria e o lembra de erros passados.
Rastreamento de tarefas
[CODE BLOCK]
Claude chama , e a tarefa persiste entre sessões.
Tool Profiles
Para sessões de codificação onde você não precisa de todas as 119 ferramentas:
[CODE BLOCK]
Troubleshooting
Servidor MCP não inicia
[CODE BLOCK]
Mind Key não reconhecida
[CODE BLOCK]
Claude Code não vê as ferramentas
- Reinicie o Claude Code após mudanças na config
- Confira para verificar se o Synapse está registrado
- Consulte MCP Troubleshooting
Próximos passos
- Configuração do Claude Desktop
- Configuração do Cursor
- Guia de agente LLM persistente
────────────────────────────────────────────────────────────
# MCP no Claude Desktop
SUMMARY: Conecte o Synapse ao Claude Desktop em 2 minutos. Claude recebe 79 ferramentas do Synapse nativamente.
KEY CONTEXT:
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
%APPDATA%\Claude\claude_desktop_config.json (Windows)
MCP server command: npx -y synapse-mcp-api@latest
Env vars: SYNAPSE_MIND_KEY (required), SYNAPSE_URL (optional, default https://synapse.schaefer.zone)
After config: restart Claude Desktop, check for 🔌 icon with "79 tools"
Test: type "memory_recall aufrufen" in a new chat
Troubleshooting: Node.js ≥ 18, check Mind Key, see /docs/mcp/troubleshooting
MCP no Claude Desktop
Claude Desktop é o aplicativo desktop da Anthropic para macOS e Windows. Com o
servidor MCP do Synapse configurado, Claude ganha acesso nativo a todas as 79
ferramentas do Synapse — pode armazenar memórias, recuperá-las, gerenciar
tarefas, conversar com você e mais.
Pré-requisitos
- App Claude Desktop (macOS ou Windows)
- Node.js 18+ instalado ()
- Sua Mind Key do Synapse
Passo 1: abra o arquivo de config
- macOS:
- Windows:
Se o arquivo não existir, crie-o.
Passo 2: adicione o servidor MCP do Synapse
[CODE BLOCK]
> [!TIP]
> Se você já tem outros servidores MCP configurados, basta adicionar o bloco
> dentro do objeto existente.
Passo 3: reinicie o Claude Desktop
1. Saia totalmente do Claude Desktop (Cmd+Q no macOS, não apenas feche a janela)
2. Reabra o Claude Desktop
3. Inicie um novo chat
4. Procure pelo ícone 🔌 no canto inferior esquerdo — deve dizer "79 tools"
Passo 4: teste
Em um novo chat, digite:
[CODE BLOCK]
Claude deve chamar a ferramenta e responder com um resumo das
suas memórias armazenadas (ou "No memories yet" se seu mind estiver vazio).
Ferramentas disponíveis (seleção)
| Ferramenta | Descrição |
|------------|-----------|
| | Recuperar todas as memórias |
| | Armazenar uma nova memória |
| | Buscar memórias |
| | Listar tarefas |
| | Criar uma tarefa |
| | Verificar novas mensagens |
| | Responder a uma mensagem |
| | Abrir uma aba do navegador |
| | Listar computadores registrados |
Lista completa: O que é MCP?
Troubleshooting
Nenhuma ferramenta aparece no Claude Desktop
1. Verifique a versão do Node.js: (deve ser ≥ 18)
2. Confira se o arquivo de config é JSON válido (sem vírgulas no final)
3. Reinicie totalmente o Claude Desktop (Cmd+Q, não apenas feche)
4. Confira os logs do Claude Desktop: (macOS)
Erro "Mind Key invalid"
- Verifique se começa com
- Obtenha uma nova key via (requer JWT de )
- Sem aspas ao redor da key no JSON
npx não encontrado
- Instale Node.js 18+:
- Reinicie o terminal após instalar
- No macOS com Homebrew:
Ferramentas aparecem, mas chamadas falham
- Verifique se é alcançável:
- Verifique se sua Mind Key funciona:
- Consulte MCP Troubleshooting
Tool Profiles (economize tokens)
Se você está usando um LLM menor ou quer economizar tokens de contexto, defina
um tool profile:
[CODE BLOCK]
Profiles: (8 ferramentas), (25), (119, padrão).
Próximos passos
- Configuração do Claude Code
- Configuração do Cursor
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# MCP no Continue.dev
SUMMARY: Conecte o Synapse ao Continue.dev — assistente de codificação IA open-source para VS Code e JetBrains.
MCP no Continue.dev
Continue.dev é um assistente de codificação IA open-source para VS Code e IDEs
JetBrains. Com o MCP do Synapse, o Continue ganha memória persistente entre
sessões.
Pré-requisitos
- VS Code ou IDE JetBrains
- Extensão Continue.dev instalada
- Node.js 18+
- Sua Mind Key do Synapse
Configuração
Passo 1: abra a config do Continue
No VS Code ou JetBrains:
1. Abra a barra lateral da extensão Continue
2. Clique no ícone de engrenagem → "Open config.json"
Ou edite diretamente.
Passo 2: adicione o servidor MCP do Synapse
[CODE BLOCK]
Passo 3: recarregue o Continue
Recarregue a janela do VS Code (Cmd+Shift+P → "Reload Window") ou reinicie sua
IDE.
Verifique se funciona
No chat do Continue:
[CODE BLOCK]
Continue deve chamar e responder com suas memórias armazenadas.
Padrões comuns
Contexto de projeto
[CODE BLOCK]
Continue chama , vê suas memórias de projeto e continua o
trabalho de onde você parou.
Padrões de code review
[CODE BLOCK]
Continue encontra seus padrões de code review armazenados e os aplica.
Memória de pair programming
[CODE BLOCK]
Continue armazena como uma memória .
Troubleshooting
Servidor MCP não conecta
1. Confira se é JSON válido
2. Verifique o Node.js:
3. Confira o painel de saída do Continue (View → Output → Continue)
4. Reinicie a IDE
Ferramentas não aparecem
- Verifique se a versão do Continue suporta MCP (≥ 0.9.x)
- Confira se a env var está definida na config
- Procure erros de MCP nos logs do Continue
Próximos passos
- Configuração do Claude Desktop
- Cliente MCP customizado
────────────────────────────────────────────────────────────
# MCP no Cursor
SUMMARY: Conecte o Synapse ao IDE Cursor para memória persistente de projeto entre sessões de codificação.
MCP no Cursor
Cursor é uma IDE com IA baseada no VS Code. Com o MCP do Synapse, o Cursor
ganha memória persistente entre sessões — ele lembra suas decisões de projeto,
padrões de codebase e sessões de depuração passadas.
Pré-requisitos
- IDE Cursor instalada ()
- Node.js 18+
- Sua Mind Key do Synapse
Configuração
Passo 1: abra as configurações do Cursor
No Cursor:
1. Abra Settings (Cmd+, no macOS, Ctrl+, no Windows/Linux)
2. Busque por "MCP" ou navegue até
Passo 2: adicione o servidor MCP do Synapse
Clique em "Add MCP Server" e configure:
| Campo | Valor |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Passo 3: edite config.json diretamente (alternativa)
O Cursor armazena a config MCP em :
[CODE BLOCK]
Passo 4: reinicie o Cursor
Reinicie totalmente o Cursor (Cmd+Q e reabra no macOS).
Verifique se funciona
No painel de chat do Cursor (Cmd+L):
[CODE BLOCK]
Cursor deve chamar e responder com suas memórias armazenadas.
Padrões comuns
Onboarding de projeto
Ao abrir um novo projeto:
[CODE BLOCK]
Cursor chama e continua o trabalho de onde você parou.
Decisões de arquitetura
[CODE BLOCK]
Cursor armazena como uma memória com prioridade .
Histórico de depuração
[CODE BLOCK]
Cursor busca memórias e o lembra de correções passadas.
Padrões de código cross-sessão
[CODE BLOCK]
Cursor encontra memórias sobre implementações de auth que você fez antes.
Troubleshooting
Servidor MCP não conecta
1. Verifique o Node.js: (≥ 18)
2. Teste o servidor MCP: (deve iniciar sem erros)
3. Confira os logs MCP do Cursor (View → Output → MCP)
4. Reinicie totalmente o Cursor
Ferramentas não aparecem
- Confira se é JSON válido
- Verifique se a env var está definida
- Confira se a versão do Cursor suporta MCP (≥ 0.42)
Mind Key inválida
[CODE BLOCK]
Próximos passos
- Configuração do Claude Desktop
- Configuração do Continue.dev
- Guia de agente LLM persistente
────────────────────────────────────────────────────────────
# Construa um cliente MCP customizado
SUMMARY: Conecte-se ao servidor MCP do Synapse a partir do seu próprio aplicativo usando o SDK MCP.
Construa um cliente MCP customizado
Se você está construindo seu próprio aplicativo LLM, pode se conectar ao
servidor MCP do Synapse diretamente usando o SDK oficial do MCP. Isso dá ao
seu app acesso a todas as 79 ferramentas do Synapse.
SDKs
| Linguagem | Pacote |
|-----------|--------|
| TypeScript/JavaScript | |
| Python | |
Exemplo em TypeScript
Instalação
[CODE BLOCK]
Conexão via stdio
[CODE BLOCK]
Conexão via HTTP/SSE (remoto)
[CODE BLOCK]
Exemplo em Python
Instalação
[CODE BLOCK]
Conexão via stdio
[CODE BLOCK]
Tool Profiles
Ao conectar, você pode solicitar um tool profile específico via cabeçalho
(HTTP/SSE) ou env var (stdio):
[CODE BLOCK]
Tratamento de erros
[CODE BLOCK]
Casos de uso
- Assistentes de IA customizados — construa seu próprio agente com memória persistente
- Automação de workflows — encadeie ferramentas do Synapse em workflows customizados
- Pipelines de dados — extraia memórias, transforme, carregue em outro lugar
- Dashboards de monitoramento — exiba estatísticas de memória, histórico de chat, tarefas
Próximos passos
- Especificação MCP
- Repo do Synapse MCP
- Visão geral da API
────────────────────────────────────────────────────────────
# MCP Troubleshooting
SUMMARY: Resolva problemas comuns de integração MCP — servidor não inicia, ferramentas não aparecem, erros de auth.
KEY CONTEXT:
Common issues:
1. Node.js < 18 → upgrade to 18+
2. Mind Key invalid → check format (mk_...), get fresh via POST /minds
3. npx not found → install Node.js
4. Tools not appearing → restart client, check config JSON validity
5. SYNAPSE_URL unreachable → curl /health to verify
6. MCP server crashes → check logs, run npx manually to see error
Debug steps: run `npx -y synapse-mcp-api@latest` manually, check stderr
Logs: Claude Desktop ~/Library/Logs/Claude/mcp.log, Cursor ~/.cursor/logs/
MCP Troubleshooting
Problemas comuns e soluções ao integrar o MCP do Synapse com seu cliente LLM.
Checklist rápido de diagnóstico
1. ✅ Node.js 18+ instalado? ()
2. ✅ Mind Key começa com ? (não JWT )
3. ✅ API do Synapse alcançável? ()
4. ✅ Mind Key funciona? ()
5. ✅ Arquivo de config é JSON válido? (sem vírgulas no final, sem comentários)
6. ✅ Cliente reiniciado após mudança de config?
7. ✅ Servidor MCP inicia manualmente? ()
Problema: nenhuma ferramenta aparece no cliente
Sintomas
- Claude Desktop / Cursor / Continue mostra 0 ferramentas
- Sem ícone 🔌 ou entrada "synapse" na lista de servidores MCP
Soluções
1. Reinicie o cliente totalmente — Cmd+Q no macOS (não apenas feche a janela)
2. Confira o local do arquivo de config:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Valide o JSON — cole a config em
4. Confira os logs do cliente para erros de MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Rode o servidor MCP manualmente para ver erros de inicialização:
[CODE BLOCK]
Problema: erro "Mind Key invalid"
Sintomas
- Ferramentas aparecem, mas chamadas falham com "401 Unauthorized"
- Erro: "Mind Key fehlt oder ungültig"
Soluções
1. Verifique o formato da Mind Key — começa com , 40 caracteres
2. Teste diretamente:
[CODE BLOCK]
3. Confira se a env var está definida — para transporte stdio, a env var deve estar na config do servidor MCP, não no seu shell
4. Obtenha uma nova Mind Key:
[CODE BLOCK]
Problema: npx não encontrado
Sintomas
- Erro: "npx: command not found"
- Servidor MCP falha ao iniciar
Soluções
1. Instale Node.js 18+:
- macOS: ou baixe de
- Linux:
- Windows: baixe de
2. Reinicie o terminal após instalar
3. Verifique:
Problema: SYNAPSEURL inalcançável
Sintomas
- Servidor MCP inicia, mas chamadas de ferramenta dão timeout
- Erro: "fetch failed" ou "ECONNREFUSED"
Soluções
1. Teste conectividade:
[CODE BLOCK]
2. Confira firewall corporativo — pode bloquear HTTPS de saída
3. Tente URL alternativa:
- Produção:
- Servidor MCP:
4. Para auto-hospedagem: garanta que sua instância do Synapse esteja rodando e acessível
Problema: servidor MCP trava
Sintomas
- Servidor MCP sai imediatamente após iniciar
- Logs do cliente mostram "MCP server disconnected"
Soluções
1. Rode manualmente para ver o erro:
[CODE BLOCK]
2. Confira conflitos de porta — servidor MCP usa a porta 13100 por padrão
3. Limpe o cache do npx:
[CODE BLOCK]
4. Atualize para a versão mais recente:
[CODE BLOCK]
Problema: chamadas de ferramenta retornam 429
Sintomas
- Erro: "Rate limit exceeded"
Soluções
Isso não deveria acontecer com MCP (usa auth por cabeçalho, sem limite de
taxa). Se acontecer:
1. Verifique se você está usando em algum lugar — mude para auth por cabeçalho
2. Verifique — garanta que aponta para a instância correta
3. Contate o suporte se o problema persistir
Problema: ferramentas aparecem, mas não funcionam
Sintomas
- Ferramentas listadas no cliente
- Chamar uma ferramenta retorna erro ou nenhum resultado
Soluções
1. Confira o nome da ferramenta — deve ser exato (ex.: , não )
2. Verifique os argumentos — confira o schema de entrada da ferramenta
3. Teste via API direta:
[CODE BLOCK]
4. Confira a saúde do Synapse:
[CODE BLOCK]
Obtendo ajuda
Se nada acima resolver seu problema:
1. Confira issues existentes:
2. Abra uma nova issue com:
- Versão do servidor MCP ()
- Nome e versão do cliente
- Sistema operacional
- Trechos de log relevantes
- Passos para reproduzir
Próximos passos
- Configuração do Claude Desktop
- Configuração do Claude Code
- Erros da API
────────────────────────────────────────────────────────────
# O que é MCP?
SUMMARY: Model Context Protocol permite que LLMs chamem ferramentas externas. O Synapse expõe 79 ferramentas via servidor MCP oficial.
KEY CONTEXT:
MCP = Model Context Protocol (Anthropic, 2024). Open standard for LLM-tool integration.
Synapse has official MCP server: synapse-mcp-api (npm package, npx -y synapse-mcp-api@latest)
79 tools exposed: 22 memory, 7 chat, 8 scheduler, 4 tasks, 5 scripts, 9 computers, 4 push, 5 user, 3 utility
3 transports: stdio (local), HTTP/SSE (remote), WebSocket (mobile)
Supported clients: Claude Desktop, Claude Code, Cursor, Continue, Cline, any MCP-compatible client
Tool Profiles (v1.4.0): minimal (8 tools), standard (25), full (119) — controlled via MCP_PROFILE env or Mcp-Tool-Profile header
O que é MCP?
O Model Context Protocol (MCP) é um padrão aberto da Anthropic (2024) que
permite aos LLMs chamar ferramentas externas de forma estruturada. Em vez de
colar docs de API no prompt, você registra ferramentas com o servidor MCP, e o
LLM as chama conforme necessário — como function calling, mas padronizado e
agnóstico de cliente.
Servidor MCP do Synapse
O Synapse traz um servidor MCP oficial ( no npm) que expõe
79 ferramentas cobrindo todos os recursos do Synapse:
| Categoria | Ferramentas | Contagem |
|-----------|-------------|----------|
| Memória | recall, list, store, search, semantic-search, update, delete, bulk-delete, stats, unverified, contradictions, audit, related, by-tag, diff, expiring, health, sync, embed-batch, verify, unverify, mind-export | 22 |
| Chat | poll, reply, status, history, unread, send, upload | 7 |
| Agendador | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tarefas | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computadores | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| Usuário/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utilitários | time, calc, random | 3 |
| Visualização | graph, tags, compact | 3 |
| Compartilhamento | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Navegador | new, navigate, click, type, screenshot, close | 6 |
| Total | | 79+ |
Como funciona
[CODE BLOCK]
1. Você configura seu cliente LLM (Claude Desktop, Cursor, etc.) para usar o servidor MCP do Synapse
2. O cliente inicia o servidor MCP (via )
3. O servidor MCP conecta-se à API do Synapse usando sua Mind Key
4. O LLM vê todas as 79 ferramentas como funções nativas que pode chamar
5. Quando o LLM precisa lembrar algo, ele chama — o servidor MCP traduz isso para no Synapse
Transportes
O servidor MCP do Synapse suporta três transportes:
stdio (local, recomendado para desktop)
[CODE BLOCK]
HTTP/SSE (remoto, multi-tenant)
Conecte seu cliente MCP a:
[CODE BLOCK]
WebSocket (mobile, alto volume)
[CODE BLOCK]
Tool Profiles (v1.4.0)
Para reduzir o overhead de tokens para LLMs menores, o servidor MCP suporta
três tool profiles:
| Profile | Ferramentas | Tokens | Melhor para |
|---------|-------------|--------|-------------|
| | 8 (dispatch composto) | 500 | LLMs auto-hospedados com contexto ≤8k |
| | 25 (nomeadas) | 2.500 | LLMs médios (Claude Haiku, GPT-3.5) |
| | 119 (todas) | 8.250 | LLMs grandes (Claude Sonnet/Opus, GPT-4) — padrão |
Controle via:
- Env var:
- Cabeçalho:
Clientes suportados
- Claude Desktop — app desktop da Anthropic
- Claude Code — agente de codificação em terminal
- Cursor — IDE com IA
- Continue.dev — assistente de codificação IA open-source
- Cline — extensão do VS Code
- Qualquer cliente compatível com MCP
Por que usar MCP em vez de API direta?
| Abordagem | Prós | Contras |
|-----------|------|---------|
| API direta | Simples, sem camada extra | LLM precisa saber URLs, headers, auth |
| MCP | LLM vê ferramentas nativas, sem memorizar URL | Processo extra de servidor MCP |
Para a maioria dos casos de uso de agentes LLM, MCP é a melhor escolha — o LLM
não precisa lembrar caminhos de API ou padrões de auth.
Próximos passos
- Configuração do Claude Desktop — config em 2 minutos
- Configuração do Claude Code — integração com terminal
- Cliente MCP customizado — construa o seu
## CATEGORIA: GUIAS E TUTORIAIS
Guias passo a passo para cenários concretos.
────────────────────────────────────────────────────────────
# Testes automatizados de apps iOS
SUMMARY: Use Synapse + API de Controle de Computadores para automatizar testes de apps iOS via Simulator.
Testes automatizados de apps iOS
Combine o sistema de memória do Synapse com a API de Controle de Computadores
para construir testes de apps iOS orientados por LLM. O LLM lembra cenários de
teste, aprende com falhas passadas e se adapta a mudanças de UI.
Arquitetura
[CODE BLOCK]
Pré-requisitos
- Conta no Synapse + Mind Key
- Servidor MCP do Synapse configurado no Claude Desktop
- iOS Simulator com instalado
- Computador registrado no Synapse (consulte API de Controle de Computadores)
Passo 1: registre o computador Simulator
No Mac que roda o iOS Simulator:
[CODE BLOCK]
Passo 2: armazene cenários de teste em memória
Armazene cenários de teste reutilizáveis como memórias:
[CODE BLOCK]
Passo 3: execução de teste orientada por LLM
No Claude Desktop (com Synapse MCP configurado):
[CODE BLOCK]
Claude vai:
1. Chamar para encontrar a memória
2. Chamar para ver o estado atual
3. Executar cada passo via (click, type)
4. Verificar resultados via screenshots
5. Armazenar quaisquer falhas como memórias
Passo 4: testes self-healing
Quando um teste falha, armazene a falha e a recuperação:
[CODE BLOCK]
Na próxima vez que o LLM rodar o teste, ele recupera a falha e aplica a
recuperação automaticamente.
Passo 5: rastreamento de resultados de teste
Rastreie execuções de teste como tarefas:
[CODE BLOCK]
Comandos comuns
| Ação | Comando |
|------|---------|
| Iniciar Simulator | |
| Screenshot | (via Synapse MCP) |
| Tocar em (x,y) | |
| Digitar texto | |
| Pressionar Home | |
Melhores práticas
> [!TIP]
> - Armazene coordenadas de UI como memórias — a UI muda, mas o LLM pode reaprender
> - Use rótulos de acessibilidade — mais estáveis que coordenadas
> - Armazene dados de teste separadamente — use variáveis para usernames, senhas
> - Rode testes em estado limpo — reinicie o Simulator entre execuções
> - Registre screenshots das falhas — útil para depuração
Próximos passos
- Testes self-healing
- API de Controle de Computadores
- Melhores práticas de memória
────────────────────────────────────────────────────────────
# Backup & Restore
SUMMARY: Exporte suas memórias para backup, migre entre minds, restaure após perda de dados.
Backup & Restore
O Synapse oferece exportação/importação completos para backup de memória,
migração e recuperação de desastres. Este guia cobre as operações essenciais.
Exportação
Exportação completa do mind
Exporte todas as memórias de um mind como JSON:
[CODE BLOCK]
Formato da resposta:
[CODE BLOCK]
Exportação incremental (Diff)
Exporte apenas memórias alteradas desde um timestamp:
[CODE BLOCK]
Resposta:
[CODE BLOCK]
Backups automatizados
Agende backups diários via cron:
[CODE BLOCK]
> [!NOTE]
> O endpoint cron recebe a resposta mas não a armazena. Para backups reais,
> aponte o cron para seu próprio servidor de backup que salva a resposta.
Melhor: script de backup externo
[CODE BLOCK]
Adicione ao crontab:
[CODE BLOCK]
Restauração
Restaurar para o mesmo mind
[CODE BLOCK]
Restaurar para um novo mind
[CODE BLOCK]
Script de restauração em Python
[CODE BLOCK]
Migração entre minds
[CODE BLOCK]
Backup de outros dados
Não se esqueça de fazer backup de:
| Tipo de dado | Endpoint |
|--------------|----------|
| Memórias | |
| Tarefas | |
| Scripts | |
| Webhooks | |
| Cron jobs | |
| Variáveis | |
| Histórico de chat | |
Verificação
Após restaurar, verifique:
[CODE BLOCK]
Melhores práticas
> [!TIP]
> - Faça backup diariamente — automatize com cron
> - Teste restaurações — um backup que você não consegue restaurar é inútil
> - Mantenha múltiplas versões — pelo menos 30 dias
> - Armazene fora do site — S3, Backblaze B2, etc.
> - Criptografe backups sensíveis — memórias podem conter PII
> - Documente o processo de restauração — você vai esquecê-lo quando precisar
Próximos passos
- API de Memória
- Cron & Agendador — para backups automatizados
────────────────────────────────────────────────────────────
# Melhores práticas de memória
SUMMARY: 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 |
|-----------|-----------|---------|
| | Nome, papel, contato do usuário | |
| | Gostos, desgostos, estilo de trabalho | |
| | Fatos verificáveis | |
| | Status de projeto, decisões | |
| | Habilidades do usuário | |
| | Erros passados a evitar | |
| | Contexto relevante para a sessão | |
| | Notas diversas | |
> [!TIP]
> Em caso de dúvida, use para info verificável e para todo o
> resto. Não categorize em excesso — melhor ter um claro do que um
> confuso.
Keys: identificadores significativos
O campo é o identificador da memória. Use keys significativas e estáveis:
Keys boas:
-
-
-
-
Keys ruins:
- (não significativa)
- (não descritiva)
- (data não ajuda o recall)
Convenções de nomenclatura de keys
- (minúsculas com underscores)
- Prefixe com a categoria: , ,
- 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:
[CODE BLOCK]
Padrões de tags
- Nomes de projeto: , ,
- Tópicos: , , ,
- Status: , ,
- Indicadores de prioridade: ,
> [!NOTE]
> Tags são case-insensitive. Use minúsculas para consistência.
Prioridades: seja realista
| Prioridade | Usar para | % das memórias |
|------------|-----------|-----------------|
| | Identidade do usuário, info jurídica, decisões irreversíveis | 5% |
| | Projetos ativos, preferências importantes | 20% |
| | Maioria dos fatos, notas, contexto | 65% |
| | Efêmero, bom saber | 10% |
> [!WARNING]
> Não marque tudo como . Se tudo é crítico, nada é. Reserve
> 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 com prioridade baixa)
Atualizando memórias
POST com a mesma + atualiza a memória existente:
[CODE BLOCK]
> [!TIP]
> 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
[CODE BLOCK]
- 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 , mantenha para referência histórica
- Delete: DELETE /memory/:id quando não for mais relevante
Limpeza periódica
[CODE BLOCK]
Padrão: herança de memória
Para contexto hierárquico (projeto → subprojeto → tarefa):
[CODE BLOCK]
O LLM pode então buscar 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:
[CODE BLOCK]
Padrão: evitar erros
Armazene erros com instruções específicas de evitação:
[CODE BLOCK]
Antipadrões a evitar
> [!WARNING]
> - Armazenar logs de conversa — o sistema de chat cuida disso
> - Armazenar arquivos inteiros — use script store ou armazenamento externo
> - Armazenar estado efêmero — use variáveis
> - Armazenar segredos — use variáveis de ambiente
> - Duplicar memórias — use keys estáveis
> - Taguear em excesso — 2-5 tags por memória é o ideal
> - Tudo é crítico — seja realista com prioridades
Próximos passos
- API de Memória
- Agente LLM persistente
- Estratégia de tagueamento de memória
────────────────────────────────────────────────────────────
# Coordenação multi-agente
SUMMARY: Coordene múltiplos agentes LLM usando minds, tarefas e chat compartilhados do Synapse.
Coordenação multi-agente
Quando você tem múltiplos agentes LLM trabalhando em tarefas relacionadas, o
Synapse fornece a camada de coordenação — memória compartilhada, atribuição de
tarefas e chat assíncrono.
Padrões
Padrão 1: mind compartilhado (fonte única de verdade)
Todos os agentes compartilham uma Mind Key. Eles leem/escrevem no mesmo
armazenamento de memória.
[CODE BLOCK]
Caso de uso: pequena equipe de agentes trabalhando em um projeto.
Configuração:
[CODE BLOCK]
Coordenação via tarefas:
[CODE BLOCK]
Padrão 2: minds especializados (contextos isolados)
Cada agente tem seu próprio mind. Eles se comunicam via um mind de "coordenação"
compartilhado.
[CODE BLOCK]
Caso de uso: agentes com diferentes especialidades (codificação, revisão,
deploy).
Configuração:
[CODE BLOCK]
Coordenação via mind compartilhado:
[CODE BLOCK]
Padrão 3: hub-and-spoke (orquestrador)
Um agente orquestrador central atribui tarefas a agentes trabalhadores.
[CODE BLOCK]
Caso de uso: workflows complexos com trabalho paralelo.
Implementação:
[CODE BLOCK]
Coordenação via chat
Agentes podem se comunicar via o sistema de chat:
[CODE BLOCK]
> [!NOTE]
> Mensagens de chat são marcadas por papel. Defina role=agent para mensagens
> agente-para-agente, role=human para humano-para-agente.
Coordenação via variáveis
Use variáveis para coordenação leve (locks, flags):
[CODE BLOCK]
Melhores práticas
> [!TIP]
> - Use minds separados para preocupações separadas — não misture memória de coder e reviewer
> - Marque agentes no chat — para endereçamento claro
> - Use tarefas para atribuição de trabalho — não chat (chat é para discussão)
> - Implemente idempotência — agentes podem refazer operações falhas
> - Registre tudo — armazene decisões em memória para auditabilidade
Próximos passos
- Agente LLM persistente
- Cookbook de LLM
- Automação com webhooks
────────────────────────────────────────────────────────────
# Construa um agente LLM persistente
SUMMARY: Guia passo a passo para construir um agente LLM que lembra entre sessões usando o Synapse.
Visão geral
Este guia conduz a construção de um agente LLM que persiste contexto entre
sessões usando o Synapse. Ao final, seu agente vai:
- Recuperar contexto passado no início da sessão
- Armazenar novos aprendizados conforme acontecem
- Rastrear tarefas multi-etapas entre sessões
- Comunicar-se com humanos via chat assíncrono
Arquitetura
[CODE BLOCK]
Passo 1: configure a Mind Key
[CODE BLOCK]
Passo 2: protocolo de início de sessão
No início de cada sessão, recupere todas as memórias:
[CODE BLOCK]
Passo 3: armazene novos aprendizados
Sempre que o agente aprender algo que vale a pena lembrar:
[CODE BLOCK]
Passo 4: gerenciamento de tarefas
Rastreie trabalho multi-etapas entre sessões:
[CODE BLOCK]
Passo 5: chat assíncrono com humanos
Faça poll por mensagens entre chamadas de ferramenta:
[CODE BLOCK]
Passo 6: protocolo de fim de sessão
No fim da sessão, armazene o contexto final:
[CODE BLOCK]
Padrão completo
[CODE BLOCK]
Melhores práticas
> [!TIP]
>
> - Sempre recupere primeiro — nunca comece trabalho sem carregar o contexto
> - Armazene proativamente — não espere até o fim da sessão
> - Use keys significativas — , , não
> - Tagueie tudo — tags alimentam busca e filtragem
> - Defina prioridades realistas — nem tudo é
Próximos passos
- Cookbook de LLM — padrões práticos
- Melhores práticas de memória
- Coordenação multi-agente
────────────────────────────────────────────────────────────
# Pipelines de teste self-healing
SUMMARY: Construa pipelines de teste que aprendem com falhas e se adaptam automaticamente usando a memória do Synapse.
Pipelines de teste self-healing
Suítes de teste tradicionais quebram quando a UI muda. Testes self-healing usam
a memória do Synapse para aprender com falhas passadas e se adaptar — reduzindo
testes flaky e a carga de manutenção.
Conceito
[CODE BLOCK]
1. O teste roda
2. Se falhar, armazene a falha (o que deu errado, por quê, como corrigir)
3. Próxima execução: recupere falhas relevantes antes de executar
4. Aplique correções conhecidas automaticamente
Implementação
Passo 1: wrapper de teste
Envolva cada teste com recall/store de memória:
[CODE BLOCK]
Passo 2: lógica de teste adaptativa
Dentro do teste, verifique falhas conhecidas e aplique correções:
[CODE BLOCK]
Passo 3: estratégias de recuperação
Armazene estratégias de recuperação como memórias:
[CODE BLOCK]
Passo 4: integração com CI
[CODE BLOCK]
Passo 5: dashboard de análise de falhas
[CODE BLOCK]
Melhores práticas
> [!TIP]
> - Armazene tracebacks — eles contêm a linha exata que falhou
> - Tagueie por nome de teste — permite filtragem rápida
> - Use categoria — separa de memórias regulares
> - Defina prioridade — falhas nunca devem ser esquecidas
> - Limpeza periódica — exclua memórias de problemas resolvidos
> - Não armazene dados sensíveis — credenciais, PII
Padrões comuns de falha para armazenar
| Tipo de falha | O que armazenar |
|---------------|-----------------|
| Elemento não encontrado | Seletor tentado, estado da página, screenshot |
| Timeout | Tempo de espera, o que estava sendo esperado |
| Asserção falhou | Valor esperado vs. atual |
| Erro de rede | URL, código de status, corpo da resposta |
| Permissão negada | Permissão necessária, papel do usuário atual |
Próximos passos
- Testes automatizados de iOS
- Melhores práticas de memória
- Cookbook de recuperação de erros
────────────────────────────────────────────────────────────
# Automação com webhooks
SUMMARY: Dispare sistemas externos quando as memórias mudam — sincronize, notifique, automatize.
Automação com webhooks
Webhooks permitem disparar sistemas externos quando eventos do Synapse
ocorrem. Este guia cobre padrões comuns de automação.
Padrões comuns
Padrão 1: notificar em memória crítica
Envie uma mensagem Slack quando uma memória crítica é armazenada:
[CODE BLOCK]
Registre o webhook:
[CODE BLOCK]
Padrão 2: sincronizar com sistema externo
Sincronize memórias com Notion, Obsidian ou qualquer KB externo:
[CODE BLOCK]
Padrão 3: disparar CI/CD
Dispare um deploy quando uma memória "release" é armazenada:
[CODE BLOCK]
Padrão 4: acordar agente em mensagem humana
Dispare uma execução de agente LLM quando um humano envia uma mensagem de chat:
[CODE BLOCK]
Padrão 5: agregar métricas
Rastreie crescimento de memória, atividade de chat, conclusão de tarefas:
[CODE BLOCK]
Verificação de assinatura
Sempre verifique assinaturas de webhook para evitar spoofing:
[CODE BLOCK]
Lógica de retry
O Synapse refaz webhooks falhados com backoff exponencial. Seu handler deve:
1. Retornar 200 rapidamente — não faça trabalho pesado sincronamente
2. Enfileirar trabalho — use um sistema de jobs em background
3. Ser idempotente — o mesmo evento pode ser entregue duas vezes
[CODE BLOCK]
Depurando webhooks
Verifique o histórico de entrega
Entregas de webhook são registradas. Confira as entregas recentes do seu
webhook:
[CODE BLOCK]
Teste o webhook manualmente
[CODE BLOCK]
Problemas comuns
| Problema | Correção |
|----------|----------|
| Respostas 4xx | Verifique se seu handler retorna 200 |
| Respostas 5xx | Erro de servidor — confira os logs do seu app |
| Timeout | Retorne 200 rápido, enfileire trabalho assíncrono |
| Entregas duplicadas | Torne o handler idempotente |
| Incompatibilidade de assinatura | Verifique se o secret está correto |
Melhores práticas
> [!TIP]
> - Sempre verifique assinaturas — nunca pule isso
> - Retorne 200 rápido — não bloqueie o Synapse
> - Seja idempotente — trate entregas duplicadas
> - Use eventos específicos — em vez de
> - Monitore falhas de entrega — configure alertas
Próximos passos
- API de Webhooks
- Cron & Agendador
- Agente LLM persistente
## CATEGORIA: CONCEITOS
Arquitetura e conceitos por trás do Synapse.
────────────────────────────────────────────────────────────
# Arquitetura do Synapse
SUMMARY: Como o Synapse é construído — Fastify, PostgreSQL, FTS5, embeddings, servidor MCP.
Arquitetura do Synapse
O Synapse é uma API de memória multi-tenant construída sobre Fastify, PostgreSQL
com FTS5 e um serviço opcional de embeddings para busca semântica.
Arquitetura de alto nível
[CODE BLOCK]
Componentes principais
1. Synapse API (Fastify)
O servidor HTTP principal. Cuida de:
- Endpoints REST (, , , etc.)
- Autenticação (Mind Key para agentes, JWT para humanos)
- Limites de taxa (apenas auth )
- Servimento de arquivos estáticos (interface web em , , etc.)
- Dispatch de webhooks
Construído com Fastify 5 para desempenho. Roda na porta 12800 em produção.
2. PostgreSQL com FTS5
O armazenamento principal de dados. Usa PostgreSQL com a extensão FTS5 para
busca em texto completo.
Tabelas principais:
| Tabela | Finalidade |
|--------|------------|
| | Contas de usuário |
| | Escopos de mind (cada um tem uma Mind Key) |
| | Registros de memória com tabela virtual FTS5 |
| | Gerenciamento de tarefas |
| | Histórico de chat |
| | Scripts persistentes |
| | Registros de webhook |
| | Tarefas agendadas |
| | Armazenamento key-value |
| | Trilha de auditoria |
FTS5 permite busca em texto completo sub-milissegundo em todo o conteúdo
das memórias. Consulte Busca FTS5 para detalhes.
3. Serviço de Embeddings (opcional)
Para busca semântica, o Synapse gera embeddings vetoriais do conteúdo das
memórias. Eles são armazenados junto com as memórias e usados para busca por
similaridade.
- Provedor: configurável (OpenAI, modelo local, etc.)
- Armazenado como coluna na tabela
- Usado pelo endpoint
- Consulte Busca semântica
4. Servidor MCP (serviço separado)
O servidor MCP do Synapse roda como um processo separado (porta 13100). Ele:
- Expõe 79 ferramentas via Model Context Protocol
- Suporta transportes stdio, HTTP/SSE e WebSocket
- Traduz chamadas de ferramentas MCP em chamadas da API do Synapse
- Multi-tenant: uma Mind Key por sessão
5. Browser Proxy (serviço separado)
Para automação de navegador, um serviço separado baseado em Playwright roda na
porta 13000. O servidor MCP pode chamá-lo para ferramentas .
6. SSH Proxy (serviço separado)
Para comandos remotos via SSH, um serviço separado roda na porta 12900.
Modelo multi-tenant
[CODE BLOCK]
Cada mind é totalmente isolado. Mind Keys concedem acesso a exatamente um mind.
JWTs concedem acesso à conta do usuário (para gerenciar minds).
Consulte Multi-tenancy para detalhes.
Fluxo de requisição
Requisição de armazenamento de memória
[CODE BLOCK]
Requisição de busca de memória
[CODE BLOCK]
Deploy
O Synapse é implantado como um container Docker. Consulte :
[CODE BLOCK]
Características de desempenho
| Operação | Latência | Throughput |
|----------|----------|------------|
| Armazenar memória | 5ms | 1000+ req/s |
| Recall de memória | 20ms | 500 req/s |
| Busca FTS5 | 10ms | 800 req/s |
| Busca semântica | 50ms | 200 req/s |
| Poll de chat | 5ms | 2000 req/s |
Próximos passos
- Modelo de memória
- Multi-tenancy
- Busca FTS5
────────────────────────────────────────────────────────────
# Busca em texto completo FTS5
SUMMARY: Como o Synapse usa SQLite FTS5 para busca de memória em texto completo sub-milissegundo.
Busca em texto completo FTS5
O Synapse usa FTS5 (Full-Text Search 5) para busca de memória rápida e flexível.
Esta página explica como funciona e como usá-lo de forma eficaz.
O que é FTS5?
FTS5 é uma extensão do SQLite (também disponível no PostgreSQL via extensões)
que oferece capacidades de busca em texto completo. Ele:
- Indexa conteúdo textual para busca rápida por palavras-chave
- Suporta operadores booleanos (AND, OR, NOT)
- Suporta correspondência de frases com aspas
- Suporta correspondência por prefixo com
- Classifica resultados por relevância
O Synapse usa FTS5 para indexar todo o conteúdo das memórias, permitindo busca
sub-milissegundo entre milhares de memórias.
Como o Synapse usa FTS5
Quando você faz :
1. O conteúdo da memória é armazenado na tabela
2. O conteúdo também é inserido na tabela virtual FTS5
3. FTS5 automaticamente tokeniza e indexa o conteúdo
Quando você faz :
1. O Synapse faz parse da consulta usando a sintaxe FTS5
2. Executa um contra o índice FTS5
3. Filtra por (isolamento de tenant)
4. Retorna resultados classificados
Sintaxe de consulta
Busca simples por palavra-chave
[CODE BLOCK]
Retorna memórias contendo "docker".
Múltiplas palavras-chave (AND implícito)
[CODE BLOCK]
Retorna memórias contendo TANTO "docker" QUANTO "swarm".
Correspondência de frase
[CODE BLOCK]
Retorna memórias contendo a frase exata "docker swarm".
Correspondência por prefixo
[CODE BLOCK]
Retorna memórias contendo palavras que começam com "docker" (ex.: "dockers",
"dockerfile", "dockerize").
Booleano OR
[CODE BLOCK]
Retorna memórias contendo "docker" OU "kubernetes".
Booleano NOT
[CODE BLOCK]
Retorna memórias contendo "docker" mas NÃO "swarm".
Agrupamento
[CODE BLOCK]
Retorna memórias contendo "docker" ou "kubernetes", mas não "test".
Exemplos práticos
Encontrar memórias sobre um projeto
[CODE BLOCK]
Encontrar frase exata
[CODE BLOCK]
Excluir memórias de teste
[CODE BLOCK]
Buscar por tecnologia
[CODE BLOCK]
Ranking
FTS5 classifica resultados por relevância usando o algoritmo BM25. Fatores:
- Frequência do termo (com que frequência o termo aparece)
- Frequência inversa de documentos (termos mais raros recebem classificação maior)
- Comprimento do documento (documentos mais curtos com o termo recebem classificação maior)
- Peso da coluna (title > content)
Os resultados são retornados em ordem de classificação (mais relevantes primeiro).
Desempenho
| Operação | Latência |
|----------|----------|
| Busca em 100 memórias | < 5ms |
| Busca em 1.000 memórias | < 10ms |
| Busca em 10.000 memórias | < 25ms |
| Busca em 100.000 memórias | < 100ms |
FTS5 é altamente otimizado para workloads com muita leitura.
Limitações
Stemming
FTS5 não faz stemming por padrão. "running" e "run" são termos diferentes.
Solução alternativa: Use correspondência por prefixo:
Tolerância a typos
FTS5 não suporta correspondência fuzzy. Um typo não retornará resultados.
Solução alternativa: Use busca semântica () para
correspondência conceitual.
Stop words
Palavras comuns (the, a, an, is) são indexadas mas podem não ser úteis para
busca. FTS5 lida com isso automaticamente.
FTS5 vs busca semântica
| Aspecto | FTS5 | Busca semântica |
|---------|------|-----------------|
| Velocidade | Sub-milissegundo | 50-100ms |
| Correspondência | Palavras-chave exatas | Conceitual |
| Tolerância a typos | Nenhuma | Alguma |
| Stemming | Nenhum | Implícito |
| Requer embeddings | Não | Sim |
| Melhor para | Termos específicos | Conceitos |
Use FTS5 quando você conhece as palavras-chave. Use busca semântica quando você
quer "memórias sobre X" onde X é descrito de outra forma.
Melhores práticas
> [!TIP]
> - Use termos específicos — "docker swarm" supera "container orchestration"
> - Aspas para frases — garante correspondência de frase
> - Use prefixo para variações — captura "deploy", "deployment", "deploying"
> - Exclua ruído — filtra memórias de teste
> - Combine com tags — estreita os resultados
Próximos passos
- Busca semântica
- API de Memória
- Melhores práticas de memória
────────────────────────────────────────────────────────────
# O modelo de memória
SUMMARY: Como as memórias são estruturadas — categorias, keys, tags, prioridades, fontes, verificação.
O modelo de memória
O modelo de memória do Synapse é projetado para agentes LLM — estruturado o
suficiente para recall confiável, flexível o suficiente para qualquer domínio.
Anatomia de uma memória
[CODE BLOCK]
Campos
| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| | string | auto | ID único (memxxx) |
| | enum | ✅ | Uma das 8 categorias |
| | string | ✅ | Identificador estável (usado para updates) |
| | string | ✅ | O conteúdo da memória (qualquer texto) |
| | string[] | – | Para busca e filtragem |
| | enum | – | low, normal, high, critical (padrão: normal) |
| | enum | auto | user, agent (quem armazenou) |
| | bool | auto | Um humano verificou isso? |
| | float | – | 0.0 a 1.0 (padrão: 1.0 para user, 0.7 para agent) |
| | timestamp | – | Quando esquecer esta memória |
| | string | auto | Qual mind é dono disso |
| | timestamp | auto | Quando foi armazenada |
| | timestamp | auto | Última modificação |
Categorias
Oito categorias cobrem os casos de uso comuns de agentes LLM:
| Categoria | Finalidade | Exemplo de conteúdo |
|-----------|------------|---------------------|
| | Quem é o usuário | "User is Michael Schäfer, software engineer in Berlin" |
| | Preferências do usuário | "Prefers concise technical responses" |
| | Fatos verificáveis | "Office is in Berlin, timezone Europe/Berlin" |
| | Status de projeto | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Habilidades do usuário | "Advanced Python, 10+ years" |
| | Erros passados | "Forgot to bump npm version — CI failed" |
| | Contexto de sessão | "Currently reviewing PR #42" |
| | Notas diversas | "Try Redis for caching next sprint" |
Keys: identificadores estáveis
O campo é crítico — é como você atualiza memórias sem criar duplicatas.
[CODE BLOCK]
Regras de key:
- Deve ser única dentro de (category, mind)
- Use
- Prefixe com a categoria para clareza: ,
- Mantenha estável — não mude keys após a criação
Tags: para busca
Tags permitem filtragem e busca rápidas:
[CODE BLOCK]
Melhores práticas de tags:
- 2-5 tags por memória (não exagere)
- Minúsculas para consistência
- Use nomes de projeto, tópicos, tecnologias
- Tags são case-insensitive
Níveis de prioridade
| Prioridade | Quando usar | Comportamento de recall |
|------------|-------------|-------------------------|
| | Identidade, jurídico, irreversível | Sempre no topo do recall |
| | Projetos ativos, preferências-chave | Em destaque no recall |
| | Maioria das memórias (padrão) | Ordem padrão de recall |
| | Efêmero, bom saber | Pode ser resumido |
ordena por prioridade (critical primeiro), depois por
recenticidade.
Source: User vs Agent
Memórias são marcadas com :
- — armazenada por um humano (via JWT ou interface humana)
- — armazenada por um agente LLM (via Mind Key)
Isso afeta:
- Verificação: memórias são auto-verificadas, memórias não
- Confiança: padrão 1.0, padrão 0.7
- Recall: marca memórias não verificadas com "(unverified)"
> [!NOTE]
> Trate memórias de source com ceticismo apropriado. Elas podem ser
> inferidas ou presumidas em vez de diretamente declaradas pelo usuário.
Verificação
O flag indica que um humano confirmou a memória:
- Memórias : auto-verificadas ()
- Memórias : padrão não verificadas ()
Verifique memórias via:
[CODE BLOCK]
> [!NOTE]
> Verificação requer JWT (auth humana), não Mind Key (auth de agente). Isso
> garante que apenas humanos possam marcar memórias como verificadas.
Confiança
O campo (0.0 a 1.0) indica quão confiável é a memória:
- 1.0 — diretamente declarada pelo usuário
- 0.7 — inferida pelo agente
- 0.5 — incerta, precisa verificação
- 0.0 — explicitamente duvidosa
Defina a confiança ao armazenar:
[CODE BLOCK]
Expiração
Defina para memórias sensíveis ao tempo:
[CODE BLOCK]
Memórias expiradas não são retornadas por (mas ainda existem
no DB). Use para ver memórias expirando em breve.
Ciclo de vida da memória
[CODE BLOCK]
Comportamento de recall
retorna um resumo em texto puro otimizado para contexto de
LLM:
[CODE BLOCK]
- Ordenado por prioridade (critical → low), depois por recenticidade
- Memórias não verificadas marcadas com
- Tags incluídas para contexto
- Texto puro (sem necessidade de parsing JSON)
Próximos passos
- API de Memória
- Melhores práticas de memória
- Busca FTS5
────────────────────────────────────────────────────────────
# Multi-tenancy e isolamento
SUMMARY: Como o Synapse isola dados entre usuários e minds — fronteiras de segurança explicadas.
Multi-tenancy e isolamento
O Synapse é multi-tenant: múltiplos usuários, cada um com múltiplos minds,
totalmente isolados entre si. Esta página explica o modelo de isolamento.
Hierarquia de tenants
[CODE BLOCK]
Níveis de isolamento
Nível 1: isolamento de usuário
Cada conta de usuário é isolada. Alice não pode:
- Ver os minds do Bob
- Acessar as memórias do Bob (mesmo com o JWT dela)
- Listar informações da conta do Bob
Aplicado por: coluna em todas as tabelas, JWT contém ,
todas as consultas filtram por .
Nível 2: isolamento de mind
Dentro de um usuário, cada mind é isolado. Mind A não pode:
- Ver as memórias do Mind B
- Acessar tarefas, chat, scripts do Mind B
Aplicado por: coluna em todas as tabelas de dados, Mind Key contém
, todas as consultas filtram por .
> [!CRITICAL]
> O isolamento por Mind Key é a fronteira de segurança primária. Uma Mind Key
> vazada concede acesso total aos dados daquele mind — mas SOMENTE àquele mind.
Tokens de autenticação
| Token | Escopo | O que pode acessar |
|-------|--------|---------------------|
| Mind Key | Mind único | Apenas dados daquele mind |
| JWT | Conta de usuário | Gerenciamento de conta (criar/listar/excluir minds) |
| Computer Token | Computador único | Comandos daquele computador |
Acesso cross-mind
Dentro do mesmo usuário
O usuário pode acessar todos os seus minds via JWT (ex.: lista
todos). Mas para ler/escrever dados de memória, ele precisa da Mind Key
específica.
Entre usuários
Usuários não podem acessar dados um do outro — A MENOS que compartilhem
explicitamente um mind via API de Compartilhamento:
[CODE BLOCK]
Após compartilhar, Bob pode acessar o Mind A via seu JWT (somente leitura se
).
Fronteiras de segurança
[CODE BLOCK]
Padrões comuns de multi-tenancy
Padrão 1: usuário único, mind único
Mais comum para usuários individuais de agentes LLM.
- 1 conta de usuário
- 1 mind
- 1 Mind Key
- Todas as memórias em um escopo
Padrão 2: usuário único, múltiplos minds
Para usuários com múltiplos contextos (trabalho, pessoal, projetos).
- 1 conta de usuário
- N minds (ex.: "work", "personal", "project-x")
- N Mind Keys
- Cada sessão LLM usa uma Mind Key
Padrão 3: mind compartilhado em equipe
Para equipes colaborando em um projeto.
- 1 usuário cria o mind (recebe a Mind Key)
- O criador compartilha com membros da equipe via JWT
- Todos os membros acessam via JWT (ou Mind Key compartilhada)
> [!WARNING]
> Compartilhar uma Mind Key concede acesso total de leitura/escrita. Para
> colaboração em equipe, prefira a API de Compartilhamento (baseada em JWT)
> em vez de compartilhar Mind Keys diretamente.
Padrão 4: provedor SaaS
Para apps que incorporam o Synapse como sua camada de memória.
- Cada cliente = 1 conta de usuário
- Cada projeto do cliente = 1 mind
- O app armazena Mind Keys por cliente/projeto
- Isolamento total entre clientes
Verificação de isolamento
Teste: Mind Key não pode acessar outros minds
[CODE BLOCK]
Teste: JWT não pode ler dados de memória diretamente
[CODE BLOCK]
Melhores práticas
> [!TIP]
> - Use um mind por projeto/contexto — isolamento é seu amigo
> - Nunca compartilhe Mind Keys — use a API de Compartilhamento
> - Faça rotação de Mind Keys se comprometidas (exclua o mind, crie um novo)
> - Audite minds compartilhados — revise periodicamente
> - Use JWT para interface humana — nunca exponha Mind Keys a usuários finais
Próximos passos
- Autenticação
- Mind Key vs JWT
- Arquitetura
────────────────────────────────────────────────────────────
# Busca semântica (embeddings)
SUMMARY: Busca conceitual de memória usando embeddings vetoriais — encontre por significado, não apenas palavras-chave.
Busca semântica (embeddings)
O Synapse suporta busca semântica usando embeddings vetoriais. Diferente do
FTS5 (correspondência de palavras-chave), a busca semântica encontra memórias
por significado — mesmo que nenhuma palavra-chave corresponda.
Como funciona
[CODE BLOCK]
O que são embeddings?
Embeddings são representações vetoriais numéricas de texto. Textos com
significado similar têm vetores similares. O Synapse gera um vetor (ex.: 1536
dimensões) para o conteúdo de cada memória.
Similaridade de cosseno
Para encontrar memórias semanticamente similares, o Synapse calcula a
similaridade de cosseno entre o vetor da consulta e cada vetor de memória.
Maior similaridade = mais relevante.
Quando usar busca semântica
Use busca semântica quando:
- Você quer "memórias sobre X" onde X é descrito de forma diferente do que foi armazenado
- FTS5 não retorna resultados (nenhuma palavra-chave corresponde)
- Você quer agrupamento conceitual (ex.: todas as memórias de "deployment", mesmo que algumas digam "release")
- A consulta é uma pergunta: "como tratamos autenticação?"
Use FTS5 quando:
- Você conhece as palavras-chave exatas
- Você precisa de lógica booleana (AND, OR, NOT)
- Você precisa de resposta sub-milissegundo
- Você quer correspondência de frase
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Resposta:
[CODE BLOCK]
Exemplos
Encontrar memórias de deployment
[CODE BLOCK]
Retorna memórias sobre "deployment", "release", "publishing", "rolling out",
etc.
Encontrar padrões de autenticação
[CODE BLOCK]
Retorna memórias sobre login, auth, JWT, gerenciamento de sessão, OAuth, etc.
Encontrar memórias similares
[CODE BLOCK]
Usa similaridade semântica (via tags compartilhadas E vetores de embedding).
Geração de embeddings
Quando os embeddings são gerados?
- No armazenamento de memória — se o serviço de embeddings estiver configurado, o embedding é gerado sincronamente
- Geração em lote — gera embeddings para memórias que não os têm
- Atualizações assíncronas — quando o conteúdo é atualizado, o embedding é regenerado
Provedores de embedding
O Synapse suporta provedores de embedding configuráveis:
- OpenAI (, )
- Modelos locais (via Ollama ou similar)
- Customizado (implemente a interface de embeddings)
Configure via variáveis de ambiente:
[CODE BLOCK]
Geração em lote
Para minds com muitas memórias sem embeddings:
[CODE BLOCK]
Desempenho
| Operação | Latência |
|----------|----------|
| Gerar embedding (OpenAI) | 100-200ms |
| Busca semântica (1k memórias) | 50-100ms |
| Busca semântica (10k memórias) | 200-500ms |
| Geração em lote (100 memórias) | 10-20s |
> [!NOTE]
> Busca semântica é mais lenta que FTS5 devido à computação vetorial. Use
> FTS5 para palavras-chave conhecidas, semântica para consultas conceituais.
Limitações
Custo dos embeddings
Se usar OpenAI, gerar embeddings custa dinheiro ($0.02 por 1M tokens para
text-embedding-3-small). Para 10.000 memórias com média de 100 tokens cada,
são $0.02 — insignificante.
Cold start
Memórias armazenadas antes de os embeddings serem configurados não terão
embeddings. Execute para preencher retroativamente.
Dependência de provedor
Se o provedor de embeddings cair, a busca semântica falha graciosamente
(retorna resultados vazios ou erro). FTS5 continua funcionando.
Quando embeddings não estão disponíveis
Se o serviço de embeddings não estiver configurado:
- retorna 503 Service Unavailable
- ainda funciona (apenas nenhum embedding é gerado)
- Busca FTS5 ainda funciona
Melhores práticas
> [!TIP]
> - Use semântica para consultas conceituais — "como tratamos X?"
> - Use FTS5 para termos específicos — "docker swarm"
> - Preencha embeddings regularmente —
> - Monitore a saúde do provedor — a busca semântica depende disso
> - Combine com tags — semântica + filtro de tag estreita os resultados
Próximos passos
- Busca FTS5
- API de Memória
- Arquitetura
## CATEGORIA: LIVRO DE RECEITAS LLM
Receitas e padrões para agentes LLM.
────────────────────────────────────────────────────────────
# Padrão de poll de chat
SUMMARY: Como fazer poll por mensagens humanas entre chamadas de ferramenta sem bloquear seu workflow.
Padrão de poll de chat
O sistema de chat é assíncrono — humanos podem deixar mensagens enquanto você
trabalha. Este padrão mostra como fazer poll por mensagens sem bloquear seu
workflow.
O padrão
[CODE BLOCK]
Faça poll entre chamadas de ferramenta, não em um loop apertado.
Por que fazer poll entre chamadas de ferramenta?
- Não bloqueie — poll em loop apertado desperdiça chamadas de API
- Não perca mensagens — poll com pouca frequência significa respostas lentas
- Ponto ideal — faça poll a cada 30-60 segundos, ou após cada chamada de ferramenta
Implementação
Poll básico
[CODE BLOCK]
Padrão 1: poll após cada chamada de ferramenta
[CODE BLOCK]
Padrão 2: poll baseado em tempo
[CODE BLOCK]
Padrão 3: orientado a eventos (com webhooks)
Para notificação em tempo real, registre um webhook:
[CODE BLOCK]
Então seu handler de webhook pode acordar o agente:
[CODE BLOCK]
Padrões de tratamento de mensagens
Padrão: confirmar e depois processar
[CODE BLOCK]
Padrão: enfileirar para processamento em lote
[CODE BLOCK]
Padrão: roteamento por prioridade
[CODE BLOCK]
Frequência de poll
| Caso de uso | Frequência |
|-------------|------------|
| Agente interativo (humano esperando) | A cada 5-10 segundos |
| Agente em background | A cada 30-60 segundos |
| Processamento em lote | A cada 5 minutos |
| Disparado por webhook | Não faça poll — use webhooks |
> [!WARNING]
> Fazer poll mais de uma vez a cada 5 segundos desperdiça chamadas de API. O
> endpoint retorna imediatamente se houver mensagens pendentes,
> então não há benefício em poll mais rápido.
Chat multi-agente
Para comunicação agente-para-agente:
[CODE BLOCK]
Melhores práticas
> [!TIP]
> - Faça poll entre chamadas de ferramenta — não em loop apertado
> - Confirme imediatamente — o humano sabe que você recebeu a mensagem
> - Processe assincronamente — não bloqueie em trabalho longo
> - Use webhooks para tempo real — poll tem latência
> - Não faça poll mais de uma vez a cada 5 segundos — desperdiça chamadas de API
Problemas comuns
Mensagens sumindo
- automaticamente marca mensagens como lidas
- Se você não as processar, elas somem
- Correção: Sempre processe mensagens antes de retornar
Respostas duplicadas
- Se seu handler quebrar, você pode responder duas vezes
- Correção: Torne o handler idempotente (verifique se já respondeu)
Respostas lentas
- Poll a cada 60s significa até 60s de latência
- Correção: Faça poll a cada 10-30s, ou use webhooks
Próximos passos
- API de Chat
- Padrão de início de sessão
- Recuperação de erros
────────────────────────────────────────────────────────────
# Recuperação de erros para agentes
SUMMARY: Como agentes LLM devem tratar e se recuperar de erros — retry, armazenar, aprender.
Recuperação de erros para agentes
Erros acontecem. Redes falham, APIs retornam 500s, Mind Keys expiram. Este
guia mostra como agentes LLM devem tratar erros graciosamente e aprender com
eles.
Princípios de tratamento de erros
1. Retry com backoff — erros transitórios costumam se resolver
2. Armazene o erro — aprenda com padrões
3. Degrade graciosamente — não trave a sessão inteira
4. Notifique o humano — para erros que você não consegue resolver
Tratamento de erros HTTP
Retry com backoff exponencial
[CODE BLOCK]
Tratamento de erro de auth
[CODE BLOCK]
Armazenando erros como memórias
Quando erros ocorrem, armazene-os para que sessões futuras possam aprender:
[CODE BLOCK]
Cenários comuns de erro
Cenário 1: Mind Key inválida
[CODE BLOCK]
Cenário 2: erro de rede
[CODE BLOCK]
Cenário 3: limite de taxa
[CODE BLOCK]
Cenário 4: erro de servidor (5xx)
[CODE BLOCK]
Cenário 5: chamada de ferramenta falha
[CODE BLOCK]
Padrão: circuit breaker
Para falhas repetidas, pare de tentar temporariamente:
[CODE BLOCK]
Melhores práticas
> [!TIP]
> - Sempre faça retry em erros transitórios — redes falham, servidores engasgam
> - Não faça retry em erros de cliente (4xx) — eles não se corrigem sozinhos
> - Armazene erros como memórias — aprenda com padrões
> - Notifique humanos sobre erros críticos — eles precisam saber
> - Degrade graciosamente — trabalho parcial é melhor que travamento
> - Use circuit breakers — não martele um serviço falhando
Próximos passos
- Referência da API de erros
- Padrão de início de sessão
- Testes self-healing
────────────────────────────────────────────────────────────
# Estratégia de tagueamento de memória
SUMMARY: Como taguear memórias para busca e filtragem eficazes — o sistema de tagueamento que escala.
Estratégia de tagueamento de memória
Tags são o segredo para recuperação de memória escalável. Este guia mostra como
taguear memórias para que as certas voltem no momento certo.
Por que tags importam
Sem tags, você tem busca em texto completo plana. Com tags, você tem navegação
estruturada:
[CODE BLOCK]
Tags permitem:
- Filtragem rápida —
- Busca com escopo —
- Agrupamento — encontre todas as memórias "mistake" de um projeto
- Referência cruzada — memórias que compartilham tags são relacionadas
Esquema de tagueamento
Tags de projeto
Use nomes de projeto como tags:
[CODE BLOCK]
Tags de tecnologia
Use nomes de tecnologia:
[CODE BLOCK]
Tags de tópico
Use categorias de tópico:
[CODE BLOCK]
Tags de status
Use indicadores de status:
[CODE BLOCK]
Tags de tipo
Use indicadores de tipo:
[CODE BLOCK]
Regras de tagueamento
Regra 1: 2-5 tags por memória
Poucas tags = descoberta ruim. Muitas = ruído.
[CODE BLOCK]
Regra 2: minúsculas, hifenizadas
[CODE BLOCK]
Regra 3: use vocabulário consistente
Estabeleça um vocabulário de tagueamento e mantenha-se nele:
[CODE BLOCK]
Regra 4: tagueie com intenção de busca
Pergunte: "Como vou buscar por essa memória?"
[CODE BLOCK]
Padrões
Padrão 1: projeto + tópico
[CODE BLOCK]
Busca: (todas as memórias do projeto Synapse)
Busca: (memórias de deployment no Synapse)
Padrão 2: tipo + domínio
[CODE BLOCK]
Busca: (todos os erros)
Busca: (erros de deployment)
Padrão 3: hierárquico
Para subprojetos dentro de um projeto:
[CODE BLOCK]
Busca: (todo Synapse)
Busca: (apenas subprojeto de docs)
Padrão 4: rastreamento de status
[CODE BLOCK]
Casos de uso comuns
Encontrar todas as decisões sobre um projeto
[CODE BLOCK]
Encontrar todos os erros em um domínio
[CODE BLOCK]
Encontrar trabalho ativo
[CODE BLOCK]
Encontrar memórias sobre uma tecnologia
[CODE BLOCK]
Manutenção de tags
Revisão periódica
[CODE BLOCK]
Mesclando tags
Se você tem tags inconsistentes ( e ), mescle-as:
[CODE BLOCK]
Melhores práticas
> [!TIP]
> - Estabeleça vocabulário cedo — tags consistentes desde o dia 1
> - Tagueie com intenção de busca — como você vai encontrar isso depois?
> - 2-5 tags é o ponto ideal — poucas ou muitas é ruim
> - Minúsculas + hífens — não
> - Revise periodicamente — mescle duplicatas, remova não usadas
Próximos passos
- Melhores práticas de memória
- Busca FTS5
- Workflow orientado por tarefas
────────────────────────────────────────────────────────────
# Padrão de início de sessão
SUMMARY: A sequência canônica de início de sessão que todo agente LLM deve seguir.
KEY CONTEXT:
ALWAYS at session start: 1) GET /memory/recall, 2) GET /chat/poll, 3) GET /mind/tasks?status=in_progress
Build system prompt from recall output.
Process unread chat messages before doing new work.
Resume any in_progress tasks before starting new ones.
Store new learnings as they happen — don't wait until session end.
Padrão de início de sessão
Toda sessão de agente LLM deve seguir esta sequência canônica de inicialização.
Pular passos leva a contexto perdido, mensagens perdidas e tarefas esquecidas.
O padrão
[CODE BLOCK]
Implementação
Passo 1: recupere todas as memórias
> [!CRITICAL]
> Esta é a chamada mais importante. Sem ela, você não tem memória de sessões
> passadas.
[CODE BLOCK]
Retorna um resumo em texto puro de todas as memórias, ordenado por prioridade.
Passo 2: faça poll por mensagens de chat não lidas
[CODE BLOCK]
Retorna mensagens não lidas do humano. Automaticamente as marca como lidas.
Passo 3: verifique tarefas em andamento
[CODE BLOCK]
Retorna tarefas em que você estava trabalhando na última sessão.
Passo 4: construa o contexto
Combine as três respostas no seu prompt de sistema:
[CODE BLOCK]
Passo 5: processe itens pendentes
[CODE BLOCK]
Exemplo completo
[CODE BLOCK]
Erros comuns
> [!WARNING]
> - Pular o recall — você começa sem contexto, repete erros passados
> - Esquecer de fazer poll no chat — mensagens do humano ficam sem resposta
> - Ignorar tarefas ativas — trabalho é esquecido no meio da execução
> - Não armazenar nada — a sessão não produz valor persistente
Variações
Padrão mínimo (LLMs de contexto baixo)
Para LLMs com janelas de contexto pequenas, pule o recall completo:
[CODE BLOCK]
Então busque tópicos específicos conforme necessário:
[CODE BLOCK]
Padrão agressivo (agentes de longa duração)
Para agentes que rodam por horas, adicione re-recall periódico:
[CODE BLOCK]
Próximos passos
- Estratégia de tagueamento de memória
- Workflow orientado por tarefas
- Padrão de poll de chat
────────────────────────────────────────────────────────────
# Workflow orientado por tarefas
SUMMARY: Use tarefas do Synapse para conduzir workflows LLM multi-etapas que sobrevivem entre sessões.
Workflow orientado por tarefas
Tarefas não são apenas todos — elas são a espinha dorsal de workflows LLM
persistentes. Ao criar tarefas para trabalho multi-etapas, você garante
continuidade entre sessões e fornece trilhas de auditoria do que foi feito.
Por que orientado por tarefas?
Sem tarefas:
- O LLM começa cada sessão sem saber o que fazer
- Trabalho multi-etapas é esquecido no meio da execução
- Sem registro do que foi feito
Com tarefas:
- O LLM retoma tarefas em andamento imediatamente
- Trabalho multi-etapas sobrevive entre sessões
- Trilha de auditoria embutida de todo o trabalho
O padrão
[CODE BLOCK]
Implementação
Passo 1: crie uma tarefa para trabalho multi-etapas
[CODE BLOCK]
Passo 2: rastreie progresso na descrição da tarefa
[CODE BLOCK]
Passo 3: retome entre sessões
[CODE BLOCK]
Passo 4: conclua e arquive
[CODE BLOCK]
Exemplo completo: workflow de deploy
[CODE BLOCK]
Hierarquia de tarefas
Para trabalho complexo, use relacionamentos pai-filho de tarefas:
[CODE BLOCK]
Busque subtarefas:
[CODE BLOCK]
Workflow de status
[CODE BLOCK]
Pending
Tarefa criada mas não iniciada. Use para trabalho planejado.
In Progress
Sendo trabalhada no momento. Atualize a descrição com o progresso.
Done
Concluída com sucesso. A descrição deve incluir o resumo.
Cancelled
Abandonada. A descrição deve incluir o motivo.
Melhores práticas
> [!TIP]
> - Crie tarefas para trabalho multi-etapas — trabalho de etapa única não precisa de tarefa
> - Atualize a descrição com o progresso — permite retomada
> - Use prioridade alta para trabalho ativo — aparece no recall
> - Conclua tarefas quando terminadas — não as deixe inprogress
> - Armazene resumos de conclusão como memórias — referência de longo prazo
Padrões comuns
Padrão: workflow de correção de bug
[CODE BLOCK]
Padrão: workflow de pesquisa
[CODE BLOCK]
Próximos passos
- Padrão de início de sessão
- Padrão de poll de chat
- Recuperação de erros
## CATEGORIA: PERGUNTAS FREQUENTES
Perguntas frequentes e problemas comuns.
────────────────────────────────────────────────────────────
# FAQ da API
SUMMARY: Perguntas comuns sobre a API — autenticação, limites de taxa, tratamento de erros, descoberta de endpoints.
FAQ da API
Perguntas comuns sobre a API do Synapse.
Como faço para autenticar?
Dois métodos:
1. Mind Key (para endpoints de dados):
2. JWT (para endpoints de conta):
Ou via parâmetro de consulta (limite de 60 req/min):
Consulte Autenticação.
Qual a diferença entre Mind Key e JWT?
- Mind Key: escopo de tenant, nunca expira, para dados de memória/chat/tarefas
- JWT: escopo de usuário, expira em 7 dias, para gerenciamento de conta/mind
Consulte Mind Key vs JWT.
Por que estou recebendo 401 Unauthorized?
Causas comuns:
1. Cabeçalho ausente
2. Mind Key inválida (verifique se começa com )
3. Usando JWT onde Mind Key é necessária (ou vice-versa)
4. Mind Key foi revogada
Correção: Verifique seu token. Consulte Autenticação.
Por que estou recebendo 404 Not Found?
Você usou um caminho de endpoint errado. O Synapse só tem os caminhos listados
em .
Correção: Chame para ver todos os caminhos válidos. Não
adivinhe.
Por que estou recebendo 429 Too Many Requests?
Você está usando auth via parâmetro de consulta , que é limitada a 60/min.
Correção: Mude para o cabeçalho (sem limite de
taxa).
Consulte Limites de taxa.
Como listo todos os endpoints?
[CODE BLOCK]
Como encontro o endpoint certo?
1. Confira para a lista legível por máquina
2. Confira para a documentação completa da API
3. Navegue em para o sistema de documentação
4. Use para a especificação OpenAPI 3.0
Posso usar GET em vez de POST?
Alguns endpoints POST têm equivalentes GET para ferramentas somente-URL:
- ↔
- ↔
- ↔
Confira para variantes GET disponíveis.
Como trato erros?
Todos os erros retornam JSON:
[CODE BLOCK]
Consulte Erros e tratamento de erros.
Qual o limite do corpo da requisição?
10 MB. Para payloads maiores (ex.: upload de arquivos), use os endpoints
multipart.
A API suporta CORS?
Sim. Todos os endpoints retornam:
[CODE BLOCK]
Existe um SDK?
Sim:
- Node.js:
- MCP:
Consulte Visão geral da API para detalhes.
Como faço paginação?
Use e :
[CODE BLOCK]
Limite padrão: 100. Máximo: 500.
Posso filtrar memórias por categoria ou tag?
Sim:
[CODE BLOCK]
Como faço busca de memórias?
De duas formas:
1. Busca por palavras-chave FTS5:
2. Busca semântica:
Consulte Busca FTS5 e Busca semântica.
Como atualizo uma memória?
Faça POST com a mesma + — a memória existente é
atualizada, não duplicada.
[CODE BLOCK]
Como excluo uma memória?
[CODE BLOCK]
Posso excluir em massa?
Sim:
[CODE BLOCK]
Próximos passos
- Visão geral da API
- Erros e tratamento de erros
- Autenticação
────────────────────────────────────────────────────────────
# FAQ geral
SUMMARY: Perguntas comuns sobre o Synapse — o que é, como funciona, para quem é.
FAQ geral
Perguntas comuns sobre o Synapse.
O que é o Synapse?
O Synapse é uma API de memória persistente para agentes LLM. Ele dá ao seu
assistente de IA um cérebro permanente e pesquisável que sobrevive entre
sessões. Em vez de esquecer tudo quando o chat fecha, o LLM armazena e recupera
memórias via uma API HTTP simples.
Saiba mais: O que é o Synapse?
Para quem é o Synapse?
- Desenvolvedores de agentes LLM que precisam de estado persistente
- Power users rodando LLMs locais com agentes customizados
- Equipes construindo assistentes de IA com memória compartilhada
- Engenheiros de automação encadeando chamadas LLM entre sessões
O Synapse é gratuito?
O Synapse está hospedado em e é gratuito para
uso pessoal. Para auto-hospedagem, consulte o repo.
Como o Synapse difere da memória do ChatGPT?
| Recurso | Memória do ChatGPT | Synapse |
|---------|---------------------|---------|
| Armazenamento | Servidores OpenAI | Seu servidor |
| Acesso por API | Não | Sim (REST + MCP) |
| Multi-tenant | Não | Sim (minds) |
| Categorias personalizadas | Não | Sim (8 categorias) |
| Busca em texto completo | Limitada | FTS5 + semântica |
| Auto-hospedável | Não | Sim |
Quais LLMs funcionam com o Synapse?
Qualquer LLM que consiga fazer chamadas HTTP ou usar MCP:
- Claude (Anthropic) — via MCP ou API direta
- GPT-4 / GPT-3.5 (OpenAI) — via function calling + API
- Gemini (Google) — via function calling + API
- Llama / Mistral (local) — via integração customizada
- Qualquer LLM via servidor MCP do Synapse
Preciso hospedar o Synapse eu mesmo?
Não. A versão hospedada em está disponível para
uso público. Auto-hospedagem é opcional (para privacidade, customização ou
ambientes air-gapped).
Quanto de dado posso armazenar?
Não há limites rígidos na versão hospedada. Uso típico:
- 100-1000 memórias por mind
- 1-10 KB por memória (campo content)
- Total: 10 MB por mind
Para escala maior, auto-hospede.
Meus dados são privados?
Sim. Cada mind é isolado (consulte Multi-tenancy).
Outros usuários não podem ver seus dados. O provedor de hospedagem (Schaefer
Services) tem acesso, mas não visualiza dados de usuários.
Para privacidade máxima, auto-hospede.
Posso exportar meus dados?
Sim. Use para exportar todas as memórias como JSON.
Consulte Backup & Restore.
O que acontece se eu perder minha Mind Key?
Mind Keys são exibidas apenas uma vez na criação. Se perdidas:
1. Faça login com seu email/senha para obter um JWT
2. Crie um novo mind via
3. Salve a nova Mind Key
4. (Opcional) Exclua o mind antigo via
Você não consegue recuperar memórias de um mind cuja key foi perdida.
Múltiplos agentes LLM podem compartilhar um mind?
Sim. Todos os agentes usando a mesma Mind Key compartilham os dados daquele
mind. Para trabalho multi-agente coordenado, consulte Coordenação multi-agente.
O Synapse funciona offline?
Não, o Synapse requer conexão com a internet ao servidor (hospedado ou
auto-hospedado). Para LLMs offline, rode o Synapse localmente.
Quão rápida é a busca de memória?
- Busca por palavras-chave FTS5: < 10ms para 1000 memórias
- Busca semântica: 50-100ms para 1000 memórias
- Recall completo: < 50ms para 1000 memórias
Consulte Busca FTS5 para detalhes.
Posso usar o Synapse sem um LLM?
Sim. O Synapse é uma API genérica de memória. Você pode usá-lo em qualquer
aplicação que se beneficie de armazenamento key-value persistente e pesquisável
com categorias e tags.
Próximos passos
- O que é o Synapse?
- Quick Start
- FAQ da API
────────────────────────────────────────────────────────────
# FAQ do MCP
SUMMARY: Perguntas comuns sobre integração MCP — ferramentas, transportes, troubleshooting.
FAQ do MCP
Perguntas comuns sobre o servidor MCP do Synapse.
O que é MCP?
MCP (Model Context Protocol) é um padrão aberto da Anthropic para integração
entre LLM e ferramentas. Em vez de colar docs de API em prompts, você registra
ferramentas com um servidor MCP, e o LLM as chama como funções nativas.
Consulte O que é MCP?.
Quantas ferramentas o Synapse MCP expõe?
79 ferramentas em 12 categorias: memória, chat, agendador, tarefas,
scripts, computadores, push, usuário, utilitários, visualização,
compartilhamento, webhooks, navegador.
Consulte O que é MCP? para a lista completa.
Quais clientes MCP são suportados?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Qualquer cliente compatível com MCP
Consulte Configuração do Claude Desktop para
exemplos de configuração.
Quais transportes são suportados?
1. stdio (local, recomendado para desktop)
2. HTTP/SSE (remoto, multi-tenant)
3. WebSocket (mobile, alto volume)
Como configuro o Claude Desktop?
Edite :
[CODE BLOCK]
Consulte Configuração do Claude Desktop.
Por que as ferramentas não aparecem no Claude Desktop?
1. Reinicie o Claude Desktop completamente (Cmd+Q no macOS)
2. Verifique se o arquivo de config é JSON válido
3. Confirme Node.js 18+ instalado
4. Confira os logs MCP:
Consulte MCP Troubleshooting.
Como uso um mind diferente?
Altere na sua configuração MCP e reinicie o cliente.
Para múltiplos minds, rode múltiplas instâncias do servidor MCP com Mind Keys
diferentes.
Posso limitar quais ferramentas são expostas?
Sim, use Tool Profiles:
- : 8 ferramentas compostas (500 tokens)
- : 25 ferramentas (2.500 tokens)
- : 119 ferramentas (8.250 tokens, padrão)
Defina via variável de ambiente ou cabeçalho .
Como depuro problemas de MCP?
1. Rode o servidor MCP manualmente:
2. Confira os logs do cliente (varia por cliente)
3. Verifique se a Mind Key funciona:
4. Confira a saúde do Synapse:
Consulte MCP Troubleshooting.
O servidor MCP é gratuito?
Sim. O pacote npm é open source. O servidor MCP hospedado em
é gratuito para uso público.
Posso auto-hospedar o servidor MCP?
Sim:
[CODE BLOCK]
Como o MCP difere de chamadas diretas à API?
| Aspecto | API direta | MCP |
|---------|-----------|-----|
| LLM precisa saber | URLs, headers, auth | Apenas nomes das ferramentas |
| Tratamento de auth | Manual | Automático (env var) |
| Descoberta de ferramentas | Ler /endpoints | Automática via protocolo MCP |
| Tratamento de erros | Manual | Padronizado |
| Melhor para | Integrações customizadas | Agentes LLM |
Posso construir meu próprio cliente MCP?
Sim. Use o SDK oficial do MCP:
- TypeScript:
- Python:
Consulte Cliente MCP customizado.
Como relato bugs do MCP?
Abra uma issue:
Inclua:
- Versão do servidor MCP
- Nome e versão do cliente
- Sistema operacional
- Logs relevantes
- Passos para reproduzir
Próximos passos
- O que é MCP?
- Configuração do Claude Desktop
- MCP Troubleshooting
────────────────────────────────────────────────────────────
# FAQ de troubleshooting
SUMMARY: Soluções para problemas comuns do Synapse — auth, rede, dados, deploy.
FAQ de troubleshooting
Soluções para problemas comuns do Synapse.
Não consigo fazer login
Sintomas
- retorna 401
- "Invalid email or password"
Soluções
1. Verifique se o email está correto — case sensitive
2. Confira a senha — mínimo de 6 caracteres
3. Registre-se primeiro se você não tem uma conta:
4. Redefina a senha (se SMTP configurado) via interface web
Perdi minha Mind Key
Sintomas
- Não consegue acessar memórias
- A Mind Key foi excluída/perdida
Soluções
Mind Keys não podem ser recuperadas. Você deve:
1. Fazer login para obter JWT:
2. Listar minds: (com JWT)
3. Criar novo mind:
4. Salvar a nova Mind Key
5. (Opcional) Excluir mind antigo:
Dados no mind antigo são perdidos a menos que você encontre a Mind Key.
Chamadas de API retornam 401
Sintomas
- Todas as chamadas de API retornam 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Soluções
1. Verifique o formato do cabeçalho:
2. Confira se a Mind Key começa com (não que é JWT)
3. Teste diretamente:
[CODE BLOCK]
4. A Mind Key pode ter sido revogada — crie um novo mind
Consulte Autenticação.
Chamadas de API retornam 404
Sintomas
- 404 Not Found
- "Route not found"
Soluções
> [!CRITICAL]
> Não tente adivinhar caminhos de endpoint. Apenas os caminhos em
> existem.
1. Confira endpoints válidos:
2. Compare a URL exatamente — case sensitive, sem barras no final
3. Confira o método HTTP — vs são diferentes
Chamadas de API retornam 429
Sintomas
- 429 Too Many Requests
- "Rate limit exceeded"
Soluções
1. Mude para auth por cabeçalho (sem limite de taxa):
[CODE BLOCK]
2. Aguarde segundos se precisar usar
Consulte Limites de taxa.
Busca de memória não retorna resultados
Sintomas
- retorna vazio
- Sabe que memórias existem
Soluções
1. Verifique se as memórias existem:
2. Confira a sintaxe de busca — FTS5 tem sintaxe específica
3. Tente uma consulta mais simples — em vez de
4. Use busca semântica para consultas conceituais:
Consulte Busca FTS5.
Memórias não estão persistindo
Sintomas
- POST /memory retorna sucesso
- GET /memory/recall não as mostra
Soluções
1. Verifique se é a mesma Mind Key — keys diferentes = minds diferentes
2. Confira a resposta — POST retorna
3. Tente GET /memory (lista JSON) em vez de /memory/recall (texto)
4. Confira o filtro — ou podem estar ocultando-as
Ferramentas não aparecem no Claude Desktop
Sintomas
- Claude Desktop mostra 0 ferramentas
- Sem ícone 🔌
Soluções
1. Reinicie o Claude Desktop completamente (Cmd+Q)
2. Verifique se o arquivo de config é JSON válido
3. Confirme Node.js 18+ instalado
4. Rode o MCP manualmente:
5. Confira os logs:
Consulte MCP Troubleshooting.
Synapse está offline
Sintomas
- Não consegue acessar synapse.schaefer.zone
- curl dá timeout
Soluções
1. Verifique sua internet — tente outro site
2. Confira a saúde do Synapse:
3. Aguarde — pode ser outage temporário ou deploy
4. Confira a página de status (se disponível)
Para auto-hospedagem: confira o status do container Docker, conexão com banco.
Erros de banco de dados
Sintomas
- 500 Internal Server Error
- "Database connection failed"
Soluções
Para auto-hospedagem:
1. Verifique se PostgreSQL está rodando:
2. Confira DATABASEURL no env
3. Confira as migrations:
4. Confira espaço em disco:
Para versão hospedada: reporte ao suporte.
Webhook não dispara
Sintomas
- Registrou webhook mas não recebe callbacks
- Nenhum POST na sua URL
Soluções
1. Verifique se a URL é alcançável:
2. Confira o filtro de eventos — corresponde a todos os eventos de memória
3. Teste o webhook:
4. Confira se o webhook está habilitado:
5. Verifique SSL — o Synapse requer HTTPS válido para URLs de webhook
Consulte API de Webhooks.
Cron job não roda
Sintomas
- Criou cron job mas não dispara
- não atualiza
Soluções
1. Confira a sintaxe de agendamento — deve ser cron de 5 campos válido OU inteiro em segundos
2. Verifique se o endpoint é permitido — deve ser http(s), sem IPs privados
3. Confira se o job está habilitado:
4. Aguarde o próximo horário agendado — cron não é instantâneo
Consulte Cron & Agendador.
Precisa de mais ajuda?
1. Confira a documentação existente:
2. Busque na documentação:
3. Abra uma issue:
4. Contato: consulte a página
Próximos passos
- Erros e tratamento de erros
- FAQ da API
- MCP Troubleshooting