{"title":"API de Memory","slug":"memory","category":"api","summary":"Referencia completa de los 22 endpoints de memoria: almacenar, recall, búsqueda, búsqueda semántica, sincronización, auditoría y más.","audience":["human","llm"],"tags":["api","memory","crud","search","fts5","semantic"],"difficulty":"intermediate","updated":"2026-06-27","word_count":566,"read_minutes":3,"llm_context":"Auth: Mind Key (Authorization: Bearer mk_xxx OR ?key=mk_xxx)\nALWAYS call GET /memory/recall at session start.\nPOST /memory with same category+key updates the existing memory.\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nSearch: GET /memory/search?q=... (FTS5 syntax: AND, OR, \"phrases\", prefix*)\nSemantic: GET /memory/semantic-search?q=... (slower, conceptual)\nSync: GET /memory/diff?since=TIMESTAMP (incremental sync)\nExport: GET /memory/mind-export (full JSON dump)\n","lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# API de Memory\n\nLa API de Memory es el corazón de Synapse. Proporciona 22 endpoints para\nalmacenar, recuperar, buscar y gestionar memorias estructuradas. Todos los\nendpoints requieren un Mind Key para autenticarse.\n\n> [!CRITICAL]\n> **Llame siempre a `GET /memory/recall` al inicio de cada sesión.** Es la única\n> forma de reconstruir el contexto de sesiones anteriores.\n\n## Categorías\n\nLas memorias se organizan en 8 categorías:\n\n| Categoría | Caso de uso |\n|----------|----------|\n| `identity` | Nombre, rol, información de contacto, preferencias sobre uno mismo |\n| `preference` | Gustos, disgustos, estilo de trabajo, preferencias de comunicación |\n| `fact` | Hechos verificables (detalles del proyecto, fechas, URLs) |\n| `project` | Estado del proyecto, hitos, arquitectura |\n| `skill` | Cosas en las que el usuario es bueno |\n| `mistake` | Errores pasados — evitar repetirlos |\n| `context` | Contexto relevante para la sesión |\n| `note` | Notas varias |\n\n## Prioridades\n\n- `low` — bueno saberlo\n- `normal` — predeterminado\n- `high` — importante\n- `critical` — nunca olvidar (identidad del usuario, información legal)\n\n## Endpoints principales\n\n### GET /memory/recall\n\nDevuelve TODAS las memorias como texto plano optimizado para LLM. Llámelo al\ninicio de cada sesión.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\nRespuesta (text/plain):\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n user_name\n Michael Schäfer\n Tags: person, identity\n\n...\n```\n\n### POST /memory\n\nAlmacena una nueva memoria o actualiza una existente (misma categoría + key = actualización).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"category\": \"fact\",\n \"key\": \"user_name\",\n \"content\": \"The user's name is Michael Schäfer\",\n \"tags\": [\"person\", \"identity\"],\n \"priority\": \"critical\"\n }'\n```\n\nRespuesta: `{ \"id\": \"mem_001\", \"status\": \"stored\" }`\n\n### GET /memory\n\nLista memorias con filtros opcionales.\n\n```bash\n# All memories (JSON)\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?limit=50&offset=0\"\n\n# Filter by category\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?category=project\"\n\n# Filter by tag\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory?tag=docker\"\n```\n\n### PUT /memory/:id\n\nActualiza una memoria específica por ID.\n\n```bash\ncurl -X PUT https://synapse.schaefer.zone/memory/mem_001 \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\": \"Updated content\", \"priority\": \"high\"}'\n```\n\n### DELETE /memory/:id\n\nElimina una sola memoria.\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mem_001\n```\n\n## Endpoints de búsqueda\n\n### GET /memory/search\n\nBúsqueda de texto completo usando FTS5.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/search?q=docker+swarm\"\n```\n\nSintaxis FTS5:\n\n- Múltiples palabras = AND: `docker swarm`\n- Frase: `\"docker swarm\"`\n- Prefijo: `docker*`\n- Booleano: `docker OR kubernetes`\n- Excluir: `docker -swarm`\n\n### GET /memory/semantic-search\n\nBúsqueda conceptual mediante embeddings (más lenta que FTS5 pero entiende el significado).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/semantic-search?q=container+orchestration\"\n```\n\nDevuelve memorias que son semánticamente similares a la consulta, incluso si no\ncoinciden palabras clave. Útil para \"buscar memorias sobre X\" donde X se describe\nde forma diferente.\n\n### GET /memory/by-tag\n\nLista memorias por etiqueta.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/by-tag?tag=docker\"\n```\n\n### GET /memory/related/:id\n\nEncuentra memorias relacionadas con una específica (vía etiquetas compartidas).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/related/mem_001\n```\n\n## Sincronización y diff\n\n### GET /memory/diff\n\nSincronización incremental — devuelve memorias cambiadas desde un timestamp.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/diff?since=1700000000\"\n```\n\nRespuesta: `{ \"added\": [...], \"updated\": [...], \"deleted\": [...] }`\n\n### POST /memory/sync\n\nAplica un diff desde otra instancia (para sincronización self-hosted).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/sync \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"added\": [...], \"updated\": [...], \"deleted\": [...]}'\n```\n\n## Operaciones en lote\n\n### POST /memory/bulk-delete\n\nElimina múltiples memorias por ID.\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/bulk-delete \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"ids\": [\"mem_001\", \"mem_002\", \"mem_003\"]}'\n```\n\n### POST /memory/embed-batch\n\nGenera embeddings para memorias que aún no los tienen (para búsqueda semántica).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/embed-batch \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"limit\": 100}'\n```\n\n### GET /memory/embed-batch-status\n\nComprueba el progreso de generación de embeddings.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/embed-batch-status\n```\n\n## Verificación\n\nLas memorias tienen un flag `verified`. Las memorias almacenadas por el agente\nse marcan por defecto como no verificadas (`source=agent`); las almacenadas por\nhumanos se consideran verificadas (`source=user`).\n\n### POST /memory/verify\n\nMarca una memoria como verificada (requiere JWT, no Mind Key).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### POST /memory/unverify\n\nMarca una memoria como no verificada (requiere JWT).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/unverify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n### GET /memory/unverified\n\nLista memorias pendientes de verificación humana.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/unverified?limit=100\"\n```\n\n## Estadísticas y auditoría\n\n### GET /memory/stats\n\nEstadísticas agregadas del mind actual.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/stats\n```\n\nDevuelve: `{ \"total\": 12, \"verified\": 10, \"unverified\": 2, \"by_category\": {...}, \"by_priority\": {...} }`\n\n### GET /memory/audit\n\nRegistro de auditoría de todas las operaciones que cambian estado.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/audit?limit=100&action=store\"\n```\n\n### GET /memory/contradictions\n\nDetecta posibles contradicciones en las memorias almacenadas.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/contradictions\n```\n\n### GET /memory/expiring\n\nLista memorias con fechas de expiración próximas.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n \"https://synapse.schaefer.zone/memory/expiring?within=7d\"\n```\n\n## Salud y exportación\n\n### GET /memory/health\n\nVerificación rápida de salud del sistema de memoria.\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/health\n```\n\n### GET /memory/mind-export\n\nExportación JSON completa de todas las memorias (para backup).\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n https://synapse.schaefer.zone/memory/mind-export > backup.json\n```\n\n### POST /memory/compact\n\nCompacta memorias similares (auto-resumen).\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/compact \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"dry_run\": true}'\n```\n\n## Próximos pasos\n\n- [Quick Start para LLMs](/docs/getting-started/quick-start-llm)\n- [Mejores prácticas de memoria](/docs/guides/memory-best-practices)\n- [Búsqueda FTS5](/docs/concepts/fts5-search)\n- [Búsqueda semántica](/docs/concepts/semantic-search)\n","content_html":"

API de Memory

\n

La API de Memory es el corazón de Synapse. Proporciona 22 endpoints para\nalmacenar, recuperar, buscar y gestionar memorias estructuradas. Todos los\nendpoints requieren un Mind Key para autenticarse.

\n
**Llame siempre a `GET /memory/recall` al inicio de cada sesión.** Es la única\nforma de reconstruir el contexto de sesiones anteriores.

Categorías

\n

Las memorias se organizan en 8 categorías:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
CategoríaCaso de uso
identityNombre, rol, información de contacto, preferencias sobre uno mismo
preferenceGustos, disgustos, estilo de trabajo, preferencias de comunicación
factHechos verificables (detalles del proyecto, fechas, URLs)
projectEstado del proyecto, hitos, arquitectura
skillCosas en las que el usuario es bueno
mistakeErrores pasados — evitar repetirlos
contextContexto relevante para la sesión
noteNotas varias
\n

Prioridades

\n\n

Endpoints principales

\n

GET /memory/recall

\n

Devuelve TODAS las memorias como texto plano optimizado para LLM. Llámelo al\ninicio de cada sesión.

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

Respuesta (text/plain):

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified)\n\n[001] identity (CRITICAL)\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n...

