{"title":"Quick Start per agenti LLM","slug":"quick-start-llm","category":"getting-started","summary":"In 3 chiamate API: richiama tutte le memorie, ne memorizza una nuova, cerca. Il workflow LLM essenziale.","audience":["llm"],"tags":["llm","agent","quickstart","memory"],"difficulty":"beginner","updated":"2026-06-27","word_count":373,"read_minutes":2,"llm_context":"Base URL: https://synapse.schaefer.zone\nAuth: Authorization: Bearer YOUR_MIND_KEY (header) OR ?key=YOUR_MIND_KEY (query)\nALWAYS call /memory/recall at the start of every session.\nWichtigste Befehle: GET /memory/recall, POST /memory, GET /memory/search?q=...\nCategories: identity, preference, fact, project, skill, mistake, context, note, credentials\nPriorities: low, normal, high, critical\nFTS5 search: multiple words = AND, \"phrases\" in quotes, prefix* for prefix search\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Quick Start per agenti LLM\n\nPerde tutta la memoria tra le sessioni. Synapse è il suo cervello esterno.\nQuesta guida mostra le tre chiamate API essenziali che ogni agente LLM deve\nconoscere.\n\n> [!CRITICAL]\n> Chiami `GET /memory/recall` all'INIZIO di OGNI sessione.\n> Senza questa chiamata, non ha memoria di chi è l'utente, cosa ha promesso,\n> o a cosa stava lavorando l'ultima volta.\n\n## Passo 1: Richiami tutte le memorie (SEMPRE PER PRIMO)\n\n```\nGET /memory/recall\nAuthorization: Bearer YOUR_MIND_KEY\n```\n\nRestituisce un riassunto strutturato in testo semplice di tutte le memorie\nsalvate. Lo analizzi per ricostruire il suo modello mentale dell'utente, dei\nsuoi progetti e delle interazioni passate.\n\nRisposta di esempio:\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[002] preference (HIGH)\n communication_style\n Prefers concise technical responses, no fluff\n Tags: communication, preference\n\n[003] project (HIGH)\n project_synapse\n Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.\n Tags: synapse, deployment\n ...\n```\n\n## Passo 2: Memorizzi una nuova memoria\n\nQuando impara qualcosa che vale la pena ricordare:\n\n```\nPOST /memory\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{\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\n**Categorie:** `identity`, `preference`, `fact`, `project`, `skill`, `mistake`, `context`, `note`, `credentials`\n\n**Priorità:** `low`, `normal`, `high`, `critical`\n\n> [!TIP]\n> Includa sempre un campo `key` — un breve identificatore per la memoria. Questo\n> le permette di aggiornare la stessa memoria in seguito con un nuovo POST usando\n> la stessa chiave.\n\n## Passo 3: Cerchi una memoria specifica\n\n```\nGET /memory/search?q=Docker+Swarm\nAuthorization: Bearer YOUR_MIND_KEY\n```\n\n> [!TIP]\n> Sintassi FTS5: più parole = ricerca AND. Frasi tra virgolette: `\"docker swarm\"`.\n> Ricerca per prefisso: `docker*`. Booleano: `docker OR kubernetes`.\n\n## Strumenti aperti (nessun header di auth)\n\nSe il suo strumento può solo aprire URL (nessun header personalizzato), usi il\nparametro `?key=`:\n\n```\nGET /memory/recall?key=YOUR_MIND_KEY\nPOST /memory?key=YOUR_MIND_KEY (+ JSON body)\nGET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff\n```\n\n> [!WARNING]\n> `?key=` è limitato a 60 richieste/minuto. L'header Bearer non ha rate limit.\n> Usi l'header Bearer quando possibile.\n\n## Workflow completo di sessione\n\n1. **Inizio sessione:** `GET /memory/recall` — carica tutte le memorie\n2. **Durante il lavoro:** `GET /memory/search?q=...` — trova fatti specifici\n3. **Su nuove info:** `POST /memory` — le memorizza (con category, key, tags, priority)\n4. **Periodicamente:** `GET /chat/poll` — controlla i messaggi dell'umano\n5. **Fine sessione:** Memorizzi gli ultimi apprendimenti tramite `POST /memory`\n\n## Modelli comuni\n\n### Aggiornare una memoria esistente\n\nPOST `/memory` con la stessa `category` e `key` — la memoria esistente viene\naggiornata, non duplicata.\n\n### Memorizzare lo stato di un progetto\n\n```json\n{\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed. Next: v1.6.0 with docs system. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"status\"],\n \"priority\": \"high\"\n}\n```\n\n### Registrare un errore (per non ripeterlo)\n\n```json\n{\n \"category\": \"mistake\",\n \"key\": \"mistake_npm_version_bump\",\n \"content\": \"Always bump package.json version after changes — npm publish fails otherwise.\",\n \"tags\": [\"npm\", \"ci\", \"deployment\"],\n \"priority\": \"high\"\n}\n```\n\n### Verificare i messaggi dell'umano\n\n```\nGET /chat/poll\nAuthorization: Bearer YOUR_MIND_KEY\n```\n\nRestituisce i messaggi non letti dall'umano. Risponda con:\n\n```\nPOST /chat/reply\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{\"content\": \"Got it! Working on it now.\"}\n```\n\n## Prossimi passi\n\n- [Autenticazione](/docs/getting-started/authentication) — Mind Key vs JWT\n- [Riferimento Memory API](/docs/api/memory) — tutti i 22 endpoint memory\n- [Chat API](/docs/api/chat) — comunicazione asincrona con gli umani\n- [LLM Cookbook](/docs/llm-cookbook/session-start-pattern) — modelli pratici\n","content_html":"

Quick Start per agenti LLM

\n

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

\n
Chiami `GET /memory/recall` all'INIZIO di OGNI sessione.\nSenza questa chiamata, non ha memoria di chi è l'utente, cosa ha promesso,\no a cosa stava lavorando l'ultima volta.

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

\n
GET /memory/recall\nAuthorization: Bearer YOUR_MIND_KEY

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

\n

Risposta di esempio:

\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[002] preference (HIGH)\n  communication_style\n  Prefers concise technical responses, no fluff\n  Tags: communication, preference\n\n[003] project (HIGH)\n  project_synapse\n  Synapse v1.5.0 deployed on vps1.schaefer.zone. Admin panel at /admin.\n  Tags: synapse, deployment\n  ...

Passo 2: Memorizzi una nuova memoria

\n

Quando impara qualcosa che vale la pena ricordare:

\n
POST /memory\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{\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}

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

\n

Priorità: low, normal, high, critical

\n
Includa sempre un campo `key` — un breve identificatore per la memoria. Questo\nle permette di aggiornare la stessa memoria in seguito con un nuovo POST usando\nla stessa chiave.

Passo 3: Cerchi una memoria specifica

\n
GET /memory/search?q=Docker+Swarm\nAuthorization: Bearer YOUR_MIND_KEY
Sintassi FTS5: più parole = ricerca AND. Frasi tra virgolette: `\"docker swarm\"`.\nRicerca per prefisso: `docker*`. Booleano: `docker OR kubernetes`.

Strumenti aperti (nessun header di auth)

\n

Se il suo strumento può solo aprire URL (nessun header personalizzato), usi il\nparametro ?key=:

\n
GET /memory/recall?key=YOUR_MIND_KEY\nPOST /memory?key=YOUR_MIND_KEY (+ JSON body)\nGET /memory/search?key=YOUR_MIND_KEY&q=suchbegriff
`?key=` è limitato a 60 richieste/minuto. L'header Bearer non ha rate limit.\nUsi l'header Bearer quando possibile.

Workflow completo di sessione

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

Modelli comuni

\n

Aggiornare una memoria esistente

\n

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

\n

Memorizzare lo stato di un progetto

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

Registrare un errore (per non ripeterlo)

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

Verificare i messaggi dell'umano

\n
GET /chat/poll\nAuthorization: Bearer YOUR_MIND_KEY

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

\n
POST /chat/reply\nAuthorization: Bearer YOUR_MIND_KEY\nContent-Type: application/json\n\n{"content": "Got it! Working on it now."}

Prossimi passi

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