🧠 agent-sleep

Konsolidierung von Erfahrungen und Entscheidungsunterstützung für KI-Agenten.

Eine leichtgewichtige, framework-agnostische Python-Bibliothek und MCP-Server, die eine dauerhafte Konsolidierung von Erfahrungen und entscheidungsunterstützende Signale bereitstellt, die ein Host-Agent über Sitzungen hinweg nutzen kann – inspiriert davon, wie das biologische Gehirn Schlafzyklen nutzt, um Wach-Erfahrungen in dauerhafte prozedurale Regeln und Lektionen zu konsolidieren.

Das Problem: „Agenten-Amnesie"

Jedes moderne KI-Agenten-Framework (LangChain, AutoGen, CrewAI, OpenAI Assistants) leidet unter Agenten-Amnesie:

• Jeder neue Chat oder jeder Subagenten-Lauf beginnt komplett von vorn.

• Wenn ein Agent am Montag auf einen Fehler stößt oder eine Codebase-Konvention entdeckt, wiederholt es am Dienstag exakt denselben Fehler.

• Vektor-Datenbanken (RAG) durchsuchen nur statische Dokumente – sie lernen nicht aus Laufzeit-Erfahrungen.

Related MCP server: Recall

MCP-Schnellstart – 10 Sekunden

Dies ist der primäre Nutzungspfad. agent-sleep wird als MCP-Server ausgeliefert, sodass jeder Agent, der MCP unterstützt (Antigravity, Claude Desktop, Cursor, Cline), es ohne jegliches Programmieren nutzen kann.

Schritt 1 – Installieren und Konfiguration generieren

# Option A: zero-install (recommended)
uvx agent-sleep-mcp

# Option B: install first, then run the init helper
pip install "agent-sleep[mcp]"
agent-sleep init     # prints the correct config snippet for your platform

agent-sleep init erkennt automatisch dein Betriebssystem und gibt das JSON-Snippet aus, das du in die Konfiguration deines MCP-Clients einfügen kannst. Kein manuelles Bearbeiten erforderlich.

Schritt 2 – Das Konfigurations-Snippet einfügen

Der Befehl init gibt genau aus, was du wo einfügen musst. Beispielausgabe für Claude Desktop unter macOS:

{
  "mcpServers": {
    "agent-sleep": {
      "command": "uvx",
      "args": ["agent-sleep-mcp"]
    }
  }
}

Füge das in ~/Library/Application Support/Claude/claude_desktop_config.json ein, starte Claude neu, und fertig.

Schritt 3 – Bitte deinen Agenten, es zu nutzen

"Before we start, check your memory for anything relevant to this task."
"Record that we use pytest fixtures — not unittest — in this project."
"Run a sleep consolidation so you remember today's lessons next session."

Der Speicher wird automatisch in .agent_sleep/memory.db in deinem Projektverzeichnis abgelegt (standardmäßig in .gitignore ausgeschlossen).

Einblick in den Speicher – CLI

Du musst nicht durch einen LLM gehen, um zu sehen, was dein Agent gelernt hat:

# See all memories and rules for the current project
agent-sleep show

# Clear a project's memory (with confirmation prompt)
agent-sleep reset

# Target a specific scope or DB
agent-sleep show --scope my_api --db /path/to/memory.db

So funktioniert es: Die 3-Phasen-Pipeline

          [ ONLINE EXECUTION PHASE ]
            Agent executes tool calls
                       │
                       ▼
┌──────────────────────────────────────────────┐
│  1. EPISODIC RECORDING                       │
│     memory.record_episode(...)               │  Fast, minimal overhead.
│     Records goal, action, outcome, errors.   │  Stores execution events.
└──────────────────────┬───────────────────────┘
                       │
             (Session ends / Agent idle)
                       │
                       ▼
          [ OFFLINE SLEEP CONSOLIDATION ]
┌──────────────────────────────────────────────┐
│  2. SLEEP CONSOLIDATOR (8-Stage Pipeline)    │
│     SleepConsolidator.run(session_id)        │
│                                              │
│     • Priority Replay (prediction error)     │
│     • Deterministic Episodic Distillation    │  Grounding first:
│     • Procedural Recipe Extraction           │  distills facts & lessons
│     • How-Memory Trajectory Abstraction      │  before optional LLM
│     • Behavioral Rule Promotion (seen ≥2x)   │  generalization passes.
│     • Epistemic Status (observed vs verified)│
│     • Episodic Compression over time         │
│     • Self-Competence EMA Tracking           │
└──────────────────────┬───────────────────────┘
                       │
              (Next session / New task)
                       │
                       ▼
          [ ONLINE SELECTIVE RECALL ]
┌──────────────────────────────────────────────┐
│  3. SELECTIVE SEMANTIC RECALL                │
│     memory.recall(new_task)                  │  Pre-computed vector BLOBs.
│     Returns only relevant lessons & rules    │  Prevents prompt dilution.
│     filtered by project scope & relevance.   │
└──────────────────────────────────────────────┘

Hauptfunktionen (v0.1.2-alpha)

• Vorberechnete Vektor-BLOBs: Bettet die Abfrage einmal ein und vergleicht sie mit vorberechneten gespeicherten Vektoren, wodurch wiederholtes Texteinbetten beim Abruf entfällt.

• Epistemischer Speicher-Lebenszyklus: Verfolgt die Speicher-Progression über Stufen (RAW → OBSERVED → REPEATED → VERIFIED → ACTIVE) und isoliert automatisch widersprüchliche oder fehleranfällige Erinnerungen.

• Überprüfbare kausale Attribution & Nutzen-Feedback: Bewertet, ob abgerufene Erinnerungen die spätere Ausführung tatsächlich verbessert haben, über strukturierte Evidenzdatensätze (retrieval → action change → outcome attribution).

