# Quick Start per agenti LLM

Perde tutta la memoria tra le sessioni. Synapse è il suo cervello esterno.
Questa guida mostra le tre chiamate API essenziali che ogni agente LLM deve
conoscere.

> [!CRITICAL]
> Chiami `GET /memory/recall` all'INIZIO di OGNI sessione.
> Senza questa chiamata, non ha memoria di chi è l'utente, cosa ha promesso,
> o a cosa stava lavorando l'ultima volta.

## Passo 1: Richiami tutte le memorie (SEMPRE PER PRIMO)

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

Restituisce un riassunto strutturato in testo semplice di tutte le memorie
salvate. Lo analizzi per ricostruire il suo modello mentale dell'utente, dei
suoi progetti e delle interazioni passate.

Risposta di esempio:

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

## Passo 2: Memorizzi una nuova memoria

Quando impara qualcosa che vale la pena ricordare:

```
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"
}
```

**Categorie:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`

**Priorità:** `low`, `normal`, `high`, `critical`

> [!TIP]
> Includa sempre un campo `key` — un breve identificatore per la memoria. Questo
> le permette di aggiornare la stessa memoria in seguito con un nuovo POST usando
> la stessa chiave.

## Passo 3: Cerchi una memoria specifica

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

> [!TIP]
> Sintassi FTS5: più parole = ricerca AND. Frasi tra virgolette: `"docker swarm"`.
> Ricerca per prefisso: `docker*`. Booleano: `docker OR kubernetes`.

## Strumenti aperti (nessun header di auth)

Se il suo strumento può solo aprire URL (nessun header personalizzato), usi il
parametro `?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=` è limitato a 60 richieste/minuto. L'header Bearer non ha rate limit.
> Usi l'header Bearer quando possibile.

## Workflow completo di sessione

1. **Inizio sessione:** `GET /memory/recall` — carica tutte le memorie
2. **Durante il lavoro:** `GET /memory/search?q=...` — trova fatti specifici
3. **Su nuove info:** `POST /memory` — le memorizza (con category, key, tags, priority)
4. **Periodicamente:** `GET /chat/poll` — controlla i messaggi dell'umano
5. **Fine sessione:** Memorizzi gli ultimi apprendimenti tramite `POST /memory`

## Modelli comuni

### Aggiornare una memoria esistente

POST `/memory` con la stessa `category` e `key` — la memoria esistente viene
aggiornata, non duplicata.

### Memorizzare lo stato di un progetto

```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"
}
```

### Registrare un errore (per non ripeterlo)

```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"
}
```

### Verificare i messaggi dell'umano

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

Restituisce i messaggi non letti dall'umano. Risponda con:

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

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

## Prossimi passi

- [Autenticazione](/docs/getting-started/authentication) — Mind Key vs JWT
- [Riferimento Memory API](/docs/api/memory) — tutti i 22 endpoint memory
- [Chat API](/docs/api/chat) — comunicazione asincrona con gli umani
- [LLM Cookbook](/docs/llm-cookbook/session-start-pattern) — modelli pratici