Waggle-mcp

Зачем нужен waggle-mcp?

Большинство LLM забывают всё после завершения диалога. waggle-mcp исправляет это, предоставляя вашему ИИ постоянный граф знаний, который он может читать и изменять через любой MCP-совместимый клиент.

Ключевое преимущество Waggle — эффективность использования токенов при структурированном контексте:

Примечание о поиске: Waggle жертвует частью полноты охвата ради значительно меньших затрат токенов и более богатого реляционного контекста. Честные цифры см. в разделе бенчмарков.

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

pip install waggle-mcp
waggle-mcp init

Мастер init обнаруживает ваш MCP-клиент, записывает файл конфигурации и создает директорию базы данных — редактирование JSON не требуется. Поддерживаются Claude Desktop, Cursor, Codex и универсальный JSON-вариант.

После инициализации перезапустите MCP-клиент, и ваш ИИ получит постоянную память. Никаких облачных сервисов. Никаких API-ключей. Семантический поиск работает полностью локально.

Посмотрите на него в действии

Вот конкретный пример «до/после» для разработчика, ежедневно использующего ИИ:

Сессия 1 — 10 апреля

User:  Let's use PostgreSQL. MySQL replication has been painful.
Agent: [calls observe_conversation()]
       → stores decision node: "Chose PostgreSQL over MySQL"
       → stores reason node:   "MySQL replication painful"
       → links them with a depends_on edge

Сессия 2 — 12 апреля (свежее окно контекста, никакой истории)

User:  What did we decide about the database?
Agent: [calls query_graph("database decision")]
       → retrieves the decision node + linked reason from April 10

       "You decided on PostgreSQL on April 10. The reason recorded was
        that MySQL replication had been painful."

Сессия 3 — 14 апреля

User:  Actually, let's reconsider — the team is more familiar with MySQL.
Agent: [calls store_node() + store_edge(new_node → old_node, "contradicts")]
       → conflict is flagged automatically; both positions are preserved in the graph

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

Как это работает

Память не просто сохраняется — она проходит через жизненный цикл:

You talk to your AI
        │
        ▼
  observe_conversation()          ← AI drops the turn in; facts extracted via structured LLM (regex fallback)
        │
        ▼
  Graph nodes are created         ← "Chose PostgreSQL" becomes a decision node
  Edges are inferred              ← linked to the "database" entity node
        │
        ▼
  Future conversation starts
        │
        ▼
  query_graph("DB schema")        ← semantic search finds the node from 3 sessions ago
        │
        ▼
  AI answers with full context    ← "You decided on PostgreSQL on Apr 10, here's why…"

Каждый узел содержит семантические эмбеддинги, вычисленные локально с помощью all-MiniLM-L6-v2 — быстрой и легкой модели, которая работает полностью на устройстве без необходимости в API-ключе или сетевых вызовах. Это означает, что семантический поиск работает офлайн, не стоит ничего за запрос и сохраняет конфиденциальность ваших данных.

Волшебный инструмент: observe_conversation

Это инструмент, который вы будете использовать чаще всего. Вам не нужно вручную сохранять факты — просто скажите агенту наблюдать за каждым ходом диалога, и он сделает всё остальное.

observe_conversation(user_message, assistant_response)

Внутри он:

1. Извлекает атомарные факты из обеих сторон диалога

2. Удаляет дубликаты, сравнивая с существующими узлами по семантическому сходству

3. Создает типизированные связи между связанными концепциями

4. Помечает противоречия с уже сохраненными убеждениями

Инструкции не нужны. Схему определять не нужно. Просто наблюдайте.

Внутри каждый вызов запускает LLM-проход для извлечения данных с проверкой через Pydantic (с резервным вариантом через регулярные выражения), чтобы вытянуть структурированные факты из хаотичного диалога.

Пример: "Давайте использовать PostgreSQL, потому что репликация MySQL слишком болезненна."

{
  "facts": [
    {
      "label": "PostgreSQL for generic events",
      "content": "Chose PostgreSQL over MySQL because MySQL replication is too painful.",
      "node_type": "decision",
      "confidence": 0.95,
      "tags": ["llm-extracted", "confidence:0.95"]
    }
  ]
}

Любое извлечение с confidence < 0.5 или неверной схемой молча отбрасывается, чтобы предотвратить шум от галлюцинаций.

Модель памяти

Типы узлов — что сохраняется:

Типы связей — как узлы соединяются:

