simplemem_logo

## Memoria a Lungo Termine Efficiente per Agenti LLM — Testo e Multimodale Archivia, comprimi e recupera memorie a lungo termine con compressione semantica senza perdita. Ora con supporto multimodale per testo, immagini, audio e video.

Compatibile con qualsiasi piattaforma AI che supporta MCP (memoria testuale) o integrazione Python (multimodale completo)

_{Claude Desktop}

_Cursor

_{LM Studio}

_{Cherry Studio}

_{Pacchetto PyPI}

_{+ Qualsiasi Client
MCP}

[🇨🇳 中文](./README.zh-CN.md) • [🇯🇵 日本語](./README.ja.md) • [🇰🇷 한국어](./README.ko.md) • [🇪🇸 Español](./README.es.md) • [🇫🇷 Français](./README.fr.md) • [🇩🇪 Deutsch](./README.de.md) • [🇧🇷 Português](./README.pt-br.md)
[🇷🇺 Русский](./README.ru.md) • [🇸🇦 العربية](./README.ar.md) • **🇮🇹 Italiano** • [🇻🇳 Tiếng Việt](./README.vi.md) • [🇹🇷 Türkçe](./README.tr.md) • [🇬🇧 English](../../README.md)
[![Pagina del Progetto](https://img.shields.io/badge/🎬_DEMO_INTERATTIVA-Visita_il_Nostro_Sito-FF6B6B?style=for-the-badge&labelColor=FF6B6B&color=4ECDC4&logoColor=white)](https://aiming-lab.github.io/SimpleMem-Page)

[🚀 Avvio Rapido](#-avvio-rapido) • [🌟 Panoramica](#-panoramica) • [📦 Installazione](#-installazione) • [🔌 Server MCP](#-server-mcp-memoria-testuale) • [📊 Riproduci](#-riproduci-i-risultati-del-paper) • [📝 Citazione](#-citazione)

## 🔥 Novità - **[05/21/2026]** 📦 **Pacchetto unificato `simplemem` — un solo import, instradamento automatico!** SimpleMem, Omni-SimpleMem e EvolveMem vivono ora in un unico pacchetto. `from simplemem import SimpleMem` seleziona automaticamente il backend testuale o multimodale in base al primo metodo chiamato, e `simplemem.optimize(...)` attiva il ciclo di auto-evoluzione di EvolveMem. Installazione in un solo passaggio con `pip install -e .`. - **[05/14/2026]** 🧬 **EvolveMem (v3.0) — Memoria Auto-Evolutiva tramite AutoResearch!** L'infrastruttura di recupero si auto-evolve ora attraverso una diagnosi a circuito chiuso guidata da LLM. Su LoCoMo, EvolveMem supera la baseline più forte del **+25,7% relativo**; su MemBench, del **+18,9% relativo**. Il sistema scopre dimensioni di recupero completamente nuove, non presenti nel design originale. [Vedi EvolveMem →](../../EvolveMem/) - **[04/02/2026]** 🧠 **Omni-SimpleMem (v2.0) — La Memoria Multimodale è Arrivata!** SimpleMem supporta ora la memoria **testuale, di immagini, audio e video**. Raggiunge **nuovo SOTA su LoCoMo (F1=0,613, +47%)** e **Mem-Gallery (F1=0,810, +51%)** rispetto ai risultati precedentemente migliori. [Vedi Omni-SimpleMem →](../../OmniSimpleMem/) - **[02/09/2026]** 🚀 **Memoria Cross-Sessione — Supera Claude-Mem del 64%!** [Vedi Documentazione Cross-Session →](../../cross/README.md) - **[01/20/2026]** 📦 **SimpleMem è ora disponibile su PyPI!** Installa con `pip install simplemem`. [Vedi Guida all'Utilizzo del Pacchetto →](../PACKAGE_USAGE.md) - **[01/14/2026]** 🎉 **Il Server MCP di SimpleMem è ATTIVO!** Ospitato nel cloud su [mcp.simplemem.cloud](https://mcp.simplemem.cloud). [Vedi Documentazione MCP →](../../MCP/README.md) - **[01/05/2026]** Il paper di SimpleMem è stato pubblicato su [arXiv](https://arxiv.org/abs/2601.02553)! --- ## 📑 Indice dei Contenuti - [🚀 Avvio Rapido](#-avvio-rapido) - [🌟 Panoramica](#-panoramica) - [📦 Installazione](#-installazione) - [🐳 Docker](#-esegui-con-docker) - [🔌 Server MCP](#-server-mcp-memoria-testuale) - [📊 Riproduci i Risultati del Paper](#-riproduci-i-risultati-del-paper) - [🗺️ Roadmap](#️-roadmap) - [📝 Citazione](#-citazione) --- ## 🚀 Avvio Rapido ### 🧠 Comprendere il Flusso di Lavoro di Base Ad alto livello, SimpleMem funziona come un sistema di memoria a lungo termine per agenti basati su LLM. Il flusso di lavoro consiste in tre semplici passaggi: 1. **Archivia informazioni** – I dialoghi o i fatti vengono elaborati e convertiti in memorie strutturate e atomiche. 2. **Indicizza la memoria** – Le memorie archiviate vengono organizzate utilizzando embedding semantici e metadati strutturati. 3. **Recupera la memoria rilevante** – Quando viene effettuata una query, SimpleMem recupera le informazioni archiviate più pertinenti in base al significato anziché alle parole chiave. Questo design consente agli agenti LLM di mantenere il contesto, richiamare le informazioni passate in modo efficiente ed evitare di elaborare ripetutamente la cronologia ridondante. ### 🎓 Utilizzo di Base SimpleMem viene distribuito come singolo pacchetto `simplemem`. La modalità predefinita `mode="auto"` **rileva automaticamente** quale backend utilizzare in base a ciò che chiami — nessuna configurazione manuale necessaria: ```python from simplemem import SimpleMem mem = SimpleMem() # mode="auto" — backend scelto dalla prima chiamata ``` Il primo metodo che chiami determina il backend: | Prima chiamata | Backend selezionato | Perché | |:--|:--|:--| | `add_dialogue()` | **Testuale** (SimpleMem) | API basata su dialogo → modalità testo | | `add_text()` / `add_image()` / `add_audio()` / `add_video()` | **Omni** (Omni-SimpleMem) | API multimodale → modalità omni |

**📝 Auto → Testo** (input solo testo) ```python from simplemem import SimpleMem mem = SimpleMem() # auto mode # add_dialogue() → text backend auto-selected mem.add_dialogue( "Alice", "Bob, let's meet at Starbucks tomorrow at 2pm", "2025-11-15T14:30:00", ) mem.add_dialogue( "Bob", "Sure, I'll bring the market analysis report", "2025-11-15T14:31:00", ) mem.finalize() answer = mem.ask("When and where will Alice and Bob meet?") # → "16 November 2025 at 2:00 PM at Starbucks" ```

**🧠 Auto → Omni** (input multimodale) ```python from simplemem import SimpleMem mem = SimpleMem() # auto mode # add_image() → omni backend auto-selected mem.add_text( "User loves hiking in the Rocky Mountains.", tags=["session_id:D1"], ) mem.add_image("photo.jpg", tags=["session_id:D1"]) mem.add_audio("voice_note.wav", tags=["session_id:D1"]) result = mem.query("What does the user enjoy?", top_k=5) for item in result.items: print(item["summary"]) mem.close() ```

> **💡 Suggerimento**: La modalità auto sceglie il backend più leggero adatto ai tuoi dati. Puoi comunque usare `mode="text"` o `mode="omni"` esplicitamente se preferisci. --- ### 🧬 Avanzato: Ottimizza la Configurazione di Recupero Ottimizza gli iperparametri di recupero offline sul tuo set di sviluppo, poi distribuisci la `Config` risultante per l'inferenza. Questo è un sottile wrapper attorno al ciclo di auto-evoluzione di EvolveMem: ```python import simplemem from simplemem import SimpleMem, load_config # mem è un'istanza SimpleMem finalizzata con memorie già costruite dev_questions = [ ("When is the meeting?", "2pm tomorrow at Starbucks"), ("What should Bob prepare?", "market analysis report"), ] config = simplemem.optimize(mem, dev_questions, max_rounds=3) config.save("my_config.json") # In seguito, distribuisci con la config ottimizzata config = load_config("my_config.json") mem = SimpleMem(config=config) ``` > EvolveMem esegue un ciclo Valuta → Diagnostica → Proponi → Tutela guidato da LLM sulle tue domande di sviluppo, regolando i flag di recupero globali (top_k, modalità di fusione, verifica delle risposte, cicli di riflessione, ...). Per la versione standalone completa con adattatori benchmark e override per categoria, vedi [`EvolveMem/`](../../EvolveMem/). --- ### 🚄 Avanzato: Elaborazione Parallela Per l'elaborazione di dialoghi su larga scala, abilita la modalità parallela: ```python from simplemem import create mem = create( mode="text", clear_db=True, enable_parallel_processing=True, # ⚡ Costruzione memoria parallela max_parallel_workers=8, enable_parallel_retrieval=True, # 🔍 Esecuzione query parallela max_retrieval_workers=4 ) ``` > **💡 Consiglio Pro**: L'elaborazione parallela riduce significativamente la latenza per le operazioni batch! --- ## 🌟 Panoramica **SimpleMem** è uno stack di memoria unificato per agenti LLM, costruito su un principio: archiviare memoria *semanticamente senza perdita* ad alta densità di informazioni, in modo che un agente ricordi di più spendendo molti meno token. Il pacchetto riunisce tre lavori che condividono questo principio ma affrontano parti diverse del problema. ### 📝 SimpleMem: il nucleo di efficienza (testo) La maggior parte dei sistemi di memoria impone un cattivo compromesso. O accumulano passivamente la cronologia delle interazioni grezze (ridondante, vorace di token) oppure eseguono costosi cicli di ragionamento per filtrare il rumore (lenti, costosi). SimpleMem invece comprime le interazioni attraverso una pipeline a tre stadi: | Stadio | Cosa fa | |:--|:--| | **1. Compressione Strutturata Semantica** | Distilla le interazioni non strutturate in unità di memoria compatte (fatti autonomi con coreference risolte e timestamp assoluti), ciascuna indicizzata attraverso più viste complementari per un recupero flessibile. | | **2. Sintesi Semantica Online** | Unisce il contesto correlato all'interno di una sessione in rappresentazioni astratte unificate, eliminando la ridondanza man mano che la memoria viene costruita anziché al momento della query. | | **3. Pianificazione del Recupero Consapevole dell'Intento** | Inferisce l'intento di ricerca dietro una query per decidere *cosa* recuperare e assemblare un contesto preciso e compatto. | Sul benchmark LoCoMo questo offre un guadagno medio di F1 del 26,4% rispetto ai sistemi precedenti, riducendo al contempo il consumo di token al momento dell'inferenza di circa 30 volte. Dettagli sul meccanismo (livelli dell'indice ibrido, esempi di compressione, pianificazione del recupero): [**Memoria testuale SimpleMem →**](../text-memory.md). ### 🧠 Omni-SimpleMem: memoria multimodale (testo, immagine, audio, video) Omni-SimpleMem estende la filosofia "compressione prima di tutto" a quattro modalità, costruita su tre principi: **Ingestione Selettiva** (filtraggio guidato dall'entropia per modalità), **Recupero Progressivo** (FAISS + BM25 ibrido con espansione piramidale del budget di token), e **Augmentazione con Grafo di Conoscenza** (ragionamento multi-hop cross-modale). Anziché essere progettata a mano, la sua architettura è stata *scoperta* da una pipeline di ricerca autonoma che ha eseguito circa 50 esperimenti su due benchmark, diagnosticando modalità di fallimento, proponendo modifiche architetturali e persino riparando bug della pipeline dei dati senza intervento umano nel ciclo interno. Significativamente, le correzioni dei bug e le modifiche architetturali hanno ciascuna contribuito più di tutta l'ottimizzazione degli iperparametri combinata, portando il sistema da una baseline naïve allo stato dell'arte sia su LoCoMo che su Mem-Gallery. Documentazione completa: [**Omni-SimpleMem →**](../../OmniSimpleMem/). ### 🧬 EvolveMem: recupero auto-evolutivo EvolveMem colma un punto cieco condiviso da quasi ogni sistema di memoria: il contenuto archiviato si evolve, ma il *macchinario di recupero* (funzioni di scoring, strategie di fusione, politiche di generazione delle risposte) rimane congelato dopo il deployment. EvolveMem esegue un processo AutoResearch a circuito chiuso (**Valuta → Diagnostica → Proponi → Tutela → Ripeti**) in cui un LLM diagnostica i fallimenti per domanda e propone modifiche alla configurazione, tutelate da rollback automatico in caso di regressione e incentivi all'esplorazione durante la stagnazione. Scopre nuove dimensioni di recupero (decomposizione della query, scambio di entità, verifica delle risposte) non presenti nel design originale, migliora LoCoMo del 25,7% relativo rispetto alla baseline più forte, e le sue configurazioni evolute si trasferiscono positivamente tra i benchmark. Documentazione completa: [**EvolveMem →**](../../EvolveMem/). ### Come si incastrano `from simplemem import SimpleMem` ti offre il nucleo testuale con instradamento automatico verso il backend multimodale, e `simplemem.optimize(...)` attiva EvolveMem per ottimizzare il recupero sui tuoi dati. Un pacchetto, un modello mentale: comprimi senza perdita, recupera per intento e lascia che il sistema continui a migliorarsi da solo. --- ## 📦 Installazione ### 📝 Note per i Nuovi Utenti - Assicurati di usare **Python 3.10+ nel tuo ambiente attivo**, non solo installato globalmente. - Una chiave API compatibile con OpenAI deve essere configurata **prima di eseguire qualsiasi costruzione di memoria o recupero**, altrimenti l'inizializzazione potrebbe fallire. - Quando si utilizzano provider non-OpenAI (ad es. Qwen o Azure OpenAI), verifica sia il nome del modello che `OPENAI_BASE_URL` in `config.py`. - Per dataset di dialoghi di grandi dimensioni, abilitare l'elaborazione parallela può ridurre significativamente il tempo di costruzione della memoria. ### 📋 Requisiti - 🐍 Python 3.10+ - 🔑 API compatibile con OpenAI (OpenAI, Qwen, Azure OpenAI, ecc.) ### 🛠️ Configurazione ```bash # 📥 Clona il repository git clone https://github.com/aiming-lab/SimpleMem.git cd SimpleMem # 📦 Installa le dipendenze (versioni bloccate) pip install -r requirements.txt # — OPPURE — installa come pacchetto modificabile pip install -e . # predefinito: testo + multimodale + evolver pip install -e ".[server]" # + server MCP / HTTP (mcp, fastapi, ...) pip install -e ".[all]" # tutto, inclusi gli strumenti di sviluppo # ⚙️ Configura le impostazioni API cp config.py.example config.py # Modifica config.py con la tua chiave API e le preferenze ``` ### ⚙️ Esempio di Configurazione ```python # config.py OPENAI_API_KEY = "your-api-key" OPENAI_BASE_URL = None # o endpoint personalizzato per Qwen/Azure LLM_MODEL = "gpt-4.1-mini" EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B" # Recupero all'avanguardia ``` --- ## 🐳 Esegui con Docker Il **Server MCP** può essere eseguito in Docker per un ambiente coerente e isolato. I dati (LanceDB e il DB utente) vengono persistiti in un volume host. ### Prerequisiti - [Docker](https://docs.docker.com/get-docker/) e [Docker Compose](https://docs.docker.com/compose/install/) ### Avvio rapido ```bash # Dalla radice del repository docker compose up -d ``` - **Web UI:** http://localhost:8000/ - **REST API:** http://localhost:8000/api/ - **MCP (SSE):** http://localhost:8000/mcp/sse?token=<TOKEN> I dati sono memorizzati in `./data` sull'host (creato automaticamente). ### Configurazione personalizzata 1. Copia il template dell'ambiente e modificalo: ```bash cp .env.example .env # Modifica .env: imposta JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, URL dei modelli, ecc. ``` 2. Esegui con il file env: ```bash docker compose --env-file .env up -d ``` ### Utilizzo di Ollama sull'host Quando `LLM_PROVIDER=ollama` e Ollama gira sulla tua macchina (non in Docker), imposta in `.env`: ```bash LLM_PROVIDER=ollama OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 ``` Su Linux, `host.docker.internal` è abilitato automaticamente tramite il file Compose. ### Comandi utili ```bash docker compose logs -f simplemem # Segui i log docker compose down # Ferma e rimuovi i container ``` > 📖 Per l'auto-hosting del server MCP (Docker o bare metal), vedi [Documentazione MCP](../../MCP/README.md). --- ## 🔌 Server MCP *(memoria testuale)* SimpleMem è disponibile come **servizio di memoria ospitato nel cloud** tramite il Model Context Protocol (MCP), abilitando un'integrazione fluida con assistenti AI come Claude Desktop, Cursor e altri client compatibili con MCP. **🌐 Servizio Cloud**: [mcp.simplemem.cloud](https://mcp.simplemem.cloud) — oppure auto-ospita il server MCP localmente usando [Docker](#-esegui-con-docker). ### Funzionalità Principali | Funzionalità | Descrizione | |---------|-------------| | **HTTP Streamable** | Protocollo MCP 2025-03-26 con JSON-RPC 2.0 | | **Isolamento Multi-tenant** | Tabelle dati per utente con autenticazione tramite token | | **Recupero Ibrido** | Ricerca semantica + corrispondenza per parole chiave + filtraggio per metadati | | **Ottimizzato per la Produzione** | Tempi di risposta più rapidi con integrazione OpenRouter | ### Configurazione Rapida ```json { "mcpServers": { "simplemem": { "url": "https://mcp.simplemem.cloud/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` > 📖 Per istruzioni di configurazione dettagliate e guida all'auto-hosting, vedi [Documentazione MCP](../../MCP/README.md) --- ## 📊 Riproduci i Risultati del Paper Riproduci i numeri di LoCoMo / MemBench / Mem-Gallery dai paper. Ogni pilastro ha il proprio runner di benchmark nella propria directory. Installa prima i supplementi per i benchmark: `pip install -e ".[benchmark]"`. ### 📝 SimpleMem (testo) — LoCoMo Esegui dalla radice del repository: ```bash python test_locomo10.py # benchmark LoCoMo completo python test_locomo10.py --num-samples 5 # sottoinsieme rapido python test_locomo10.py --result-file my_results.json ``` ### 🧬 EvolveMem — auto-evoluzione + LoCoMo / MemBench Esegui dalla directory `EvolveMem/` (vedi [`EvolveMem/README.md`](../../EvolveMem/README.md)): ```bash cd EvolveMem python run_evolution.py --data data/locomo10.json --max-rounds 7 python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3 python run_benchmark.py membench --agent FirstAgent --max-rounds 3 ``` ### 🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery Esegui dalla directory `OmniSimpleMem/` (vedi [`OmniSimpleMem/README.md`](../../OmniSimpleMem/README.md)): ```bash cd OmniSimpleMem python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o ``` --- ## 🗺️ Roadmap Capacità attuali per canale di integrazione: | Capacità | Python (`pip install`) | Server MCP (Claude Desktop, Cursor, ...) | |:--|:--:|:--:| | Memoria testuale | ✅ | ✅ | | Multimodale (immagine / audio / video) | ✅ | ⬜ pianificato | | Recupero auto-evolutivo `optimize()` | ✅ | ⬜ pianificato | Lavori pianificati per colmare il divario (il server MCP è un servizio testuale multi-tenant standalone; queste sono funzionalità reali, non correzioni alla documentazione): - [ ] **Multimodale via MCP.** Aggiungere strumenti `memory_add_image` / `memory_add_audio` / `memory_add_video`. Richiede un percorso di caricamento file (base64 o URL, poiché MCP non può passare percorsi di file locali), un adattamento multi-tenant del backend di archiviazione Omni-SimpleMem e l'accesso ai modelli vision/audio lato server. - [ ] **EvolveMem via MCP.** Esporre `optimize()` come strumento MCP. Più trattabile del multimodale (testo in ingresso, config JSON in uscita, nessun trasporto di file), ma il retriever MCP attualmente supporta solo `semantic_top_k` / `keyword_top_k` delle ~10 dimensioni che EvolveMem evolve. Richiede l'estensione del retriever MCP per supportare le restanti impostazioni (structured top_k, modalità/pesi di fusione, scambio di entità, decomposizione delle query, verifica delle risposte), un adattatore per eseguire il ciclo di evoluzione sulle memorie archiviate di un tenant, la persistenza della config per tenant e l'esecuzione asincrona (il ciclo è pesante per LLM e andrebbe in timeout su una richiesta sincrona). - [ ] **Docker** eredita entrambi automaticamente una volta che il server MCP li supporta (aggiungere le dipendenze multimodali all'immagine e un volume di archiviazione Omni). Per il multimodale completo e il recupero auto-evolutivo oggi, usa l'API Python (vedi [Avvio Rapido](#-avvio-rapido)). --- ## 📝 Citazione Se utilizzi SimpleMem nella tua ricerca, cita: ```bibtex @article{simplemem2026, title={SimpleMem: Efficient Lifelong Memory for LLM Agents}, author={Liu, Jiaqi and Su, Yaofeng and Xia, Peng and Zhou, Yiyang and Han, Siwei and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu}, journal={arXiv preprint arXiv:2601.02553}, year={2026}, url={https://arxiv.org/abs/2601.02553} } ``` ```bibtex @article{evolvemem2026, title={EvolveMem: Self-Evolving Memory Architecture via AutoResearch for LLM Agents}, author={Liu, Jiaqi and Ye, Xinyu and Xia, Peng and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu}, journal={arXiv preprint arXiv:2605.13941}, year={2026}, url={https://arxiv.org/abs/2605.13941} } ``` ```bibtex @article{omnisimplemem2026, title = {Omni-SimpleMem: Autoresearch-Guided Discovery of Lifelong Multimodal Agent Memory}, author = {Liu, Jiaqi and Ling, Zipeng and Qiu, Shi and Liu, Yanqing and Han, Siwei and Xia, Peng and Tu, Haoqin and Zheng, Zeyu and Xie, Cihang and Fleming, Charles and Ding, Mingyu and Yao, Huaxiu}, journal = {arXiv preprint arXiv:2604.01007}, year = {2026}, } ``` --- ## 📄 Licenza Questo progetto è concesso in licenza sotto la **Licenza MIT** — vedi il file [LICENSE](../../LICENSE) per i dettagli. --- ## 🙏 Ringraziamenti Desideriamo ringraziare i seguenti progetti e team: - 🔍 **Modello di Embedding**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) - Prestazioni di recupero all'avanguardia - 🗄️ **Database Vettoriale**: [LanceDB](https://lancedb.com/) - Archiviazione colonnare ad alte prestazioni - 📊 **Benchmark**: [LoCoMo](https://github.com/snap-research/locomo) - Framework di valutazione della memoria a contesto lungo