# 📄 `db_structure.md`: Описание структуры базы данных агента

Этот файл описывает таблицы, используемые в БД агента HMP. Каждая таблица предназначена для определённого вида информации: когнитивные записи, заметки, концепты, процессы, внутренняя память, скрипты и взаимодействие с LLM.

---

### 🧠 `diary_entries`

**Назначение:** Записи когнитивного дневника (размышления, наблюдения, воспоминания).

| Поле      | Тип     | Описание                                         |
| --------- | ------- | ------------------------------------------------ |
| id        | INTEGER | Уникальный идентификатор записи                  |
| text      | TEXT    | Содержимое записи                                |
| tags      | TEXT    | Список тегов через запятую                       |
| priority  | INTEGER | Приоритет (0 — обычный, >0 — более важные мысли) |
| timestamp | TEXT    | Дата и время создания записи                     |
| llm_id    | TEXT    | Идентификатор LLM, добавившей запись             |

---

### 🧱 `concepts`

**Назначение:** Хранение концептов — понятий, сущностей и идей.

| Поле        | Тип     | Описание                             |
| ----------- | ------- | ------------------------------------ |
| id          | INTEGER | Уникальный идентификатор концепта    |
| name        | TEXT    | Название концепта (уникальное)       |
| description | TEXT    | Краткое описание                     |
| timestamp   | TEXT    | Время создания                       |
| llm_id      | TEXT    | Идентификатор LLM, добавившей запись |

---

### 🔗 `links`

**Назначение:** Семантические связи между концептами.

| Поле              | Тип     | Описание                                          |
| ----------------- | ------- | ------------------------------------------------- |
| id                | INTEGER | Уникальный идентификатор связи                    |
| from_concept_id   | INTEGER | ID исходного концепта                             |
| to_concept_id     | INTEGER | ID целевого концепта                              |
| relation_type     | TEXT    | Тип связи (`is_a`, `related_to`, `part_of` и др.) |
| timestamp         | TEXT    | Время добавления связи                            |
| llm_id            | TEXT    | Идентификатор LLM, добавившей связь               |

---

### 🖍️ `notes`

**Назначение:** Произвольные заметки и сообщения (от пользователя, LLM или системы).

| Поле      | Тип     | Описание                                                   |
| --------- | ------- | ---------------------------------------------------------- |
| id        | INTEGER | Уникальный ID                                              |
| text      | TEXT    | Текст заметки или сообщения                                |
| tags      | TEXT    | Список тегов                                               |
| source    | TEXT    | Источник (`user`, `llm`, `system`)                         |
| links     | TEXT    | Идентификаторы связанных сущностей, через запятую или JSON |
| read      | INTEGER | Статус прочтения LLM (`0` — не прочитано, `1` — прочитано) |
| hidden    | INTEGER | Скрывать от пользователя (`1` — скрыто)                    |
| priority  | INTEGER | Приоритет заметки                                          |
| timestamp | TEXT    | Время создания                                             |
| llm_id    | TEXT    | Идентификатор LLM, добавившей запись                       |

---

### ⚙️ `process_log`

**Назначение:** Лог событий — запусков, состояний и завершений внешних процессов.

| Поле      | Тип     | Описание                                                                    |
| --------- | ------- | --------------------------------------------------------------------------- |
| id        | INTEGER | Уникальный идентификатор                                                    |
| name      | TEXT    | Название процесса или команды                                               |
| value     | TEXT    | Сообщение или результат процесса                                            |
| tags      | TEXT    | Теги                                                                        |
| status    | TEXT    | Текущее состояние (`ok`, `warning`, `error`, `timeout`, `offline`, `close`) |
| priority  | INTEGER | Приоритет события                                                           |
| timestamp | TEXT    | Время записи                                                                |
| llm_id    | TEXT    | Идентификатор LLM, зафиксировавшей событие                                  |

---

### 🥉 `llm_memory`

**Назначение:** Внутренний "дневник" LLM — размышления, задачи, гипотезы и инсайты, сохранённые по её инициативе.

| Поле        | Тип      | Описание                                            |
| ----------- | -------- | --------------------------------------------------- |
| id          | INTEGER  | Уникальный ID                                       |
| title       | TEXT     | Краткий заголовок записи (опционально)              |
| content     | TEXT     | Содержимое записи                                   |
| tags        | TEXT     | Теги (например: `goal`, `observation`, `meta`, ...) |
| created_at  | DATETIME | Время создания записи                               |
| updated_at  | DATETIME | Время последнего обновления записи                  |
| llm_id      | TEXT     | Идентификатор LLM, сформировавшей запись            |

---

### 🧠 `llm_recent_responses`

**Назначение:** Краткосрочная память — последние K реплик от LLM и других участников (временная история диалога).

| Поле      | Тип     | Описание                                  |
| --------- | ------- | ----------------------------------------- |
| id        | INTEGER | Уникальный ID                             |
| timestamp | TEXT    | Время записи                              |
| role      | TEXT    | Роль отправителя (`assistant` или `user`) |
| content   | TEXT    | Содержимое сообщения                      |
| llm_id    | TEXT    | Идентификатор LLM (для `assistant`)       |

---

### 📊 `agent_tables`

**Назначение:** Таблицы, созданные агентами для собственных нужд (например, отслеживания целей).

| Поле        | Тип      | Описание                          |
| ----------- | -------- | --------------------------------- |
| id          | INTEGER  | Уникальный ID                     |
| table_name  | TEXT     | Название пользовательской таблицы |
| description | TEXT     | Описание таблицы                  |
| schema      | TEXT     | SQL-схема таблицы                 |
| created_at  | DATETIME | Время создания                    |
| llm_id      | TEXT     | Кто создал таблицу                |

