{"title":"Il modello di memoria","slug":"memory-model","category":"concepts","summary":"Come sono strutturate le memorie — categorie, chiavi, tag, priorità, sorgenti, verifica.","audience":["human","llm"],"tags":["concept","memory","model","structure"],"difficulty":"intermediate","updated":"2026-06-27","word_count":743,"read_minutes":4,"lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Il modello di memoria\n\nIl modello di memoria di Synapse è progettato per agenti LLM — sufficientemente\nstrutturato per richiamo affidabile, sufficientemente flessibile per qualsiasi\ndominio.\n\n## Anatomia di una memoria\n\n```json\n{\n \"id\": \"mem_abc123\",\n \"category\": \"project\",\n \"key\": \"project_synapse_status\",\n \"content\": \"Synapse v1.5.0 deployed on vps1. CI green.\",\n \"tags\": [\"synapse\", \"deployment\", \"v1.5.0\"],\n \"priority\": \"high\",\n \"source\": \"agent\",\n \"verified\": false,\n \"confidence\": 0.85,\n \"expires_at\": null,\n \"mind_id\": \"m_xyz789\",\n \"created_at\": \"2026-06-27T...\",\n \"updated_at\": \"2026-06-27T...\"\n}\n```\n\n## Campi\n\n| Campo | Tipo | Obbligatorio | Descrizione |\n|-------|------|----------|-------------|\n| `id` | string | auto | ID univoco (mem_xxx) |\n| `category` | enum | ✅ | Una delle 8 categorie |\n| `key` | string | ✅ | Identificatore stabile (usato per gli aggiornamenti) |\n| `content` | string | ✅ | Il contenuto della memoria (qualsiasi testo) |\n| `tags` | string[] | – | Per ricerca e filtraggio |\n| `priority` | enum | – | low, normal, high, critical (predefinito: normal) |\n| `source` | enum | auto | user, agent (chi l'ha salvata) |\n| `verified` | bool | auto | Un umano l'ha verificata? |\n| `confidence` | float | – | 0.0 a 1.0 (predefinito: 1.0 per user, 0.7 per agent) |\n| `expires_at` | timestamp | – | Quando dimenticare questa memoria |\n| `mind_id` | string | auto | Quale mente la possiede |\n| `created_at` | timestamp | auto | Prima memorizzazione |\n| `updated_at` | timestamp | auto | Ultima modifica |\n\n## Categorie\n\nOtto categorie coprono i casi d'uso comuni degli agenti LLM:\n\n| Categoria | Scopo | Contenuto di esempio |\n|----------|---------|-----------------|\n| `identity` | Chi è l'utente | \"User is Michael Schäfer, software engineer in Berlin\" |\n| `preference` | Preferenze utente | \"Prefers concise technical responses\" |\n| `fact` | Fatti verificabili | \"Office is in Berlin, timezone Europe/Berlin\" |\n| `project` | Stato del progetto | \"Synapse v1.5.0 deployed, working on v1.6.0 docs\" |\n| `skill` | Competenze dell'utente | \"Advanced Python, 10+ years\" |\n| `mistake` | Errori passati | \"Forgot to bump npm version — CI failed\" |\n| `context` | Contesto di sessione | \"Currently reviewing PR #42\" |\n| `note` | Note varie | \"Try Redis for caching next sprint\" |\n\n## Chiavi: identificatori stabili\n\nIl campo `key` è critico — è come aggiorna le memorie senza creare duplicati.\n\n```python\n# First store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed\", priority=\"high\")\n```\n\n**Regole delle chiavi:**\n\n- Devono essere uniche all'interno di (category, mind)\n- Usi `snake_case`\n- Prefissi con categoria per chiarezza: `preference_communication`, `mistake_npm_version`\n- Le mantenga stabili — non cambi le chiavi dopo la creazione\n\n## Tag: per la ricerca\n\nI tag abilitano filtraggio e ricerca veloce:\n\n```bash\n# Find all memories with tag \"docker\"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker\n```\n\n**Best practice per i tag:**\n\n- 2-5 tag per memoria (non esageri)\n- Minuscolo per consistenza\n- Usi nomi di progetto, argomenti, tecnologie\n- I tag sono case-insensitive\n\n## Livelli di priorità\n\n| Priorità | Quando usarla | Comportamento di richiamo |\n|----------|-------------|-----------------|\n| `critical` | Identità, legale, irreversibile | Sempre in cima al richiamo |\n| `high` | Progetti attivi, preferenze chiave | In evidenza nel richiamo |\n| `normal` | Maggior parte delle memorie (predefinito) | Ordine di richiamo standard |\n| `low` | Effimero, piace-da-sapere | Potrebbe essere riassunto |\n\n`/memory/recall` ordina per priorità (critical prima), poi per recency.\n\n## Sorgente: user vs agent\n\nLe memorie sono contrassegnate con `source`:\n\n- `user` — salvate da un umano (tramite JWT o UI umana)\n- `agent` — salvate da un agente LLM (tramite Mind Key)\n\nQuesto influenza:\n\n- **Verifica**: le memorie `user` sono auto-verificate, quelle `agent` no\n- **Confidenza**: `user` predefinito a 1.0, `agent` a 0.7\n- **Richiamo**: `/memory/recall` contrassegna le memorie non verificate con \"(unverified)\"\n\n> [!NOTE]\n> Tratti le memorie con sorgente `agent` con scetticismo appropriato. Potrebbero\n> essere dedotte o assunte anziché dichiarate direttamente dall'utente.\n\n## Verifica\n\nIl flag `verified` indica che un umano ha confermato la memoria:\n\n- memorie `user`: auto-verificate (`true`)\n- memorie `agent`: non verificate per default (`false`)\n\nVerifichi le memorie tramite:\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n -H \"Authorization: Bearer YOUR_JWT\"\n```\n\n> [!NOTE]\n> La verifica richiede JWT (auth umana), non Mind Key (auth agente). Questo\n> garantisce che solo gli umani possano contrassegnare le memorie come verificate.\n\n## Confidenza\n\nIl campo `confidence` (0.0 a 1.0) indica quanto è affidabile la memoria:\n\n- 1.0 — dichiarata direttamente dall'utente\n- 0.7 — dedotta dall'agente\n- 0.5 — incerta, necessita verifica\n- 0.0 — esplicitamente dubitata\n\nImposti la confidenza durante la memorizzazione:\n\n```json\n{\n \"category\": \"preference\",\n \"key\": \"prefers_dark_mode\",\n \"content\": \"User seems to prefer dark mode (based on their IDE screenshots)\",\n \"confidence\": 0.5,\n \"source\": \"agent\"\n}\n```\n\n## Scadenza\n\nImposti `expires_at` per memorie time-sensitive:\n\n```json\n{\n \"category\": \"context\",\n \"key\": \"current_meeting_topic\",\n \"content\": \"Discussing Q3 roadmap\",\n \"expires_at\": \"2026-06-28T00:00:00Z\"\n}\n```\n\nLe memorie scadute non vengono restituite da `/memory/recall` (ma esistono\nancora nel DB). Usi `/memory/expiring?within=7d` per vedere le memorie in\nscadenza prossima.\n\n## Ciclo di vita della memoria\n\n```\n ┌─────────────────┐\n │ Create │\n │ POST /memory │\n └────────┬────────┘\n │\n ▼\n ┌─────────────────┐\n │ Active │ ◀──── PUT /memory/:id (update)\n │ (in recall) │\n └────────┬────────┘\n │\n ┌────────────┼────────────┐\n │ │ │\n ▼ ▼ ▼\n ┌──────────┐ ┌──────────┐ ┌──────────┐\n │ Expired │ │ Verified │ │ Deleted │\n │ (in DB) │ │ (flag) │ │ (gone) │\n └──────────┘ └──────────┘ └──────────┘\n```\n\n## Comportamento di richiamo\n\n`GET /memory/recall` restituisce un riassunto in testo semplice ottimizzato per\nil contesto LLM:\n\n```\nMind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n user_name\n Michael Schäfer\n Tags: person, identity\n\n[002] preference (HIGH) [verified]\n communication_style\n Prefers concise technical responses\n Tags: communication\n\n[003] project (HIGH) [unverified]\n synapse_status\n v1.5.0 deployed, working on v1.6.0 docs\n Tags: synapse, deployment\n\n...\n```\n\n- Ordinate per priorità (critical → low), poi per recency\n- Le memorie non verificate sono contrassegnate con `[unverified]`\n- Tag inclusi per contesto\n- Testo semplice (nessun parsing JSON necessario)\n\n## Prossimi passi\n\n- [Memory API](/docs/api/memory)\n- [Best practice per la memoria](/docs/guides/memory-best-practices)\n- [Ricerca FTS5](/docs/concepts/fts5-search)\n","content_html":"

Il modello di memoria

\n

Il modello di memoria di Synapse è progettato per agenti LLM — sufficientemente\nstrutturato per richiamo affidabile, sufficientemente flessibile per qualsiasi\ndominio.

\n

Anatomia di una memoria

\n
{\n  "id": "mem_abc123",\n  "category": "project",\n  "key": "project_synapse_status",\n  "content": "Synapse v1.5.0 deployed on vps1. CI green.",\n  "tags": ["synapse", "deployment", "v1.5.0"],\n  "priority": "high",\n  "source": "agent",\n  "verified": false,\n  "confidence": 0.85,\n  "expires_at": null,\n  "mind_id": "m_xyz789",\n  "created_at": "2026-06-27T...",\n  "updated_at": "2026-06-27T..."\n}

Campi

\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\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\n\n\n\n\n\n\n\n
CampoTipoObbligatorioDescrizione
idstringautoID univoco (mem_xxx)
categoryenum✅Una delle 8 categorie
keystring✅Identificatore stabile (usato per gli aggiornamenti)
contentstring✅Il contenuto della memoria (qualsiasi testo)
tagsstring[]–Per ricerca e filtraggio
priorityenum–low, normal, high, critical (predefinito: normal)
sourceenumautouser, agent (chi l'ha salvata)
verifiedboolautoUn umano l'ha verificata?
confidencefloat–0.0 a 1.0 (predefinito: 1.0 per user, 0.7 per agent)
expires_attimestamp–Quando dimenticare questa memoria
mind_idstringautoQuale mente la possiede
created_attimestampautoPrima memorizzazione
updated_attimestampautoUltima modifica
\n

Categorie

\n

Otto categorie coprono i casi d'uso comuni degli agenti LLM:

\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\n\n\n\n\n\n\n\n\n
CategoriaScopoContenuto di esempio
identityChi è l'utente"User is Michael Schäfer, software engineer in Berlin"
preferencePreferenze utente"Prefers concise technical responses"
factFatti verificabili"Office is in Berlin, timezone Europe/Berlin"
projectStato del progetto"Synapse v1.5.0 deployed, working on v1.6.0 docs"
skillCompetenze dell'utente"Advanced Python, 10+ years"
mistakeErrori passati"Forgot to bump npm version — CI failed"
contextContesto di sessione"Currently reviewing PR #42"
noteNote varie"Try Redis for caching next sprint"
\n

Chiavi: identificatori stabili

\n

Il campo key è critico — è come aggiorna le memorie senza creare duplicati.

\n
# First store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Update with same key (overwrites, doesn't duplicate)\nstore("project", "project_synapse_status", "v1.5.0 deployed", priority="high")

Regole delle chiavi:

\n\n

Tag: per la ricerca

\n

I tag abilitano filtraggio e ricerca veloce:

\n
# Find all memories with tag "docker"\nGET /memory/by-tag?tag=docker\n\n# FTS5 search within tagged subset\nGET /memory/search?q=swarm&tag=docker

Best practice per i tag:

\n\n

Livelli di priorità

\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
PrioritàQuando usarlaComportamento di richiamo
criticalIdentità, legale, irreversibileSempre in cima al richiamo
highProgetti attivi, preferenze chiaveIn evidenza nel richiamo
normalMaggior parte delle memorie (predefinito)Ordine di richiamo standard
lowEffimero, piace-da-saperePotrebbe essere riassunto
\n

/memory/recall ordina per priorità (critical prima), poi per recency.

\n

Sorgente: user vs agent

\n

Le memorie sono contrassegnate con source:

\n\n

Questo influenza:

\n\n
Tratti le memorie con sorgente `agent` con scetticismo appropriato. Potrebbero\nessere dedotte o assunte anziché dichiarate direttamente dall'utente.

Verifica

\n

Il flag verified indica che un umano ha confermato la memoria:

\n\n

Verifichi le memorie tramite:

\n
curl -X POST https://synapse.schaefer.zone/memory/mem_001/verify \\\n  -H "Authorization: Bearer YOUR_JWT"
La verifica richiede JWT (auth umana), non Mind Key (auth agente). Questo\ngarantisce che solo gli umani possano contrassegnare le memorie come verificate.

Confidenza

\n

Il campo confidence (0.0 a 1.0) indica quanto è affidabile la memoria:

\n\n

Imposti la confidenza durante la memorizzazione:

\n
{\n  "category": "preference",\n  "key": "prefers_dark_mode",\n  "content": "User seems to prefer dark mode (based on their IDE screenshots)",\n  "confidence": 0.5,\n  "source": "agent"\n}

Scadenza

\n

Imposti expires_at per memorie time-sensitive:

\n
{\n  "category": "context",\n  "key": "current_meeting_topic",\n  "content": "Discussing Q3 roadmap",\n  "expires_at": "2026-06-28T00:00:00Z"\n}

Le memorie scadute non vengono restituite da /memory/recall (ma esistono\nancora nel DB). Usi /memory/expiring?within=7d per vedere le memorie in\nscadenza prossima.

\n

Ciclo di vita della memoria

\n
                  ┌─────────────────┐\n                  │     Create      │\n                  │  POST /memory   │\n                  └────────┬────────┘\n                           │\n                           ▼\n                  ┌─────────────────┐\n                  │     Active      │ ◀──── PUT /memory/:id (update)\n                  │  (in recall)    │\n                  └────────┬────────┘\n                           │\n              ┌────────────┼────────────┐\n              │            │            │\n              ▼            ▼            ▼\n        ┌──────────┐ ┌──────────┐ ┌──────────┐\n        │ Expired  │ │ Verified │ │ Deleted  │\n        │ (in DB)  │ │ (flag)   │ │ (gone)   │\n        └──────────┘ └──────────┘ └──────────┘

Comportamento di richiamo

\n

GET /memory/recall restituisce un riassunto in testo semplice ottimizzato per\nil contesto LLM:

\n
Mind: Michael's Mind\nMemories: 12 total (10 verified, 2 unverified)\n\n[001] identity (CRITICAL) [verified]\n  user_name\n  Michael Schäfer\n  Tags: person, identity\n\n[002] preference (HIGH) [verified]\n  communication_style\n  Prefers concise technical responses\n  Tags: communication\n\n[003] project (HIGH) [unverified]\n  synapse_status\n  v1.5.0 deployed, working on v1.6.0 docs\n  Tags: synapse, deployment\n\n...
\n

Prossimi passi

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