🧠 agent-sleep

Consolidación persistente de experiencia y soporte de decisiones para agentes de IA.

Una biblioteca de Python ligera y agnóstica al framework, y un servidor MCP que proporciona consolidación persistente de experiencia y señales de soporte de decisiones que un agente anfitrión puede usar para adaptarse entre sesiones, inspirado en cómo el cerebro biológico utiliza los ciclos de sueño para consolidar experiencias de vigilia en reglas procedimentales y lecciones duraderas.

El problema: "Amnesia del agente"

Todos los frameworks modernos de agentes de IA (LangChain, AutoGen, CrewAI, OpenAI Assistants) sufren de Amnesia del agente:

• Cada nueva conversación o ejecución de subagente comienza completamente desde cero.

• Cuando un agente encuentra un error o descubre una convención del código base el lunes, repite exactamente el mismo error el martes.

• Las bases de datos vectoriales (RAG) solo buscan documentos estáticos — no aprenden de la experiencia en tiempo de ejecución.

Related MCP server: cortex-engine

Inicio rápido con MCP — 10 segundos

Esta es la ruta de uso principal. agent-sleep se distribuye como un servidor MCP, por lo que cualquier agente que soporte MCP (Antigravity, Claude Desktop, Cursor, Cline) puede usarlo sin escribir código.

Paso 1 — Instala y genera tu configuración

# 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 detecta automáticamente tu sistema operativo e imprime el fragmento JSON para pegar en el archivo de configuración de tu cliente MCP. No se requiere edición manual.

Paso 2 — Pega el fragmento de configuración

El comando init imprime exactamente qué pegar y dónde. Ejemplo de salida para Claude Desktop en macOS:

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

Pégalo en ~/Library/Application Support/Claude/claude_desktop_config.json, reinicia Claude, y listo.

Paso 3 — Pide a tu agente que lo use

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

La memoria se almacena automáticamente en .agent_sleep/memory.db en el directorio de tu proyecto (ignorado por git por defecto).

Inspecciona lo almacenado — CLI

No necesitas pasar por un LLM para ver lo que tu agente ha aprendido:

# 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

Cómo funciona: el pipeline de 3 fases

          [ 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.   │
└──────────────────────────────────────────────┘

Características clave (v0.1.2-alpha)

• BLOBs vectoriales precomputados: Incrusta la consulta una vez y la compara con vectores almacenados precomputados, eliminando la incrustación repetida de texto durante la recuperación.

• Ciclo de vida de memoria epistémica: Rastrea la progresión de la memoria a través de etapas (RAW → OBSERVED → REPEATED → VERIFIED → ACTIVE), poniendo automáticamente en cuarentena memorias contradictorias o con alta tasa de fallos.

• Atribución causal verificable y retroalimentación de utilidad: Evalúa si las memorias recuperadas realmente ayudaron a la ejecución futura mediante registros de evidencia estructurados (retrieval → action change → outcome attribution).

• Hipótesis causales por diversidad de evidencia: Destila fallos recurrentes en mecanismos causales utilizando escalado de diversidad de evidencia en fuentes y entornos independientes.

• Modelo bayesiano de autocompetencia: Estima la competencia en el dominio y la incertidumbre de distribución Beta bayesiana en dominios compuestos para proporcionar soporte de decisiones adaptativo (intensidad de verificación, presupuestos de reintento) para agentes anfitriones.

• Motor de especificidad de reglas de primera clase: Resuelve conflictos de reglas mediante precedencia jerárquica (specific verified > general verified > specific candidate > general candidate) y supresión dinámica de excepciones.

• Aislamiento de alcance y proyecto: Espacios de nombres de múltiples niveles (scope="repo_a", scope="global"). El conocimiento específico del proyecto está estrictamente aislado, mientras que los modismos universales y los modos de fallo de herramientas pueden compartirse opcionalmente mediante global.

• Cero dependencias pesadas obligatorias: Funciona de inmediato usando SQLite estándar y un respaldo determinista de bolsa de palabras con hash. Se actualiza sin problemas a sentence-transformers (all-MiniLM-L6-v2) cuando está instalado.

Benchmarks y evaluación

1. Simulación de transferencia controlada (benchmarks/run.py)

Evalúa la consolidación de memoria, la recuperación vectorial y la transferencia de conocimiento en 12 tareas de software secuenciales con trampas arquitectónicas recurrentes:

Nota: La simulación de transferencia controlada evalúa la dinámica determinista de control cognitivo de la recuperación de memoria y la evitación de trampas.

2. Benchmark canónico de ablación de 6 vías (benchmarks/agent_eval/runner.py)

Evaluación controlada en sandbox de la dinámica de control del agente impulsada por memoria en 8 tareas estandarizadas de ingeniería de software:

python benchmarks/agent_eval/runner.py

[!NOTE] Divulgación científica y de backend:

• El benchmark en sandbox evalúa la dinámica de control del agente, la eficiencia de tokens y la evitación de errores bajo suites de pruebas controladas.

• Backends de incrustación: La similitud vectorial de alta precisión depende de sentence-transformers (all-MiniLM-L6-v2). Cuando faltan dependencias, la biblioteca recurre automáticamente a una incrustación determinista de bolsa de palabras con hash.

• Los protocolos completos de reproducibilidad y los registros de métricas están documentados en benchmarks/agent_eval/results.json.

Uso de la biblioteca Python

Si prefieres manejar el sistema de memoria desde tu propio código de agente en lugar de a través de MCP, la API de Python es totalmente compatible.

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]

Instalación

Instalación rápida con soporte MCP:

pip install "agent-sleep[mcp]"

Con incrustaciones semánticas completas (recomendado):

pip install "agent-sleep[all]"

Desde GitHub (última alfa):

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

Instalación editable para desarrollo:

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

Referencia de herramientas MCP

Todas las herramientas establecen por defecto scope al nombre del directorio de trabajo actual y db_path a .agent_sleep/memory.db en la raíz del proyecto. No se requiere configuración para el caso común.

Ejecutar pruebas

pytest tests/ -v

Hazte descubrir — Listados en registros

Enviar agent-sleep a los registros MCP toma unos 5 minutos cada uno y es la forma más rápida de llegar a desarrolladores que buscan herramientas de memoria:

• Smithery — pega la URL de GitHub, añade una breve descripción, listo.

• modelcontextprotocol/servers — abre un PR añadiendo una entrada al README bajo "Community Servers".

• Cursor — también muestra servidores MCP; consulta su documentación actual para el proceso de envío más reciente.

Licencia

Licencia MIT — libre para uso personal, comercial y de investigación.