🧠 agent-sleep

Постоянная консолидация опыта и поддержка принятия решений для ИИ-агентов.

Легковесная, не зависящая от фреймворка Python-библиотека и MCP-сервер, которые обеспечивают постоянную консолидацию опыта и сигналы поддержки принятия решений, которые агент-хост может использовать для адаптации между сессиями — вдохновлено тем, как биологический мозг использует циклы сна для консолидации дневного опыта в долговременные процедурные правила и уроки.

Проблема: «Амнезия агента»

Каждый современный фреймворк ИИ-агентов (LangChain, AutoGen, CrewAI, OpenAI Assistants) страдает от амнезии агента:

• Каждый новый чат или запуск субагента начинается с нуля.

• Если агент сталкивается с ошибкой или обнаруживает соглашение в кодовой базе в понедельник, во вторник он повторяет ту же самую ошибку.

• Векторные БД (RAG) ищут только в статических документах — они не учатся на опыте выполнения.

Related MCP server: Recall

MCP Быстрый старт — 10 секунд

Это основной путь использования. agent-sleep поставляется как MCP-сервер, поэтому любой агент, поддерживающий MCP (Antigravity, Claude Desktop, Cursor, Cline), может использовать его без написания кода.

Шаг 1 — Установите и сгенерируйте конфигурацию

# 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 автоматически определяет вашу ОС и выводит JSON-фрагмент для вставки в файл конфигурации вашего MCP-клиента. Ручное редактирование не требуется.

Шаг 2 — Вставьте фрагмент конфигурации

Команда init выводит точно, что и куда вставить. Пример вывода для Claude Desktop на macOS:

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

Вставьте это в ~/Library/Application Support/Claude/claude_desktop_config.json, перезапустите Claude, и готово.

Шаг 3 — Попросите агента использовать это

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

Память автоматически сохраняется в .agent_sleep/memory.db в вашем проекте (по умолчанию игнорируется git).

Просмотр сохранённого — CLI

Вам не нужно обращаться к LLM, чтобы увидеть, что выучил ваш агент:

# 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

Как это работает: конвейер из 3 фаз

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

Ключевые возможности (v0.1.2-alpha)

• Предвычисленные векторные BLOB-объекты: Встраивает запрос один раз и сравнивает его с предвычисленными сохранёнными векторами, устраняя повторное встраивание текста при извлечении.

• Эпистемический жизненный цикл памяти: Отслеживает прогрессию памяти по стадиям (RAW → OBSERVED → REPEATED → VERIFIED → ACTIVE), автоматически помещая в карантин противоречивые или часто ошибочные воспоминания.

• Проверяемая причинно-следственная атрибуция и обратная связь по полезности: Оценивает, действительно ли извлечённые воспоминания помогли будущему выполнению, с помощью структурированных записей доказательств (retrieval → action change → outcome attribution).

• Причинные гипотезы на основе разнообразия доказательств: Сводит повторяющиеся сбои к причинным механизмам, используя масштабирование разнообразия доказательств по независимым источникам и средам.

• Байесовская модель самооценки компетентности: Оценивает компетентность в домене и неопределённость по бета-распределению Байеса для составных доменов, обеспечивая адаптивную поддержку принятия решений (интенсивность проверки, бюджеты повторных попыток) для агентов-хостов.

• Механизм специфичности правил первого класса: Разрешает конфликты правил через иерархический приоритет (specific verified > general verified > specific candidate > general candidate) и динамическое подавление исключений.

• Изоляция области и проекта: Многоуровневые пространства имён (scope="repo_a", scope="global"). Знания, специфичные для проекта, строго изолированы, в то время как универсальные идиомы и режимы отказов инструментов могут по желанию распространяться через global.

• Ноль обязательных тяжёлых зависимостей: Работает из коробки с использованием стандартного SQLite и детерминированного резервного варианта на основе хэшированного мешка слов. Бесшовно обновляется до sentence-transformers (all-MiniLM-L6-v2) при установке.

Бенчмарки и оценка

1. Контролируемая симуляция переноса (benchmarks/run.py)

Оценивает консолидацию памяти, векторное извлечение и перенос знаний в 12 последовательных программных задачах с повторяющимися архитектурными ловушками:

Примечание: Контролируемая симуляция переноса оценивает детерминированную динамику когнитивного контроля при извлечении памяти и избегании ловушек.

2. Канонический 6-сторонний абляционный бенчмарк (benchmarks/agent_eval/runner.py)

Контролируемая песочница для оценки динамики управления агентом на основе памяти в 8 стандартизированных задачах разработки ПО:

python benchmarks/agent_eval/runner.py

[!NOTE] Научное и серверное раскрытие:

• Песочница-бенчмарк оценивает динамику управления агентом, эффективность токенов и предотвращение ошибок в контролируемых тестовых наборах.

• Бэкенды встраивания: Высокоточное векторное сходство опирается на sentence-transformers (all-MiniLM-L6-v2). При отсутствии зависимостей библиотека автоматически переключается на детерминированное встраивание на основе хэшированного мешка слов.

• Полные протоколы воспроизводимости и журналы метрик задокументированы в benchmarks/agent_eval/results.json.

Использование Python-библиотеки

Если вы предпочитаете управлять системой памяти из собственного кода агента, а не через MCP, Python API полностью поддерживается.

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]

Установка

Быстрая установка с поддержкой MCP:

pip install "agent-sleep[mcp]"

С полными семантическими встраиваниями (рекомендуется):

pip install "agent-sleep[all]"

Из GitHub (последняя альфа):

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

Редактируемая установка для разработки:

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

Справочник MCP-инструментов

Все инструменты по умолчанию устанавливают scope на имя текущей рабочей директории и db_path на .agent_sleep/memory.db в корне проекта. Для обычного случая конфигурация не требуется.

Запуск тестов

pytest tests/ -v

Как стать обнаруженным — листинги в реестрах

Отправка agent-sleep в MCP-реестры занимает около 5 минут на каждый и является самым быстрым способом привлечь разработчиков, ищущих инструменты памяти:

• Smithery — вставьте URL GitHub, добавьте краткое описание, готово.

• modelcontextprotocol/servers — откройте PR, добавив запись в README в раздел "Community Servers".

• Cursor — также отображает MCP-серверы; проверьте их текущую документацию для актуального процесса подачи.

Лицензия

Лицензия MIT — бесплатно для личного, коммерческого и исследовательского использования.