# 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) ✅ ЗАВЕРШЕНА
- [x] Структура проекта + venv + зависимости
- [x] DDL Postgres (schema.sql)
- [x] Клиент эмбеддингов EmbeddingGemma 2 (dim=768)
- [x] Клиент Qdrant (коллекция `alicorn_atoms`)
- [x] Клиент Memgraph (узлы atom + рёбра atom_link)
- [x] Ингест: text/pdf/epub/web → чанки
- [x] Дистилляция чанка → атомы (LLM)
- [x] Outbox-синк PG → Qdrant + Memgraph
- [x] Smoke-тест end-to-end

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

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

### Фаза 4 — Интеграция с DSH (MCP) ✅ ВЫПОЛНЕНА
- [x] MCP-сервер (memory_search/store/ingest/add_gap/list_gaps/research/stats/get_context)
- [x] Подключение к 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`
  за квартал, доля предложенных → принято правил инференции (ревью-соотношение).