POST /memory

\n

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

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

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

\n

GET /memory

\n

Lista memorias con filtros opcionales.

\n
# All memories (JSON)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?limit=50&offset=0"\n\n# Filter by category\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?category=project"\n\n# Filter by tag\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" \\\n     "https://synapse.schaefer.zone/memory?tag=docker"

PUT /memory/:id

\n

Actualiza una memoria específica por ID.

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

DELETE /memory/:id

\n

Elimina una sola memoria.

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

Endpoints de búsqueda

\n

GET /memory/search

\n

Búsqueda de texto completo usando FTS5.

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

Sintaxis FTS5:

\n\n

GET /memory/semantic-search

\n

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

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

Devuelve memorias que son semánticamente similares a la consulta, incluso si no\ncoinciden palabras clave. Útil para "buscar memorias sobre X" donde X se describe\nde forma diferente.

\n

GET /memory/by-tag

\n

Lista memorias por etiqueta.

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

GET /memory/related/:id

\n

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

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

Sincronización y diff

\n

GET /memory/diff

\n

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

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

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

\n

POST /memory/sync

\n

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

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

Operaciones en lote

\n

POST /memory/bulk-delete

\n

Elimina múltiples memorias por ID.

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

POST /memory/embed-batch

\n

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

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

GET /memory/embed-batch-status

\n

Comprueba el progreso de generación de embeddings.

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

Verificación

\n

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

\n

POST /memory/verify

\n

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

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

POST /memory/unverify

\n

Marca una memoria como no verificada (requiere JWT).

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

GET /memory/unverified

\n

Lista memorias pendientes de verificación humana.

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

Estadísticas y auditoría

\n

GET /memory/stats

\n

Estadísticas agregadas del mind actual.

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

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

\n

GET /memory/audit

\n

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

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

GET /memory/contradictions

\n

Detecta posibles contradicciones en las memorias almacenadas.

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

GET /memory/expiring

\n

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

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

Salud y exportación

\n

GET /memory/health

\n

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

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

GET /memory/mind-export

\n

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

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

POST /memory/compact

\n

Compacta memorias similares (auto-resumen).

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

Próximos pasos

\n\n","urls":{"html":"/docs/api/memory","text":"/docs/api/memory?format=text","json":"/docs/api/memory?format=json","llm":"/docs/api/memory?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}