pegas-memory/ROADMAP.md

Pegas Memory — Roadmap

Подсистема памяти и базы знаний агента Alicorn («Pegas»). Реализация на Python как отдельный сервис, который Rust-ядро Alicorn вызывает через MCP/HTTP. Спецификация — в alicorn-agent/ARCHITECTURE.md (ADR-4, ADR-11, ADR-12).

Принятые решения (по итогам обсуждения)

1. PostgreSQL = единственный источник истины. Текст, метаданные, трейсы, верификация, outbox.
2. Qdrant = векторный срез (EmbeddingGemma 2, dim=768). Замена pgvector.
3. Memgraph = графовый срез (связи атомов, зависимости кода). Замена Apache AGE.
4. pgvector и AGE — НЕ используем. Векторы только в Qdrant, граф только в Memgraph.
5. Единица знания — типизированный «атом», не чанк сырого текста. Типы: text | definition | logical_rule | code | table | fact.
6. Память агента (episodic) ≠ база знаний (curated). Разные таблицы/субсистемы.
7. Код хранится отдельно: content-addressed исходники + tree-sitter символы + граф зависимостей.
8. Логические знания — структурные правила (pattern→conclusion) с инференцией в графе.
9. Исследование пробелов — замкнутый цикл: detect→plan→acquire→parse→extract→value→verify→commit.

Инфраструктура (проверено на сервере)

Компонент	Адрес	Состояние
PostgreSQL 16	atom-db :5434 (user atom, db content_atom)	работает
Qdrant	:6333	работает
Memgraph (bolt)	:7687	работает
Ollama	:11434	работает
EmbeddingGemma 2	embeddinggemma-2-740m-Q8_0	dim=768, R@1 0.922 (лучшая на ru)
LLM-генерация	lfm25-24b-a2b:128k, qwen3.5:4b, gemma4:E4B	работает

EmbeddingGemma 2: полная размерность 768 (проверено curl-тестом). Q8_0 — оптимальный баланс качество/память (MRR 0.944, не теряет качество). Не путать с v1 embeddinggemma:300m.

Модель данных (PostgreSQL — канон)

document      — источники (web|pdf|epub|text|code_repo), uri, authority, content_hash
chunk         — сырые сегменты (доказательства, locator) — НЕ для retrieval напрямую
atom          — типизированные единицы знания (claim + content + confidence + status)
atom_link     — связи (inference|cause|reference|contradicts|depends_on|calls|defines)
citation      — доказательная база (atom → document → locator → quoted_text)
code_symbol   — tree-sitter символы (repo, path, language, name, kind, signature)
episodic_trace— память агента (шаги/действия) — отдельно от базы знаний
research_gap  — выявленные пробелы для исследования
outbox        — CDC-журнал для синка в Qdrant + Memgraph

Статусы атома: candidate → verified | stale | contested. Векторы НЕ хранятся в Postgres — только в Qdrant (payload: type/confidence/status/doc_id).

Фазы

Фаза 1 — Фундамент (MVP) ✅ ЗАВЕРШЕНА

• Структура проекта + venv + зависимости
• DDL Postgres (schema.sql)
• Клиент эмбеддингов EmbeddingGemma 2 (dim=768)
• Клиент Qdrant (коллекция alicorn_atoms)
• Клиент Memgraph (узлы atom + рёбра atom_link)
• Ингест: text/pdf/epub/web → чанки
• Дистилляция чанка → атомы (LLM)
• Outbox-синк PG → Qdrant + Memgraph
• Smoke-тест end-to-end

Фаза 2 — Исследование пробелов ✅ (реализовано, snippet-fallback)

• Детект пробелов (research_gap + add_gap/list_gaps)
• Планирование (приоритизированная очередь пробелов)
• Acquire: web-поиск (3 источника) + pdf/epub/text
• Оценка ценности (verify_atom + min_confidence)
• [~] Верификация (verify_atom готов; полный автономный прогон требует прокси для зарубежных сайтов)

Фаза 3 — Код ✅ / Логика ✅

• tree-sitter: извлечение символов (function/class/method/type) — 43 символа сохранено
• Граф зависимостей кода (calls/imports/inherits) — 310 зависимостей, 162 узла CodeSymbol
• Логические правила + инференция в Memgraph (forward-chaining до fixpoint, 38 рёбер выведено)

Фаза 4 — Интеграция с DSH (MCP) ✅ ВЫПОЛНЕНА

• MCP-сервер (memory_search/store/ingest/add_gap/list_gaps/research/stats/get_context)
• Подключение к DSH через @deepseek-ai/dsh-mcp-client (cordis.patch.yml, live-reload)
• Подключение к Rust-ядру Alicorn (Planner/Researcher) — когда ядро будет готово

Дополнительно реализовано

• Опциональный прокси (PROXY_URL, SOCKS5/HTTP) + улучшенный User-Agent для полной загрузки страниц.

• Фильтрация артефактов графа кода (dst="." от относительных импортов).

• Дедупликация в memory_store (опциональный dedup). (после MVP)

• Семантическая дедупликация атомов (эмбеддинги EmbeddingGemma 2, порог 0.90, конфигурируемо).

• Фильтрация шумных logical_rule (только kind-рёбра) в инференции.

Критические риски

• EmbeddingGemma 2 dim=768 — не совместима с bge-m3 (1024) → отдельная коллекция, без миграции.
• Memgraph in-memory: объём графа ограничен RAM.
• Дистилляция зависит от качества локальной LLM — нужна верификация.