relates_to · contradicts · depends_on · part_of · updates · derived_from · similar_to

MCP-инструменты

Ваш ИИ вызывает их напрямую — вам не нужно использовать их вручную.

Производительность и бенчмаркинг

Все приведенные ниже цифры воспроизводимы с помощью фикстур в benchmarks/fixtures/ с использованием инструментария scripts/benchmark_extraction.py. Сохраненные артефакты вывода находятся в tests/artifacts/.

Одна команда создает все таблицы ниже (базовая линия regex-извлечения, поиск, дедупликация и пилотный проект по сравнительной эффективности токенов):

PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend regex \
  --systems waggle rag_naive \
  --output tests/artifacts/benchmark_current.json

Строка извлечения LLM (75%) требует отдельного запуска с локальным экземпляром Ollama — она не включена в benchmark_current.json:

# Requires Ollama running locally with qwen2.5:7b pulled
PYTHONPATH=src .venv/bin/python scripts/benchmark_extraction.py \
  --extraction-backend llm --ollama-model qwen2.5:7b --ollama-timeout-seconds 30

Точность извлечения

Корпус: 12 пар диалогов, охватывающих простое вспоминание, прерывания, изменения мнений, расплывчатые утверждения и противоречивые сигналы (benchmarks/fixtures/extraction_cases.json).

Точность поиска

Корпус: 18 узлов, 18 запросов — 6 простых (прямое перефразирование) и 12 сложных (состязательные: семантическое обобщение, временная дезамбигуация, косвенный перевод домена, фрейминг конфиденциальности). Источник: benchmarks/fixtures/retrieval_cases.json.

Эффективность токенов по сравнению с наивным RAG на чанках

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

Корпус: 24 мультисессионных сценария, 66 поисковых запросов по 7 семействам задач (benchmarks/fixtures/comparative_eval.json).

Waggle использует ~4× меньше токенов на поиск, чем наивный базовый уровень на чанках в этом корпусе.

Разрыв между Hit@k Waggle (91%) и точной поддержкой (74%) указывает на то, что поиск по графу находит нужную тему, но иногда возвращает недостаточно подтверждающих деталей — наиболее заметно в запросах cross_scenario_synthesis (8/8 попаданий, 1/8 точно). Улучшение сборки контекста — особенно глубины обхода связей и расширения подграфа — является следующим шагом в плане разработки.

Компромисс честен: базовый уровень на чанках достигает 100% Hit@k на этом корпусе, потому что при top_k=5 каждый факт извлекаем из своего собственного чанка сессии. Преимущество в эффективности токенов реально и воспроизводимо; утверждение о превосходстве поиска требует корпуса, где покрытие чанков не может компенсировать отсутствие реляционного контекста. Укрепление корпуса продолжается.

Когда извлечение не удается

Пользователь: "Да, давай просто сделаем ту штуку, о которой мы говорили."

LLM присваивает низкую уверенность (confidence < 0.5) неоднозначному вводу; Waggle молча отбрасывает извлечение, вместо того чтобы сохранять догадку. Конвейер не переключается молча на regex при таймауте — сбои бэкенда проявляются как явные ошибки, которые логируются.

Корпус: 22 пары узлов — 11 истинных дубликатов (синоним, перефразирование, эквивалентность доменов) и 11 «ложных друзей» (одна категория технологий, разные технологии). Источник: benchmarks/fixtures/dedup_cases.json.

Конвейер запускает пять уровней:

1. Уровень 0 — Жесткая блокировка по ключу сущности — если оба узла называют разные технологии в одной категории (например, postgresql против mysql), слияние блокируется безусловно.

2. Уровень 0b — Защита от числовых конфликтов — та же сущность, но разные критические числа (например, jwt 15 мин против 1 часа) → блокировка. Защищает от слияния различных фактов, которые разделяют технологию, но различаются по ключевому значению.

3. Уровень 1 — Точное совпадение строк — нормализованное содержимое или равенство меток.

4. Уровень 2 — Содержание подстроки — одно предложение является строгим подмножеством другого.

5. Уровень 3 — Семантическое сходство — косинус через all-MiniLM-L6-v2:

   • Агрессивный путь для одной сущности: если оба ссылаются на один и тот же токен сущности, слияние при косинусе ≥ 0.60 (ловит истинные дубликаты-перефразирования, такие как "fastapi был выбран" / "мы выбрали fastapi, потому что async")

   • Порог с учетом типа: decision/preference → 0.82; fact → 0.92