Skip to main content

API de Memory

intermediate 🤖 Compatible con LLM 3 min · 566 palabras Actualizado: 2026-06-27 Español

Referencia completa de los 22 endpoints de memoria: almacenar, recall, búsqueda, búsqueda semántica, sincronización, auditoría y más.

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

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.

**Llame siempre a `GET /memory/recall` 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
identity Nombre, rol, información de contacto, preferencias sobre uno mismo
preference Gustos, disgustos, estilo de trabajo, preferencias de comunicación
fact Hechos verificables (detalles del proyecto, fechas, URLs)
project Estado del proyecto, hitos, arquitectura
skill Cosas en las que el usuario es bueno
mistake Errores pasados — evitar repetirlos
context Contexto relevante para la sesión
note Notas varias

Prioridades

  • low — bueno saberlo
  • normal — predeterminado
  • high — importante
  • critical — 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.

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

Respuesta (text/plain):

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

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

...

POST /memory

Almacena una nueva memoria o actualiza una existente (misma categoría + key = actualización).

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

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

GET /memory

Lista memorias con filtros opcionales.

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

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

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

PUT /memory/:id

Actualiza una memoria específica por ID.

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

DELETE /memory/:id

Elimina una sola memoria.

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

Endpoints de búsqueda

GET /memory/search

Búsqueda de texto completo usando FTS5.

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

Sintaxis FTS5:

  • Múltiples palabras = AND: docker swarm
  • Frase: "docker swarm"
  • Prefijo: docker*
  • Booleano: docker OR kubernetes
  • Excluir: docker -swarm

GET /memory/semantic-search

Búsqueda conceptual mediante embeddings (más lenta que FTS5 pero entiende el significado).

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

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.

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

GET /memory/related/:id

Encuentra memorias relacionadas con una específica (vía etiquetas compartidas).

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

Sincronización y diff

GET /memory/diff

Sincronización incremental — devuelve memorias cambiadas desde un timestamp.

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

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

POST /memory/sync

Aplica un diff desde otra instancia (para sincronización self-hosted).

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

Operaciones en lote

POST /memory/bulk-delete

Elimina múltiples memorias por ID.

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

POST /memory/embed-batch

Genera embeddings para memorias que aún no los tienen (para búsqueda semántica).

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

GET /memory/embed-batch-status

Comprueba el progreso de generación de embeddings.

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

Verificación

Las memorias tienen un flag verified. Las memorias almacenadas por el agente se marcan por defecto como no verificadas (source=agent); las almacenadas por humanos se consideran verificadas (source=user).

POST /memory/verify

Marca una memoria como verificada (requiere JWT, no Mind Key).

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

POST /memory/unverify

Marca una memoria como no verificada (requiere JWT).

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

GET /memory/unverified

Lista memorias pendientes de verificación humana.

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

Estadísticas y auditoría

GET /memory/stats

Estadísticas agregadas del mind actual.

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

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

GET /memory/audit

Registro de auditoría de todas las operaciones que cambian estado.

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

GET /memory/contradictions

Detecta posibles contradicciones en las memorias almacenadas.

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

GET /memory/expiring

Lista memorias con fechas de expiración próximas.

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

Salud y exportación

GET /memory/health

Verificación rápida de salud del sistema de memoria.

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

GET /memory/mind-export

Exportación JSON completa de todas las memorias (para backup).

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

POST /memory/compact

Compacta memorias similares (auto-resumen).

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

Próximos pasos

← Volver a Referencia de la API