Skip to content

README.ru.md

Latest commit

 

History

History
219 lines (157 loc) · 16.7 KB

README.ru.md

File metadata and controls

219 lines (157 loc) · 16.7 KB
Raw

Dragon Brain

English | 中文 | 日本語 | Español | Русский | 한국어 | Português | Deutsch | Français

Инфраструктура памяти для ИИ-агентов — которая громко падает при сбоях, по замыслу.

LongMemEval

License: MIT Python 3.12+ Docker Инструменты MCP Тесты Качество GPU GitHub stars

LongMemEval R@5 100% · 34 инструмента MCP · Гибридный поиск менее 200мс · CI-ограничения на громкие сбои (Fail-Loud) · LLM не требуется

Открытый MCP-сервер, предоставляющий любой LLM долгосрочную память через гибрид графа знаний и векторного поиска. Сохраняйте сущности, наблюдения и связи — затем извлекайте их семантически между сессиями. Работает с любым MCP-клиентом: Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI.

В отличие от плоской истории чатов или простого RAG, Dragon Brain понимает связи между воспоминаниями — не только похожесть. Автономный агент («Библиотекарь») периодически кластеризует и синтезирует воспоминания в концепции более высокого порядка.

И он скажет вам, если не сможет вспомнить — вместо того чтобы притворяться, что воспоминания никогда не было.

Быстрый старт

Требования: Docker и Docker Compose. Подробная настройка: См. docs/SETUP.md для платформо-специфичных заметок и устранения неполадок.

1. Запуск сервисов

docker compose up -d

Запускает 4 контейнера:

  • FalkorDB (граф знаний) — порт 6379
  • Qdrant (векторный поиск) — порт 6333
  • Embedding API (BGE-M3, CPU по умолчанию) — порт 8001
  • Dashboard (Streamlit) — порт 8501

Пользователи GPU: docker compose --profile gpu up -d для ускорения NVIDIA CUDA.

Проверьте здоровье сервисов:

docker ps --filter "name=claude-memory"

Установка через pip

pip install dragon-brain

Примечание: Dragon Brain требует FalkorDB и Qdrant, работающие как Docker-сервисы. pip-пакет устанавливает MCP-сервер — сначала запустите docker compose up -d для инфраструктуры. Модель эмбеддингов (~1ГБ) обслуживается через Docker, без локальной загрузки.

2. Подключите вашего ИИ-агента

Claude Code (рекомендуется):

claude mcp add dragon-brain -- python -m claude_memory.server
Claude Desktop / Другие MCP-клиенты

Добавьте в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "dragon-brain": {
      "command": "python",
      "args": ["-m", "claude_memory.server"],
      "env": {
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379",
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "6333",
        "EMBEDDING_API_URL": "http://localhost:8001"
      }
    }
  }
}

Полный шаблон см. в mcp_config.example.json.

3. Начните запоминать

Вы: "Запомни, что я создаю Atlas на Rust и предпочитаю функциональные паттерны."
ИИ:  [создаёт сущность "Atlas", добавляет наблюдения о Rust и функциональных паттернах]

Вы (следующая сессия): "Что ты знаешь о моих проектах?"
ИИ:  "Вы создаёте Atlas на Rust с функциональным подходом..." [извлечено из графа]

Сравнение

Функция История чатов Простой RAG Dragon Brain
Сохраняется между сессиями Нет Зависит Да
Понимает связи Нет Нет Да (граф)
Семантический поиск Нет Да Да (гибрид)
Запросы путешествия во времени Нет Нет Да
Авто-кластеризация Нет Нет Да (Библиотекарь)
Обнаружение связей Нет Нет Да (Семантический Радар)
Работает с любым MCP-клиентом Н/Д Зависит Да
Инфраструктура Fail-Loud Нет Нет Да (Контракт SearchError, проверен в CI)

Бенчмарк

Dragon Brain набирает 100% recall@5 на LongMemEval (ICLR 2025), отраслевом стандарте для систем памяти ИИ — 500 вопросов, 6 категорий, без LLM.

Система Результат Метрика Требуется LLM Локально
Dragon Brain v1.2.0 100% R@5 Нет Да
MemPalace (Haiku rerank) 100% R@5 Да Да
MemPalace (raw) 96.6% R@5 Нет Да
Mem0 ~85% R@5 Да Нет

Полная методология и данные: RESULTS.md

Возможности

Возможность Как работает
Хранение воспоминаний Создание сущностей (люди, проекты, концепции) с типизированными наблюдениями
Семантический поиск Поиск по смыслу, а не только по ключевым словам — «то, что про распределённые системы» работает
Обход графа Следование по связям — «что связано с проектом X?»
Путешествие во времени Запросы к графу памяти на любой момент — «что я знал во вторник?»
Авто-кластеризация Фоновый агент обнаруживает паттерны и создаёт сводки концепций
Обнаружение связей Семантический Радар находит отсутствующие связи, сравнивая векторное сходство с расстоянием в графе
Отслеживание сессий Запоминание контекста разговора и прорывов

Выковано в аудите (Forged in Audit)

Большинство систем памяти с открытым исходным кодом полируют только «счастливый путь» (happy path). Вот баг, с которым Dragon Brain выходил в продакшен в течение двух месяцев — и инфраструктура, которая теперь не даст этому повториться.

