# 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