## Effizientes lebenslanges Gedächtnis für LLM-Agenten — Text & Multimodal
Langzeitgedächtnisse speichern, komprimieren und abrufen mit semantisch verlustfreier Kompression. Jetzt mit multimodaler Unterstützung für Text, Bild, Audio & Video.
Funktioniert mit jeder KI-Plattform, die MCP (Textgedächtnis) oder Python-Integration (vollständig multimodal) unterstützt
|
**📝 Auto → Text** (reiner Texteingabe)
```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** (multimodale Eingabe)
```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()
```
|
> **💡 Tipp**: Der Auto-Modus wählt das leichteste Backend, das zu Ihren Daten passt. Sie können auch explizit `mode="text"` oder `mode="omni"` verwenden, wenn Sie dies bevorzugen.
---
### 🧬 Erweitert: Abrufkonfiguration optimieren
Passen Sie Abruf-Hyperparameter offline auf Ihrem eigenen Entwicklungsdatensatz an und verwenden Sie dann die resultierende `Config` für die Inferenz. Dies ist ein dünner Wrapper um EvolveMems Selbstentwicklungs-Loop:
```python
import simplemem
from simplemem import SimpleMem, load_config
# mem is a finalized SimpleMem instance with memories already built
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")
# Later, deploy with the optimized config
config = load_config("my_config.json")
mem = SimpleMem(config=config)
```
> EvolveMem führt einen LLM-gesteuerten Evaluate → Diagnose → Propose → Guard-Zyklus über Ihren Entwicklungsfragen aus und passt globale Abruf-Flags an (top_k, Fusionsmodus, Antwortverifikation, Reflexionsrunden, ...). Für die vollständige eigenständige Version mit Benchmark-Adaptern und kategorienspezifischen Überschreibungen, siehe [`EvolveMem/`](../../EvolveMem/).
---
### 🚄 Erweitert: Parallelverarbeitung
Für die großskalige Dialogverarbeitung aktivieren Sie den Parallelmodus:
```python
from simplemem import create
mem = create(
mode="text",
clear_db=True,
enable_parallel_processing=True, # ⚡ Parallel memory building
max_parallel_workers=8,
enable_parallel_retrieval=True, # 🔍 Parallel query execution
max_retrieval_workers=4
)
```
> **💡 Profi-Tipp**: Parallelverarbeitung reduziert die Latenz bei Batch-Operationen erheblich!
---
## 🌟 Überblick
**SimpleMem** ist ein einheitlicher Gedächtnis-Stack für LLM-Agenten, aufgebaut auf einem Prinzip: *semantisch verlustfreie* Erinnerungen bei hoher Informationsdichte speichern, damit ein Agent mehr abruft, während er deutlich weniger Token verbraucht. Das Paket vereint drei Arbeiten, die dieses Prinzip teilen, aber unterschiedliche Teile des Problems angehen.
### 📝 SimpleMem: der Effizienz-Kern (Text)
Die meisten Gedächtnissysteme erzwingen einen schlechten Kompromiss. Sie akkumulieren entweder passiv rohe Interaktionshistorie (redundant, tokenintensiv) oder führen teure Reasoning-Schleifen durch, um Rauschen zu filtern (langsam, kostspielig). SimpleMem komprimiert stattdessen Interaktionen durch eine dreistufige Pipeline:
| Stufe | Was sie tut |
|:--|:--|
| **1. Semantische strukturierte Kompression** | Destilliert unstrukturierte Interaktionen in kompakte Gedächtniseinheiten (in sich geschlossene Fakten mit aufgelösten Koreferenzen und absoluten Zeitstempeln), die jeweils durch mehrere komplementäre Ansichten für flexiblen Abruf indiziert werden. |
| **2. Online-Semantische-Synthese** | Fügt verwandten Kontext innerhalb einer Sitzung zu einheitlichen abstrakten Repräsentationen zusammen, wobei Redundanz beim Aufbau des Gedächtnisses statt zur Abfragezeit beseitigt wird. |
| **3. Absichtsbewusstes Abrufplanen** | Leitet die Suchabsicht hinter einer Abfrage ab, um zu entscheiden, *was* abgerufen werden soll, und stellt einen präzisen, kompakten Kontext zusammen. |
Auf dem LoCoMo-Benchmark liefert dies einen durchschnittlichen F1-Gewinn von 26,4 % gegenüber früheren Systemen, während der Token-Verbrauch zur Inferenzzeit um ca. 30x reduziert wird. Mechanismusdetails (hybride Indexschichten, Kompressionsbeispiele, Abrufplanung): [**SimpleMem Textgedächtnis →**](../text-memory.md).
### 🧠 Omni-SimpleMem: multimodales Gedächtnis (Text, Bild, Audio, Video)
Omni-SimpleMem erweitert die Kompression-zuerst-Philosophie auf vier Modalitäten, aufgebaut auf drei Prinzipien: **Selektive Aufnahme** (entropiegesteuertes Filtern pro Modalität), **Progressiver Abruf** (hybrides FAISS + BM25 mit pyramidenförmiger Token-Budget-Erweiterung) und **Wissensgraph-Augmentierung** (Multi-Hop-Cross-Modal-Reasoning). Statt handentworfen zu sein, wurde die Architektur von einer autonomen Forschungspipeline *entdeckt*, die rund 50 Experimente über zwei Benchmarks hinweg durchführte, Fehlermodi diagnostizierte, Architekturänderungen vorschlug und sogar Datenpipeline-Bugs ohne menschliche Eingriffe in der inneren Schleife behob. Bezeichnenderweise trugen die Bug-Fixes und Architekturänderungen jeweils mehr bei als alle Hyperparameter-Optimierungen zusammen, wobei das System von einer naiven Baseline zum Stand der Technik auf LoCoMo und Mem-Gallery gelangte. Vollständige Dokumentation: [**Omni-SimpleMem →**](../../OmniSimpleMem/).
### 🧬 EvolveMem: sich selbst weiterentwickelnder Abruf
EvolveMem schließt einen blinden Fleck, den fast jedes Gedächtnissystem teilt: Der gespeicherte Inhalt entwickelt sich weiter, aber die *Abruf*-Maschinerie (Bewertungsfunktionen, Fusionsstrategien, Antwortgenerierungsrichtlinien) bleibt nach dem Deployment eingefroren. EvolveMem führt einen geschlossenen AutoResearch-Prozess durch (**Evaluate → Diagnose → Propose → Guard → Repeat**), bei dem ein LLM Pro-Fragen-Fehler diagnostiziert und Konfigurationsänderungen vorschlägt, gesichert durch automatisches Rollback bei Regression und Explorations-Anreizen bei Stagnation. Es entdeckt neue Abrufdimensionen (Abfragezerlegung, Entitätsaustausch, Antwortverifikation), die nicht im ursprünglichen Design vorhanden waren, verbessert LoCoMo um 25,7 % relativ gegenüber der stärksten Baseline, und seine entwickelten Konfigurationen übertragen sich positiv auf andere Benchmarks. Vollständige Dokumentation: [**EvolveMem →**](../../EvolveMem/).
### Wie sie zusammenpassen
`from simplemem import SimpleMem` gibt Ihnen den Textkern mit automatischem Routing zum multimodalen Backend, und `simplemem.optimize(...)` nutzt EvolveMem zur Feinabstimmung des Abrufs auf Ihren eigenen Daten. Ein Paket, ein mentales Modell: verlustfrei komprimieren, nach Absicht abrufen und das System sich kontinuierlich weiterentwickeln lassen.
---
## 📦 Installation
### 📝 Hinweise für Erstbenutzer
- Stellen Sie sicher, dass Sie **Python 3.10+ in Ihrer aktiven Umgebung** verwenden, nicht nur global installiert.
- Ein OpenAI-kompatibler API-Schlüssel muss **vor dem Ausführen einer Gedächtniskonstruktion oder eines Abrufs** konfiguriert werden, sonst kann die Initialisierung fehlschlagen.
- Wenn Sie Nicht-OpenAI-Anbieter verwenden (z. B. Qwen oder Azure OpenAI), überprüfen Sie sowohl den Modellnamen als auch `OPENAI_BASE_URL` in `config.py`.
- Bei großen Dialogdatensätzen kann die Aktivierung der Parallelverarbeitung die Gedächtnisaufbauzeit erheblich reduzieren.
### 📋 Anforderungen
- 🐍 Python 3.10+
- 🔑 OpenAI-kompatible API (OpenAI, Qwen, Azure OpenAI usw.)
### 🛠️ Einrichtung
```bash
# 📥 Repository klonen
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem
# 📦 Abhängigkeiten installieren (gepinnte Versionen)
pip install -r requirements.txt
# — ODER — als bearbeitbares Paket installieren
pip install -e . # Standard: Text + Multimodal + Evolver
pip install -e ".[server]" # + MCP / HTTP-Server (mcp, fastapi, ...)
pip install -e ".[all]" # Alles, einschließlich Entwicklungswerkzeuge
# ⚙️ API-Einstellungen konfigurieren
cp config.py.example config.py
# config.py mit Ihrem API-Schlüssel und Ihren Einstellungen bearbeiten
```
### ⚙️ Konfigurationsbeispiel
```python
# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None # or custom endpoint for Qwen/Azure
LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B" # State-of-the-art retrieval
```
---
## 🐳 Mit Docker ausführen
Der **MCP-Server** kann in Docker für eine konsistente, isolierte Umgebung ausgeführt werden. Daten (LanceDB und Benutzer-DB) werden in einem Host-Volume gespeichert.
### Voraussetzungen
- [Docker](https://docs.docker.com/get-docker/) und [Docker Compose](https://docs.docker.com/compose/install/)
### Schnellstart
```bash
# Vom Repository-Stammverzeichnis
docker compose up -d
```
- **Web-UI:** http://localhost:8000/
- **REST-API:** http://localhost:8000/api/
- **MCP (SSE):** http://localhost:8000/mcp/sse?token=<TOKEN>
Daten werden in `./data` auf dem Host gespeichert (wird automatisch erstellt).
### Benutzerdefinierte Konfiguration
1. Kopieren Sie die Umgebungsvorlage und bearbeiten Sie sie:
```bash
cp .env.example .env
# .env bearbeiten: JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, Modell-URLs usw. setzen
```
2. Mit der Env-Datei ausführen:
```bash
docker compose --env-file .env up -d
```
### Ollama auf dem Host verwenden
Wenn `LLM_PROVIDER=ollama` und Ollama auf Ihrem Rechner läuft (nicht in Docker), setzen Sie in `.env`:
```bash
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
```
Unter Linux wird `host.docker.internal` automatisch über die Compose-Datei aktiviert.
### Nützliche Befehle
```bash
docker compose logs -f simplemem # Logs verfolgen
docker compose down # Container stoppen und entfernen
```
> 📖 Für das Self-Hosting des MCP-Servers (Docker oder Bare Metal), siehe [MCP-Dokumentation](../../MCP/README.md).
---
## 🔌 MCP-Server *(Textgedächtnis)*
SimpleMem ist als **cloudgehosteter Gedächtnisdienst** über das Model Context Protocol (MCP) verfügbar und ermöglicht eine nahtlose Integration mit KI-Assistenten wie Claude Desktop, Cursor und anderen MCP-kompatiblen Clients.
**🌐 Cloud-Dienst**: [mcp.simplemem.cloud](https://mcp.simplemem.cloud) — oder Self-Hosting des MCP-Servers lokal mit [Docker](#-mit-docker-ausführen).
### Hauptfunktionen
| Funktion | Beschreibung |
|---------|-------------|
| **Streamable HTTP** | MCP 2025-03-26-Protokoll mit JSON-RPC 2.0 |
| **Multi-Tenant-Isolation** | Benutzerspezifische Datentabellen mit Token-Authentifizierung |
| **Hybridabruf** | Semantische Suche + Schlüsselwortabgleich + Metadatenfilterung |
| **Produktionsoptimiert** | Schnellere Antwortzeiten durch OpenRouter-Integration |
### Schnellkonfiguration
```json
{
"mcpServers": {
"simplemem": {
"url": "https://mcp.simplemem.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
```
> 📖 Für detaillierte Einrichtungsanleitungen und Self-Hosting-Leitfaden, siehe [MCP-Dokumentation](../../MCP/README.md)
---
## 📊 Paper-Ergebnisse reproduzieren
Reproduzieren Sie die LoCoMo / MemBench / Mem-Gallery-Zahlen aus den Papers. Jede Säule hat ihren eigenen Benchmark-Runner in ihrem eigenen Verzeichnis. Installieren Sie zuerst die Benchmark-Extras: `pip install -e ".[benchmark]"`.
### 📝 SimpleMem (Text) — LoCoMo
Vom Repository-Stammverzeichnis ausführen:
```bash
python test_locomo10.py # vollständiger LoCoMo-Benchmark
python test_locomo10.py --num-samples 5 # schnelle Teilmenge
python test_locomo10.py --result-file my_results.json
```
### 🧬 EvolveMem — Selbstentwicklung + LoCoMo / MemBench
Aus dem Verzeichnis `EvolveMem/` ausführen (siehe [`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
Aus dem Verzeichnis `OmniSimpleMem/` ausführen (siehe [`OmniSimpleMem/README.md`](../../OmniSimpleMem/README.md)):
```bash
cd OmniSimpleMem
python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o
```
---
## 🗺️ Fahrplan
Aktuelle Fähigkeiten nach Integrationskanal:
| Fähigkeit | Python (`pip install`) | MCP-Server (Claude Desktop, Cursor, ...) |
|:--|:--:|:--:|
| Textgedächtnis | ✅ | ✅ |
| Multimodal (Bild / Audio / Video) | ✅ | ⬜ geplant |
| `optimize()` sich selbst weiterentwickelnder Abruf | ✅ | ⬜ geplant |
Geplante Arbeiten zur Schließung der Lücke (der MCP-Server ist ein eigenständiger Multi-Tenant-Textdienst; dies sind echte Funktionen, keine Dokumentationsverbesserungen):
- [ ] **Multimodal über MCP.** `memory_add_image` / `memory_add_audio` / `memory_add_video`-Werkzeuge hinzufügen. Benötigt einen Datei-Upload-Pfad (Base64 oder URL, da MCP keine lokalen Dateipfade übergeben kann), eine Multi-Tenant-Anpassung des Omni-SimpleMem-Storage-Backends und serverseitigen Zugriff auf Vision-/Audio-Modelle.
- [ ] **EvolveMem über MCP.** `optimize()` als MCP-Werkzeug bereitstellen. Handhabbarer als Multimodal (Text rein, JSON-Konfiguration raus, kein Dateitransport), aber der MCP-Retriever berücksichtigt derzeit nur `semantic_top_k` / `keyword_top_k` der ~10 Dimensionen, die EvolveMem entwickelt. Erfordert die Erweiterung des MCP-Retrievers zur Unterstützung der verbleibenden Regler (strukturiertes top_k, Fusionsmodus/-gewichtungen, Entitätsaustausch, Abfragezerlegung, Antwortverifikation), einen Adapter zur Ausführung des Evolutionsloops über die gespeicherten Erinnerungen eines Mandanten, mandantenspezifische Konfigurationspersistenz und asynchrone Ausführung (der Loop ist LLM-intensiv und würde eine synchrone Anfrage zum Timeout bringen).
- [ ] **Docker** erbt beides automatisch, sobald der MCP-Server sie unterstützt (multimodale Abhängigkeiten zum Image hinzufügen und ein Omni-Storage-Volume).
Für vollständiges Multimodal und sich selbst weiterentwickelnden Abruf heute, verwenden Sie die Python-API (siehe [Schnellstart](#-schnellstart)).
---
## 📝 Zitierung
Wenn Sie SimpleMem in Ihrer Forschung verwenden, zitieren Sie bitte:
```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},
}
```
---
## 📄 Lizenz
Dieses Projekt ist unter der **MIT-Lizenz** lizenziert — siehe die [LICENSE](../../LICENSE)-Datei für Details.
---
## 🙏 Danksagungen
Wir möchten den folgenden Projekten und Teams danken:
- 🔍 **Einbettungsmodell**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) - Hochmoderne Abrufleistung
- 🗄️ **Vektordatenbank**: [LanceDB](https://lancedb.com/) - Hochleistungs-Spaltenspeicher
- 📊 **Benchmark**: [LoCoMo](https://github.com/snap-research/locomo) - Framework zur Bewertung von Langzeitgedächtnis