Ложь

До апреля 2026 года пайплайн search() выглядел примерно так:

try:
    # ... 6-канальный пайплайн поиска ...
except Exception:
    return []

Инструмент MCP search_memory затем преобразовывал [] в строку "No results found.". Claude получал эту строку и воспринимал её как авторитетный факт — "у пользователя действительно нет воспоминаний на эту тему" — хотя на самом деле мог упасть сервис эмбеддингов, пропасть связь с FalkorDB или отвалиться по таймауту Qdrant.

Каждый деградировавший запрос заставлял ИИ строить выводы без контекста, даже не подозревая об этом. Это была уверенная ложь, неотличимая от истинной пустоты, вшитая в самую вызываемую функцию системы.

Исправление

4-этапный состязательный аудит выявил 83 нарушения контрактов в 37 исходных файлах. 10 пакетов исправлений вышли с апреля по май 2026 года:

  • Сбой инфраструктуры теперь вызывает SearchError — пустой список означает «результатов не найдено», и только это.
  • MCP search_memory возвращает структурированную ошибку {"error": "MEMORY_LAYER_DEGRADED", "retry_safe": true} — чётко сообщая ИИ о деградации, и больше никакой уверенной лжи.
  • Межхранилищная компенсация при создании/обновлении/удалении сущностей — ошибка записи в Qdrant откатывает изменения в FalkorDB, предотвращая появление потерянных узлов (split-brain).
  • Запись рёбер (связей) использует MERGE, а не CREATE — повторные вызовы create_relationship не дублируют рёбра.
  • Ошибки записи в FTS пробрасываются вызывающему — мы исключили тихое устаревание индексов.
  • Менеджер блокировок бросает TimeoutError при конфликтах — он больше никогда тихо не продолжает работу без блокировки.
  • Инструменты MCP теперь валидируют семантику — некорректные UUID возвращают {"error": "ENTITY_NOT_FOUND"}, а не молча пустой результат.

Дисциплина

  • tox -e contracts — CI зафиксировал базовый предел в 13 нарушений (было 64). Любое новое нарушение прервёт сборку до слияния. Ежеквартальные ревью будут снижать этот предел до нуля.
  • Поведенческие интеграционные тесты — testcontainers-python поднимает реальные falkordb/falkordb:v4.14.11 и qdrant/qdrant:v1.16.3, а затем выполняет container.kill() прямо в процессе операции, чтобы гарантировать соблюдение контракта громких сбоев (fail-loud) на всех уровнях.
  • Нативный асинхронный репозиторий — AsyncMemoryRepository изолирует синхронные драйверы БД в пулах потоков в ~75 местах вызова.
  • Документирование границ доверия — каждая межпроцессная граница имеет явный контракт, описанный в docs/ARCHITECTURE.md.

Почему это важно

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

Насколько нам известно, Dragon Brain — первая open-source система памяти, где принцип громких сбоев (fail-loud) является CI-проверяемым контрактом. Если подобное когда-либо повторится, код просто не пройдёт сборку.

Итоги (Receipts)

  • 1 337 тестов в 106 тестовых файлах, 0 упавших, 0 пропущенных
  • Мутационное тестирование — 2 270 мутантов, из которых убито 1 184 в 27 файлах (3 злобных / 1 грустный / 1 счастливый тест на каждую функцию)
  • Property-based тесты — 38 свойств Hypothesis
  • Фаззинг-тестирование — 30 000+ входных данных, 0 падений
  • Статический анализ — mypy strict mode (0 ошибок), ruff (0 ошибок)
  • Аудит безопасности — Проверка на Cypher-инъекции, поиск утёкших учётных данных
  • Поиск мёртвого кода — Vulture (0 находок)
  • Dragon Brain Gauntlet — 20 раундов автоматизированного аудита качества, A− (95/100)

Полные результаты Gauntlet: docs/GAUNTLET_RESULTS.md · Границы доверия: docs/ARCHITECTURE.md · Интеграционные тесты: tests/integration/test_db_kill_scenarios.py

Варианты использования

  • Долгосрочные проекты — Накапливайте контекст неделями/месяцами. Dragon Brain запоминает архитектурные решения, прорывы и аргументацию.
  • Исследования — Создавайте постоянный граф знаний из статей, концепций и связей.
  • Мультиагентные системы — Общий слой памяти для команд агентов. Открытия одного агента мгновенно доступны другим.
  • Управление личными знаниями — Ваш ИИ учится вашим предпочтениям, стилю работы и экспертизе.

Устранение неполадок

Проблема Решение
Инструменты MCP не отображаются Ошибки MCP бесшумны. Проверьте docker ps --filter "name=claude-memory" — все 4 контейнера должны быть здоровы.
search_memory возвращает пустоту Убедитесь, что сервис эмбеддингов работает на порту 8001. Проверьте curl http://localhost:8001/health.
Путаница с именем графа Граф FalkorDB называется claude_memory (не dragon_brain). Используйте это имя для прямых Cypher-запросов.

Подробнее: docs/GOTCHAS.md · docs/RUNBOOK.md

Лицензия

MIT