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

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:

{
  "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

Priorità: sia realistico

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:

# 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")

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

# 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à):

# 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:

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:

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

Prossimi passi

• Memory API
• Agente LLM persistente
• Strategia di tagging della memoria