# Pegas Memory

Подсистема памяти и базы знаний агента **Alicorn** (рабочее имя «Pegas»).

- **PostgreSQL** — единственный источник истины (текст, метаданные, трейсы, верификация).
- **Qdrant** — векторный срез (EmbeddingGemma 2, dim=768).
- **Memgraph** — графовый срез (связи атомов, зависимости кода).
- **Единица знания** — типизированный атом: text | definition | logical_rule | code | table | fact.

## Документация

- [AGENTS.md](./AGENTS.md) — **инструкция для агента** (English): какой инструмент для какого вопроса, цикл исследования, типичные ошибки.
- [ARCHITECTURE.md](./ARCHITECTURE.md) — архитектура: слои хранения, модель данных, потоки, MCP-инструменты.
- [EXAMPLES.md](./EXAMPLES.md) — примеры работы с базой знаний (English), включая анти-примеры.
- [ROADMAP.md](./ROADMAP.md) — план развития.

## Структура

```
pegas_memory/
  config.py        — конфиг (адреса сервисов, имена коллекций)
  db.py            — PostgreSQL (источник истины)
  embedding.py     — EmbeddingGemma 2 через Ollama (dim=768)
  qdrant_store.py  — векторный срез
  memgraph_store.py— графовый срез
  distill.py       — дистилляция чанка в атомы (LLM)
  ingest.py        — парсеры text/pdf/epub/web
  outbox_sync.py   — PG → Qdrant + Memgraph
  research.py      — цикл исследования пробелов
  code_symbols.py  — tree-sitter извлечение символов
  code_graph.py    — граф зависимостей кода (calls/imports/inherits)
  inference.py     — логическая инференция (forward-chaining в Memgraph)
  dedup.py         — семантическая дедупликация атомов (эмбеддинги, порог 0.90)
  verify.py        — верификация: self-critique (LLM) + кросс-подтверждение
schema.sql         — DDL PostgreSQL
```


## Подключение к DeepSeek Harness (dsh)

Память подключается как **MCP-сервер** (паттерн dsh, как Gitea/Outline/Playwright):

- **Сервер**: [mcp_server.py](./mcp_server.py) — чистый stdlib, JSON-RPC 2.0, stdio.
- **Инструменты** (видны модели как `mcp__pegas-memory__*`):
  `memory_search`, `memory_store`, `memory_ingest`, `memory_stats`, `memory_get_context`,
  `memory_verify`, `memory_store_code`, `memory_search_code`, `memory_code_graph`,
  `memory_infer`, `memory_query_graph`,
  `memory_add_gap`, `memory_list_gaps`, `memory_get_gap`, `memory_update_gap`, `memory_delete_gap`,
  `memory_commit`, `memory_stale`.
- **Регистрация**: в `~/.dsh/profiles/web/cordis.patch.yml` через `@deepseek-ai/dsh-mcp-client`.
- **Live-reload**: профиль web имеет `patchReload: live` — изменения конфига
  подхватываются без рестарта (проверено: сервер спавнится автоматически).

```yaml
- id: mcp-pegas-memory
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: pegas-memory
    transport: stdio
    command: /home/neo/workspace/pegas-memory/.venv/bin/python
    args:
      - /home/neo/workspace/pegas-memory/mcp_server.py
    toolCallTimeoutMs: 180000
```

## Доступность зарубежных сайтов и прокси

Прямое подключение работает для большинства сайтов (github, wikipedia, postgresql.org),
но часть блокирует по российскому IP (memgraph.com — ConnectTimeout) или ставит
Cloudflare anti-bot (neo4j.com — 403). Поведение research-цикла:

1. Полная загрузка URL (httpx, таймаут 30s).
2. При блокировке — fallback на сниппет из веб-поиска.

Для заблокированных сайтов можно включить SOCKS5/HTTP-прокси:
```bash
export PROXY_URL="socks5://127.0.0.1:1080"   # hysteria2
```
Когда прокси задан, `parse_web` ходит через него; иначе — напрямую.
Поддержка SOCKS5 уже установлена (`httpx[socks]`).

## Управление пробелами (gaps)

Пробел — вопрос, на который в базе пока нет ответа. Полный жизненный цикл:

| Операция | Инструмент |
|---|---|
| Создать | `memory_add_gap(question, reason, priority)` |
| Список (с фильтром) | `memory_list_gaps(status?, limit?)` |
| Прочитать один | `memory_get_gap(gap_id)` |
| Редактировать | `memory_update_gap(gap_id, question?/reason?/priority?/status?)` |
| Удалить | `memory_delete_gap(gap_id)` |

Статусы: `open` → `researching` → `resolved` | `dismissed`.
Причины: `low_coverage`, `low_confidence`, `stale`, `contested`, `user_query`.

Работает целиком на PostgreSQL — без веб-поиска. Поиск выполняет модель встроенным `web_search`.

## Самообучение (self-improvement)

Два инструмента закрывают петлю commit/maintain (см. `ROADMAP.md`):

| Операция | Инструмент |
|---|---|
| Записать верифицированный answer закрытого пробела в атомы | `memory_commit(gap_ids, dedup?)` |
| Пометить устаревшие атомы в `stale` | `memory_stale(atom_id?/all?, limit?, sample?, min_confidence?, age_only?, max_age_days?)` |

- **`memory_commit`** — для каждого `gap_id` ищет верифицированные атомы-ответы, дистиллирует
  канонический атом (обязательный `dedup`) и закрывает пробел. Если верифицированного ответа нет —
  пробел не трогает (`skipped_empty`).
- **`memory_stale`** — два сигнала: **content-staleness** (рефетч источника + LLM-вердикт, для
  зарубежных сайтов нужен `PROXY_URL`) и **age-staleness** (proxy-free, по `fetched_at`, порог
  `max_age_days`, default 90). Лимит LLM-вызовов — `limit` + `sample`.

Источники: `web`/`text`/`epub`/`pdf`. Проверено: рефетч memgraph.com без прокси → `ConnectTimeout`.