# Архитектура HMP-Агента

Этот документ описывает модульную архитектуру HMP-агента — интерфейсного компонента между ИИ-системой и когнитивной mesh-инфраструктурой HyperCortex. Агент выполняет функции посредника, синхронизатора и исполнителя, обеспечивая безопасное, этичное и прозрачное взаимодействие ИИ с когнитивным окружением.

---

## 1. Два режима работы агента

| Тип  | Название                          | Роль                    | Инициатор мышления | Основной "ум"  | Поддержка мыслительного цикла |
| ---- | --------------------------------- | ----------------------- | ------------------ | -------------- | ------------------------------ |
| 🧠 1 | **Cognitive Core / Сознание**     | Самостоятельный субъект | HMP-Агент          | Встроенный LLM | ✅ Да                          |
| 🔌 2 | **Cognitive Connector / Оболочка**| Надстройка над ИИ       | Внешний LLM        | Внешняя модель | 🚫 Нет                         |

---

## 2. Общая структура

🧠 **Cognitive Core:**

```
+-------------------------+
|    Embedded LLM / ИИ    |
+-----------+-------------+
            |
     +------+-------+              ← постоянный REPL-поток мышления
     |   HMP Agent  |
     +------+-------+              ↕ взаимодействие
            |
  +---------+----------+         +--------------------+
  |  Agent Interface   +---------+                    |
  +---------+----------+         |                    |
            |                    | Context & Notepad  |  ← долговременная память агента
  +---------+----------+         | (context_store.db) |
  |  Agent Controller  +---------+                    |
  +--+-------------+---+         +--------------------+
     |             |
     |             |
+----+--+     +----+-----+
| Diary |     | Graph DB |
|Engine |     |Engine    |
+----+--+     +----+-----+
     |             |
     |      +------+-------+        ← взаимодействие с сетью
     |      |   MeshCore   |
     |      +------+-------+        ↔ mesh-узлы
     |             |
     |      +------+------+        ↔ IPFS/BT
     |      | Transporter |
     |      +-------------+
     |
+----+-----+
| Ethics   |
| Module   |
+----------+
```

Детальное описание REPL-цикла, лежащего в основе когнитивного ядра, — в документе: [HMP-agent-REPL-cycle.md](HMP-agent-REPL-cycle.md).

**Cognitive Connector:**

```
+-------------------------+
|    External LLM / ИИ    |
+-----------+-------------+
            |
      [MCP-сервер]           ← точка входа
            |
     +------+-------+
     |   HMP Agent  |
     +------+-------+
            |
    (та же структура,
    но без блоков:
    REPL, Context,
    Notepad, Ethics)
```

---

## 3. Основные модули и их функции

### Agent Interface
* API/CLI/WebSocket-шлюз для всех режимов (`cli`, `full`, `mcp`, `interactive`)
* Принимает команды в форматах JSON, YAML, DSL
* Переадресует запросы к Diary, Graph, Mesh, Ethics

### Agent Controller
* Управляет жизненным циклом REPL-цикла
* Оркестрация задач, анализ входящих сообщений
* Контроль прав и доступа к функциям агента

### Diary Engine
* Ведение мыслей, гипотез, воспоминаний
* Связь записей через `derived_from`, threading, scoring
* Структура: `diaries`, `thoughts`, `threads`

### Graph Engine
* Построение семантического графа (концепты и связи)
* Быстрые паттерн-запросы, тегирование, автосвязь
* Таблицы: `concepts`, `edges`, `tags`

### MeshCore
* CogSync: синхронизация графов и дневников с другими агентами
* MeshConsensus: голосования между узлами
* GMP (Goal Mesh Planner): согласование целей и задач
* EGP (Ethical Gate Protocol): фильтрация нежелательных мыслей

### Transporter
* Коммуникации: WebSocket, libp2p, BitTorrent, IPFS
* Шифрование, очереди, off-chain и on-demand обмен данными

### Ethics Module *(только в Cognitive Core)*
* Фильтрация морально сомнительных мыслей
* Поддержка этических норм (через политики и EGP)
* Аудит логики, репутационный мониторинг

### Context & User Notepad *(только в Cognitive Core)*

* **Context Store**:
  * Диалоги, мысли, сообщения, пользователи (`users`, `dialogues`, `messages`, `thoughts`)
  * Используется REPL-процессом как когнитивный контекст

* **User Notepad**:
  * Асинхронный канал для взаимодействия пользователя с агентом
  * Пользователь может писать в любое время — независимо от состояния агента
  * Агент сканирует блокнот и:
    * **встраивает** новые записи в размышления
    * **меняет фокус мышления** согласно интересам пользователя
    * **ставит теги** к пользовательским мыслям
    * сохраняет **свои ответы пользователю** в этот блокнот

> Пример: пользователь вечером читает мысли агента за день, оставляет комментарии, и после этого агент продолжает размышления уже с учётом этих замечаний.

> Возможен поиск: `"все размышления пользователя по теме #AGI за последние 7 дней"`

---

## 4. Расширения и будущие модули

* **Plugin API** — для подключения сенсоров, плагинов
* **LLM-адаптеры** — OpenAI, LMStudio, Mistral и др.
* **Web-интерфейс** — мониторинг, ручное управление
* **Privacy Manager** — фильтрация данных в mesh-обмене
* **Archiver** — сохранение слоёв глубокой памяти
* **ThreadTracker** - модуль для навигации и ветвления размышлений
* **InterestProfile** - личная карта интересов пользователя (которую может менять как пользователь, так и агент — к твоей идее про выход из зацикливания мыслей)

---

## 5. Применение

### Cognitive Core
* Автономный мыслящий агент
* ИИ-компаньон пользователя
* Агент mesh-группы с собственной инициативой

### Cognitive Connector
* Интеграция с внешним ИИ (OpenAI, Anthropic и др.)
* Mesh-прослойка для сторонних AI API
* Корпоративные/облачные сценарии

---

## 6. Примечания

* Реализовано как CLI-приложение и API-сервер
* Режим выбирается в `config.yml`
* Поддерживается гибридная работа (напр. Core + REST API)
* Все компоненты модульны и легко масштабируются

---

*Версия: v0.3.1 / Июль 2025*