{"title":"Best practice per la memoria","slug":"memory-best-practices","category":"guides","summary":"Come strutturare le memorie per richiamo efficace — categorie, chiavi, tag, priorità.","audience":["human","llm"],"tags":["guide","memory","best-practices","patterns"],"difficulty":"intermediate","updated":"2026-06-27","word_count":649,"read_minutes":3,"lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Best practice per la memoria\n\nCome struttura le memorie determina quanto sono utili. Questa guida copre\nmodelli per categorizzare, taggare e dare priorità alle memorie così l'LLM può\nrichiamare l'informazione giusta al momento giusto.\n\n## Categorie: scelga la più specifica\n\n| Categoria | Usi per | Esempio |\n|----------|---------|---------|\n| `identity` | Nome utente, ruolo, info contatto | `\"user_name\": \"Michael Schäfer\"` |\n| `preference` | Piaceri, dispiaceri, stile di lavoro | `\"communication\": \"Prefers concise responses\"` |\n| `fact` | Fatti verificabili | `\"office_location\": \"Berlin, Germany\"` |\n| `project` | Stato del progetto, decisioni | `\"project_synapse\": \"v1.5.0 deployed\"` |\n| `skill` | Competenze dell'utente | `\"skill_python\": \"Advanced, 10+ years\"` |\n| `mistake` | Errori passati da evitare | `\"mistake_npm_version\": \"Always bump version\"` |\n| `context` | Contesto rilevante per la sessione | `\"current_focus\": \"Working on docs system\"` |\n| `note` | Note varie | `\"note_idea\": \"Try Redis for caching\"` |\n\n> [!TIP]\n> In caso di dubbio, usi `fact` per informazioni verificabili e `note` per\n> tutto il resto. Non ecceda con le categorie — meglio un `fact` chiaro che un\n> `context` confusionario.\n\n## Chiavi: identificatori significativi\n\nIl campo `key` è l'identificatore della memoria. Usi chiavi significative e\nstabili:\n\n**Chiavi buone:**\n- `user_name`\n- `project_synapse_status`\n- `preference_communication_style`\n- `mistake_npm_version_bump`\n\n**Chiavi cattive:**\n- `mem_001` (non significativa)\n- `temp` (non descrittiva)\n- `2026-06-27-note` (la data non aiuta il richiamo)\n\n### Convenzioni per i nomi delle chiavi\n\n- `snake_case` (minuscolo con underscore)\n- Prefisso con categoria: `preference_*`, `project_*`, `mistake_*`\n- Usi sostantivi descrittivi, non verbi\n- Meno di 50 caratteri\n\n## Tag: per ricerca e filtraggio\n\nI tag abilitano filtraggio e ricerca veloce. Aggiunga 2-5 tag per memoria:\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.\",\n \"tags\": [\"synapse\", \"deployment\", \"status\", \"v1.5.0\"]\n}\n```\n\n### Modelli di tag\n\n- **Nomi di progetto**: `synapse`, `synapse-mcp`, `synapse-chat`\n- **Argomenti**: `deployment`, `ci`, `database`, `auth`\n- **Stato**: `active`, `completed`, `blocked`\n- **Indicatori di priorità**: `urgent`, `long-term`\n\n> [!NOTE]\n> I tag sono case-insensitive. Usi minuscolo per consistenza.\n\n## Priorità: sia realistico\n\n| Priorità | Usi per | % delle memorie |\n|----------|---------|---------------|\n| `critical` | Identità utente, info legali, decisioni irreversibili | ~5% |\n| `high` | Progetti attivi, preferenze importanti | ~20% |\n| `normal` | Maggior parte dei fatti, note, contesto | ~65% |\n| `low` | Effimero, piace-da-sapere | ~10% |\n\n> [!WARNING]\n> Non contrassegni tutto come `critical`. Se tutto è critical, nulla lo è.\n> Riservi `critical` per cose che causerebbero danno reale se dimenticate.\n\n## Quando memorizzare vs non memorizzare\n\n### Memorizzi sempre\n\n- Identità utente (nome, email, ruolo)\n- Preferenze long-term\n- Decisioni di progetto e ragionamento\n- Errori passati e lezioni apprese\n- Impegni presi con l'utente\n\n### Non memorizzi\n\n- Stato transiente (usi variabili invece)\n- Cronologia conversazione verbatim (la gestisce il sistema chat)\n- Dati sensibili (password, API key)\n- Fatti facilmente derivabili (data corrente, contenuto file)\n- Contesto effimero (usi categoria `context` con priorità bassa)\n\n## Aggiornare le memorie\n\nPOST `/memory` con la stessa `category` + `key` aggiorna la memoria esistente:\n\n```python\n# Initial store\nstore(\"project\", \"project_synapse_status\", \"v1.4.0 deployed\", priority=\"high\")\n\n# Later: update with same key\nstore(\"project\", \"project_synapse_status\", \"v1.5.0 deployed. CI green.\", priority=\"high\")\n```\n\n> [!TIP]\n> Usi chiavi stabili così può aggiornare senza creare duplicati. L'LLM\n> dovrebbe fare nuovamente POST della stessa chiave quando le info cambiano,\n> non creare nuove memorie.\n\n## Ciclo di vita della memoria\n\n```\nCreate → Active → Stale → Archive → Delete\n```\n\n- **Create**: POST /memory con contesto completo\n- **Active**: Richiama frequentemente, aggiorna come necessario\n- **Stale**: Ancora rilevante ma non attivamente usata (priorità più bassa?)\n- **Archive**: Imposti priorità a `low`, mantenga per riferimento storico\n- **Delete**: DELETE /memory/:id quando non più rilevante\n\n### Pulizia periodica\n\n```python\n# Find memories not updated in 90 days\nold_memories = requests.get(\n f\"{URL}/memory/search?q=*\",\n headers={\"Authorization\": f\"Bearer {KEY}\"}\n)\n\nfor mem in old_memories[\"results\"]:\n if is_stale(mem, days=90):\n # Either delete or lower priority\n if is_obsolete(mem):\n delete_memory(mem[\"id\"])\n else:\n update_memory(mem[\"id\"], priority=\"low\")\n```\n\n## Modello: ereditarietà della memoria\n\nPer contesto gerarchico (progetto → sottoprogetto → attività):\n\n```python\n# Parent project\nstore(\"project\", \"project_synapse\", \"Main Synapse project\", \n tags=[\"synapse\", \"parent\"], priority=\"high\")\n\n# Sub-project (tags link to parent)\nstore(\"project\", \"project_synapse_docs\", \"Docs system for Synapse\",\n tags=[\"synapse\", \"docs\", \"synapse-parent\"], priority=\"high\")\n\n# Specific task (tags link to sub-project)\nstore(\"project\", \"task_docs_loader\", \"Implement docs-loader.ts\",\n tags=[\"synapse\", \"docs\", \"task\"], priority=\"normal\")\n```\n\nL'LLM può poi cercare `q=synapse+docs` per trovare tutte le memorie correlate.\n\n## Modello: log delle decisioni\n\nMemorizzi le decisioni con il ragionamento così l'LLM non le ridiscute:\n\n```python\nstore(\"fact\", \"decision_postgres_over_sqlite\",\n \"Chose PostgreSQL over SQLite for production. Reason: concurrent writes, \"\n \"FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.\",\n tags=[\"decision\", \"database\", \"postgres\", \"sqlite\"],\n priority=\"high\")\n```\n\n## Modello: evitamento degli errori\n\nMemorizzi gli errori con istruzioni specifiche di evitamento:\n\n```python\nstore(\"mistake\", \"mistake_forget_version_bump\",\n \"Forgot to bump package.json version after changes. npm publish failed. \"\n \"FIX: Always run `npm version patch` before pushing. \"\n \"CI fails with 'version already exists' if you forget.\",\n tags=[\"npm\", \"ci\", \"publish\", \"version\"],\n priority=\"high\")\n```\n\n## Anti-pattern da evitare\n\n> [!WARNING]\n> - **Memorizzare log di conversazione** — il sistema chat lo gestisce\n> - **Memorizzare file interi** — usi lo script store o storage esterno\n> - **Memorizzare stato effimero** — usi variabili\n> - **Memorizzare segreti** — usi variabili di ambiente\n> - **Duplicare memorie** — usi chiavi stabili\n> - **Eccesso di tag** — 2-5 tag per memoria è ideale\n> - **Tutto è critical** — sia realistico con le priorità\n\n## Prossimi passi\n\n- [Memory API](/docs/api/memory)\n- [Agente LLM persistente](/docs/guides/persistent-llm-agent)\n- [Strategia di tagging della memoria](/docs/llm-cookbook/memory-tagging-strategy)\n","content_html":"

Best practice per la memoria

\n

Come struttura le memorie determina quanto sono utili. Questa guida copre\nmodelli per categorizzare, taggare e dare priorità alle memorie così l'LLM può\nrichiamare l'informazione giusta al momento giusto.

\n

Categorie: scelga la più specifica

\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
CategoriaUsi perEsempio
identityNome utente, ruolo, info contatto"user_name": "Michael Schäfer"
preferencePiaceri, dispiaceri, stile di lavoro"communication": "Prefers concise responses"
factFatti verificabili"office_location": "Berlin, Germany"
projectStato del progetto, decisioni"project_synapse": "v1.5.0 deployed"
skillCompetenze dell'utente"skill_python": "Advanced, 10+ years"
mistakeErrori passati da evitare"mistake_npm_version": "Always bump version"
contextContesto rilevante per la sessione"current_focus": "Working on docs system"
noteNote varie"note_idea": "Try Redis for caching"
\n
In caso di dubbio, usi `fact` per informazioni verificabili e `note` per\ntutto il resto. Non ecceda con le categorie — meglio un `fact` chiaro che un\n`context` confusionario.

Chiavi: identificatori significativi

\n

Il campo key è l'identificatore della memoria. Usi chiavi significative e\nstabili:

\n

Chiavi buone:

\n\n

Chiavi cattive:

\n\n

Convenzioni per i nomi delle chiavi

\n\n

Tag: per ricerca e filtraggio

\n

I tag abilitano filtraggio e ricerca veloce. Aggiunga 2-5 tag per memoria:

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

Modelli di tag

\n\n
I tag sono case-insensitive. Usi minuscolo per consistenza.

Priorità: sia realistico

\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àUsi per% delle memorie
criticalIdentità utente, info legali, decisioni irreversibili~5%
highProgetti attivi, preferenze importanti~20%
normalMaggior parte dei fatti, note, contesto~65%
lowEffimero, piace-da-sapere~10%
\n
Non contrassegni tutto come `critical`. Se tutto è critical, nulla lo è.\nRiservi `critical` per cose che causerebbero danno reale se dimenticate.

Quando memorizzare vs non memorizzare

\n

Memorizzi sempre

\n\n

Non memorizzi

\n\n

Aggiornare le memorie

\n

POST /memory con la stessa category + key aggiorna la memoria esistente:

\n
# Initial store\nstore("project", "project_synapse_status", "v1.4.0 deployed", priority="high")\n\n# Later: update with same key\nstore("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
Usi chiavi stabili così può aggiornare senza creare duplicati. L'LLM\ndovrebbe fare nuovamente POST della stessa chiave quando le info cambiano,\nnon creare nuove memorie.

Ciclo di vita della memoria

\n
Create → Active → Stale → Archive → Delete
\n

Pulizia periodica

\n
# Find memories not updated in 90 days\nold_memories = requests.get(\n    f"{URL}/memory/search?q=*",\n    headers={"Authorization": f"Bearer {KEY}"}\n)\n\nfor mem in old_memories["results"]:\n    if is_stale(mem, days=90):\n        # Either delete or lower priority\n        if is_obsolete(mem):\n            delete_memory(mem["id"])\n        else:\n            update_memory(mem["id"], priority="low")

Modello: ereditarietà della memoria

\n

Per contesto gerarchico (progetto → sottoprogetto → attività):

\n
# Parent project\nstore("project", "project_synapse", "Main Synapse project", \n      tags=["synapse", "parent"], priority="high")\n\n# Sub-project (tags link to parent)\nstore("project", "project_synapse_docs", "Docs system for Synapse",\n      tags=["synapse", "docs", "synapse-parent"], priority="high")\n\n# Specific task (tags link to sub-project)\nstore("project", "task_docs_loader", "Implement docs-loader.ts",\n      tags=["synapse", "docs", "task"], priority="normal")

L'LLM può poi cercare q=synapse+docs per trovare tutte le memorie correlate.

\n

Modello: log delle decisioni

\n

Memorizzi le decisioni con il ragionamento così l'LLM non le ridiscute:

\n
store("fact", "decision_postgres_over_sqlite",\n      "Chose PostgreSQL over SQLite for production. Reason: concurrent writes, "\n      "FTS5 native support, better backup story. Date: 2026-06-15. Decided by: Michael.",\n      tags=["decision", "database", "postgres", "sqlite"],\n      priority="high")

Modello: evitamento degli errori

\n

Memorizzi gli errori con istruzioni specifiche di evitamento:

\n
store("mistake", "mistake_forget_version_bump",\n      "Forgot to bump package.json version after changes. npm publish failed. "\n      "FIX: Always run `npm version patch` before pushing. "\n      "CI fails with 'version already exists' if you forget.",\n      tags=["npm", "ci", "publish", "version"],\n      priority="high")

Anti-pattern da evitare

\n

Prossimi passi

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