Skip to content

Latest commit

 

History

History
550 lines (394 loc) · 25 KB

File metadata and controls

550 lines (394 loc) · 25 KB
simplemem-Logo

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

Claude Desktop
Claude Desktop
Cursor
Cursor
LM Studio
LM Studio
Cherry Studio
Cherry Studio
PyPI
PyPI-Paket
+ Jeder MCP-
Client

🔥 Neuigkeiten

  • [05/21/2026] 📦 Einheitliches simplemem-Paket — ein Import, automatisches Routing! SimpleMem, Omni-SimpleMem und EvolveMem sind jetzt in einem einzigen Paket vereint. from simplemem import SimpleMem wählt automatisch das Text- oder multimodale Backend anhand der ersten aufgerufenen Methode aus, und simplemem.optimize(...) nutzt EvolveMems Selbstentwicklungs-Loop. Installation in einem Schritt mit pip install -e ..
  • [05/14/2026] 🧬 EvolveMem (v3.0) — Sich selbst weiterentwickelndes Gedächtnis via AutoResearch! Die Abrufinfrastruktur selbst entwickelt sich jetzt durch LLM-gesteuerte Closed-Loop-Diagnose weiter. Auf LoCoMo übertrifft EvolveMem die stärkste Baseline um +25,7 % relativ; auf MemBench um +18,9 % relativ. Das System entdeckt völlig neue Abrufdimensionen, die im ursprünglichen Design nicht vorhanden waren. EvolveMem ansehen →
  • [04/02/2026] 🧠 Omni-SimpleMem (v2.0) — Multimodales Gedächtnis ist da! SimpleMem unterstützt jetzt Text-, Bild-, Audio- & Video-Gedächtnis. Erreicht neuen SOTA auf LoCoMo (F1=0,613, +47%) und Mem-Gallery (F1=0,810, +51%) gegenüber dem bisherigen Bestwert. Omni-SimpleMem ansehen →
  • [02/09/2026] 🚀 Sitzungsübergreifendes Gedächtnis — übertrifft Claude-Mem um 64%! Dokumentation zum sitzungsübergreifenden Betrieb ansehen →
  • [01/20/2026] 📦 SimpleMem ist jetzt auf PyPI verfügbar! Installation via pip install simplemem. Paket-Verwendungsanleitung ansehen →
  • [01/14/2026] 🎉 SimpleMem MCP-Server ist LIVE! Cloud-gehostet unter mcp.simplemem.cloud. MCP-Dokumentation ansehen →
  • [01/05/2026] SimpleMem-Paper wurde auf arXiv veröffentlicht!

📑 Inhaltsverzeichnis


🚀 Schnellstart

🧠 Den grundlegenden Arbeitsablauf verstehen

Auf hoher Ebene funktioniert SimpleMem als Langzeitgedächtnissystem für LLM-basierte Agenten. Der Arbeitsablauf besteht aus drei einfachen Schritten:

  1. Informationen speichern – Dialoge oder Fakten werden verarbeitet und in strukturierte, atomare Gedächtniseinheiten umgewandelt.
  2. Gedächtnis indizieren – Gespeicherte Erinnerungen werden mithilfe semantischer Einbettungen und strukturierter Metadaten organisiert.
  3. Relevantes Gedächtnis abrufen – Bei einer Abfrage ruft SimpleMem die relevantesten gespeicherten Informationen auf der Grundlage von Bedeutung statt Schlüsselwörtern ab.

Dieses Design ermöglicht es LLM-Agenten, Kontext aufrechtzuerhalten, vergangene Informationen effizient abzurufen und die wiederholte Verarbeitung redundanter Verläufe zu vermeiden.

🎓 Grundlegende Verwendung

SimpleMem wird als einzelnes simplemem-Paket ausgeliefert. Der Standard mode="auto" erkennt automatisch, welches Backend verwendet werden soll, basierend auf dem, was Sie aufrufen — keine manuelle Konfiguration erforderlich:

from simplemem import SimpleMem

mem = SimpleMem()  # mode="auto" — Backend wird durch ersten Aufruf gewählt

Die erste aufgerufene Methode bestimmt das Backend:

Erster Aufruf Gewähltes Backend Warum
add_dialogue() Text (SimpleMem) Dialogbasierte API → Textmodus
add_text() / add_image() / add_audio() / add_video() Omni (Omni-SimpleMem) Multimodale API → Omni-Modus

📝 Auto → Text (reiner Texteingabe)

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)

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:

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


🚄 Erweitert: Parallelverarbeitung

Für die großskalige Dialogverarbeitung aktivieren Sie den Parallelmodus:

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

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

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

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

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

# 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

Schnellstart

# Vom Repository-Stammverzeichnis
docker compose up -d

Daten werden in ./data auf dem Host gespeichert (wird automatisch erstellt).

Benutzerdefinierte Konfiguration

  1. Kopieren Sie die Umgebungsvorlage und bearbeiten Sie sie:
    cp .env.example .env
    # .env bearbeiten: JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, Modell-URLs usw. setzen
  2. Mit der Env-Datei ausführen:
    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:

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

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-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 — oder Self-Hosting des MCP-Servers lokal mit Docker.

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

{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

📖 Für detaillierte Einrichtungsanleitungen und Self-Hosting-Leitfaden, siehe MCP-Dokumentation


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

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

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

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


📝 Zitierung

Wenn Sie SimpleMem in Ihrer Forschung verwenden, zitieren Sie bitte:

@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},
}

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert — siehe die LICENSE-Datei für Details.


🙏 Danksagungen

Wir möchten den folgenden Projekten und Teams danken:

  • 🔍 Einbettungsmodell: Qwen3-Embedding - Hochmoderne Abrufleistung
  • 🗄️ Vektordatenbank: LanceDB - Hochleistungs-Spaltenspeicher
  • 📊 Benchmark: LoCoMo - Framework zur Bewertung von Langzeitgedächtnis