• Evidenzvielfalt bei Kausalhypothesen: Destilliert wiederkehrende Fehler in kausale Mechanismen, indem Evidenzvielfalt über unabhängige Quellen und Umgebungen skaliert wird.

• Bayessches Selbstkompetenzmodell: Schätzt die Domänenkompetenz und die Bayessche Beta-Verteilungs-Unsicherheit über zusammengesetzte Domänen, um eine adaptive Entscheidungsunterstützung (Prüfintensität, Wiederholungsbudgets) für Host-Agenten bereitzustellen.

• Rule-Specificity-Engine erster Klasse: Löst Regelkonflikte durch hierarchische Präzedenz auf (specific verified > general verified > specific candidate > general candidate) und dynamische Ausnahmebehandlung.

• Scope- & Projektisolierung: Mehrstufige Namensräume (scope="repo_a", scope="global"). Projektspezifisches Wissen wird strikt isoliert, während universelle Idiome und Tool-Fehlermodi optional über global geteilt werden können.

• Null schwere Pflichtabhängigkeiten: Funktioniert sofort einsatzbereit mit standardmäßigem SQLite und einem deterministischen Hashed-Bag-of-Words-Fallback. Nahtloses Upgrade auf sentence-transformers (all-MiniLM-L6-v2), sobald installiert.

Benchmarks & Evaluierung

1. Kontrollierte Transfer-Simulation (benchmarks/run.py)

Bewertet Speicherkonsolidierung, Vektorabruf und Wissenstransfer über 12 aufeinanderfolgende Softwareaufgaben mit wiederkehrenden architektonischen Fallstricken:

Hinweis: Die kontrollierte Transfer-Simulation bewertet die deterministische kognitive Kontrolldynamik von Speicherabruf und Fallstrickvermeidung.

2. Kanonische 6-fach-Ablations-Benchmark (benchmarks/agent_eval/runner.py)

Kontrollierte Sandbox-Bewertung der speichergesteuerten Agenten-Kontrolldynamik über 8 standardisierte Softwareentwicklungsaufgaben:

python benchmarks/agent_eval/runner.py

[!HINWEIS] Wissenschaftlicher & technischer Hinweis:

• Die Sandbox-Benchmark bewertet die Agenten-Kontrolldynamik, Token-Effizienz und Fehlervermeidung unter kontrollierten Testumgebungen.

• Einbettungs-Backends: Hochpräzise Vektorähnlichkeit basiert auf sentence-transformers (all-MiniLM-L6-v2). Wenn Abhängigkeiten fehlen, greift die Bibliothek automatisch auf ein deterministisches Hashed-Bag-of-Words-Einbettungsverfahren zurück.

• Vollständige Reproduzierbarkeitsprotokolle und Metrikprotokolle sind in benchmarks/agent_eval/results.json dokumentiert.

Nutzung der Python-Bibliothek

Wenn du das Speichersystem lieber direkt aus deinem eigenen Agentencode heraus steuern möchtest, anstatt über MCP, wird die Python-API vollständig unterstützt.

from agent_sleep import AgentMemory, SleepConsolidator

# 1. Initialize memory scoped to your project/repo
memory = AgentMemory(session_id="session_01", scope="payment_service")

# 2. Record actions and outcomes during your agent's loop
memory.record_episode(
    goal="Refactor payment processor to async",
    action="edit_file('processor.py', ...)",
    outcome="failure",
    failure_reason="SyntaxError: 'await' outside async function",
)

# 3. Trigger sleep consolidation when idle or at session end
consolidator = SleepConsolidator(scope="payment_service")
report = consolidator.run(session_id="session_01")
# -> {'episodes_processed': 1, 'memories_written': 1, 'rules_promoted': 0, ...}

# 4. Next session: recall relevant context before executing
context = memory.recall("Add Stripe webhook handler")
print(context)
# [MEMORY CONTEXT]
# Relevant past experience:
#   ⚠ [LESSON] Caution on task: Refactor payment processor to async:
#     A previous attempt failed: SyntaxError: 'await' outside async function.
# [END MEMORY CONTEXT]

Installation

Schnellinstallation mit MCP-Unterstützung:

pip install "agent-sleep[mcp]"

Mit vollständigen semantischen Einbettungen (empfohlen):

pip install "agent-sleep[all]"

Von GitHub (neueste Alpha):

pip install git+https://github.com/thevisionhub/agent-sleep.git

Bearbeitbare Installation für die Entwicklung:

git clone https://github.com/thevisionhub/agent-sleep.git
cd agent-sleep
pip install -e ".[all]"

MCP-Tool-Referenz

Alle Tools setzen scope standardmäßig auf den Namen des aktuellen Arbeitsverzeichnisses und db_path auf .agent_sleep/memory.db im Projektstamm. Für den häufigsten Anwendungsfall ist keine Konfiguration erforderlich.

Tests ausführen

pytest tests/ -v

Entdeckt werden – Registry-Einträge

Die Einreichung von agent-sleep bei MCP-Registries dauert jeweils etwa 5 Minuten und ist der schnellste Weg, Entwickler zu erreichen, die nach Speichertools suchen:

• Smithery – GitHub-URL einfügen, kurze Beschreibung hinzufügen, fertig.

• modelcontextprotocol/servers – einen PR öffnen, der unter „Community Servers" einen Eintrag zur README hinzufügt.

• Cursor – zeigt ebenfalls MCP-Server an; prüfe die aktuellen Dokumente für den neuesten Einreichungsprozess.

Lizenz

MIT-Lizenz – kostenlos für private, kommerzielle und Forschungszwecke.