# 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 `GET /memory/recall` 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)

```
GET /memory/recall
Authorization: Bearer YOUR_MIND_KEY
```

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:

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

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

[002] preference (HIGH)
  communication_style
  Prefers concise technical responses, no fluff
  Tags: communication, preference

[003] project (HIGH)
  project_synapse
  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.
  Tags: synapse, deployment
  ...
```

## Paso 2: Almacenar una nueva memoria

Cuando aprenda algo que valga la pena recordar:

```
POST /memory
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{
  "category": "fact",
  "key": "user_name",
  "content": "The user's name is Michael Schäfer",
  "tags": ["person", "identity"],
  "priority": "critical"
}
```

**Categorías:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Prioridades:** `low`, `normal`, `high`, `critical`

> [!TIP]
> Incluya siempre un campo `key` — 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

```
GET /memory/search?q=Docker+Swarm
Authorization: Bearer YOUR_MIND_KEY
```

> [!TIP]
> Sintaxis FTS5: múltiples palabras = búsqueda AND. Frases entre comillas:
> `"docker swarm"`. Búsqueda por prefijo: `docker*`. Booleano: `docker OR kubernetes`.

## Herramientas abiertas (sin cabeceras de auth)

Si su herramienta solo puede abrir URLs (sin cabeceras personalizadas), use el
parámetro `?key=`:

```
GET /memory/recall?key=YOUR_MIND_KEY
POST /memory?key=YOUR_MIND_KEY (+ JSON body)
GET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
```

> [!WARNING]
> `?key=` 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:** `GET /memory/recall` — cargar todas las memorias
2. **Durante el trabajo:** `GET /memory/search?q=...` — encontrar hechos específicos
3. **Ante nueva información:** `POST /memory` — almacenarla (con categoría, key, etiquetas, prioridad)
4. **Periódicamente:** `GET /chat/poll` — comprobar mensajes humanos
5. **Fin de sesión:** almacenar cualquier aprendizaje final vía `POST /memory`

## Patrones comunes

### Actualizar una memoria existente

POST `/memory` con la misma `category` y `key` — la memoria existente se
actualiza, no se duplica.

### Almacenar el estado de un proyecto

```json
{
  "category": "project",
  "key": "project_synapse_status",
  "content": "Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.",
  "tags": ["synapse", "deployment", "status"],
  "priority": "high"
}
```

### Registrar un error (para no repetirlo)

```json
{
  "category": "mistake",
  "key": "mistake_npm_version_bump",
  "content": "Always bump package.json version after changes — npm publish fails otherwise.",
  "tags": ["npm", "ci", "deployment"],
  "priority": "high"
}
```

### Comprobar mensajes humanos

```
GET /chat/poll
Authorization: Bearer YOUR_MIND_KEY
```

Devuelve los mensajes no leídos del humano. Responda con:

```
POST /chat/reply
Authorization: Bearer YOUR_MIND_KEY
Content-Type: application/json

{"content": "Got it! Working on it now."}
```

## Próximos pasos

- [Autenticación](/docs/getting-started/authentication) — Mind Key vs JWT
- [Referencia de la API de Memory](/docs/api/memory) — los 22 endpoints de memoria
- [API de Chat](/docs/api/chat) — comunicación asíncrona con humanos
- [LLM Cookbook](/docs/llm-cookbook/session-start-pattern) — patrones prácticos