Skip to content

README.it.md

Latest commit

 

History

History
550 lines (394 loc) · 24.8 KB

README.it.md

File metadata and controls

550 lines (394 loc) · 24.8 KB
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
Claude Desktop 		Cursor
Cursor 		LM Studio
LM Studio 		Cherry Studio
Cherry Studio 		PyPI
Pacchetto PyPI 		+ Qualsiasi Client
MCP

🔥 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 →
  • [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 →
  • [02/09/2026] 🚀 Memoria Cross-Sessione — Supera Claude-Mem del 64%! Vedi Documentazione Cross-Session →
  • [01/20/2026] 📦 SimpleMem è ora disponibile su PyPI! Installa con pip install simplemem. Vedi Guida all'Utilizzo del Pacchetto →
  • [01/14/2026] 🎉 Il Server MCP di SimpleMem è ATTIVO! Ospitato nel cloud su mcp.simplemem.cloud. Vedi Documentazione MCP →
  • [01/05/2026] Il paper di SimpleMem è stato pubblicato su arXiv!

📑 Indice dei Contenuti

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

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)

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)

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:

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/.

🚄 Avanzato: Elaborazione Parallela

Per l'elaborazione di dialoghi su larga scala, abilita la modalità parallela:

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 →.

🧠 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 →.

🧬 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 →.

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

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

# 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

Avvio rapido

# Dalla radice del repository
docker compose up -d

I dati sono memorizzati in ./data sull'host (creato automaticamente).

Configurazione personalizzata

  1. Copia il template dell'ambiente e modificalo: 
    cp .env.example .env
# Modifica .env: imposta JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, URL dei modelli, ecc.
  2. Esegui con il file env: 
    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:

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

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.

🔌 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 — oppure auto-ospita il server MCP localmente usando 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

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

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

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

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

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).

📝 Citazione

Se utilizzi SimpleMem nella tua ricerca, cita:

@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}
}
@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}
}
@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 per i dettagli.

🙏 Ringraziamenti

Desideriamo ringraziare i seguenti progetti e team:

  • 🔍 Modello di Embedding: Qwen3-Embedding - Prestazioni di recupero all'avanguardia
  • 🗄️ Database Vettoriale: LanceDB - Archiviazione colonnare ad alte prestazioni
  • 📊 Benchmark: LoCoMo - Framework di valutazione della memoria a contesto lungo