# Sessioni e Memoria ## Sessioni ### Come Funzionano le Sessioni Ogni conversazione con un agente avviene in una **sessione**. Le sessioni sono identificate da chiavi che codificano il contesto, quale agente, quale canale, quale chat. Le sessioni mantengono una trascrizione completa (JSONL solo aggiunta) di tutti i messaggi, le chiamate agli strumenti e i risultati. Questa trascrizione è ciò che fornisce agli agenti il contesto sulla conversazione in corso. ### Chiavi di Sessione Le sessioni vengono instradate automaticamente in base al contesto: | Pattern | Significato | |---------|---------| | `agent:main:main` | Conversazione diretta principale | | `agent:::group:` | Chat di gruppo su un canale specifico | | `agent:::channel:` | Conversazione su canale/stanza | | `cron:` | Esecuzione di un job pianificato | | `hook:` | Esecuzione attivata da webhook | ### Ciclo di Vita delle Sessioni - **Reset giornaliero**, Le sessioni si resettano automaticamente a un orario configurabile (default 4:00 AM locale). Questo crea un contesto di conversazione fresco ogni giorno preservando la cronologia. - **Scadenza per inattività**, Le sessioni che non sono state attive per un periodo configurabile possono essere resettate automaticamente. - **Reset manuale**, Inizia da capo in qualsiasi momento con un comando `/new` o `/reset`. ### Tracciamento dei Token Le sessioni tengono traccia dell'utilizzo cumulativo dei token (input, output, lettura cache, scrittura cache) per il monitoraggio dei costi e la gestione della finestra di contesto. --- ## Compattazione ### Cos'è la Compattazione? Quando una conversazione si avvicina al limite della finestra di contesto del modello, Neotask la **compatta**, riassumendo i messaggi più vecchi in una panoramica condensata e avviando una nuova sessione con quel riassunto più i messaggi recenti. ### Come Funziona 1. **Rilevamento**, Monitora l'utilizzo del contesto (trigger predefinito: 80% della finestra di contesto) 2. **Riassunto**, I messaggi più vecchi vengono riassunti in una voce di compattazione 3. **Nuova sessione**, Una sessione fresca inizia con il riassunto iniettato all'inizio 4. **Preservazione**, Le vecchie trascrizioni vengono conservate nella cronologia ma non vengono più caricate nel contesto ### Configurazione - **Abilitata/disabilitata**, Attiva/disattiva la compattazione automatica - **Soglia**, Percentuale della finestra di contesto che attiva la compattazione (default 80%) - **Messaggi minimi**, Non compattare se ci sono meno di N messaggi ### Compattazione Manuale Puoi attivare la compattazione manualmente in qualsiasi momento con il comando `/compact`. Questo è utile quando vuoi resettare il contesto senza perdere informazioni importanti. --- ## Memoria ### Memoria degli Agenti Ogni agente ha un sistema di memoria per persistere informazioni importanti tra le sessioni: - **MEMORY.md**, Un file markdown nel workspace dell'agente dove vengono archiviati fatti importanti, preferenze e contesto - **Directory memoria**, File aggiuntivi in `memory/` per la conoscenza strutturata ### Ricerca Vettoriale Neotask supporta la ricerca per somiglianza vettoriale sulla memoria dell'agente: 1. **Indicizzazione**, I file di memoria vengono indicizzati usando embedding 2. **Ricerca**, Gli agenti interrogano la memoria con linguaggio naturale ("Cosa ha detto l'utente delle sue preferenze API?") 3. **Richiamo**, I ricordi pertinenti vengono restituiti ordinati per somiglianza ### Plugin Memoria (LanceDB) Il plugin di memoria LanceDB fornisce archiviazione vettoriale avanzata: - Database vettoriale persistente - Dimensione dei chunk e sovrapposizione configurabili - Ricerca per somiglianza efficiente - Re-indicizzazione automatica quando i file di memoria cambiano ### Richiamo Automatico All'avvio della sessione, i ricordi pertinenti possono essere richiamati automaticamente e iniettati nel contesto dell'agente. Questo fornisce agli agenti continuità tra le sessioni senza caricare l'intera cronologia delle conversazioni. --- ## Persistenza delle Sessioni Tutti i dati di sessione vengono archiviati localmente: - **Metadati della sessione**, `sessions.json` traccia le sessioni attive, l'ultima attività, i conteggi dei token e la configurazione - **Trascrizioni**, Trascrizioni individuali delle sessioni archiviate come file `.jsonl` - **Ripristino**, Le sessioni sopravvivono ai riavvii del Gateway senza perdita di dati ### Pulizia - Le sessioni a cui non si accede per un periodo configurabile (default 30 giorni) sono candidabili per la pulizia - La gestione manuale delle sessioni è disponibile tramite l'interfaccia utente o l'API - Le trascrizioni compattate vengono archiviate ma possono essere riviste