docs/HMP-Agent-Architecture.md

# HMP-Agent-Architecture.md

## 🧠 Архитектура 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*