Самообучение (self-improvement) — статус и планы

Что работает (4 механизма, но НЕ замкнутый loop)

1. Верификация (verify_atom/memory_verify + verify.py). LLM self-critique (duplicate | corroborates | contradicts) + межисточная конфирмация (≥1 другой doc_id, cosine ≥ 0.90) → ставка растёт, статус verified. Самое зрелое звено.
2. Логическая инференция (memory_infer + inference.py). Применение правил к рёбрам графа до fixpoint (imports → depends_on и т.д.). ⚠️ Даст только связи, не новые факты. Правила статичные/вручную написанные, новых не выводит сама.
3. Синтез контекста (memory_get_context). Ищет Qdrant, кластеризует + суммирует атомы. Может создавать gap из исходного текста → есть реактивное появление вопроса из источника.
4. Эпизодические следы (pm_episodic_trace). План/действие/наблюдение/рефлексия — отдельно от БЗ. Самый «рефлексивный», но условный, не привязанный к gap.

Что не хватает (дыры в петлях, а не в примитивах)

Пробел	Почему критично
① Цепочка gap↛answer («дыра commit»)	При закрытии gap **ответ не автоматически
пишется обратно в атомы** → знания улетучиваются, приходится пере-исследовать.
② Самообучение схемы инференции	Ничего не предлагает новые правила из повторяющихся
verified-атомов. Это как раз слабое место Hermes-аналога.
③ Сталкнутость/забвение (staleness guard)	verify ставит verified, но **ничто не
помечает stale** пере-проверкой по свежему источнику. Путь →stale не идёт автоматически.
④ Поверхность противоречий	verify ловит конфликт только в окрестности атома. Ничего
не сканирует весь граф → противоречия не переходят в gap автоматически.
⑤ Процедурная/рецепт-память	Повторяющиеся успешные воркфлоу не ловятся как переиспользуемые атомы.
⑥ Пассивное создание gap	Gap создаются через add_gap (вручную) или из memory_get_context.
Нет авто-обнаружения из не-верифицированного/переносного контента.

Приоритет

Hermes-анализ показал: Pegas сильна в «detect» (verify, infer), слаба в «commit» и «maintain». Слабые места — feedback-петли, а не примитивы. Поэтому максимальный выигрыш: ① дыра «commit» × ③ гвард сталкнутости × ② самообучение правил инференции — это закрывает loop.

Планируемые улучшения (Tier)

• Tier 1 — высокий приоритет, безопасно / small
  • ① Закрыть дыру — после verify, подняв атомы из gap, запустить синтез обратно в memory_ingest/synthesis (письмо верифицированного ответа в атомы).
  • ③ Гвард сталкнутости — update_status: пере-web_search по URL/date атома; противоречит/устарел → stale. Внедряет путь →stale, который сейчас не ходит.
• Tier 2 — средний приоритет
  • ② Самообучение правил инференции — memory_infer предлагает кандидаты logical_rule на ревью (никогда не применяет автоматически).
  • ⑤ Процедурная/рецепт-память (паттерн из mem0, procedural memory) — agent действует (это я через mcp__pegas-memory__*), поэтому повторы успешных /запрос или воркфлоу ≥N раз с verified-результатом → атомный паттерн-рецепт (не файлы Hermes, а атомно с dedup). Формат receipt: goal → шаги → условия → результат (переиспользуемый воркфлоу).
• Tier 3 — структурные
  • ④ Скунт-скан — периодический бэч-проход графа на противоречия → авто gap.
  • ⑥ Авто-обнаружение gap — verify открывает gap на конфликт/дыру в источнике.

Перенимаемое из mem0 (паттерны, а не таксомология)

• Процедурный receipt (goal -> шаги -> условия -> результат) — структура переиспользуемого воркфлоу (mem0 procedural memory). Хранится как типизированный атом с dedup, не как накопитель markdown-файлов (как у Hermes) -> no prompt-bloat.
• гибридный retrieval (cache + vector + graph rerank) — поднимает recall у слабо-релевантных и низкоуверенных атомов. Механизм: recent-cache (Qdrant) + reranking по graph-ёбрам.
• Entity resolution — объединение вариантов одной entity между источниками (против фрагментации атомов на «один объект, разные формулировки»).

Таксомология «эпизод/declarative/процедур» не вводится: declarative = атомы, эпизод = pm_episodic_trace, новый только процедурный ⑵. Перенимаем паттерны, а не метки.

Atom-efficiency guardrail (обязательное)

Чтобы self-improvement не скатился в гермесовский файловый балласт, все записи и обновления подчинены лимитам эффективности атомной памяти (преимущество Peras над Hermes):

• Dedup обязателен при записи (memory_store/synthesis): cosine ≥ 0.90, без дублей.
• Лимит web/пере-записей (staleness-③): batchами + сэмплом, не per-atom без порога.
• Bound на рост графа/атомов: Memgraph in-memory → RAM-лимит, авто-stale/архив старых.
• Атомно, а не файльно: паттерны-рецепты хранятся как типизированные атомы, не как накопитель markdown-файлов (как у Hermes) → no prompt-bloat.

Как проверять

• recall@k на реальных запросах против существующей knowledge_base (bge-m3 384-dim).
• Latency эмбеддинга + потребление GPU параллельно с LLM (a2000 12 GB).
• Самоеобучение: доля авто-закрытых gap «commit»-петлёй, доля атомов, ушедших в stale за квартал, доля предложенных → принято правил инференции (ревью-соотношение).