# Best practice per la memoria

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

## Categorie: scelga la più specifica

| Categoria | Usi per | Esempio |
|----------|---------|---------|
| `identity` | Nome utente, ruolo, info contatto | `"user_name": "Michael Schäfer"` |
| `preference` | Piaceri, dispiaceri, stile di lavoro | `"communication": "Prefers concise responses"` |
| `fact` | Fatti verificabili | `"office_location": "Berlin, Germany"` |
| `project` | Stato del progetto, decisioni | `"project_synapse": "v1.5.0 deployed"` |
| `skill` | Competenze dell'utente | `"skill_python": "Advanced, 10+ years"` |
| `mistake` | Errori passati da evitare | `"mistake_npm_version": "Always bump version"` |
| `context` | Contesto rilevante per la sessione | `"current_focus": "Working on docs system"` |
| `note` | Note varie | `"note_idea": "Try Redis for caching"` |

> [!TIP]
> In caso di dubbio, usi `fact` per informazioni verificabili e `note` per
> tutto il resto. Non ecceda con le categorie — meglio un `fact` chiaro che un
> `context` confusionario.

## Chiavi: identificatori significativi

Il campo `key` è l'identificatore della memoria. Usi chiavi significative e
stabili:

**Chiavi buone:**
- `user_name`
- `project_synapse_status`
- `preference_communication_style`
- `mistake_npm_version_bump`

**Chiavi cattive:**
- `mem_001` (non significativa)
- `temp` (non descrittiva)
- `2026-06-27-note` (la data non aiuta il richiamo)

### Convenzioni per i nomi delle chiavi

- `snake_case` (minuscolo con underscore)
- Prefisso con categoria: `preference_*`, `project_*`, `mistake_*`
- Usi sostantivi descrittivi, non verbi
- Meno di 50 caratteri

## Tag: per ricerca e filtraggio

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

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

### Modelli di tag

- **Nomi di progetto**: `synapse`, `synapse-mcp`, `synapse-chat`
- **Argomenti**: `deployment`, `ci`, `database`, `auth`
- **Stato**: `active`, `completed`, `blocked`
- **Indicatori di priorità**: `urgent`, `long-term`

> [!NOTE]
> I tag sono case-insensitive. Usi minuscolo per consistenza.

## Priorità: sia realistico

| Priorità | Usi per | % delle memorie |
|----------|---------|---------------|
| `critical` | Identità utente, info legali, decisioni irreversibili | ~5% |
| `high` | Progetti attivi, preferenze importanti | ~20% |
| `normal` | Maggior parte dei fatti, note, contesto | ~65% |
| `low` | Effimero, piace-da-sapere | ~10% |

> [!WARNING]
> Non contrassegni tutto come `critical`. Se tutto è critical, nulla lo è.
> Riservi `critical` per cose che causerebbero danno reale se dimenticate.

## Quando memorizzare vs non memorizzare

### Memorizzi sempre

- Identità utente (nome, email, ruolo)
- Preferenze long-term
- Decisioni di progetto e ragionamento
- Errori passati e lezioni apprese
- Impegni presi con l'utente

### Non memorizzi

- Stato transiente (usi variabili invece)
- Cronologia conversazione verbatim (la gestisce il sistema chat)
- Dati sensibili (password, API key)
- Fatti facilmente derivabili (data corrente, contenuto file)
- Contesto effimero (usi categoria `context` con priorità bassa)

## Aggiornare le memorie

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

```python
# Initial store
store("project", "project_synapse_status", "v1.4.0 deployed", priority="high")

# Later: update with same key
store("project", "project_synapse_status", "v1.5.0 deployed. CI green.", priority="high")
```

> [!TIP]
> Usi chiavi stabili così può aggiornare senza creare duplicati. L'LLM
> dovrebbe fare nuovamente POST della stessa chiave quando le info cambiano,
> non creare nuove memorie.

## Ciclo di vita della memoria

```
Create → Active → Stale → Archive → Delete
```

- **Create**: POST /memory con contesto completo
- **Active**: Richiama frequentemente, aggiorna come necessario
- **Stale**: Ancora rilevante ma non attivamente usata (priorità più bassa?)
- **Archive**: Imposti priorità a `low`, mantenga per riferimento storico
- **Delete**: DELETE /memory/:id quando non più rilevante

### Pulizia periodica

```python
# Find memories not updated in 90 days
old_memories = requests.get(
    f"{URL}/memory/search?q=*",
    headers={"Authorization": f"Bearer {KEY}"}
)

for mem in old_memories["results"]:
    if is_stale(mem, days=90):
        # Either delete or lower priority
        if is_obsolete(mem):
            delete_memory(mem["id"])
        else:
            update_memory(mem["id"], priority="low")
```

## Modello: ereditarietà della memoria

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

```python
# Parent project
store("project", "project_synapse", "Main Synapse project", 
      tags=["synapse", "parent"], priority="high")

# Sub-project (tags link to parent)
store("project", "project_synapse_docs", "Docs system for Synapse",
      tags=["synapse", "docs", "synapse-parent"], priority="high")

# Specific task (tags link to sub-project)
store("project", "task_docs_loader", "Implement docs-loader.ts",
      tags=["synapse", "docs", "task"], priority="normal")
```

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

## Modello: log delle decisioni

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

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

## Modello: evitamento degli errori

Memorizzi gli errori con istruzioni specifiche di evitamento:

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

## Anti-pattern da evitare

> [!WARNING]
> - **Memorizzare log di conversazione** — il sistema chat lo gestisce
> - **Memorizzare file interi** — usi lo script store o storage esterno
> - **Memorizzare stato effimero** — usi variabili
> - **Memorizzare segreti** — usi variabili di ambiente
> - **Duplicare memorie** — usi chiavi stabili
> - **Eccesso di tag** — 2-5 tag per memoria è ideale
> - **Tutto è critical** — sia realistico con le priorità

## Prossimi passi

- [Memory API](/docs/api/memory)
- [Agente LLM persistente](/docs/guides/persistent-llm-agent)
- [Strategia di tagging della memoria](/docs/llm-cookbook/memory-tagging-strategy)