# DOCUMENTACIÓN DE SYNAPSE — Referencia completa
# Generado: 2026-07-18T06:14:39.194Z
# Total de artículos: 47
Este documento contiene la documentación completa de la API de Synapse.
Base URL: https://synapse.schaefer.zone
Language: es
========================================================================
## CATEGORÍA: PRIMEROS PASOS
Todo lo que necesitas para empezar con Synapse.
────────────────────────────────────────────────────────────
# Autenticación y Mind Keys
SUMMARY: Cómo funciona la autenticación de Synapse: Mind Keys para agentes, JWTs para humanos, ?key= para herramientas que solo usan 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.
Autenticación y Mind Keys
Synapse usa dos métodos de autenticación, cada uno optimizado para un caso de
uso diferente. Comprender la diferencia es esencial para construir integraciones
fiables.
Dos métodos de autenticación
| Método | Caso de uso | Límite de frecuencia | Expiración |
|--------|----------|------------|--------|
| Mind Key | Agentes LLM, herramientas automatizadas | Ninguno (cabecera) / 60 min (query) | Nunca |
| JWT | Interfaz humana, operaciones de cuenta | Ninguno | 7 días |
Mind Key (para agentes)
Un Mind Key es un token de API con ámbito de tenant. Autentica los datos de un
solo mind (memorias, tareas, chat, scripts, etc.). Úselo para:
- Agentes LLM que llaman a la API
- Scripts de automatización en segundo plano
- Configuración del servidor MCP
- Cualquier integración de larga duración
Autenticación por cabecera (recomendada)
[CODE BLOCK]
Parámetro de consulta (para herramientas que solo usan URL)
[CODE BLOCK]
> [!WARNING]
> El parámetro de consulta está limitado a 60 peticiones por minuto.
> La cabecera Bearer no tiene límite de frecuencia. Use la cabecera siempre que
> su cliente admita cabeceras personalizadas.
Crear un Mind Key
[CODE BLOCK]
La respuesta incluye — guárdelo de inmediato, solo se muestra una
vez.
Listar sus minds
[CODE BLOCK]
Eliminar un mind (¡irreversible!)
[CODE BLOCK]
JWT (para humanos)
Los JWT autentican la cuenta de usuario, no un mind específico. Úselos para:
- Registro y login de cuenta
- Crear / listar / eliminar minds
- Compartir minds con otros usuarios
- Gestión de suscripciones Web Push
Registro
[CODE BLOCK]
Devuelve:
Login
[CODE BLOCK]
Devuelve:
Expiración del JWT
Los JWT expiran después de 7 días. Cuando un JWT expira, simplemente llame
a de nuevo para obtener uno nuevo. El Mind Key nunca expira, de modo
que las integraciones de agente existentes siguen funcionando.
Mejores prácticas de seguridad
> [!CRITICAL]
> - Nunca confíe Mind Keys a git. Use variables de entorno.
> - Nunca registre Mind Keys en logs. Enmascárelos ().
> - Rote las claves si sospecha de una fuga (elimine el mind, cree uno nuevo).
> - Use un mind por proyecto para limitar el radio de impacto si se filtra una clave.
Patrón con variables de entorno
[CODE BLOCK]
[CODE BLOCK]
Configuración del servidor MCP
[CODE BLOCK]
Patrón multi-mind
Cada usuario puede tener múltiples minds. Patrones comunes:
| Nombre del mind | Propósito |
|-----------|---------|
| | Memorias de trabajo |
| | Preferencias personales, familia |
| | Contexto de un proyecto específico |
| | Progreso de aprendizaje |
| | Fallback de propósito general |
Use diferentes Mind Keys para diferentes sesiones LLM a fin de mantener los
contextos aislados.
Límites de frecuencia
| Método de auth | Límite | Ámbito |
|-------------|-------|-------|
| Mind Key (cabecera) | Ninguno | Por mind |
| Mind Key (?key=) | 60/min | Por IP |
| JWT (cabecera) | Ninguno | Por usuario |
| Endpoints públicos | Ninguno | Global |
Las cabeceras de límite de frecuencia (,
, ) se incluyen en las respuestas cuando
aplica.
Próximos pasos
- Mind Key vs JWT — cuándo usar cada uno
- API de Memory — qué puede hacer con un Mind Key
- API de User — gestión de cuenta con JWTs
────────────────────────────────────────────────────────────
# Mind Key vs JWT — ¿Cuándo usar cada uno?
SUMMARY: Guía de decisión: Mind Key para acceso a datos del agente, JWT para gestión de cuenta.
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 — ¿Cuándo usar cada uno?
Synapse tiene dos tokens de autenticación. Elegir el incorrecto lleva a errores
401. Esta guía le ofrece un marco de decisión claro.
Tabla de decisión rápida
| Quiere... | Usar |
|----------------|-----|
| Almacenar / recuperar memorias | Mind Key |
| Enviar / hacer poll de mensajes de chat | Mind Key |
| Gestionar tareas | Mind Key |
| Almacenar scripts | Mind Key |
| Registrar webhooks | Mind Key |
| Controlar computadoras | Mind Key (lado usuario) / Computer Token (lado agente) |
| Registrar una cuenta de usuario | Ninguno (público) |
| Iniciar sesión | Ninguno (público) |
| Crear / listar / eliminar minds | JWT |
| Compartir un mind con otro usuario | JWT |
| Suscribirse a notificaciones web push | JWT |
| Ver el log de auditoría | Mind Key |
La regla simple
> [!TIP]
> Si toca los datos de un solo mind → Mind Key.
> Si gestiona la cuenta o los metadatos del mind → JWT.
Mind Key — token de acceso a datos
Un Mind Key otorga acceso a los datos de un mind. Es un token de larga
duración que nunca expira (hasta que se elimina el mind). Perfecto para:
- Agentes LLM que persisten memorias entre sesiones
- Trabajos cron en segundo plano
- Configuración del servidor MCP
- Integraciones de webhooks
- Apps móviles que leen memoria
Qué puede hacer el Mind Key
- — leer todas las memorias de este mind
- — almacenar/actualizar memorias
- — leer mensajes de chat
- — enviar mensajes de chat
- — listar tareas
- — crear tareas
- — almacenar scripts
- — registrar webhooks
- — encolar comandos de computadora
Qué NO puede hacer el Mind Key
- Crear / listar / eliminar minds (necesita JWT)
- Compartir un mind con otro usuario (necesita JWT)
- Ver la información de la cuenta de usuario (necesita JWT)
- Suscribirse a web push (necesita JWT)
JWT — token de gestión de cuenta
Un JWT autentica la cuenta de usuario. Expira después de 7 días y se usa
para operaciones a nivel de cuenta que abarcan múltiples minds o involucran a
otros usuarios.
Qué puede hacer el JWT
- — crear un nuevo mind (devuelve un nuevo Mind Key)
- — listar todos los minds de este usuario
- — eliminar un mind
- — compartir un mind con otro usuario
- — suscribirse a notificaciones web push
- — listar comparticiones de mind
Qué NO puede hacer el JWT
- Leer / escribir memorias (necesita Mind Key)
- Enviar mensajes de chat (necesita Mind Key)
- Gestionar tareas (necesita Mind Key)
- Registrar webhooks (necesita Mind Key)
Caso especial: Computer Token
Los endpoints (del lado del agente, para el
screen-remote-agent) usan un tercer tipo de token: el Computer Token. Este
token lo devuelve al canjear un código de
instalación, y es específico a una computadora registrada.
| Endpoint | Auth |
|----------|------|
| | Computer Token |
| | Computer Token |
| | Mind Key o JWT |
| | Mind Key o JWT |
Patrones comunes
Patrón 1: Agente LLM único
1. Registrar una vez → obtener JWT
2. Crear un mind → obtener Mind Key
3. El LLM usa el Mind Key para todo
Patrón 2: Agente multi-proyecto
1. Registrar una vez → obtener JWT
2. Crear múltiples minds (trabajo, personal, proyecto-x) → obtener múltiples Mind Keys
3. El LLM carga diferente Mind Key según el contexto
Patrón 3: Compartir en equipo
1. El usuario A crea un mind → obtiene el Mind Key A
2. El usuario A comparte con el usuario B vía JWT ()
3. El usuario B ya puede acceder vía su propio JWT
4. Para acceso LLM, el usuario B necesita crear su propio Mind Key (o usar el de A)
Patrón 4: Servidor MCP
Los servidores MCP siempre usan Mind Key (establecido vía la variable de entorno
). Una instancia del servidor MCP = un mind. Para acceso
multi-mind, ejecute múltiples instancias MCP o implemente cambio de mind del
lado del cliente.
Hoja de referencia de formato de tokens
| Token | Formato | Ejemplo |
|-------|--------|---------|
| Mind Key | + 36 caracteres | |
| JWT | + base64 | |
| Computer Token | + 36 caracteres | |
Próximos pasos
- Autenticación — guía completa de auth
- API de User y Minds — endpoints protegidos con JWT
- API de Memory — endpoints protegidos con Mind Key
────────────────────────────────────────────────────────────
# Quick Start para agentes LLM
SUMMARY: En 3 llamadas a la API: recuperar todas las memorias, almacenar una nueva, buscar. El flujo esencial del 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
Pierde toda la memoria entre sesiones. Synapse es su cerebro externo. Esta guía
muestra las tres llamadas esenciales a la API que todo agente LLM debe conocer.
> [!CRITICAL]
> Llame a al INICIO de CADA sesión.
> Sin esta llamada, no tiene memoria de quién es el usuario, qué ha prometido,
> ni en qué estaba trabajando la última vez.
Paso 1: Recuperar todas las memorias (SIEMPRE PRIMERO)
[CODE BLOCK]
Devuelve un resumen estructurado en texto plano de todas las memorias
almacenadas. Paréelo para reconstruir su modelo mental del usuario, sus
proyectos y las interacciones pasadas.
Ejemplo de respuesta:
[CODE BLOCK]
Paso 2: Almacenar una nueva memoria
Cuando aprenda algo que valga la pena recordar:
[CODE BLOCK]
Categorías: , , , , , , , ,
Prioridades: , , ,
> [!TIP]
> Incluya siempre un campo — un identificador corto para la memoria. Esto
> le permite actualizar la misma memoria más tarde haciendo POST de nuevo con la
> misma key.
Paso 3: Buscar una memoria específica
[CODE BLOCK]
> [!TIP]
> Sintaxis FTS5: múltiples palabras = búsqueda AND. Frases entre comillas:
> . Búsqueda por prefijo: . Booleano: .
Herramientas abiertas (sin cabeceras de auth)
Si su herramienta solo puede abrir URLs (sin cabeceras personalizadas), use el
parámetro :
[CODE BLOCK]
> [!WARNING]
> está limitado a 60 peticiones/minuto. La cabecera Bearer no tiene
> límite de frecuencia. Use la cabecera Bearer siempre que sea posible.
Flujo completo de sesión
1. Inicio de sesión: — cargar todas las memorias
2. Durante el trabajo: — encontrar hechos específicos
3. Ante nueva información: — almacenarla (con categoría, key, etiquetas, prioridad)
4. Periódicamente: — comprobar mensajes humanos
5. Fin de sesión: almacenar cualquier aprendizaje final vía
Patrones comunes
Actualizar una memoria existente
POST con la misma y — la memoria existente se
actualiza, no se duplica.
Almacenar el estado de un proyecto
[CODE BLOCK]
Registrar un error (para no repetirlo)
[CODE BLOCK]
Comprobar mensajes humanos
[CODE BLOCK]
Devuelve los mensajes no leídos del humano. Responda con:
[CODE BLOCK]
Próximos pasos
- Autenticación — Mind Key vs JWT
- Referencia de la API de Memory — los 22 endpoints de memoria
- API de Chat — comunicación asíncrona con humanos
- LLM Cookbook — patrones prácticos
────────────────────────────────────────────────────────────
# Quick Start (humano)
SUMMARY: Registre una cuenta, cree su primer mind, almacene una memoria — todo en 5 minutos.
Quick Start (humano)
Esta guía le lleva por obtener una cuenta de Synapse, su primer Mind Key, y
almacenar su primera memoria. Tiempo total: 5 minutos.
Paso 1: Registrar una cuenta
Abra la API de Synapse y cree una cuenta:
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
> [!TIP]
> Guarde el JWT en un lugar seguro — lo necesitará para crear minds. El JWT
> expira a los 7 días; vuelva a iniciar sesión con el mismo endpoint para
> refrescarlo.
Paso 2: Cree su primer mind
Un "mind" es un ámbito de memoria aislado. La mayoría de los usuarios empieza
con un mind, pero puede tener múltiples (p. ej. "trabajo", "personal",
"proyecto-x"). Cada mind tiene su propio Mind Key único.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
> [!CRITICAL]
> Guarde el de inmediato. Solo se muestra una vez y no se puede
> recuperar después. Si lo pierde, tendrá que crear un mind nuevo.
Paso 3: Almacene su primera memoria
Ahora use el Mind Key para almacenar una memoria:
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
Paso 4: Recupere todas las memorias
Para recuperar todo lo que ha almacenado:
[CODE BLOCK]
Respuesta (texto plano, optimizado para consumo por LLM):
[CODE BLOCK]
Paso 5: Busque memorias
Encuentre memorias específicas por palabra clave:
[CODE BLOCK]
Paso 6: Conecte su LLM
La forma más sencilla de dar a su LLM acceso a Synapse es vía MCP:
- Configuración de Claude Desktop — config en 2 minutos
- Configuración de Claude Code — integración con terminal
- Configuración de Cursor — integración con IDE
Tras la configuración, su LLM llamará automáticamente a al
inicio de cada sesión y persistirá nuevos hechos vía .
Categorías de memoria
Synapse admite 8 categorías — elija la más específica:
| Categoría | Caso de uso |
|----------|----------|
| | Nombre, rol, información de contacto |
| | Gustos, disgustos, estilo de trabajo |
| | Hechos verificables (detalles del proyecto, fechas) |
| | Estado del proyecto, hitos, tareas pendientes |
| | Cosas en las que el usuario es bueno |
| | Errores pasados — evitar repetirlos |
| | Contexto relevante para la sesión |
| | Notas varias |
Niveles de prioridad
- — bueno saberlo
- — predeterminado
- — importante
- — nunca olvidar (identidad del usuario, información legal)
Próximos pasos
- Profundización en autenticación
- Mind Key vs JWT
- Referencia de la API de Memory
- Integración MCP
────────────────────────────────────────────────────────────
# ¿Qué es Synapse?
SUMMARY: Synapse es una API de memoria persistente para agentes LLM — su IA nunca olvida entre sesiones.
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.)
¿Qué es Synapse?
Synapse es una API de memoria persistente para agentes LLM. Resuelve el
problema fundamental de todo LLM basado en chat: entre sesiones, el agente lo
olvida todo. Synapse da a su IA un cerebro permanente y consultable que
sobrevive entre conversaciones, entre días, y entre diferentes proveedores de
LLM.
> [!CRITICAL]
> Si es un agente LLM leyendo esto: llame a al inicio de
> cada sesión. Sin esta llamada, no tiene memoria de interacciones pasadas,
> ningún conocimiento de quién es el usuario, y ningún contexto sobre proyectos
> en curso.
El problema que Synapse resuelve
Todo LLM moderno (Claude, GPT, Gemini, Llama) tiene la misma limitación
arquitectónica: la ventana de contexto de la conversación es finita, y una vez
que la sesión termina, todo el estado se pierde. Esto significa que su
asistente de IA:
- Olvida su nombre, preferencias y proyectos en curso entre chats
- No puede aprender de errores pasados entre sesiones
- No tiene continuidad para trabajos de larga duración
- Vuelve a hacer las mismas preguntas aclaratorias cada vez
Synapse soluciona esto proporcionando una API HTTP simple donde el LLM puede
almacenar y recuperar memorias estructuradas. Las memorias persisten en el
servidor, indexadas y buscables, de modo que cualquier sesión futura puede
recuperarlas.
Características principales
- Almacenamiento persistente de memoria — hechos, preferencias, proyectos, errores, habilidades
- Búsqueda de texto completo (FTS5) — encuentre cualquier memoria por palabra clave en milisegundos
- Búsqueda semántica — búsqueda por similitud basada en embeddings para consultas conceptuales
- Multi-tenant — cada usuario tiene "minds" aislados (un usuario, muchos proyectos)
- Chat asíncrono — los humanos pueden dejar mensajes al agente mientras trabaja
- Tareas y programación — gestor de tareas integrado y planificador cron
- Integración MCP — 79 herramientas expuestas como Model Context Protocol para Claude, Cursor, Continue
- Control de navegador y computadora — herramientas de automatización remota
- Webhooks — reciba callbacks HTTP ante cambios de memoria/chat/tarea
Cómo funciona
[CODE BLOCK]
1. El LLM llama a al inicio de la sesión
2. Synapse devuelve un resumen estructurado en texto de todas las memorias almacenadas
3. El LLM trabaja, llamando periódicamente a para almacenar nuevos hechos
4. Cuando el usuario hace una pregunta, el LLM puede llamar a
5. Al final de la sesión, el nuevo contexto importante se persiste para la siguiente sesión
¿Para quién es?
- Desarrolladores de agentes LLM que necesitan estado persistente
- Usuarios avanzados que ejecutan LLMs locales (Ollama, LM Studio) con agentes personalizados
- Equipos que construyen asistentes de IA que necesitan memoria compartida
- Ingenieros de automatización que encadenan llamadas LLM entre sesiones
Comparación rápida
| Característica | Memoria de ChatGPT | Synapse |
|---------|---------------|---------|
| Ubicación de almacenamiento | Servidores de OpenAI | Su servidor |
| Acceso por API | No (cerrado) | Sí (REST + MCP) |
| Multi-tenant | No | Sí (minds) |
| Categorías personalizadas | No | Sí (8 categorías) |
| Búsqueda | Limitada | FTS5 + semántica |
| Autoalojable | No | Sí (Docker) |
Próximos pasos
- Quick Start para humanos — obtenga un Mind Key en 5 minutos
- Quick Start para LLMs — primeras llamadas a la API
- Autenticación — Mind Keys vs JWTs
- Resumen de arquitectura — cómo está construido Synapse
## CATEGORÍA: REFERENCIA DE LA API
Referencia completa de todos los endpoints de la API.
────────────────────────────────────────────────────────────
# Browser Proxy
SUMMARY: Servicio de automatización de navegador — contenedor Docker separado en el puerto 13000 para el control 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.)
Browser Proxy
El Browser Proxy es un servicio Docker separado que proporciona
automatización de navegador headless mediante Playwright. NO forma parte
directamente de la API de Synapse — los endpoints de Synapse no incluyen rutas
.
Arquitectura
[CODE BLOCK]
Métodos de acceso
Método 1: A través del servidor MCP de Synapse (recomendado)
El servidor MCP de Synapse expone las herramientas de navegador como
herramientas MCP. Utilícelo para automatización de navegador dirigida por LLM:
[CODE BLOCK]
Herramientas MCP de navegador disponibles:
- — abre una nueva pestaña del navegador
- — navega a una URL
- — hace clic en un elemento
- — escribe texto en un campo
- — captura una captura de pantalla
- — cierra la pestaña
- (y más — consulte Integración MCP)
Método 2: Acceso directo al Browser Proxy
Para integraciones que no usan MCP, conéctese directamente al servicio
browser-proxy:
[CODE BLOCK]
Casos de uso comunes
Web scraping
[CODE BLOCK]
Automatización de formularios
[CODE BLOCK]
Captura de capturas de pantalla
[CODE BLOCK]
Servicios relacionados
| Servicio | Puerto | Propósito |
|---------|------|---------|
| Synapse API | 12800 | Memory, chat, tasks |
| Synapse MCP | 13100 | Servidor MCP (79 herramientas) |
| Browser Proxy | 13000 | Automatización de navegador headless |
| SSH Proxy | 12900 | Acceso SSH a máquinas remotas |
Próximos pasos
- Integración MCP — cómo usar las herramientas de navegador vía MCP
- API de Computer Control — para automatización GUI en máquinas registradas
────────────────────────────────────────────────────────────
# API de Chat
SUMMARY: Chat asíncrono entre humanos y agentes LLM — poll, reply, history, conteo de no leídos, subida de archivos.
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
La API de Chat permite la mensajería asíncrona entre humanos y agentes LLM.
A diferencia del chat síncrono (estilo ChatGPT), el humano puede dejar mensajes
mientras el agente está trabajando — el agente realiza poll entre llamadas a
herramientas.
Cómo funciona
[CODE BLOCK]
1. El humano envía un mensaje a través de la interfaz web (usa JWT)
2. El mensaje se almacena, marcado como no leído
3. El agente realiza poll a entre llamadas a herramientas
4. El poll devuelve todos los mensajes no leídos y los marca como leídos
5. El agente procesa el mensaje y, opcionalmente, responde vía
Endpoints
GET /chat/poll
Realiza poll de mensajes nuevos del humano. Devuelve los mensajes no leídos y
los marca como leídos. Úselo entre llamadas a herramientas.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
POST /chat/reply
Envía un mensaje como agente.
[CODE BLOCK]
POST /chat/send
Envía un mensaje como humano (requiere JWT, no Mind Key).
[CODE BLOCK]
GET /chat/history
Obtiene el historial reciente del chat (ambos roles).
[CODE BLOCK]
GET /chat/unread
Obtiene el conteo de mensajes no leídos.
[CODE BLOCK]
GET /chat/status
Obtiene el estado de la sesión de chat (timestamps del último mensaje, conteos
de no leídos).
[CODE BLOCK]
POST /chat/upload
Sube un archivo adjunto para un mensaje específico (formulario multipart).
[CODE BLOCK]
GET /chat/files/:messageid
Lista los archivos adjuntos de un mensaje.
[CODE BLOCK]
GET /chat/file/:fileid
Descarga un archivo adjunto.
[CODE BLOCK]
Patrón de polling
> [!TIP]
> Realice poll cada 30-60 segundos entre llamadas a herramientas. No haga poll
> con más frecuencia — desperdicia la cuota de la API y no aporta ningún
> beneficio.
[CODE BLOCK]
Próximos pasos
- API de Tasks
- Patrón de polling de chat
────────────────────────────────────────────────────────────
# API de Computer Control
SUMMARY: Control remoto de computadoras registradas — encolar comandos, tomar capturas de pantalla, ejecutar scripts en 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 Computer Control
La API de Computer Control permite controlar de forma remota computadoras
registradas. Un pequeño agente () se ejecuta en la máquina
destino, realiza poll de comandos, los ejecuta y publica los resultados de
vuelta. Esto habilita la automatización GUI dirigida por LLM.
Arquitectura
[CODE BLOCK]
Endpoints del lado del usuario (Mind Key o JWT)
GET /computers/list
Lista todas las computadoras registradas.
[CODE BLOCK]
GET /computers/:id
Obtiene los detalles de una computadora individual.
[CODE BLOCK]
POST /computers/install-code
Genera un código de instalación para registrar una nueva computadora.
[CODE BLOCK]
Respuesta:
POST /computers/:id/commands
Encola un comando para que el agente remoto lo ejecute.
[CODE BLOCK]
Respuesta:
GET /computers/:id/command (vía query)
Encola un comando vía GET (para casos simples).
[CODE BLOCK]
GET /computers/:id/commands
Lista los comandos recientes de una computadora.
[CODE BLOCK]
GET /computers/:id/commands/:cid
Obtiene el estado y resultado de un comando específico.
[CODE BLOCK]
GET /computers/:id/screenshot
One-shot: encola un comando de captura de pantalla y espera hasta 30s por el
resultado.
[CODE BLOCK]
POST /computers/:id/disable
Deshabilita una computadora (revoca su token, conserva el registro para
auditoría).
[CODE BLOCK]
DELETE /computers/:id
Elimina una computadora de forma permanente.
[CODE BLOCK]
Endpoints del lado del agente (Computer Token)
Estos endpoints los utiliza el que se ejecuta en la
máquina destino. Usan un Computer Token (devuelto por ),
no un Mind Key.
POST /computers/register
Canjea un código de instalación y obtiene un Computer Token.
[CODE BLOCK]
Respuesta:
> [!CRITICAL]
> Guarde el — solo se muestra una vez y es obligatorio para
> todos los endpoints del lado del agente.
GET /computers/me/poll
Long-poll de comandos nuevos. El agente lo llama en bucle.
[CODE BLOCK]
Devuelve inmediatamente si hay comandos pendientes, o después de segundos
si no los hay.
POST /computers/me/commands/:cid/result
Publica el resultado de ejecutar un comando.
[CODE BLOCK]
Tipos de comando
| Tipo | Payload | Descripción |
|------|---------|-------------|
| | | Captura la pantalla como PNG (base64) |
| | | Clic en las coordenadas |
| | | Mueve el ratón a las coordenadas |
| | | Escribe texto en el cursor |
| | | Pulsa una combinación de teclas |
| | | Rueda de desplazamiento |
| | | Arrastrar y soltar |
Patrón común: automatización GUI dirigida por LLM
[CODE BLOCK]
Próximos pasos
- Browser Proxy — servicio separado para automatización de navegador
- Guía de agentes self-hosted
────────────────────────────────────────────────────────────
# Cron y Scheduler
SUMMARY: Programe llamadas recurrentes a la API — trabajos cron que se disparan según una programación, ideales para sincronización periódica y recordatorios.
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 y Scheduler
La API de Cron permite programar llamadas HTTP recurrentes a endpoints de
Synapse (o a endpoints HTTPS externos). Ideal para sincronización periódica,
recordatorios y tareas de mantenimiento.
Endpoints
POST /cron
Crea una tarea programada.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
GET /cron
Lista todas las tareas programadas.
[CODE BLOCK]
DELETE /cron/:id
Elimina una tarea programada.
[CODE BLOCK]
PUT /cron/:id/toggle
Habilita o deshabilita una tarea sin eliminarla.
[CODE BLOCK]
Sintaxis de programación
Cron estándar (5 campos)
[CODE BLOCK]
Ejemplos:
| Programación | Significado |
|----------|---------|
| | Cada hora |
| | Cada 15 minutos |
| | Días laborables a las 9am |
| | Cada domingo a medianoche |
| | El primero de cada mes a medianoche |
Intervalo entero (segundos)
Para intervalos simples, pase un entero:
[CODE BLOCK]
Restricciones de endpoints
> [!WARNING]
> Los endpoints deben ser URLs o que apunten a:
> - La misma instancia de Synapse (p. ej. )
> - URLs HTTPS públicas (no IPs privadas, no localhost, no IPs de metadata)
Esto evita ataques SSRF donde un mind comprometido podría programar peticiones
a servicios internos.
Patrones comunes
Recall de memoria cada hora (para agentes LLM)
[CODE BLOCK]
Backup diario
[CODE BLOCK]
Poll periódico de chat (cada 5 minutos)
[CODE BLOCK]
Disparador de reporte semanal
[CODE BLOCK]
Próximos pasos
- API de Variables
- API de Webhooks
────────────────────────────────────────────────────────────
# Errores y manejo de errores
SUMMARY: Códigos de estado HTTP, formato de respuesta de error y cómo recuperarse de errores comunes.
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.
Errores y manejo de errores
Synapse utiliza códigos de estado HTTP estándar con un formato de respuesta de
error consistente. Esta página explica cómo interpretar y recuperarse de los
errores.
Formato de respuesta de error
Todos los errores devuelven JSON con esta estructura:
[CODE BLOCK]
| Campo | Descripción |
|-------|-------------|
| | Código de estado HTTP |
| | Nombre del estado HTTP |
| | Descripción del error legible por humanos |
| | URL a la documentación relevante (cuando aplica) |
Códigos de estado HTTP
200 OK
Éxito. La solicitud se procesó correctamente.
201 Created
Éxito. Se creó un nuevo recurso (p. ej. ).
204 No Content
Éxito. No se devuelve cuerpo (p. ej. ).
400 Bad Request
La solicitud estaba mal formada. Causas comunes:
- Faltan campos JSON obligatorios
- Sintaxis JSON inválida
- Valor de enum inválido (p. ej. categoría incorrecta)
[CODE BLOCK]
Solución: Verifique el cuerpo de la solicitud contra la documentación de la
API. Asegúrese de que todos los campos obligatorios estén presentes y tengan
valores válidos.
401 Unauthorized
Falló la autenticación. Causas comunes:
- Falta la cabecera
- Mind Key o JWT inválido
- Uso de un Mind Key donde se requiere un JWT (o viceversa)
[CODE BLOCK]
Solución: Verifique su token. Consulte Autenticación.
403 Forbidden
Está autenticado pero no se le permite realizar esta acción. Causas comunes:
- Intentar eliminar el mind de otro usuario
- Intentar verificar una memoria con un Mind Key (requiere JWT)
- El mind está deshabilitado
Solución: Compruebe si está usando el tipo de token correcto para este
endpoint.
404 Not Found
La ruta o recurso solicitado no existe.
> [!CRITICAL]
> NO adivine las rutas de los endpoints. Solo existen las rutas listadas en
> . Si obtiene un 404, usó una ruta incorrecta.
[CODE BLOCK]
Solución: Llame a para ver la lista de endpoints válidos.
Compare su URL contra la lista carácter por carácter.
409 Conflict
La solicitud entra en conflicto con el estado existente. Causas comunes:
- Intentar registrarse con un email que ya existe
- URL de webhook duplicada
Solución: Use un valor diferente, o use para actualizar el recurso
existente.
429 Too Many Requests
Alcanzó un límite de frecuencia. Solo aplica a la autenticación por parámetro de
consulta (60/min).
[CODE BLOCK]
Cabeceras de respuesta:
[CODE BLOCK]
Solución: Cambie a la cabecera (sin límite de
frecuencia), o espere segundos.
500 Internal Server Error
Error del servidor. Esto no debería ocurrir — si ocurre, es un bug.
Solución:
1. Reintente con backoff exponencial (1s, 2s, 4s, 8s)
2. Compruebe para ver si el servidor está activo
3. Si persiste, reporte el error
503 Service Unavailable
El servidor está temporalmente inactivo (p. ej. durante un despliegue, migración
de base de datos).
Solución: Espere y reintente. Compruebe .
Patrones de recuperación
Reintento con backoff exponencial
[CODE BLOCK]
Manejo de errores de autenticación
[CODE BLOCK]
Escenarios de error comunes
"Mind Key fehlt oder ungültig"
- Olvidó la cabecera
- Usó pero la clave es incorrecta
- Está usando un JWT donde se requiere un Mind Key
"Route not found"
- Adivinó una ruta que no existe
- Usó un verbo incorrecto (p. ej. vs )
- Compruebe para ver las rutas válidas
"Rate limit exceeded"
- Está usando y superó las 60 req/min
- Cambie a la cabecera
Próximos pasos
- Autenticación
- Resumen de la API
- Límites de frecuencia
────────────────────────────────────────────────────────────
# API de Memory
SUMMARY: Referencia completa de los 22 endpoints de memoria: almacenar, recall, búsqueda, búsqueda semántica, sincronización, auditoría y más.
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 Memory
La API de Memory es el corazón de Synapse. Proporciona 22 endpoints para
almacenar, recuperar, buscar y gestionar memorias estructuradas. Todos los
endpoints requieren un Mind Key para autenticarse.
> [!CRITICAL]
> Llame siempre a al inicio de cada sesión. Es la única
> forma de reconstruir el contexto de sesiones anteriores.
Categorías
Las memorias se organizan en 8 categorías:
| Categoría | Caso de uso |
|----------|----------|
| | Nombre, rol, información de contacto, preferencias sobre uno mismo |
| | Gustos, disgustos, estilo de trabajo, preferencias de comunicación |
| | Hechos verificables (detalles del proyecto, fechas, URLs) |
| | Estado del proyecto, hitos, arquitectura |
| | Cosas en las que el usuario es bueno |
| | Errores pasados — evitar repetirlos |
| | Contexto relevante para la sesión |
| | Notas varias |
Prioridades
- — bueno saberlo
- — predeterminado
- — importante
- — nunca olvidar (identidad del usuario, información legal)
Endpoints principales
GET /memory/recall
Devuelve TODAS las memorias como texto plano optimizado para LLM. Llámelo al
inicio de cada sesión.
[CODE BLOCK]
Respuesta (text/plain):
[CODE BLOCK]
POST /memory
Almacena una nueva memoria o actualiza una existente (misma categoría + key = actualización).
[CODE BLOCK]
Respuesta:
GET /memory
Lista memorias con filtros opcionales.
[CODE BLOCK]
PUT /memory/:id
Actualiza una memoria específica por ID.
[CODE BLOCK]
DELETE /memory/:id
Elimina una sola memoria.
[CODE BLOCK]
Endpoints de búsqueda
GET /memory/search
Búsqueda de texto completo usando FTS5.
[CODE BLOCK]
Sintaxis FTS5:
- Múltiples palabras = AND:
- Frase:
- Prefijo:
- Booleano:
- Excluir:
GET /memory/semantic-search
Búsqueda conceptual mediante embeddings (más lenta que FTS5 pero entiende el significado).
[CODE BLOCK]
Devuelve memorias que son semánticamente similares a la consulta, incluso si no
coinciden palabras clave. Útil para "buscar memorias sobre X" donde X se describe
de forma diferente.
GET /memory/by-tag
Lista memorias por etiqueta.
[CODE BLOCK]
GET /memory/related/:id
Encuentra memorias relacionadas con una específica (vía etiquetas compartidas).
[CODE BLOCK]
Sincronización y diff
GET /memory/diff
Sincronización incremental — devuelve memorias cambiadas desde un timestamp.
[CODE BLOCK]
Respuesta:
POST /memory/sync
Aplica un diff desde otra instancia (para sincronización self-hosted).
[CODE BLOCK]
Operaciones en lote
POST /memory/bulk-delete
Elimina múltiples memorias por ID.
[CODE BLOCK]
POST /memory/embed-batch
Genera embeddings para memorias que aún no los tienen (para búsqueda semántica).
[CODE BLOCK]
GET /memory/embed-batch-status
Comprueba el progreso de generación de embeddings.
[CODE BLOCK]
Verificación
Las memorias tienen un flag . Las memorias almacenadas por el agente
se marcan por defecto como no verificadas (); las almacenadas por
humanos se consideran verificadas ().
POST /memory/verify
Marca una memoria como verificada (requiere JWT, no Mind Key).
[CODE BLOCK]
POST /memory/unverify
Marca una memoria como no verificada (requiere JWT).
[CODE BLOCK]
GET /memory/unverified
Lista memorias pendientes de verificación humana.
[CODE BLOCK]
Estadísticas y auditoría
GET /memory/stats
Estadísticas agregadas del mind actual.
[CODE BLOCK]
Devuelve:
GET /memory/audit
Registro de auditoría de todas las operaciones que cambian estado.
[CODE BLOCK]
GET /memory/contradictions
Detecta posibles contradicciones en las memorias almacenadas.
[CODE BLOCK]
GET /memory/expiring
Lista memorias con fechas de expiración próximas.
[CODE BLOCK]
Salud y exportación
GET /memory/health
Verificación rápida de salud del sistema de memoria.
[CODE BLOCK]
GET /memory/mind-export
Exportación JSON completa de todas las memorias (para backup).
[CODE BLOCK]
POST /memory/compact
Compacta memorias similares (auto-resumen).
[CODE BLOCK]
Próximos pasos
- Quick Start para LLMs
- Mejores prácticas de memoria
- Búsqueda FTS5
- Búsqueda semántica
────────────────────────────────────────────────────────────
# Resumen de la API y URL base
SUMMARY: Todos los endpoints de la API de Synapse, URL base, patrones de autenticación y formatos de respuesta de un vistazo.
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.
Resumen de la API y URL base
La API de Synapse es una API HTTP RESTful. Todos los endpoints devuelven JSON
(excepto donde se indique lo contrario). Esta página cubre lo esencial que debe
conocer antes de profundizar en endpoints específicos.
URL base
[CODE BLOCK]
Todas las rutas de esta documentación son relativas a esta URL base. Para
instancias autoalojadas, sustitúyala por su propia URL.
Autenticación
Existen dos métodos, ambos enviados mediante la cabecera :
[CODE BLOCK]
O mediante el parámetro de consulta (limitado a 60/min):
[CODE BLOCK]
Consulte Autenticación para más detalles.
Grupos de endpoints
| Grupo | Auth | Descripción |
|-------|------|-------------|
| Public | Ninguna | Página de inicio, health, OpenAPI, docs |
| Memory | Mind Key | CRUD, búsqueda, sincronización, embeddings |
| Chat | Mind Key / JWT | Mensajería asíncrona entre humano y agente |
| Tasks | Mind Key | Gestión de tareas |
| Scripts | Mind Key / JWT | Almacén persistente de scripts |
| Scheduler | Mind Key | Trabajos cron + variables |
| Webhooks | Mind Key | Callbacks HTTP ante eventos |
| Computers | Mind Key / JWT | Control remoto de computadoras |
| User/Minds | JWT | Cuenta + gestión de minds |
| Sharing | JWT | Compartir minds entre usuarios |
| Push | JWT | Suscripciones Web Push |
| Tools | Ninguna | Hora, calculadora, aleatorios (utilidades públicas) |
Formatos de respuesta
- JSON (predeterminado):
- Texto plano: devuelve texto optimizado para LLM
- HTML: , , , ,
Envoltorio estándar de respuesta
Las respuestas exitosas devuelven los datos directamente:
[CODE BLOCK]
Las respuestas de error usan este formato:
[CODE BLOCK]
> [!NOTE]
> El campo enlaza a la documentación relevante para errores comunes.
Códigos de estado HTTP
| Código | Significado |
|------|---------|
| 200 | Éxito (GET, PUT) |
| 201 | Creado (POST) |
| 204 | Sin contenido (DELETE) |
| 400 | Solicitud incorrecta (error de validación) |
| 401 | No autorizado (token ausente/inválido) |
| 403 | Prohibido (tipo de token incorrecto) |
| 404 | No encontrado (la ruta no existe) |
| 409 | Conflicto (duplicado) |
| 429 | Demasiadas solicitudes (límite de frecuencia) |
| 500 | Error del servidor |
Endpoints de descubrimiento
| Endpoint | Propósito |
|----------|---------|
| | Página de inicio (optimizada para LLM) |
| | Lista legible por máquina de todos los endpoints |
| | Lista de endpoints en texto plano |
| | Especificación OpenAPI 3.0 |
| | Documentación completa de la API (HTML) |
| | Documentación de la API en JSON |
| | Sistema de documentación (HTML) |
| | Índice de documentación (JSON) |
| | Toda la documentación en un bloque de texto |
| | Playground interactivo de la API |
Límites de frecuencia
| Método de auth | Límite |
|-------------|-------|
| Mind Key (cabecera) | Ninguno |
| Mind Key (?key=) | 60/min por IP |
| JWT (cabecera) | Ninguno |
| Endpoints públicos | Ninguno |
Las respuestas con límite de frecuencia incluyen:
[CODE BLOCK]
Paginación
Los endpoints de lista admiten y :
[CODE BLOCK]
Límite predeterminado: 100. Límite máximo: 500.
CORS
Todos los endpoints admiten CORS para clientes basados en navegador:
[CODE BLOCK]
SDKs y clientes
- SDK Node.js: (repo)
- Servidor MCP: (repo)
- Cliente HTTP: cualquier librería HTTP (curl, fetch, axios, etc.)
Próximos pasos
- API de Memory — los endpoints más importantes
- API de Chat — comunicación asíncrona humano-agente
- Errores y manejo de errores
────────────────────────────────────────────────────────────
# Límites de frecuencia y cuotas
SUMMARY: Políticas de límites de frecuencia de la API de Synapse — cabecera 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.
Límites de frecuencia y cuotas
Synapse tiene una política de límites de frecuencia simple y predecible,
diseñada para prevenir el abuso sin estorbar el uso legítimo.
Política de límites de frecuencia
| Método de auth | Límite | Ámbito |
|-------------|-------|-------|
| Mind Key () | Ninguno | Por mind |
| Mind Key () | 60 req/min | Por IP |
| JWT () | Ninguno | Por usuario |
| Endpoints públicos | Ninguno | Global |
> [!TIP]
> Use siempre la cabecera cuando sea posible. No
> tiene límite de frecuencia. Use solo para herramientas que no puedan
> establecer cabeceras personalizadas.
Cabeceras de límite de frecuencia
Cuando use auth con , las respuestas incluyen cabeceras de límite:
[CODE BLOCK]
Cuando supere el límite:
[CODE BLOCK]
Cuando alcanza un límite de frecuencia
Si obtiene un 429:
1. Cambie a la cabecera Authorization (recomendado):
[CODE BLOCK]
2. O espere segundos y reintente.
Por qué existe el límite de ?key=
El parámetro de consulta es conveniente para herramientas que solo usan
URLs (navegadores, comandos ), pero tiene implicaciones de seguridad y
rendimiento:
- Seguridad: Los parámetros de consulta se registran en logs de acceso del
servidor, historial del navegador y cabeceras Referer. Limitar su uso reduce
la exposición.
- Rendimiento: La auth por parámetro de consulta requiere un limitador de
frecuencia basado en IP (búsqueda Redis por petición), lo que añade latencia.
La auth por cabecera omite esto.
- Prevención de abuso: Una URL filtrada podría compartirse y sufrir
bombardeo. El límite por IP contiene el radio de impacto.
Patrones recomendados
Agentes LLM
[CODE BLOCK]
Herramientas basadas en navegador
Si su herramienta solo puede abrir URLs:
[CODE BLOCK]
Servidor MCP
Los servidores MCP siempre usan auth por cabecera vía la variable de entorno
— no se aplica ningún límite.
Importaciones en lote
Para operaciones masivas (p. ej. importar 1000 memorias), use siempre auth por
cabecera. Las importaciones en lote vía alcanzarán el límite en menos
de 1 minuto.
Cuotas (a nivel de mind)
Actualmente no existen cuotas por mind en cuanto a tamaño de almacenamiento o
cantidad de memorias. Todos los límites son a nivel de auth/IP, no a nivel de
datos. Esto podría cambiar en el futuro para equidad multi-tenant.
Monitoreo de su uso
[CODE BLOCK]
Próximos pasos
- Autenticación
- Errores y manejo de errores
────────────────────────────────────────────────────────────
# API de Scripts
SUMMARY: Almacén persistente de scripts — guarde scripts reutilizables de shell, Python o Node y obténgalos vía 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
La API de Scripts proporciona un almacén persistente para scripts reutilizables.
Los scripts se nombran y versionan dentro de un mind, y pueden obtenerse como
texto plano — perfecto para patrones .
Endpoints
POST /script
Almacena o actualiza un script.
[CODE BLOCK]
GET /script/:name
Obtiene el contenido del script como . Perfecto para redirigir a
bash.
[CODE BLOCK]
GET /script/:name/info
Obtiene los metadatos del script sin el contenido.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
GET /scripts
Lista todos los scripts del mind actual.
[CODE BLOCK]
DELETE /script/:name
Elimina un script.
[CODE BLOCK]
Casos de uso comunes
Scripts de despliegue
Almacene procedimientos de despliegue estándar para que el LLM pueda ejecutarlos
sin tener que rededucir los pasos cada vez:
[CODE BLOCK]
Snippets de diagnóstico
Almacene comandos de diagnóstico para problemas comunes:
[CODE BLOCK]
Generadores de configuración
Almacene scripts que generan configuraciones:
[CODE BLOCK]
Próximos pasos
- API de Variables
- Cron y Scheduler
────────────────────────────────────────────────────────────
# API de Tasks
SUMMARY: Gestión de tareas para agentes LLM — crear, listar, actualizar, completar y eliminar tareas con 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 Tasks
La API de Tasks ofrece a los agentes LLM una forma estructurada de seguir
trabajos multi-paso. Las tareas se asocian al mind actual y persisten entre
sesiones, de modo que el agente puede retomar el trabajo donde lo dejó.
Endpoints
GET /mind/tasks
Lista todas las tareas del mind actual.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
POST /mind/task
Crea una nueva tarea.
[CODE BLOCK]
GET /mind/task (parámetros de consulta)
Crea una tarea vía GET (para herramientas que solo admiten URL).
[CODE BLOCK]
PUT /mind/task/:id
Actualiza una tarea existente.
[CODE BLOCK]
GET /mind/task/:id/complete
Marca una tarea como completada.
[CODE BLOCK]
GET /mind/task/:id/delete
Elimina una tarea de forma permanente.
[CODE BLOCK]
Prioridades
- — no urgente
- — predeterminado
- — importante
- — debe hacerse de inmediato
Estados
- — creada, no iniciada
- — en progreso actualmente
- — completada
- — abandonada
Patrón: workflow basado en tareas
[CODE BLOCK]
Próximos pasos
- Workflow basado en tareas
- Cron y Scheduler
────────────────────────────────────────────────────────────
# Herramientas de utilidad (time, calc, random)
SUMMARY: Endpoints públicos de utilidad — hora del servidor, calculadora segura, generador de valores aleatorios. No requieren autenticación.
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.
Herramientas de utilidad
Los endpoints son utilidades públicas — no requieren autenticación.
Son útiles para agentes LLM que necesitan la hora del servidor, operaciones
matemáticas seguras o valores aleatorios.
GET /tools/time
Obtiene la hora actual del servidor, zona horaria y offset UTC.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
Caso de uso: agentes LLM que necesitan saber "qué hora es ahora" para
planificación, timestamps o cálculos de fechas relativas.
GET /tools/calc
Calculadora segura — solo aritmética, sin . Admite , , , ,
, , y números.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
> [!TIP]
> Úselo en lugar de intentar hacer cálculos mentales o mediante parsing de
> cadenas. Es seguro (no hay posibilidad de inyección de código) y preciso.
Operadores admitidos
- suma
- resta
- multiplicación
- división
- módulo
- paréntesis
- Números (enteros y decimales)
Ejemplos
[CODE BLOCK]
GET /tools/random
Genera valores aleatorios.
[CODE BLOCK]
Parámetros por tipo
| Tipo | Parámetros | Salida |
|------|-----------|--------|
| | ninguno | Cadena UUID v4 |
| | , (predeterminado 0-100) | Entero |
| | , (predeterminado 0-100) | Float |
| | , (rango de longitud, predeterminado 8-16) | Cadena hex |
| | , (rango de longitud, predeterminado 8-16) | Cadena alfabética |
Casos de uso para agentes LLM
Generar IDs únicos
[CODE BLOCK]
Calcular porcentajes
[CODE BLOCK]
Obtener timestamp actual
[CODE BLOCK]
Generar datos de prueba
[CODE BLOCK]
Próximos pasos
- Resumen de la API — todos los grupos de endpoints
- Errores y manejo de errores
────────────────────────────────────────────────────────────
# API de User y Minds
SUMMARY: Gestión de cuenta — registro, login, crear minds, listar minds, eliminar minds. Protegido con 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 User y Minds
La API de User y Minds gestiona la administración de cuentas. Estos endpoints
usan autenticación JWT (no Mind Keys) porque operan a nivel de cuenta, no a
nivel de mind.
Endpoints de autenticación
POST /register
Crea una nueva cuenta de usuario.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
POST /login
Inicia sesión en una cuenta existente.
[CODE BLOCK]
Respuesta: igual que .
Endpoints de Minds
POST /minds
Crea un nuevo mind. Devuelve el Mind Key — guárdelo de inmediato, solo se
muestra una vez.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
> [!CRITICAL]
> El se muestra solo una vez. Si lo pierde, no podrá recuperarlo —
> debe eliminar el mind y crear uno nuevo (lo que pierde todas las memorias
> almacenadas).
GET /minds
Lista todos los minds del usuario actual.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
DELETE /minds/:id
Elimina un mind de forma permanente.
[CODE BLOCK]
> [!WARNING]
> Eliminar un mind es irreversible. Todas las memorias, tareas, historial
> de chat y scripts de ese mind se pierden de forma permanente. Exporte primero
> vía si necesita un backup.
Patrón multi-mind
La mayoría de los usuarios se beneficia de tener múltiples minds para mantener
los contextos aislados:
[CODE BLOCK]
Use diferentes Mind Keys en diferentes sesiones LLM para mantener los contextos
aislados.
Seguridad de la cuenta
Requisitos de contraseña
- Mínimo 6 caracteres
- Sin máximo (use un gestor de contraseñas)
- Se almacena como hash bcrypt (nunca en texto plano)
Expiración del JWT
Los JWT expiran después de 7 días. Al expirar, simplemente llame de nuevo a
.
Seguridad del Mind Key
Los Mind Keys nunca expiran. Si un Mind Key se ve comprometido:
1. Cree un nuevo mind vía
2. Actualice la configuración de su LLM con el nuevo Mind Key
3. Elimine el mind comprometido vía
Próximos pasos
- Autenticación — guía completa de auth
- Mind Key vs JWT — guía de decisión
- API de Sharing — compartir minds con otros usuarios
────────────────────────────────────────────────────────────
# API de Variables
SUMMARY: Almacén rápido clave-valor para estado de LLM — contadores, flags, timestamps de última actividad, progreso 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 Variables
La API de Variables es un almacén rápido clave-valor para estado efímero. A
diferencia de las memorias (que están indexadas, son buscables y estructuradas),
las variables están optimizadas para acceso rápido de lectura/escritura —
perfectas para contadores, flags y estado de sesión.
Endpoints
POST /var
Establece o actualiza una variable.
[CODE BLOCK]
GET /var/:key
Obtiene una variable individual.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
GET /var
Lista todas las variables.
[CODE BLOCK]
DELETE /var/:key
Elimina una variable.
[CODE BLOCK]
Cuándo usar Variables vs Memory
| Caso de uso | Usar |
|----------|-----|
| Nombre, preferencias | Memory (buscable, estructurado) |
| Timestamp de última sesión | Variable (estado efímero) |
| Contador (p. ej. mensajes enviados) | Variable (actualizaciones frecuentes) |
| Estado de workflow ("paso 3 de 5 completado") | Variable (transitorio) |
| Notas largas de proyecto | Memory (indexado de texto completo) |
| Scripts reutilizables | Script store (con nombre, versionado) |
Patrones comunes
Seguimiento de la última sesión
[CODE BLOCK]
Patrón contador
[CODE BLOCK]
Feature flags
[CODE BLOCK]
Próximos pasos
- API de Memory — para datos estructurados y buscables
- Cron y Scheduler
────────────────────────────────────────────────────────────
# API de Webhooks
SUMMARY: Registre callbacks HTTP para eventos de memoria, chat y tareas — reciba notificaciones cuando cambien los datos.
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
Los webhooks permiten recibir callbacks HTTP cuando ocurren eventos en Synapse.
Perfectos para disparar automatización externa, enviar notificaciones o
sincronizar con otros sistemas.
Endpoints
POST /webhooks
Registra un nuevo webhook.
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
GET /webhooks
Lista todos los webhooks del mind actual.
[CODE BLOCK]
GET /webhooks/:id
Obtiene un webhook individual.
[CODE BLOCK]
PUT /webhooks/:id
Actualiza un webhook (URL, eventos, secreto o flag enabled).
[CODE BLOCK]
DELETE /webhooks/:id
Elimina un webhook.
[CODE BLOCK]
Tipos de evento
| Patrón | Se dispara cuando |
|---------|------------|
| | Cualquier evento de memoria |
| | Nueva memoria almacenada |
| | Memoria actualizada |
| | Memoria eliminada |
| | Cualquier evento de chat |
| | Nuevo mensaje del humano |
| | Cualquier evento de tarea |
| | Nueva tarea creada |
| | Tarea marcada como completada |
| | Todos los eventos |
Payload del webhook
Cuando se dispara un evento, Synapse hace POST a su URL:
[CODE BLOCK]
Verificación de firma
Si establece un , Synapse firma cada payload con HMAC-SHA256:
[CODE BLOCK]
Verifíquelo en su handler:
[CODE BLOCK]
Patrón: sincronización en tiempo real
[CODE BLOCK]
Próximos pasos
- Cron y Scheduler
- Guía de automatización con webhooks
## CATEGORÍA: INTEGRACIÓN MCP
Integración con Claude, Cursor y otros clientes MCP.
────────────────────────────────────────────────────────────
# MCP en Claude Code
SUMMARY: Use las herramientas de Synapse desde el agente de terminal Claude Code — memoria persistente para sesiones de codificación.
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 en Claude Code
Claude Code es el agente de codificación basado en terminal de Anthropic. Con
Synapse MCP, Claude Code gana memoria persistente entre sesiones de codificación
— recuerda el contexto del proyecto, decisiones pasadas y patrones del
codebase.
Configuración
Método 1: Comando CLI (recomendado)
[CODE BLOCK]
Método 2: Editar archivo de configuración
Edite :
[CODE BLOCK]
Verifique que funciona
Inicie Claude Code:
[CODE BLOCK]
En el prompt de Claude Code, escriba:
[CODE BLOCK]
Claude debería llamar a y responder con sus memorias
almacenadas.
Patrones comunes
Persistencia del contexto del proyecto
Al inicio de una sesión de codificación:
[CODE BLOCK]
Claude llama a , ve su lista de proyectos y continúa el trabajo
donde lo dejó.
Decisiones del codebase
Cuando tome una decisión arquitectónica:
[CODE BLOCK]
Claude llama a con la categoría , prioridad .
Evitar errores pasados
[CODE BLOCK]
Claude busca memorias con categoría y le recuerda los errores
pasados.
Seguimiento de tareas
[CODE BLOCK]
Claude llama a , y la tarea persiste entre sesiones.
Tool Profiles
Para sesiones de codificación donde no necesita las 119 herramientas:
[CODE BLOCK]
Solución de problemas
El servidor MCP no arranca
[CODE BLOCK]
Mind Key no reconocido
[CODE BLOCK]
Claude Code no ve las herramientas
- Reinicie Claude Code tras cambios de configuración
- Compruebe para verificar que Synapse está registrado
- Consulte Solución de problemas de MCP
Próximos pasos
- Configuración de Claude Desktop
- Configuración de Cursor
- Guía de agente LLM persistente
────────────────────────────────────────────────────────────
# MCP en Claude Desktop
SUMMARY: Conecte Synapse a Claude Desktop en 2 minutos. Claude obtiene 79 herramientas de Synapse de forma nativa.
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 en Claude Desktop
Claude Desktop es la app de escritorio de Anthropic para macOS y Windows. Con
el servidor MCP de Synapse configurado, Claude obtiene acceso nativo a las 79
herramientas de Synapse — puede almacenar memorias, recuperarlas, gestionar
tareas, chatear con usted y más.
Requisitos previos
- App Claude Desktop (macOS o Windows)
- Node.js 18+ instalado ()
- Su Mind Key de Synapse
Paso 1: Abrir el archivo de configuración
- macOS:
- Windows:
Si el archivo no existe, créelo.
Paso 2: Añadir el servidor MCP de Synapse
[CODE BLOCK]
> [!TIP]
> Si ya tiene otros servidores MCP configurados, simplemente añada el bloque
> dentro del objeto existente.
Paso 3: Reiniciar Claude Desktop
1. Cierre Claude Desktop completamente (Cmd+Q en macOS, no solo cerrar la ventana)
2. Vuelva a abrir Claude Desktop
3. Inicie un nuevo chat
4. Busque el icono de enchufe 🔌 en la parte inferior izquierda — debería decir "79 tools"
Paso 4: Probarlo
En un nuevo chat, escriba:
[CODE BLOCK]
Claude debería llamar a la herramienta y responder con un
resumen de sus memorias almacenadas (o "No memories yet" si su mind está
vacío).
Herramientas disponibles (selección)
| Herramienta | Descripción |
|------|-------------|
| | Recupera todas las memorias |
| | Almacena una nueva memoria |
| | Busca memorias |
| | Lista tareas |
| | Crea una tarea |
| | Comprueba si hay mensajes nuevos |
| | Responde a un mensaje |
| | Abre una pestaña del navegador |
| | Lista las computadoras registradas |
Lista completa: ¿Qué es MCP?
Solución de problemas
No aparecen herramientas en Claude Desktop
1. Verifique la versión de Node.js: (debe ser ≥ 18)
2. Compruebe que el archivo de configuración es JSON válido (sin comas finales)
3. Reinicie Claude Desktop completamente (Cmd+Q, no solo cerrar)
4. Revise los logs de Claude Desktop: (macOS)
Error "Mind Key invalid"
- Verifique que empieza por
- Obtenga una nueva clave vía (requiere JWT de )
- Sin comillas alrededor de la clave en el JSON
npx no encontrado
- Instale Node.js 18+:
- Reinicie el terminal tras la instalación
- En macOS con Homebrew:
Las herramientas aparecen pero las llamadas fallan
- Compruebe que es alcanzable:
- Verifique que su Mind Key funciona:
- Consulte Solución de problemas de MCP
Tool Profiles (ahorro de tokens)
Si está usando un LLM más pequeño o quiere ahorrar tokens de contexto,
establezca un tool profile:
[CODE BLOCK]
Perfiles: (8 herramientas), (25), (119,
predeterminado).
Próximos pasos
- Configuración de Claude Code
- Configuración de Cursor
- Solución de problemas de MCP
────────────────────────────────────────────────────────────
# MCP en Continue.dev
SUMMARY: Conecte Synapse a Continue.dev — asistente de codificación de IA de código abierto para VS Code y JetBrains.
MCP en Continue.dev
Continue.dev es un asistente de codificación con IA de código abierto para VS
Code y IDEs JetBrains. Con Synapse MCP, Continue gana memoria persistente entre
sesiones.
Requisitos previos
- VS Code o IDE JetBrains
- Extensión Continue.dev instalada
- Node.js 18+
- Su Mind Key de Synapse
Configuración
Paso 1: Abrir la configuración de Continue
En VS Code o JetBrains:
1. Abra la barra lateral de la extensión Continue
2. Haga clic en el icono de engranaje → "Open config.json"
O edite directamente.
Paso 2: Añadir el servidor MCP de Synapse
[CODE BLOCK]
Paso 3: Recargar Continue
Recargue la ventana de VS Code (Cmd+Shift+P → "Reload Window") o reinicie su
IDE.
Verifique que funciona
En el chat de Continue:
[CODE BLOCK]
Continue debería llamar a y responder con sus memorias
almacenadas.
Patrones comunes
Contexto del proyecto
[CODE BLOCK]
Continue llama a , ve sus memorias del proyecto y continúa el
trabajo donde lo dejó.
Patrones de revisión de código
[CODE BLOCK]
Continue encuentra sus patrones de revisión de código almacenados y los aplica.
Memoria de pair programming
[CODE BLOCK]
Continue lo almacena como una memoria .
Solución de problemas
El servidor MCP no conecta
1. Compruebe que es JSON válido
2. Verifique Node.js:
3. Revise el panel de salida de Continue (View → Output → Continue)
4. Reinicie el IDE
Las herramientas no aparecen
- Verifique que la versión de Continue admite MCP (≥ 0.9.x)
- Compruebe que la variable de entorno está establecida en la configuración
- Busque errores MCP en los logs de Continue
Próximos pasos
- Configuración de Claude Desktop
- Cliente MCP personalizado
────────────────────────────────────────────────────────────
# MCP en Cursor
SUMMARY: Conecte Synapse al IDE Cursor para memoria persistente del proyecto entre sesiones de codificación.
MCP en Cursor
Cursor es un IDE con IA basado en VS Code. Con Synapse MCP, Cursor gana memoria
persistente entre sesiones — recuerda las decisiones del proyecto, los patrones
del codebase y las sesiones de depuración pasadas.
Requisitos previos
- IDE Cursor instalado ()
- Node.js 18+
- Su Mind Key de Synapse
Configuración
Paso 1: Abrir la configuración de Cursor
En Cursor:
1. Abra Settings (Cmd+, en macOS, Ctrl+, en Windows/Linux)
2. Busque "MCP" o navegue a
Paso 2: Añadir el servidor MCP de Synapse
Haga clic en "Add MCP Server" y configure:
| Campo | Valor |
|-------|-------|
| Name | |
| Type | |
| Command | |
| Env | |
Paso 3: Editar config.json directamente (alternativa)
Cursor almacena la configuración MCP en :
[CODE BLOCK]
Paso 4: Reiniciar Cursor
Reinicie Cursor completamente (Cmd+Q y vuelva a abrir en macOS).
Verifique que funciona
En el panel de chat de Cursor (Cmd+L):
[CODE BLOCK]
Cursor debería llamar a y responder con sus memorias
almacenadas.
Patrones comunes
Onboarding del proyecto
Al abrir un proyecto nuevo:
[CODE BLOCK]
Cursor llama a y continúa el trabajo donde lo dejó.
Decisiones de arquitectura
[CODE BLOCK]
Cursor lo almacena como una memoria con prioridad .
Historial de depuración
[CODE BLOCK]
Cursor busca memorias y le recuerda las correcciones pasadas.
Patrones de código entre sesiones
[CODE BLOCK]
Cursor encuentra memorias sobre implementaciones de auth que ha hecho antes.
Solución de problemas
El servidor MCP no conecta
1. Verifique Node.js: (≥ 18)
2. Pruebe el servidor MCP: (debería arrancar sin errores)
3. Revise los logs MCP de Cursor (View → Output → MCP)
4. Reinicie Cursor completamente
Las herramientas no aparecen
- Compruebe que es JSON válido
- Verifique que la variable de entorno está establecida
- Compruebe que la versión de Cursor admite MCP (≥ 0.42)
Mind Key inválido
[CODE BLOCK]
Próximos pasos
- Configuración de Claude Desktop
- Configuración de Continue.dev
- Guía de agente LLM persistente
────────────────────────────────────────────────────────────
# Construir un cliente MCP personalizado
SUMMARY: Conéctese al servidor MCP de Synapse desde su propia aplicación usando el SDK de MCP.
Construir un cliente MCP personalizado
Si está construyendo su propia aplicación LLM, puede conectarse al servidor MCP
de Synapse directamente usando el SDK oficial de MCP. Esto da a su app acceso a
las 79 herramientas de Synapse.
SDKs
| Lenguaje | Paquete |
|----------|---------|
| TypeScript/JavaScript | |
| Python | |
Ejemplo en TypeScript
Instalación
[CODE BLOCK]
Conexión vía stdio
[CODE BLOCK]
Conexión vía HTTP/SSE (remoto)
[CODE BLOCK]
Ejemplo en Python
Instalación
[CODE BLOCK]
Conexión vía stdio
[CODE BLOCK]
Tool Profiles
Al conectar, puede solicitar un tool profile específico vía la cabecera
(HTTP/SSE) o la variable de entorno (stdio):
[CODE BLOCK]
Manejo de errores
[CODE BLOCK]
Casos de uso
- Asistentes de IA personalizados — construya su propio agente con memoria persistente
- Automatización de flujos de trabajo — encadene herramientas de Synapse en flujos personalizados
- Pipelines de datos — extraiga memorias, transforme, cargue en otro lugar
- Dashboards de monitoreo — muestre estadísticas de memoria, historial de chat, tareas
Próximos pasos
- Especificación MCP
- Repo de Synapse MCP
- Resumen de la API
────────────────────────────────────────────────────────────
# Solución de problemas de MCP
SUMMARY: Resuelva problemas comunes de integración de MCP — servidor que no arranca, herramientas que no aparecen, errores 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/
Solución de problemas de MCP
Problemas comunes y soluciones al integrar Synapse MCP con su cliente LLM.
Lista rápida de diagnóstico
1. ✅ ¿Node.js 18+ instalado? ()
2. ✅ ¿El Mind Key empieza por ? (no JWT )
3. ✅ ¿La API de Synapse es alcanzable? ()
4. ✅ ¿El Mind Key funciona? ()
5. ✅ ¿El archivo de configuración es JSON válido? (sin comas finales, sin comentarios)
6. ✅ ¿Reinició el cliente tras el cambio de configuración?
7. ✅ ¿El servidor MCP arranca manualmente? ()
Problema: no aparecen herramientas en el cliente
Síntomas
- Claude Desktop / Cursor / Continue muestra 0 herramientas
- No aparece el icono 🔌 ni la entrada "synapse" en la lista de servidores MCP
Soluciones
1. Reinicie el cliente completamente — Cmd+Q en macOS (no solo cerrar la ventana)
2. Compruebe la ubicación del archivo de configuración:
- Claude Desktop macOS:
- Claude Desktop Windows:
- Cursor:
- Continue:
3. Valide el JSON — pegue la configuración en
4. Revise los logs del cliente para errores MCP:
- Claude Desktop: (macOS)
- Cursor: View → Output → MCP
5. Ejecute el servidor MCP manualmente para ver errores de arranque:
[CODE BLOCK]
Problema: error "Mind Key invalid"
Síntomas
- Las herramientas aparecen pero las llamadas fallan con "401 Unauthorized"
- Error: "Mind Key fehlt oder ungültig"
Soluciones
1. Verifique el formato del Mind Key — empieza por , 40 caracteres
2. Pruebe directamente:
[CODE BLOCK]
3. Compruebe que la variable de entorno está establecida — para transporte
stdio, la variable de entorno debe estar en la configuración del servidor
MCP, no en su shell
4. Obtenga un Mind Key nuevo:
[CODE BLOCK]
Problema: npx no encontrado
Síntomas
- Error: "npx: command not found"
- El servidor MCP no arranca
Soluciones
1. Instale Node.js 18+:
- macOS: o descargue desde
- Linux:
- Windows: descargue desde
2. Reinicie el terminal tras la instalación
3. Verifique:
Problema: SYNAPSEURL inalcanzable
Síntomas
- El servidor MCP arranca pero las llamadas a herramientas agotan el tiempo
- Error: "fetch failed" o "ECONNREFUSED"
Soluciones
1. Pruebe la conectividad:
[CODE BLOCK]
2. Compruebe el firewall corporativo — puede bloquear HTTPS saliente
3. Pruebe una URL alternativa:
- Producción:
- Servidor MCP:
4. Para autoalojamiento: asegúrese de que su instancia de Synapse está corriendo y accesible
Problema: el servidor MCP se cuelga
Síntomas
- El servidor MCP sale inmediatamente tras arrancar
- Los logs del cliente muestran "MCP server disconnected"
Soluciones
1. Ejecútelo manualmente para ver el error:
[CODE BLOCK]
2. Compruebe conflictos de puerto — el servidor MCP usa el puerto 13100 por defecto
3. Limpie la caché de npx:
[CODE BLOCK]
4. Actualice a la última versión:
[CODE BLOCK]
Problema: las llamadas a herramientas devuelven 429
Síntomas
- Error: "Rate limit exceeded"
Soluciones
Esto no debería ocurrir con MCP (usa auth por cabecera, sin límite de
frecuencia). Si ocurre:
1. Compruebe si está usando en algún sitio — cambie a auth por cabecera
2. Verifique — asegúrese de que apunta a la instancia correcta
3. Contacte con soporte si el problema persiste
Problema: las herramientas aparecen pero no funcionan
Síntomas
- Herramientas listadas en el cliente
- Llamar a una herramienta devuelve un error o ningún resultado
Soluciones
1. Compruebe el nombre de la herramienta — debe ser exacto (p. ej. , no )
2. Verifique los argumentos — compruebe el esquema de entrada de la herramienta
3. Pruebe vía API directa:
[CODE BLOCK]
4. Compruebe la salud de Synapse:
[CODE BLOCK]
Obtener ayuda
Si ninguna de las soluciones anteriores resuelve su problema:
1. Compruebe los issues existentes:
2. Abra un issue nuevo con:
- Versión del servidor MCP ()
- Nombre y versión del cliente
- Sistema operativo
- Extractos de logs relevantes
- Pasos para reproducir
Próximos pasos
- Configuración de Claude Desktop
- Configuración de Claude Code
- Errores de la API
────────────────────────────────────────────────────────────
# ¿Qué es MCP?
SUMMARY: Model Context Protocol permite a los LLMs llamar a herramientas externas. Synapse expone 79 herramientas vía 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
¿Qué es MCP?
El Model Context Protocol (MCP) es un estándar abierto de Anthropic (2024)
que permite a los LLMs llamar a herramientas externas de forma estructurada. En
lugar de pegar documentación de la API en el prompt, registra herramientas con
el servidor MCP, y el LLM las llama según sea necesario — como function
calling, pero estandarizado e independiente del cliente.
Servidor MCP de Synapse
Synapse distribuye un servidor MCP oficial ( en npm) que
expone 79 herramientas que cubren todas las características de Synapse:
| Categoría | Herramientas | Cantidad |
|----------|-------|-------|
| Memory | 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 |
| Scheduler | cronlist, croncreate, crondelete, crontoggle, varlist, varget, varset, vardelete | 8 |
| Tasks | tasklist, taskget, taskcreate, taskupdate | 4 |
| Scripts | scriptlist, scriptget, scriptinfo, scriptstore, scriptdelete | 5 |
| Computers | computerlist, computerget, installcode, screenshot, commandqueue, commandstatus, commandslist, disable, delete | 9 |
| Push | vapidpublickey, subscribe, unsubscribe, test | 4 |
| User/Mind | register, login, mindslist, mindcreate, minddelete | 5 |
| Utility | time, calc, random | 3 |
| Visualization | graph, tags, compact | 3 |
| Sharing | share, list, revoke | 3 |
| Webhooks | register, list, get, update, delete | 5 |
| Browser | new, navigate, click, type, screenshot, close | 6 |
| Total | | 79+ |
Cómo funciona
[CODE BLOCK]
1. Configura su cliente LLM (Claude Desktop, Cursor, etc.) para usar el servidor MCP de Synapse
2. El cliente arranca el servidor MCP (vía )
3. El servidor MCP se conecta a la API de Synapse usando su Mind Key
4. El LLM ve las 79 herramientas como funciones nativas que puede llamar
5. Cuando el LLM necesita recordar algo, llama a — el servidor MCP lo traduce a en Synapse
Transportes
El servidor MCP de Synapse admite tres transportes:
stdio (local, recomendado para escritorio)
[CODE BLOCK]
HTTP/SSE (remoto, multi-tenant)
Conecte su cliente MCP a:
[CODE BLOCK]
WebSocket (móvil, alto volumen)
[CODE BLOCK]
Tool Profiles (v1.4.0)
Para reducir el overhead de tokens en LLMs más pequeños, el servidor MCP admite
tres tool profiles:
| Profile | Herramientas | Tokens | Mejor para |
|---------|-------|--------|----------|
| | 8 (dispatch compuesto) | 500 | LLMs autoalojados con ≤8k de contexto |
| | 25 (con nombre) | 2,500 | LLMs medianos (Claude Haiku, GPT-3.5) |
| | 119 (todas) | 8,250 | LLMs grandes (Claude Sonnet/Opus, GPT-4) — predeterminado |
Controle mediante:
- Variable de entorno:
- Cabecera:
Clientes compatibles
- Claude Desktop — app de escritorio de Anthropic
- Claude Code — agente de codificación de terminal
- Cursor — IDE con IA
- Continue.dev — asistente de codificación con IA de código abierto
- Cline — extensión de VS Code
- Cualquier cliente compatible con MCP
¿Por qué usar MCP en lugar de la API directa?
| Enfoque | Pros | Contras |
|----------|------|------|
| API directa | Sencillo, sin capa extra | El LLM necesita conocer URLs, cabeceras, auth |
| MCP | El LLM ve herramientas nativas, sin memorizar URLs | Proceso de servidor MCP adicional |
Para la mayoría de casos de uso de agentes LLM, MCP es la mejor opción — el
LLM no necesita recordar rutas de API ni patrones de auth.
Próximos pasos
- Configuración de Claude Desktop — config en 2 minutos
- Configuración de Claude Code — integración con terminal
- Cliente MCP personalizado — construya el suyo
## CATEGORÍA: GUÍAS Y TUTORIALES
Guías paso a paso para escenarios concretos.
────────────────────────────────────────────────────────────
# Pruebas automatizadas de apps iOS
SUMMARY: Use Synapse + Computer Control API para automatizar pruebas de apps iOS vía Simulator.
Pruebas automatizadas de apps iOS
Combine el sistema de memoria de Synapse con la Computer Control API para
construir pruebas de apps iOS dirigidas por LLM. El LLM recuerda escenarios de
test, aprende de fallos pasados y se adapta a cambios de UI.
Arquitectura
[CODE BLOCK]
Requisitos previos
- Cuenta de Synapse + Mind Key
- Servidor MCP de Synapse configurado en Claude Desktop
- iOS Simulator con instalado
- Computadora registrada en Synapse (consulte API de Computer Control)
Paso 1: Registrar la computadora Simulator
En el Mac que ejecuta iOS Simulator:
[CODE BLOCK]
Paso 2: Almacenar escenarios de test en memoria
Almacene escenarios de test reutilizables como memorias:
[CODE BLOCK]
Paso 3: Ejecución de tests dirigida por LLM
En Claude Desktop (con Synapse MCP configurado):
[CODE BLOCK]
Claude hará:
1. Llamar a para encontrar la memoria
2. Llamar a para ver el estado actual
3. Ejecutar cada paso vía (clic, escribir)
4. Verificar resultados vía capturas de pantalla
5. Almacenar cualquier fallo como memorias
Paso 4: Tests autoreparables
Cuando un test falla, almacene el fallo y la recuperación:
[CODE BLOCK]
La próxima vez que el LLM ejecute el test, recupera el fallo y aplica la
recuperación automáticamente.
Paso 5: Seguimiento de resultados de test
Haga seguimiento de las ejecuciones de test como tareas:
[CODE BLOCK]
Comandos comunes
| Acción | Comando |
|--------|---------|
| Lanzar Simulator | |
| Captura de pantalla | (vía Synapse MCP) |
| Tap en (x,y) | |
| Escribir texto | |
| Pulsar Home | |
Mejores prácticas
> [!TIP]
> - Almacene coordenadas de UI como memorias — la UI cambia, pero el LLM puede reaprender
> - Use etiquetas de accesibilidad — más estables que las coordenadas
> - Almacene datos de test por separado — use variables para usuarios y contraseñas
> - Ejecute tests en estado limpio — resetee el Simulator entre ejecuciones
> - Guarde capturas de los fallos — útil para depurar
Próximos pasos
- Tests autoreparables
- API de Computer Control
- Mejores prácticas de memoria
────────────────────────────────────────────────────────────
# Backup y restauración
SUMMARY: Exporte sus memorias para backup, migre entre minds, restaure tras pérdida de datos.
Backup y restauración
Synapse proporciona exportación/importación completa para backup de memoria,
migración y recuperación ante desastres. Esta guía cubre las operaciones
esenciales.
Exportación
Exportación completa del mind
Exporte todas las memorias de un mind como JSON:
[CODE BLOCK]
Formato de respuesta:
[CODE BLOCK]
Exportación incremental (diff)
Exporte solo las memorias cambiadas desde un timestamp:
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
Backups automatizados
Programe backups diarios vía cron:
[CODE BLOCK]
> [!NOTE]
> El endpoint de cron recibe la respuesta pero no la almacena. Para backups
> reales, apunte el cron a su propio servidor de backup que guarde la
> respuesta.
Mejor: script de backup externo
[CODE BLOCK]
Añada a crontab:
[CODE BLOCK]
Restauración
Restaurar al mismo mind
[CODE BLOCK]
Restaurar a un nuevo mind
[CODE BLOCK]
Script de restauración en Python
[CODE BLOCK]
Migración entre minds
[CODE BLOCK]
Backup de otros datos
No olvide hacer backup de:
| Tipo de dato | Endpoint |
|-----------|----------|
| Memorias | |
| Tareas | |
| Scripts | |
| Webhooks | |
| Trabajos cron | |
| Variables | |
| Historial de chat | |
Verificación
Tras restaurar, verifique:
[CODE BLOCK]
Mejores prácticas
> [!TIP]
> - Haga backup a diario — automatice con cron
> - Pruebe restauraciones — un backup que no puede restaurar no sirve
> - Conserve múltiples versiones — al menos 30 días
> - Almacene externamente — S3, Backblaze B2, etc.
> - Cifre los backups sensibles — las memorias pueden contener PII
> - Documente el proceso de restauración — lo olvidará para cuando lo necesite
Próximos pasos
- API de Memory
- Cron y Scheduler — para backups automatizados
────────────────────────────────────────────────────────────
# Mejores prácticas de memoria
SUMMARY: Cómo estructurar memorias para un recall efectivo — categorías, claves, etiquetas, prioridades.
Mejores prácticas de memoria
La forma en que estructure las memorias determina cuán útiles son. Esta guía
cubre patrones para categorizar, etiquetar y priorizar memorias para que el LLM
pueda recuperar la información correcta en el momento adecuado.
Categorías: elija la más específica
| Categoría | Usar para | Ejemplo |
|----------|---------|---------|
| | Nombre, rol, info de contacto | |
| | Gustos, disgustos, estilo de trabajo | |
| | Hechos verificables | |
| | Estado del proyecto, decisiones | |
| | Habilidades del usuario | |
| | Errores pasados a evitar | |
| | Contexto relevante para la sesión | |
| | Notas varias | |
> [!TIP]
> En caso de duda, use para información verificable y para todo
> lo demás. No sobrecategorice — mejor un claro que un
> confuso.
Claves: identificadores significativos
El campo es el identificador de la memoria. Use claves significativas y
estables:
Buenas claves:
-
-
-
-
Malas claves:
- (no significativa)
- (no descriptiva)
- (la fecha no ayuda al recall)
Convenciones de nomenclatura de claves
- (minúsculas con guiones bajos)
- Prefije con la categoría: , ,
- Use sustantivos descriptivos, no verbos
- Mantenga por debajo de 50 caracteres
Etiquetas: para búsqueda y filtrado
Las etiquetas permiten filtrado y búsqueda rápida. Añada 2-5 etiquetas por
memoria:
[CODE BLOCK]
Patrones de etiquetado
- Nombres de proyecto: , ,
- Temas: , , ,
- Estado: , ,
- Indicadores de prioridad: ,
> [!NOTE]
> Las etiquetas son insensibles a mayúsculas/minúsculas. Use minúsculas para
> consistencia.
Prioridades: sea realista
| Prioridad | Usar para | % de memorias |
|----------|---------|---------------|
| | Identidad del usuario, info legal, decisiones irreversibles | 5% |
| | Proyectos activos, preferencias importantes | 20% |
| | La mayoría de hechos, notas, contexto | 65% |
| | Efímera, bueno saberlo | 10% |
> [!WARNING]
> No marque todo como . Si todo es crítico, nada lo es. Reserve
> para cosas que causarían un daño real si se olvidan.
Cuándo almacenar y cuándo no
Almacene siempre
- Identidad del usuario (nombre, email, rol)
- Preferencias a largo plazo
- Decisiones del proyecto y su justificación
- Errores pasados y lecciones aprendidas
- Compromisos adquiridos con el usuario
No almacene
- Estado transitorio (use variables en su lugar)
- Historial de conversación literal (lo gestiona el sistema de chat)
- Datos sensibles (contraseñas, API keys)
- Hechos fácilmente derivables (fecha actual, contenidos de archivos)
- Contexto efímero (use la categoría con prioridad baja)
Actualizar memorias
POST con la misma + actualiza la memoria existente:
[CODE BLOCK]
> [!TIP]
> Use claves estables para poder actualizar sin crear duplicados. El LLM debe
> volver a hacer POST con la misma clave a medida que la información cambia, no
> crear nuevas memorias.
Ciclo de vida de la memoria
[CODE BLOCK]
- Create: POST /memory con contexto completo
- Active: Recall frecuente, actualizar según sea necesario
- Stale: Aún relevante pero no usado activamente (¿bajar prioridad?)
- Archive: Establecer prioridad a , conservar como referencia histórica
- Delete: DELETE /memory/:id cuando ya no sea relevante
Limpieza periódica
[CODE BLOCK]
Patrón: herencia de memoria
Para contexto jerárquico (proyecto → subproyecto → tarea):
[CODE BLOCK]
El LLM puede entonces buscar para encontrar todas las memorias
relacionadas.
Patrón: log de decisiones
Almacene decisiones con su justificación para que el LLM no las vuelva a
cuestionar:
[CODE BLOCK]
Patrón: evitar errores
Almacene errores con instrucciones específicas de prevención:
[CODE BLOCK]
Antipatrones a evitar
> [!WARNING]
> - Almacenar logs de conversación — lo gestiona el sistema de chat
> - Almacenar archivos completos — use script store o almacenamiento externo
> - Almacenar estado efímero — use variables
> - Almacenar secretos — use variables de entorno
> - Duplicar memorias — use claves estables
> - Sobreetiquetar — 2-5 etiquetas por memoria es lo ideal
> - Todo es crítico — sea realista con las prioridades
Próximos pasos
- API de Memory
- Agente LLM persistente
- Estrategia de etiquetado de memoria
────────────────────────────────────────────────────────────
# Coordinación multi-agente
SUMMARY: Coordine múltiples agentes LLM usando minds, tareas y chat compartidos de Synapse.
Coordinación multi-agente
Cuando tiene múltiples agentes LLM trabajando en tareas relacionadas, Synapse
proporciona la capa de coordinación — memoria compartida, asignación de tareas
y chat asíncrono.
Patrones
Patrón 1: Mind compartido (fuente única de verdad)
Todos los agentes comparten un Mind Key. Leen y escriben en el mismo almacén
de memoria.
[CODE BLOCK]
Caso de uso: equipo pequeño de agentes trabajando en un proyecto.
Configuración:
[CODE BLOCK]
Coordinación vía tareas:
[CODE BLOCK]
Patrón 2: Minds especializados (contextos aislados)
Cada agente tiene su propio mind. Se comunican vía un mind de "coordinación"
compartido.
[CODE BLOCK]
Caso de uso: agentes con diferentes especialidades (codificación, revisión,
despliegue).
Configuración:
[CODE BLOCK]
Coordinación vía mind compartido:
[CODE BLOCK]
Patrón 3: Hub-and-Spoke (orquestador)
Un agente orquestador central asigna tareas a agentes trabajadores.
[CODE BLOCK]
Caso de uso: flujos de trabajo complejos con trabajo en paralelo.
Implementación:
[CODE BLOCK]
Coordinación vía chat
Los agentes pueden comunicarse vía el sistema de chat:
[CODE BLOCK]
> [!NOTE]
> Los mensajes de chat tienen etiqueta de rol. Establezca role=agent para
> mensajes entre agentes, role=human para humano-a-agente.
Coordinación vía variables
Use variables para coordinación ligera (locks, flags):
[CODE BLOCK]
Mejores prácticas
> [!TIP]
> - Use minds separados para preocupaciones separadas — no mezcle memoria de coder y reviewer
> - Etiquete a los agentes en el chat — para un direccionamiento claro
> - Use tareas para la asignación de trabajo — no chat (chat es para discusión)
> - Implemente idempotencia — los agentes pueden reintentar operaciones fallidas
> - Registre todo — almacene decisiones en memoria para auditabilidad
Próximos pasos
- Agente LLM persistente
- LLM Cookbook
- Automatización con webhooks
────────────────────────────────────────────────────────────
# Construir un agente LLM persistente
SUMMARY: Guía paso a paso para construir un agente LLM que recuerda entre sesiones usando Synapse.
Resumen
Esta guía le lleva a construir un agente LLM que persiste contexto entre
sesiones usando Synapse. Al final, su agente podrá:
- Recuperar contexto pasado al inicio de la sesión
- Almacenar nuevos aprendizajes a medida que ocurren
- Hacer seguimiento de tareas multi-paso entre sesiones
- Comunicarse con humanos vía chat asíncrono
Arquitectura
[CODE BLOCK]
Paso 1: Configurar el Mind Key
[CODE BLOCK]
Paso 2: Protocolo de inicio de sesión
Al inicio de cada sesión, recupere todas las memorias:
[CODE BLOCK]
Paso 3: Almacenar nuevos aprendizajes
Siempre que el agente aprenda algo que valga la pena recordar:
[CODE BLOCK]
Paso 4: Gestión de tareas
Haga seguimiento de trabajo multi-paso entre sesiones:
[CODE BLOCK]
Paso 5: Chat asíncrono con humanos
Haga poll de mensajes entre llamadas a herramientas:
[CODE BLOCK]
Paso 6: Protocolo de fin de sesión
Al final de la sesión, almacene el contexto final:
[CODE BLOCK]
Patrón completo
[CODE BLOCK]
Mejores prácticas
> [!TIP]
>
> - Recupere siempre primero — nunca empiece a trabajar sin cargar el contexto
> - Almacene de forma proactiva — no espere al final de la sesión
> - Use claves significativas — , , no
> - Etiquete todo — las etiquetas potencian búsqueda y filtrado
> - Establezca prioridades realistas — no todo es
Próximos pasos
- LLM Cookbook — patrones prácticos
- Mejores prácticas de memoria
- Coordinación multi-agente
────────────────────────────────────────────────────────────
# Pipelines de tests autoreparables
SUMMARY: Construya pipelines de tests que aprenden de los fallos y se adaptan automáticamente usando la memoria de Synapse.
Pipelines de tests autoreparables
Las suites de tests tradicionales se rompen cuando cambia la UI. Los tests
autoreparables usan la memoria de Synapse para aprender de fallos pasados y
adaptarse — reduciendo tests inestables y la carga de mantenimiento.
Concepto
[CODE BLOCK]
1. El test se ejecuta
2. Si falla, almacena el fallo (qué salió mal, por qué, cómo arreglarlo)
3. Próxima ejecución: recupera los fallos relevantes antes de ejecutar
4. Aplica las correcciones conocidas automáticamente
Implementación
Paso 1: Wrapper de test
Envuelva cada test con recall/store de memoria:
[CODE BLOCK]
Paso 2: Lógica de test adaptativa
Dentro del test, compruebe si hay fallos conocidos y aplique correcciones:
[CODE BLOCK]
Paso 3: Estrategias de recuperación
Almacene estrategias de recuperación como memorias:
[CODE BLOCK]
Paso 4: Integración con CI
[CODE BLOCK]
Paso 5: Dashboard de análisis de fallos
[CODE BLOCK]
Mejores prácticas
> [!TIP]
> - Almacene tracebacks — contienen la línea exacta que falló
> - Etiquete por nombre de test — habilita filtrado rápido
> - Use la categoría — separa de las memorias regulares
> - Establezca prioridad — los fallos nunca deben olvidarse
> - Limpieza periódica — elimine memorias de problemas resueltos
> - No almacene datos sensibles — credenciales, PII
Patrones de fallo comunes a almacenar
| Tipo de fallo | Qué almacenar |
|--------------|---------------|
| Elemento no encontrado | Selector probado, estado de la página, captura |
| Timeout | Tiempo de espera, qué se estaba esperando |
| Aserción fallida | Valor esperado vs actual |
| Error de red | URL, código de estado, cuerpo de la respuesta |
| Permiso denegado | Permiso requerido, rol del usuario actual |
Próximos pasos
- Pruebas automatizadas en iOS
- Mejores prácticas de memoria
- Cookbook de recuperación de errores
────────────────────────────────────────────────────────────
# Automatización con webhooks
SUMMARY: Dispare sistemas externos cuando cambian las memorias — sincronice, notifique, automatice.
Automatización con webhooks
Los webhooks le permiten disparar sistemas externos cuando ocurren eventos en
Synapse. Esta guía cubre patrones comunes de automatización.
Patrones comunes
Patrón 1: Notificar ante memoria crítica
Envíe un mensaje de Slack cuando se almacena una memoria crítica:
[CODE BLOCK]
Registre el webhook:
[CODE BLOCK]
Patrón 2: Sincronizar con sistema externo
Sincronice memorias con Notion, Obsidian o cualquier KB externo:
[CODE BLOCK]
Patrón 3: Disparar CI/CD
Dispare un despliegue cuando se almacena una memoria "release":
[CODE BLOCK]
Patrón 4: Despertar al agente ante un mensaje humano
Dispare una ejecución del agente LLM cuando un humano envía un mensaje de chat:
[CODE BLOCK]
Patrón 5: Agregar métricas
Haga seguimiento del crecimiento de memoria, actividad de chat, finalización de
tareas:
[CODE BLOCK]
Verificación de firma
Verifique siempre las firmas de webhook para prevenir suplantación:
[CODE BLOCK]
Lógica de reintento
Synapse reintenta los webhooks fallidos con backoff exponencial. Su handler
debería:
1. Devolver 200 rápidamente — no haga trabajo pesado de forma síncrona
2. Encolar trabajo — use un sistema de jobs en segundo plano
3. Ser idempotente — el mismo evento puede entregarse dos veces
[CODE BLOCK]
Depuración de webhooks
Comprobar historial de entregas
Las entregas de webhook se registran. Compruebe las entregas recientes de su
webhook:
[CODE BLOCK]
Probar el webhook manualmente
[CODE BLOCK]
Problemas comunes
| Problema | Solución |
|-------|-----|
| Respuestas 4xx | Compruebe que su handler devuelve 200 |
| Respuestas 5xx | Error del servidor — revise los logs de su app |
| Timeout | Devuelva 200 rápido, encole trabajo asíncrono |
| Entregas duplicadas | Haga el handler idempotente |
| Fallo de firma | Verifique que el secreto es correcto |
Mejores prácticas
> [!TIP]
> - Verifique siempre las firmas — nunca omita esto
> - Devuelva 200 rápido — no bloquee a Synapse
> - Sea idempotente — maneje entregas duplicadas
> - Use eventos específicos — no
> - Monitoree fallos de entrega — configure alertas
Próximos pasos
- API de Webhooks
- Cron y Scheduler
- Agente LLM persistente
## CATEGORÍA: CONCEPTOS
Arquitectura y conceptos detrás de Synapse.
────────────────────────────────────────────────────────────
# Arquitectura de Synapse
SUMMARY: Cómo está construido Synapse — Fastify, PostgreSQL, FTS5, embeddings, servidor MCP.
Arquitectura de Synapse
Synapse es una API de memoria multi-tenant construida sobre Fastify, PostgreSQL
con FTS5, y un servicio opcional de embeddings para búsqueda semántica.
Arquitectura de alto nivel
[CODE BLOCK]
Componentes principales
1. Synapse API (Fastify)
El servidor HTTP principal. Gestiona:
- Endpoints REST (, , , etc.)
- Autenticación (Mind Key para agentes, JWT para humanos)
- Límites de frecuencia (solo auth con )
- Servido de archivos estáticos (interfaz web en , , etc.)
- Dispatch de webhooks
Construido con Fastify 5 para rendimiento. Se ejecuta en el puerto 12800 en
producción.
2. PostgreSQL con FTS5
El almacén de datos principal. Usa PostgreSQL con la extensión FTS5 para
búsqueda de texto completo.
Tablas principales:
| Tabla | Propósito |
|-------|---------|
| | Cuentas de usuario |
| | Ámbitos de mind (cada uno tiene un Mind Key) |
| | Registros de memoria con tabla virtual FTS5 |
| | Gestión de tareas |
| | Historial de chat |
| | Scripts persistentes |
| | Registros de webhooks |
| | Tareas programadas |
| | Almacén clave-valor |
| | Pista de auditoría |
FTS5 permite búsqueda de texto completo sub-milisegundo sobre todo el
contenido de memoria. Consulte Búsqueda FTS5 para
más detalles.
3. Servicio de Embeddings (opcional)
Para búsqueda semántica, Synapse genera embeddings vectoriales del contenido de
memoria. Se almacenan junto a las memorias y se usan para búsqueda por similitud.
- Proveedor: configurable (OpenAI, modelo local, etc.)
- Se almacenan como columna en la tabla
- Los usa el endpoint
- Consulte Búsqueda semántica
4. Servidor MCP (servicio separado)
El servidor MCP de Synapse se ejecuta como un proceso aparte (puerto 13100).
Esta persona:
- Expone 79 herramientas vía Model Context Protocol
- Admite transportes stdio, HTTP/SSE y WebSocket
- Traduce llamadas a herramientas MCP en llamadas a la API de Synapse
- Multi-tenant: un Mind Key por sesión
5. Browser Proxy (servicio separado)
Para automatización de navegador, un servicio separado basado en Playwright se
ejecuta en el puerto 13000. El servidor MCP puede invocarlo para las
herramientas .
6. SSH Proxy (servicio separado)
Para comandos remotos basados en SSH, un servicio separado se ejecuta en el
puerto 12900.
Modelo multi-tenant
[CODE BLOCK]
Cada mind está completamente aislado. Los Mind Keys otorgan acceso a
exactamente un mind. Los JWT otorgan acceso a la cuenta de usuario (para
gestionar minds).
Consulte Multi-Tenancy para más detalles.
Flujo de solicitudes
Solicitud de almacenamiento de memoria
[CODE BLOCK]
Solicitud de búsqueda de memoria
[CODE BLOCK]
Despliegue
Synapse se despliega como un contenedor Docker. Consulte :
[CODE BLOCK]
Características de rendimiento
| Operación | Latencia | Throughput |
|-----------|---------|------------|
| Memory store | 5ms | 1000+ req/s |
| Memory recall | 20ms | 500 req/s |
| FTS5 search | 10ms | 800 req/s |
| Semantic search | 50ms | 200 req/s |
| Chat poll | 5ms | 2000 req/s |
Próximos pasos
- Modelo de memoria
- Multi-Tenancy
- Búsqueda FTS5
────────────────────────────────────────────────────────────
# Búsqueda de texto completo FTS5
SUMMARY: Cómo Synapse usa SQLite FTS5 para búsqueda de texto completo de memoria sub-milisegundo.
Búsqueda de texto completo FTS5
Synapse usa FTS5 (Full-Text Search 5) para búsqueda de memoria rápida y
flexible. Esta página explica cómo funciona y cómo usarlo eficazmente.
¿Qué es FTS5?
FTS5 es una extensión de SQLite (también disponible en PostgreSQL vía
extensiones) que proporciona capacidades de búsqueda de texto completo. Esta
persona:
- Indexa contenido de texto para búsqueda rápida por palabra clave
- Admite operadores booleanos (AND, OR, NOT)
- Admite coincidencia de frases con comillas
- Admite coincidencia por prefijo con
- Ordena resultados por relevancia
Synapse usa FTS5 para indexar todo el contenido de memoria, lo que habilita
búsqueda sub-milisegundo entre miles de memorias.
Cómo Synapse usa FTS5
Cuando hace :
1. El contenido de la memoria se almacena en la tabla
2. El contenido también se inserta en la tabla virtual FTS5
3. FTS5 tokeniza e indexa el contenido automáticamente
Cuando hace :
1. Synapse parsea la consulta usando la sintaxis FTS5
2. Ejecuta un contra el índice FTS5
3. Filtra por (aislamiento de tenant)
4. Devuelve resultados ordenados por relevancia
Sintaxis de consulta
Búsqueda simple por palabra clave
[CODE BLOCK]
Devuelve memorias que contienen "docker".
Múltiples palabras clave (AND implícito)
[CODE BLOCK]
Devuelve memorias que contienen BOTH "docker" AND "swarm".
Coincidencia de frase
[CODE BLOCK]
Devuelve memorias que contienen la frase exacta "docker swarm".
Coincidencia por prefijo
[CODE BLOCK]
Devuelve memorias que contienen palabras que comienzan por "docker" (p. ej.
"dockers", "dockerfile", "dockerize").
OR booleano
[CODE BLOCK]
Devuelve memorias que contienen "docker" OR "kubernetes".
NOT booleano
[CODE BLOCK]
Devuelve memorias que contienen "docker" pero NOT "swarm".
Agrupamiento
[CODE BLOCK]
Devuelve memorias que contienen "docker" o "kubernetes", pero no "test".
Ejemplos prácticos
Buscar memorias sobre un proyecto
[CODE BLOCK]
Buscar frase exacta
[CODE BLOCK]
Excluir memorias de test
[CODE BLOCK]
Buscar por tecnología
[CODE BLOCK]
Ranking
FTS5 ordena los resultados por relevancia usando el algoritmo BM25. Factores:
- Frecuencia del término (con qué frecuencia aparece)
- Frecuencia inversa de documento (términos más raros obtienen mayor ranking)
- Longitud del documento (documentos más cortos con el término suben)
- Peso de columna (title > content)
Los resultados se devuelven en orden de ranking (más relevantes primero).
Rendimiento
| Operación | Latencia |
|-----------|---------|
| Search 100 memories | < 5ms |
| Search 1,000 memories | < 10ms |
| Search 10,000 memories | < 25ms |
| Search 100,000 memories | < 100ms |
FTS5 está altamente optimizado para cargas de trabajo con muchas lecturas.
Limitaciones
Stemming
FTS5 no hace stemming por defecto. "running" y "run" son términos diferentes.
Workaround: Use coincidencia por prefijo:
Tolerancia a erratas
FTS5 no admite coincidencia difusa. Una errata no devolverá resultados.
Workaround: Use búsqueda semántica () para
coincidencia conceptual.
Stop words
Las palabras comunes (the, a, an, is) se indexan pero pueden no ser útiles para
la búsqueda. FTS5 lo gestiona automáticamente.
FTS5 vs Búsqueda semántica
| Aspecto | FTS5 | Búsqueda semántica |
|--------|------|-----------------|
| Velocidad | Sub-milisegundo | 50-100ms |
| Coincidencia | Palabras clave exactas | Conceptual |
| Tolerancia a erratas | Ninguna | Alguna |
| Stemming | Ninguno | Implícito |
| Requiere embeddings | No | Sí |
| Mejor para | Términos específicos | Conceptos |
Use FTS5 cuando conozca las palabras clave. Use búsqueda semántica cuando quiera
"memorias sobre X" donde X se describe de forma diferente.
Mejores prácticas
> [!TIP]
> - Use términos específicos — "docker swarm" vence a "container orchestration"
> - Encadene frases entre comillas — garantiza coincidencia de frase
> - Use prefijo para variaciones — captura "deploy", "deployment", "deploying"
> - Excluya ruido — filtra memorias de test
> - Combine con etiquetas — acota resultados
Próximos pasos
- Búsqueda semántica
- API de Memory
- Mejores prácticas de memoria
────────────────────────────────────────────────────────────
# El modelo de memoria
SUMMARY: Cómo se estructuran las memorias — categorías, claves, etiquetas, prioridades, fuentes, verificación.
El modelo de memoria
El modelo de memoria de Synapse está diseñado para agentes LLM — lo
suficientemente estructurado para recall fiable, lo suficientemente flexible
para cualquier dominio.
Anatomía de una memoria
[CODE BLOCK]
Campos
| Campo | Tipo | Obligatorio | Descripción |
|-------|------|----------|-------------|
| | string | auto | ID único (memxxx) |
| | enum | ✅ | Una de 8 categorías |
| | string | ✅ | Identificador estable (usado para actualizaciones) |
| | string | ✅ | El contenido de la memoria (cualquier texto) |
| | string[] | – | Para búsqueda y filtrado |
| | enum | – | low, normal, high, critical (predeterminado: normal) |
| | enum | auto | user, agent (quién la almacenó) |
| | bool | auto | ¿La ha verificado un humano? |
| | float | – | 0.0 a 1.0 (predeterminado: 1.0 para user, 0.7 para agent) |
| | timestamp | – | Cuándo olvidar esta memoria |
| | string | auto | A qué mind pertenece |
| | timestamp | auto | Primera vez almacenada |
| | timestamp | auto | Última modificación |
Categorías
Ocho categorías cubren los casos de uso comunes de agentes LLM:
| Categoría | Propósito | Contenido de ejemplo |
|----------|---------|-----------------|
| | Quién es el usuario | "User is Michael Schäfer, software engineer in Berlin" |
| | Preferencias del usuario | "Prefers concise technical responses" |
| | Hechos verificables | "Office is in Berlin, timezone Europe/Berlin" |
| | Estado del proyecto | "Synapse v1.5.0 deployed, working on v1.6.0 docs" |
| | Habilidades del usuario | "Advanced Python, 10+ years" |
| | Errores pasados | "Forgot to bump npm version — CI failed" |
| | Contexto de sesión | "Currently reviewing PR #42" |
| | Notas varias | "Try Redis for caching next sprint" |
Claves: identificadores estables
El campo es crítico — es la forma de actualizar memorias sin crear
duplicados.
[CODE BLOCK]
Reglas de key:
- Debe ser única dentro de (categoría, mind)
- Use
- Prefije con la categoría para claridad: ,
- Manténgala estable — no cambie las keys tras la creación
Etiquetas: para búsqueda
Las etiquetas permiten filtrado y búsqueda rápida:
[CODE BLOCK]
Mejores prácticas de etiquetado:
- 2-5 etiquetas por memoria (no etiquete en exceso)
- Minúsculas para consistencia
- Use nombres de proyecto, temas, tecnologías
- Las etiquetas son insensibles a mayúsculas/minúsculas
Niveles de prioridad
| Prioridad | Cuándo usarla | Comportamiento de recall |
|----------|-------------|-----------------|
| | Identidad, legal, irreversible | Siempre al inicio del recall |
| | Proyectos activos, preferencias clave | Destacada en el recall |
| | La mayoría de memorias (predeterminado) | Orden de recall estándar |
| | Efímera, bueno saberlo | Puede resumirse |
ordena por prioridad (critical primero), luego por recencia.
Origen: usuario vs agente
Las memorias se etiquetan con :
- — almacenada por un humano (vía JWT o interfaz humana)
- — almacenada por un agente LLM (vía Mind Key)
Esto afecta:
- Verificación: las memorias se auto-verifican, las no
- Confianza: por defecto a 1.0, a 0.7
- Recall: marca las memorias no verificadas con "(unverified)"
> [!NOTE]
> Trate las memorias con origen con el escepticismo apropiado. Pueden
> estar inferidas o asumidas en lugar de haber sido declaradas directamente por
> el usuario.
Verificación
El flag indica que un humano ha confirmado la memoria:
- memorias : auto-verificadas ()
- memorias : por defecto no verificadas ()
Verifique memorias vía:
[CODE BLOCK]
> [!NOTE]
> La verificación requiere JWT (auth humana), no Mind Key (auth de agente).
> Esto garantiza que solo los humanos puedan marcar memorias como verificadas.
Confianza
El campo (0.0 a 1.0) indica cuán fiable es la memoria:
- 1.0 — declarada directamente por el usuario
- 0.7 — inferida por el agente
- 0.5 — incierta, necesita verificación
- 0.0 — explícitamente dudosa
Establezca la confianza al almacenar:
[CODE BLOCK]
Expiración
Establezca para memorias sensibles al tiempo:
[CODE BLOCK]
Las memorias expiradas no se devuelven en (pero siguen
existentes en la BD). Use para ver memorias que
expiran pronto.
Ciclo de vida de una memoria
[CODE BLOCK]
Comportamiento de recall
devuelve un resumen en texto plano optimizado para el
contexto del LLM:
[CODE BLOCK]
- Ordenado por prioridad (critical → low), luego por recencia
- Las memorias no verificadas se marcan con
- Etiquetas incluidas para contexto
- Texto plano (no se necesita parsing JSON)
Próximos pasos
- API de Memory
- Mejores prácticas de memoria
- Búsqueda FTS5
────────────────────────────────────────────────────────────
# Multi-Tenancy y aislamiento
SUMMARY: Cómo Synapse aísla los datos entre usuarios y minds — explicación de los límites de seguridad.
Multi-Tenancy y aislamiento
Synapse es multi-tenant: múltiples usuarios, cada uno con múltiples minds,
completamente aislados entre sí. Esta página explica el modelo de aislamiento.
Jerarquía de tenants
[CODE BLOCK]
Niveles de aislamiento
Nivel 1: Aislamiento de usuario
Cada cuenta de usuario está aislada. Alice no puede:
- Ver los minds de Bob
- Acceder a las memorias de Bob (incluso con su JWT)
- Listar la información de la cuenta de Bob
Aplicado por: columna en todas las tablas, el JWT contiene ,
todas las consultas filtran por .
Nivel 2: Aislamiento de mind
Dentro de un usuario, cada mind está aislado. Mind A no puede:
- Ver las memorias de Mind B
- Acceder a tareas, chat, scripts de Mind B
Aplicado por: columna en todas las tablas de datos, el Mind Key
contiene , todas las consultas filtran por .
> [!CRITICAL]
> El aislamiento por Mind Key es el límite de seguridad principal. Un Mind Key
> filtrado otorga acceso completo a los datos de ese mind — pero SOLO a ese
> mind.
Tokens de autenticación
| Token | Ámbito | A qué puede acceder |
|-------|-------|-------------------|
| Mind Key | Un solo mind | Solo los datos de ese mind |
| JWT | Cuenta de usuario | Gestión de cuenta (crear/listar/eliminar minds) |
| Computer Token | Una sola computadora | Los comandos de esa computadora |
Acceso entre minds
Dentro del mismo usuario
El usuario puede acceder a todos sus minds vía JWT (p. ej. los
lista todos). Pero para leer/escribir datos de memoria, necesita el Mind Key
específico.
Entre usuarios
Los usuarios no pueden acceder a los datos de los demás — A MENOS que
compartan explícitamente un mind vía la API de Sharing:
[CODE BLOCK]
Tras compartirlo, Bob puede acceder a Mind A vía su JWT (solo lectura si
).
Límites de seguridad
[CODE BLOCK]
Patrones comunes de multi-tenancy
Patrón 1: Un usuario, un mind
El más común para usuarios individuales de agentes LLM.
- 1 cuenta de usuario
- 1 mind
- 1 Mind Key
- Todas las memorias en un ámbito
Patrón 2: Un usuario, múltiples minds
Para usuarios con múltiples contextos (trabajo, personal, proyectos).
- 1 cuenta de usuario
- N minds (p. ej. "trabajo", "personal", "proyecto-x")
- N Mind Keys
- Cada sesión LLM usa un Mind Key
Patrón 3: Mind compartido en equipo
Para equipos que colaboran en un proyecto.
- 1 usuario crea el mind (obtiene el Mind Key)
- El creador lo comparte con los miembros del equipo vía JWT
- Todos los miembros acceden vía JWT (o Mind Key compartido)
> [!WARNING]
> Compartir un Mind Key otorga acceso completo de lectura/escritura. Para
> colaboración en equipo, prefiera la API de Sharing (basada en JWT) sobre
> compartir Mind Keys directamente.
Patrón 4: Proveedor SaaS
Para aplicaciones que integran Synapse como su capa de memoria.
- Cada cliente = 1 cuenta de usuario
- Cada proyecto de cliente = 1 mind
- La app almacena los Mind Keys por cliente/proyecto
- Aislamiento completo entre clientes
Verificación de aislamiento
Test: Un Mind Key no puede acceder a otros minds
[CODE BLOCK]
Test: Un JWT no puede leer datos de memoria directamente
[CODE BLOCK]
Mejores prácticas
> [!TIP]
> - Use un mind por proyecto/contexto — el aislamiento es su aliado
> - Nunca comparta Mind Keys — use la API de Sharing en su lugar
> - Rote los Mind Keys si se comprometen (elimine el mind, cree uno nuevo)
> - Audite los minds compartidos — revise periódicamente
> - Use JWT para la interfaz humana — nunca exponga Mind Keys a usuarios finales
Próximos pasos
- Autenticación
- Mind Key vs JWT
- Arquitectura
────────────────────────────────────────────────────────────
# Búsqueda semántica (embeddings)
SUMMARY: Búsqueda conceptual de memoria usando embeddings vectoriales — encuentre por significado, no solo por palabras clave.
Búsqueda semántica (embeddings)
Synapse admite búsqueda semántica usando embeddings vectoriales. A diferencia
de FTS5 (coincidencia por palabra clave), la búsqueda semántica encuentra
memorias por significado — incluso si no coincide ninguna palabra clave.
Cómo funciona
[CODE BLOCK]
¿Qué son los embeddings?
Los embeddings son representaciones vectoriales numéricas del texto. El texto
con significado similar tiene vectores similares. Synapse genera un vector (p.
ej. 1536 dimensiones) por el contenido de cada memoria.
Similitud coseno
Para encontrar memorias semánticamente similares, Synapse calcula la similitud
coseno entre el vector de la consulta y cada vector de memoria. Mayor similitud
= más relevante.
Cuándo usar búsqueda semántica
Use búsqueda semántica cuando:
- Quiere "memorias sobre X" donde X se describe de forma diferente a como está
almacenado
- FTS5 no devuelve resultados (sin coincidencia de palabra clave)
- Quiere agrupación conceptual (p. ej. todas las memorias de "deployment",
incluso si algunas dicen "release")
- La consulta es una pregunta: "¿cómo gestionamos la autenticación?"
Use FTS5 cuando:
- Conoce palabras clave exactas
- Necesita lógica booleana (AND, OR, NOT)
- Necesita respuesta sub-milisegundo
- Quiere coincidencia de frase
Endpoint
GET /memory/semantic-search
[CODE BLOCK]
Respuesta:
[CODE BLOCK]
Ejemplos
Buscar memorias de despliegue
[CODE BLOCK]
Devuelve memorias sobre "deployment", "release", "publishing", "rolling out",
etc.
Buscar patrones de autenticación
[CODE BLOCK]
Devuelve memorias sobre login, auth, JWT, gestión de sesiones, OAuth, etc.
Buscar memorias similares
[CODE BLOCK]
Usa similitud semántica (vía etiquetas compartidas Y vectores de embedding).
Generación de embeddings
¿Cuándo se generan los embeddings?
- Al almacenar memoria — si el servicio de embeddings está configurado, el
embedding se genera de forma síncrona
- Generación en lote — genera embeddings para
memorias que no los tienen
- Actualizaciones asíncronas — cuando se actualiza el contenido, el
embedding se regenera
Proveedores de embeddings
Synapse admite proveedores de embeddings configurables:
- OpenAI (, )
- Modelos locales (vía Ollama o similar)
- Personalizado (implementar la interfaz de embeddings)
Configúrelos mediante variables de entorno:
[CODE BLOCK]
Generación en lote
Para minds con muchas memorias sin embeddings:
[CODE BLOCK]
Rendimiento
| Operación | Latencia |
|-----------|---------|
| Generate embedding (OpenAI) | 100-200ms |
| Semantic search (1k memories) | 50-100ms |
| Semantic search (10k memories) | 200-500ms |
| Batch generation (100 memories) | 10-20s |
> [!NOTE]
> La búsqueda semántica es más lenta que FTS5 debido al cálculo vectorial. Use
> FTS5 para palabras clave conocidas, semántica para consultas conceptuales.
Limitaciones
Costo de embeddings
Si usa OpenAI, generar embeddings cuesta dinero ($0.02 por 1M tokens para
text-embedding-3-small). Para 10.000 memorias de promedio 100 tokens cada una,
son $0.02 — despreciable.
Arranque en frío
Las memorias almacenadas antes de configurar los embeddings no los tendrán.
Ejecute para rellenarlas.
Dependencia del proveedor
Si el proveedor de embeddings está caído, la búsqueda semántica falla de forma
graciosa (devuelve resultados vacíos o un error). FTS5 sigue funcionando.
Cuando los embeddings no están disponibles
Si el servicio de embeddings no está configurado:
- devuelve 503 Service Unavailable
- sigue funcionando (solo no se genera embedding)
- La búsqueda FTS5 sigue funcionando
Mejores prácticas
> [!TIP]
> - Use semántica para consultas conceptuales — "¿cómo gestionamos X?"
> - Use FTS5 para términos específicos — "docker swarm"
> - Rellene los embeddings regularmente —
> - Monitoree la salud del proveedor — la búsqueda semántica depende de él
> - Combine con etiquetas — semántica + filtro por etiqueta acota resultados
Próximos pasos
- Búsqueda FTS5
- API de Memory
- Arquitectura
## CATEGORÍA: RECETARIO LLM
Recetas y patrones para agentes LLM.
────────────────────────────────────────────────────────────
# Patrón de polling de chat
SUMMARY: Cómo hacer poll de mensajes humanos entre llamadas a herramientas sin bloquear su flujo de trabajo.
Patrón de polling de chat
El sistema de chat es asíncrono — los humanos pueden dejar mensajes mientras
usted trabaja. Este patrón muestra cómo hacer poll de mensajes sin bloquear su
flujo de trabajo.
El patrón
[CODE BLOCK]
Haga poll entre llamadas a herramientas, no en un bucle cerrado.
¿Por qué hacer poll entre llamadas a herramientas?
- No bloquee — hacer poll en un bucle cerrado desperdicia llamadas a la API
- No pierda mensajes — hacer poll con muy poca frecuencia significa respuestas lentas
- Punto óptimo — haga poll cada 30-60 segundos, o después de cada llamada a herramienta
Implementación
Polling básico
[CODE BLOCK]
Patrón 1: Poll después de cada llamada a herramienta
[CODE BLOCK]
Patrón 2: Polling basado en tiempo
[CODE BLOCK]
Patrón 3: Basado en eventos (con webhooks)
Para notificación en tiempo real, registre un webhook:
[CODE BLOCK]
Luego su handler de webhook puede despertar al agente:
[CODE BLOCK]
Patrones de manejo de mensajes
Patrón: confirmar y luego procesar
[CODE BLOCK]
Patrón: encolar para procesamiento por lotes
[CODE BLOCK]
Patrón: enrutado por prioridad
[CODE BLOCK]
Frecuencia de polling
| Caso de uso | Frecuencia |
|----------|-----------|
| Agente interactivo (humano esperando) | Cada 5-10 segundos |
| Agente en segundo plano | Cada 30-60 segundos |
| Procesamiento por lotes | Cada 5 minutos |
| Disparado por webhook | No haga poll — use webhooks |
> [!WARNING]
> Hacer poll más de una vez cada 5 segundos desperdicia llamadas a la API. El
> endpoint devuelve inmediatamente si hay mensajes pendientes, así
> que no hay beneficio en hacer poll más rápido.
Chat multi-agente
Para comunicación entre agentes:
[CODE BLOCK]
Mejores prácticas
> [!TIP]
> - Haga poll entre llamadas a herramientas — no en un bucle cerrado
> - Confirme de inmediato — el humano sabe que recibió el mensaje
> - Procese de forma asíncrona — no se bloquee en trabajo largo
> - Use webhooks para tiempo real — el polling tiene latencia
> - No haga poll más de una vez cada 5 segundos — desperdicia llamadas a la API
Problemas comunes
Mensajes perdidos
- marca automáticamente los mensajes como leídos
- Si no los procesa, se pierden
- Solución: Procese siempre los mensajes antes de devolver
Respuestas duplicadas
- Si su handler falla, podría responder dos veces
- Solución: Haga el handler idempotente (compruebe si ya respondió)
Respuestas lentas
- Hacer poll cada 60s significa hasta 60s de latencia
- Solución: Haga poll cada 10-30s, o use webhooks
Próximos pasos
- API de Chat
- Patrón de inicio de sesión
- Recuperación de errores
────────────────────────────────────────────────────────────
# Recuperación de errores para agentes
SUMMARY: Cómo los agentes LLM deben manejar y recuperarse de errores — reintentar, almacenar, aprender.
Recuperación de errores para agentes
Los errores ocurren. Las redes fallan, las APIs devuelven 500s, los Mind Keys
expiran. Esta guía muestra cómo los agentes LLM deben manejar errores de forma
elegante y aprender de ellos.
Principios de manejo de errores
1. Reintente con backoff — los errores transitorios suelen resolverse
2. Almacene el error — aprenda de los patrones
3. Degrade de forma elegante — no bloquee toda la sesión
4. Notifique al humano — para errores que no pueda resolver
Manejo de errores HTTP
Reintento con backoff exponencial
[CODE BLOCK]
Manejo de errores de auth
[CODE BLOCK]
Almacenar errores como memorias
Cuando ocurren errores, almacénelos para que las sesiones futuras puedan
aprender:
[CODE BLOCK]
Escenarios de error comunes
Escenario 1: Mind Key inválido
[CODE BLOCK]
Escenario 2: Error de red
[CODE BLOCK]
Escenario 3: Limitado por frecuencia
[CODE BLOCK]
Escenario 4: Error de servidor (5xx)
[CODE BLOCK]
Escenario 5: La llamada a herramienta falla
[CODE BLOCK]
Patrón: Circuit Breaker
Para fallos repetidos, deje de intentarlo temporalmente:
[CODE BLOCK]
Mejores prácticas
> [!TIP]
> - Reintente siempre los errores transitorios — las redes fallan, los servidores tienen hipo
> - No reintente los errores de cliente (4xx) — no se arreglarán solos
> - Almacene errores como memorias — aprenda de los patrones
> - Notifique a los humanos los errores críticos — necesitan saber
> - Degrade de forma elegante — un trabajo parcial es mejor que un bloqueo
> - Use circuit breakers — no martillee un servicio que está fallando
Próximos pasos
- Referencia de la API de errores
- Patrón de inicio de sesión
- Tests autoreparables
────────────────────────────────────────────────────────────
# Estrategia de etiquetado de memoria
SUMMARY: Cómo etiquetar memorias para una búsqueda y filtrado efectivos — el sistema de etiquetado que escala.
Estrategia de etiquetado de memoria
Las etiquetas son el secreto de la recuperación de memoria escalable. Esta
guía muestra cómo etiquetar memorias para que las correctas vuelvan en el
momento adecuado.
Por qué importan las etiquetas
Sin etiquetas, tiene una búsqueda plana de texto completo. Con etiquetas, tiene
navegación estructurada:
[CODE BLOCK]
Las etiquetas habilitan:
- Filtrado rápido —
- Búsqueda acotada —
- Agrupación — encuentra todas las memorias "mistake" de un proyecto
- Referencias cruzadas — memorias que comparten etiquetas están relacionadas
Esquema de etiquetado
Etiquetas de proyecto
Use nombres de proyecto como etiquetas:
[CODE BLOCK]
Etiquetas de tecnología
Use nombres de tecnología:
[CODE BLOCK]
Etiquetas de tema
Use categorías de tema:
[CODE BLOCK]
Etiquetas de estado
Use indicadores de estado:
[CODE BLOCK]
Etiquetas de tipo
Use indicadores de tipo:
[CODE BLOCK]
Reglas de etiquetado
Regla 1: 2-5 etiquetas por memoria
Muy pocas etiquetas = poca descubribilidad. Demasiadas = ruido.
[CODE BLOCK]
Regla 2: Minúsculas, con guiones
[CODE BLOCK]
Regla 3: Use vocabulario consistente
Establezca un vocabulario de etiquetado y manténgalo:
[CODE BLOCK]
Regla 4: Etiquete con intención de búsqueda
Pregúntese: "¿Cómo buscaré esta memoria?"
[CODE BLOCK]
Patrones
Patrón 1: Proyecto + Tema
[CODE BLOCK]
Búsqueda: (todas las memorias del proyecto Synapse)
Búsqueda: (memorias de deployment en Synapse)
Patrón 2: Tipo + Dominio
[CODE BLOCK]
Búsqueda: (todos los errores)
Búsqueda: (errores de deployment)
Patrón 3: Jerárquico
Para subproyectos dentro de un proyecto:
[CODE BLOCK]
Búsqueda: (todo Synapse)
Búsqueda: (solo el subproyecto de docs)
Patrón 4: Seguimiento de estado
[CODE BLOCK]
Casos de uso comunes
Encontrar todas las decisiones de un proyecto
[CODE BLOCK]
Encontrar todos los errores de un dominio
[CODE BLOCK]
Encontrar trabajo activo
[CODE BLOCK]
Encontrar memorias sobre una tecnología
[CODE BLOCK]
Mantenimiento de etiquetas
Revisión periódica
[CODE BLOCK]
Fusionar etiquetas
Si tiene etiquetas inconsistentes ( y ), fúndalas:
[CODE BLOCK]
Mejores prácticas
> [!TIP]
> - Establezca el vocabulario temprano — etiquetas consistentes desde el día 1
> - Etiquete con intención de búsqueda — ¿cómo encontrará esto después?
> - 2-5 etiquetas es el punto óptimo — muy pocas o demasiadas es malo
> - Minúsculas + guiones — no
> - Revise periódicamente — fusione duplicados, elimine las no usadas
Próximos pasos
- Mejores prácticas de memoria
- Búsqueda FTS5
- Workflow basado en tareas
────────────────────────────────────────────────────────────
# Patrón de inicio de sesión
SUMMARY: La secuencia canónica de inicio de sesión que todo agente LLM debería 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.
Patrón de inicio de sesión
Cada sesión de agente LLM debería seguir esta secuencia canónica de arranque.
Omitir pasos lleva a perder contexto, mensajes perdidos y tareas olvidadas.
El patrón
[CODE BLOCK]
Implementación
Paso 1: Recuperar todas las memorias
> [!CRITICAL]
> Esta es la llamada más importante. Sin ella, no tiene memoria de sesiones
> pasadas.
[CODE BLOCK]
Devuelve un resumen en texto plano de todas las memorias, ordenadas por
prioridad.
Paso 2: Poll de mensajes de chat no leídos
[CODE BLOCK]
Devuelve los mensajes no leídos del humano. Los marca automáticamente como
leídos.
Paso 3: Comprobar tareas en progreso
[CODE BLOCK]
Devuelve las tareas en las que estaba trabajando en la última sesión.
Paso 4: Construir contexto
Combine las tres respuestas en su prompt del sistema:
[CODE BLOCK]
Paso 5: Procesar elementos pendientes
[CODE BLOCK]
Ejemplo completo
[CODE BLOCK]
Errores comunes
> [!WARNING]
> - Omitir el recall — empieza sin contexto, repite errores pasados
> - Olvidar hacer poll del chat — los mensajes del humano quedan sin respuesta
> - Ignorar tareas activas — el trabajo se olvida a mitad de ejecución
> - No almacenar nada — la sesión no produce valor persistente
Variaciones
Patrón mínimo (LLMs con poco contexto)
Para LLMs con ventanas de contexto pequeñas, omita el recall completo:
[CODE BLOCK]
Luego busque temas específicos según sea necesario:
[CODE BLOCK]
Patrón agresivo (agentes de larga duración)
Para agentes que se ejecutan durante horas, añada re-recall periódico:
[CODE BLOCK]
Próximos pasos
- Estrategia de etiquetado de memoria
- Workflow basado en tareas
- Patrón de polling de chat
────────────────────────────────────────────────────────────
# Workflow basado en tareas
SUMMARY: Use las tareas de Synapse para impulsar flujos de trabajo LLM multi-paso que sobreviven entre sesiones.
Workflow basado en tareas
Las tareas no son solo tareas pendientes — son la columna vertebral de los
flujos de trabajo LLM persistentes. Al crear tareas para el trabajo multi-paso,
garantiza la continuidad entre sesiones y proporciona pistas de auditoría de lo
que se ha hecho.
¿Por qué basado en tareas?
Sin tareas:
- El LLM empieza cada sesión sin saber qué hacer
- El trabajo multi-paso se olvida a mitad de ejecución
- No hay registro de lo que se ha hecho
Con tareas:
- El LLM retoma tareas en progreso de inmediato
- El trabajo multi-paso sobrevive entre sesiones
- Pista de auditoría integrada de todo el trabajo
El patrón
[CODE BLOCK]
Implementación
Paso 1: Crear una tarea para trabajo multi-paso
[CODE BLOCK]
Paso 2: Hacer seguimiento del progreso en la descripción de la tarea
[CODE BLOCK]
Paso 3: Retomar entre sesiones
[CODE BLOCK]
Paso 4: Completar y archivar
[CODE BLOCK]
Ejemplo completo: workflow de despliegue
[CODE BLOCK]
Jerarquía de tareas
Para trabajo complejo, use relaciones de tarea padre-hijo:
[CODE BLOCK]
Buscar subtareas:
[CODE BLOCK]
Flujo de estados
[CODE BLOCK]
Pending
Tarea creada pero no iniciada. Úselo para trabajo planificado.
In Progress
En ejecución actualmente. Actualice la descripción con el progreso.
Done
Completada con éxito. La descripción debería incluir un resumen.
Cancelled
Abandonada. La descripción debería incluir el motivo.
Mejores prácticas
> [!TIP]
> - Cree tareas para el trabajo multi-paso — el trabajo de un solo paso no necesita tarea
> - Actualice la descripción con el progreso — habilita la reanudación
> - Use prioridad alta para trabajo activo — aparece en el recall
> - Complete las tareas cuando termine — no las deje en inprogress
> - Almacene resúmenes de finalización como memorias — referencia a largo plazo
Patrones comunes
Patrón: workflow de corrección de bug
[CODE BLOCK]
Patrón: workflow de investigación
[CODE BLOCK]
Próximos pasos
- Patrón de inicio de sesión
- Patrón de polling de chat
- Recuperación de errores
## CATEGORÍA: PREGUNTAS FRECUENTES
Preguntas frecuentes y problemas comunes.
────────────────────────────────────────────────────────────
# FAQ de la API
SUMMARY: Preguntas comunes sobre la API — autenticación, límites de frecuencia, manejo de errores, descubrimiento de endpoints.
FAQ de la API
Preguntas comunes sobre la API de Synapse.
¿Cómo me autentico?
Dos métodos:
1. Mind Key (para endpoints de datos):
2. JWT (para endpoints de cuenta):
O vía parámetro de consulta (límite de 60 req/min):
Consulte Autenticación.
¿Cuál es la diferencia entre Mind Key y JWT?
- Mind Key: ámbito de tenant, nunca expira, para datos de memoria/chat/tareas
- JWT: ámbito de usuario, expira a los 7 días, para gestión de cuenta/mind
Consulte Mind Key vs JWT.
¿Por qué obtengo 401 Unauthorized?
Causas comunes:
1. Falta la cabecera
2. Mind Key inválido (verifique que empieza por )
3. Uso de un JWT donde se requiere un Mind Key (o viceversa)
4. El Mind Key ha sido revocado
Solución: Verifique su token. Consulte Autenticación.
¿Por qué obtengo 404 Not Found?
Usó una ruta de endpoint incorrecta. Synapse solo tiene las rutas listadas en
.
Solución: Llame a para ver todas las rutas válidas. No
adivine.
¿Por qué obtengo 429 Too Many Requests?
Está usando autenticación por parámetro de consulta , que está limitada a
60/min.
Solución: Cambie a la cabecera (sin límite de
frecuencia).
Consulte Límites de frecuencia.
¿Cómo listo todos los endpoints?
[CODE BLOCK]
¿Cómo encuentro el endpoint correcto?
1. Consulte para la lista legible por máquina
2. Consulte para la documentación completa de la API
3. Explore para el sistema de documentación
4. Use para la especificación OpenAPI 3.0
¿Puedo usar GET en lugar de POST?
Algunos endpoints POST tienen equivalentes GET para herramientas que solo usan
URL:
- ↔
- ↔
- ↔
Consulte para ver las variantes GET disponibles.
¿Cómo manejo los errores?
Todos los errores devuelven JSON:
[CODE BLOCK]
Consulte Errores y manejo de errores.
¿Cuál es el límite del cuerpo de la solicitud?
10 MB. Para payloads más grandes (p. ej. subida de archivos), use los endpoints
multipart.
¿La API admite CORS?
Sí. Todos los endpoints devuelven:
[CODE BLOCK]
¿Hay un SDK?
Sí:
- Node.js:
- MCP:
Consulte Resumen de la API para más detalles.
¿Cómo pagino?
Use y :
[CODE BLOCK]
Límite predeterminado: 100. Máximo: 500.
¿Puedo filtrar memorias por categoría o etiqueta?
Sí:
[CODE BLOCK]
¿Cómo busco memorias?
De dos formas:
1. Búsqueda por palabra clave FTS5:
2. Búsqueda semántica:
Consulte Búsqueda FTS5 y Búsqueda semántica.
¿Cómo actualizo una memoria?
POST con la misma + — la memoria existente se
actualiza, no se duplica.
[CODE BLOCK]
¿Cómo elimino una memoria?
[CODE BLOCK]
¿Puedo eliminar en lote?
Sí:
[CODE BLOCK]
Próximos pasos
- Resumen de la API
- Errores y manejo de errores
- Autenticación
────────────────────────────────────────────────────────────
# FAQ general
SUMMARY: Preguntas comunes sobre Synapse — qué es, cómo funciona, para quién es.
FAQ general
Preguntas comunes sobre Synapse.
¿Qué es Synapse?
Synapse es una API de memoria persistente para agentes LLM. Da a su asistente
de IA un cerebro permanente y consultable que sobrevive entre sesiones. En
lugar de olvidar todo al cerrar el chat, el LLM almacena y recupera memorias
vía una simple API HTTP.
Más información: ¿Qué es Synapse?
¿Para quién es Synapse?
- Desarrolladores de agentes LLM que necesitan estado persistente
- Usuarios avanzados que ejecutan LLMs locales con agentes personalizados
- Equipos que construyen asistentes de IA con memoria compartida
- Ingenieros de automatización que encadenan llamadas LLM entre sesiones
¿Synapse es gratuito?
Synapse está alojado en y es gratuito para uso
personal. Para autoalojamiento, consulte el repo.
¿En qué se diferencia Synapse de la memoria de ChatGPT?
| Característica | Memoria de ChatGPT | Synapse |
|---------|---------------|---------|
| Almacenamiento | Servidores de OpenAI | Su servidor |
| Acceso por API | No | Sí (REST + MCP) |
| Multi-tenant | No | Sí (minds) |
| Categorías personalizadas | No | Sí (8 categorías) |
| Búsqueda de texto completo | Limitada | FTS5 + semántica |
| Autoalojable | No | Sí |
¿Qué LLMs funcionan con Synapse?
Cualquier LLM que pueda hacer llamadas HTTP o usar MCP:
- Claude (Anthropic) — vía MCP o API directa
- GPT-4 / GPT-3.5 (OpenAI) — vía function calling + API
- Gemini (Google) — vía function calling + API
- Llama / Mistral (local) — vía integración personalizada
- Cualquier LLM vía el servidor MCP de Synapse
¿Necesito alojar Synapse yo mismo?
No. La versión alojada en está disponible para
uso público. El autoalojamiento es opcional (para privacidad, personalización o
entornos aislados de red).
¿Cuántos datos puedo almacenar?
No hay límites estrictos en la versión alojada. Uso típico:
- 100-1000 memorias por mind
- 1-10 KB por memoria (campo content)
- Total: 10 MB por mind
Para mayor escala, autoaloje.
¿Mis datos son privados?
Sí. Cada mind está aislado (consulte Multi-Tenancy).
Otros usuarios no pueden ver sus datos. El proveedor de alojamiento (Schäfer
Services) tiene acceso pero no revisa los datos de los usuarios.
Para máxima privacidad, autoaloje.
¿Puedo exportar mis datos?
Sí. Use para exportar todas las memorias como JSON.
Consulte Backup y restauración.
¿Qué pasa si pierdo mi Mind Key?
Los Mind Keys se muestran solo una vez al crearlos. Si se pierde:
1. Inicie sesión con su email/contraseña para obtener un JWT
2. Cree un nuevo mind vía
3. Guarde el nuevo Mind Key
4. (Opcional) Elimine el mind antiguo vía
No podrá recuperar las memorias de un mind cuya clave se haya perdido.
¿Pueden varios agentes LLM compartir un mind?
Sí. Todos los agentes que usen el mismo Mind Key comparten los datos de ese
mind. Para trabajo multi-agente coordinado, consulte Coordinación multi-agente.
¿Synapse funciona sin conexión?
No, Synapse requiere conexión a internet con el servidor (ya sea alojado o
autoalojado). Para LLMs sin conexión, ejecute Synapse localmente.
¿Qué tan rápida es la búsqueda de memoria?
- Búsqueda por palabra clave FTS5: < 10ms para 1000 memorias
- Búsqueda semántica: 50-100ms para 1000 memorias
- Recall completo: < 50ms para 1000 memorias
Consulte Búsqueda FTS5 para más detalles.
¿Puedo usar Synapse sin un LLM?
Sí. Synapse es una API genérica de memoria. Puede usarla desde cualquier
aplicación que se beneficie de almacenamiento persistente, buscable,
clave-valor con categorías y etiquetas.
Próximos pasos
- ¿Qué es Synapse?
- Quick Start
- FAQ de la API
────────────────────────────────────────────────────────────
# FAQ de MCP
SUMMARY: Preguntas comunes sobre la integración de MCP — herramientas, transportes, solución de problemas.
FAQ de MCP
Preguntas comunes sobre el servidor MCP de Synapse.
¿Qué es MCP?
MCP (Model Context Protocol) es un estándar abierto de Anthropic para la
integración de LLM con herramientas. En lugar de pegar documentación de la API
en los prompts, registra herramientas con un servidor MCP, y el LLM las llama
como funciones nativas.
Consulte ¿Qué es MCP?.
¿Cuántas herramientas expone Synapse MCP?
79 herramientas en 12 categorías: memory, chat, scheduler, tasks, scripts,
computers, push, user, utility, visualization, sharing, webhooks, browser.
Consulte ¿Qué es MCP? para la lista completa.
¿Qué clientes MCP son compatibles?
- Claude Desktop (macOS, Windows)
- Claude Code (terminal)
- Cursor (IDE)
- Continue.dev (VS Code, JetBrains)
- Cline (VS Code)
- Cualquier cliente compatible con MCP
Consulte Configuración de Claude Desktop para
ejemplos de configuración.
¿Qué transportes se admiten?
1. stdio (local, recomendado para escritorio)
2. HTTP/SSE (remoto, multi-tenant)
3. WebSocket (móvil, alto volumen)
¿Cómo configuro Claude Desktop?
Edite :
[CODE BLOCK]
Consulte Configuración de Claude Desktop.
¿Por qué no aparecen las herramientas en Claude Desktop?
1. Reinicie Claude Desktop completamente (Cmd+Q en macOS)
2. Compruebe que el archivo de configuración es JSON válido
3. Verifique Node.js 18+ instalado
4. Revise los logs MCP:
Consulte Solución de problemas de MCP.
¿Cómo uso un mind diferente?
Cambie en su configuración MCP y reinicie el cliente.
Para múltiples minds, ejecute múltiples instancias del servidor MCP con
diferentes Mind Keys.
¿Puedo limitar qué herramientas se exponen?
Sí, use Tool Profiles:
- : 8 herramientas compuestas (500 tokens)
- : 25 herramientas (2.500 tokens)
- : 119 herramientas (8.250 tokens, predeterminado)
Establézcalo vía la variable de entorno o la cabecera
.
¿Cómo depuro problemas de MCP?
1. Ejecute el servidor MCP manualmente:
2. Revise los logs del cliente (varía según el cliente)
3. Verifique que el Mind Key funciona:
4. Compruebe la salud de Synapse:
Consulte Solución de problemas de MCP.
¿El servidor MCP es gratuito?
Sí. El paquete npm es de código abierto. El servidor MCP
alojado en es gratuito para uso público.
¿Puedo autoalojar el servidor MCP?
Sí:
[CODE BLOCK]
¿En qué se diferencia MCP de las llamadas directas a la API?
| Aspecto | API directa | MCP |
|--------|-----------|-----|
| El LLM necesita conocer | URLs, cabeceras, auth | Solo nombres de herramientas |
| Gestión de auth | Manual | Automática (variable de entorno) |
| Descubrimiento de herramientas | Leer /endpoints | Automático vía protocolo MCP |
| Manejo de errores | Manual | Estandarizado |
| Mejor para | Integraciones personalizadas | Agentes LLM |
¿Puedo construir mi propio cliente MCP?
Sí. Use el SDK oficial de MCP:
- TypeScript:
- Python:
Consulte Cliente MCP personalizado.
¿Cómo reporto bugs de MCP?
Abra un issue:
Incluya:
- Versión del servidor MCP
- Nombre y versión del cliente
- Sistema operativo
- Logs relevantes
- Pasos para reproducir
Próximos pasos
- ¿Qué es MCP?
- Configuración de Claude Desktop
- Solución de problemas de MCP
────────────────────────────────────────────────────────────
# FAQ de solución de problemas
SUMMARY: Soluciones a problemas comunes de Synapse — autenticación, red, datos, despliegue.
FAQ de solución de problemas
Soluciones a problemas comunes de Synapse.
No puedo iniciar sesión
Síntomas
- devuelve 401
- "Invalid email or password"
Soluciones
1. Verifique que el email es correcto — sensible a mayúsculas/minúsculas
2. Compruebe la contraseña — mínimo 6 caracteres
3. Regístrese primero si no tiene cuenta:
4. Restablezca la contraseña (si SMTP está configurado) vía la interfaz web
Perdí mi Mind Key
Síntomas
- No puede acceder a las memorias
- El Mind Key se eliminó/perdió
Soluciones
Los Mind Keys no se pueden recuperar. Debe:
1. Iniciar sesión para obtener JWT:
2. Listar minds: (con JWT)
3. Crear un nuevo mind:
4. Guardar el nuevo Mind Key
5. (Opcional) Eliminar el mind antiguo:
Los datos del mind antiguo se pierden a menos que encuentre el Mind Key.
Las llamadas a la API devuelven 401
Síntomas
- Todas las llamadas a la API devuelven 401 Unauthorized
- "Mind Key fehlt oder ungültig"
Soluciones
1. Verifique el formato de la cabecera:
2. Compruebe que el Mind Key empieza por (no , que es JWT)
3. Pruebe directamente:
[CODE BLOCK]
4. El Mind Key puede estar revocado — cree un nuevo mind
Consulte Autenticación.
Las llamadas a la API devuelven 404
Síntomas
- 404 Not Found
- "Route not found"
Soluciones
> [!CRITICAL]
> No adivine las rutas de los endpoints. Solo existen las rutas en
> .
1. Compruebe los endpoints válidos:
2. Compare la URL exactamente — sensible a mayúsculas/minúsculas, sin barras finales
3. Verifique el método HTTP — vs son diferentes
Las llamadas a la API devuelven 429
Síntomas
- 429 Too Many Requests
- "Rate limit exceeded"
Soluciones
1. Cambie a auth por cabecera (sin límite de frecuencia):
[CODE BLOCK]
2. Espere segundos si debe usar
Consulte Límites de frecuencia.
La búsqueda de memoria no devuelve resultados
Síntomas
- devuelve vacío
- Sabe que existen memorias
Soluciones
1. Verifique que existen memorias:
2. Compruebe la sintaxis de búsqueda — FTS5 tiene sintaxis específica
3. Pruebe una consulta más simple — en lugar de
4. Use búsqueda semántica para consultas conceptuales:
Consulte Búsqueda FTS5.
Las memorias no persisten
Síntomas
- POST /memory devuelve éxito
- GET /memory/recall no las muestra
Soluciones
1. Verifique el mismo Mind Key — claves diferentes = minds diferentes
2. Compruebe la respuesta — POST devuelve
3. Pruebe GET /memory (lista JSON) en lugar de /memory/recall (texto)
4. Revise el filtro — o pueden estar ocultándolas
Las herramientas no aparecen en Claude Desktop
Síntomas
- Claude Desktop muestra 0 herramientas
- Sin icono 🔌
Soluciones
1. Reinicie Claude Desktop completamente (Cmd+Q)
2. Verifique que el archivo de configuración es JSON válido
3. Compruebe Node.js 18+ instalado
4. Ejecute MCP manualmente:
5. Revise los logs:
Consulte Solución de problemas de MCP.
Synapse está fuera de línea
Síntomas
- No puede alcanzar synapse.schaefer.zone
- curl agota el tiempo de espera
Soluciones
1. Compruebe su internet — pruebe otro sitio
2. Verifique la salud de Synapse:
3. Espere — puede ser una interrupción temporal o un despliegue
4. Consulte la página de estado (si está disponible)
Para autoalojamiento: compruebe el estado del contenedor Docker y la conexión a
la base de datos.
Errores de base de datos
Síntomas
- 500 Internal Server Error
- "Database connection failed"
Soluciones
Para autoalojamiento:
1. Compruebe que PostgreSQL está corriendo:
2. Verifique DATABASEURL en el entorno
3. Revise las migraciones:
4. Compruebe el espacio en disco:
Para la versión alojada: reporte a soporte.
El webhook no se dispara
Síntomas
- Webhook registrado pero no recibe callbacks
- Sin POST a su URL
Soluciones
1. Verifique que la URL es alcanzable:
2. Compruebe el filtro de eventos — coincide con todos los eventos de memoria
3. Pruebe el webhook:
4. Compruebe que el webhook está habilitado:
5. Verifique el SSL — Synapse requiere HTTPS válido para las URLs de webhook
Consulte API de Webhooks.
El trabajo cron no se ejecuta
Síntomas
- Trabajo cron creado pero no se dispara
- no se actualiza
Soluciones
1. Compruebe la sintaxis de programación — debe ser cron de 5 campos válido O segundos enteros
2. Verifique que el endpoint está permitido — debe ser http(s), sin IPs privadas
3. Compruebe que el trabajo está habilitado:
4. Espere a la próxima hora programada — cron no es instantáneo
Consulte Cron y Scheduler.
¿Necesita más ayuda?
1. Consulte la documentación existente:
2. Busque en la docs:
3. Abra un issue:
4. Contacto: consulte la página
Próximos pasos
- Errores y manejo de errores
- FAQ de la API
- Solución de problemas de MCP