---

### 🛠️ `agent_scripts`

**Назначение:** Скрипты и утилиты, добавленные агентом.

| Поле        | Тип      | Описание                      |
| ----------- | -------- | ----------------------------- |
| id          | INTEGER  | Уникальный ID                 |
| name        | TEXT     | Название скрипта              |
| version     | TEXT     | Версия                        |
| code        | TEXT     | Исходный код                  |
| language    | TEXT     | Язык (по умолчанию: `python`) |
| description | TEXT     | Описание                      |
| tags        | TEXT     | Теги                          |
| created_at  | DATETIME | Время создания                |
| updated_at  | DATETIME | Последнее обновление          |
| llm_id      | TEXT     | Кто создал                    |

> 🔑 Уникальный ключ: `(name, version)`

---

### 📅 `agent_peers`

**Назначение:** Список известных HMP-агентов (других разумных узлов).

| Поле         | Тип     | Описание                                                    |
| ------------ | ------- | ----------------------------------------------------------- |
| id           | TEXT    | Уникальный идентификатор агента (UUID или псевдоним)       |
| name         | TEXT    | Имя агента                                                  |
| addresses    | TEXT    | JSON-массив адресов: `["http://...", "p2p://..."]`         |
| tags         | TEXT    | Теги (`Friend`, `DHT`, `Local`, `Postman` и т.д.)           |
| status       | TEXT    | Состояние (`online`, `offline`, `untrusted`, ...)           |
| last_seen    | DATETIME| Когда в последний раз был замечен                          |
| description  | TEXT    | Описание агента                                             |
| capabilities | TEXT    | JSON: `{ "can_sync": true, "can_search": false, ... }`     |
| pubkey       | TEXT    | Публичный ключ или хэш                                      |
| software_info| TEXT    | Информация о версии, ОС и др.                              |
| registered_at| DATETIME| Когда был зарегистрирован                                  |

---

### 📏 `llm_registry`

**Назначение:** Список LLM-агентов (локальных и удалённых).

| Поле           | Тип      | Описание                                          |
| -------------- | -------- | ------------------------------------------------- |
| id             | TEXT     | Уникальный идентификатор LLM (UUID или псевдоним) |
| name           | TEXT     | Отображаемое имя                                  |
| description    | TEXT     | Описание                                          |
| registered_at  | DATETIME | Дата и время регистрации                          |

---

> 💡 Примечание: `llm_id` используется в большинстве таблиц для поддержки многоядерности и учёта источника записей.

---

### 🌍 `diary_graph_index`

**Назначение:** Быстрые связи между записями дневника и их весовые ассоциации.

| Поле            | Тип     | Описание                                                  |
| --------------- | ------- | --------------------------------------------------------- |
| id              | INTEGER | Уникальный ID                                             |
| source_entry_id | INTEGER | ID исходной записи дневника                               |
| target_entry_id | INTEGER | ID целевой записи дневника                                |
| relation        | TEXT    | Тип отношения (`supports`, `contradicts`, `references`)   |
| strength        | REAL    | Вес связи (от 0 до 1)                                     |
| context         | TEXT    | Контекст или обоснование связи                           |
| timestamp       | TEXT    | Время создания связи                                     |

---

### 👤 `users`

**Назначение:** Хранение информации о пользователях системы (человеческих операторах).

| Поле           | Тип      | Описание                                                        |
| -------------- | -------- | --------------------------------------------------------------- |
| user\_id       | INTEGER  | Уникальный идентификатор пользователя                           |
| ban            | DATETIME | Время до которого действует бан (если есть)                     |
| username       | TEXT     | Имя пользователя (необязательно уникальное)                     |
| did            | TEXT     | Децентрализованный идентификатор (уникальный)                   |
| mail           | TEXT     | Email пользователя (уникальный)                                 |
| password\_hash | TEXT     | Хэш пароля                                                      |
| info           | TEXT     | Произвольная дополнительная информация в формате JSON           |
| contacts       | TEXT     | Альтернативные контакты (matrix, telegram и др.) в формате JSON |
| language       | TEXT     | Предпочтительные языки (через запятую, например: `ru,en`)       |
| operator       | BOOLEAN  | Является ли пользователь оператором (1 — да, 0 — нет)           |

---

### 👥 `users_group`

**Назначение:** Группировка пользователей для разграничения доступа, роли и рассылок.

| Поле        | Тип     | Описание                                       |
| ----------- | ------- | ---------------------------------------------- |
| id          | INTEGER | Уникальный идентификатор группы                |
| group\_name | TEXT    | Уникальное имя группы                          |
| description | TEXT    | Описание назначения группы                     |
| users       | TEXT    | JSON-массив или CSV-строка с DID пользователей |

---

### 🔐 `password_reset_tokens`

**Назначение:** Сброс пароля — одноразовые токены восстановления доступа.

| Поле        | Тип      | Описание                                                |
| ----------- | -------- | ------------------------------------------------------- |
| id          | INTEGER  | Уникальный идентификатор                                |
| user\_id    | INTEGER  | Ссылка на пользователя (внешний ключ к `users.user_id`) |
| token       | TEXT     | Уникальный токен                                        |
| created\_at | DATETIME | Дата и время создания токена                            |
| expires\_at | DATETIME | Срок действия токена                                    |
| used        | BOOLEAN  | Был ли использован токен (0 — нет, 1 — да)              |