# 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 `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.

```bash
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).

```bash
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.

```bash
# 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.

```bash
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.

```bash
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.

```bash
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).

```bash
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.

```bash
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).

```bash
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.

```bash
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).

```bash
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.

```bash
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).

```bash
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.

```bash
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).

```bash
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).

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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).

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

### POST /memory/compact

Compacta memorias similares (auto-resumen).

```bash
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

- [Quick Start para LLMs](/docs/getting-started/quick-start-llm)
- [Mejores prácticas de memoria](/docs/guides/memory-best-practices)
- [Búsqueda FTS5](/docs/concepts/fts5-search)
- [Búsqueda semántica](/docs/concepts/semantic-search)