obsidian-vault/personal/tech/hermes-memory-architecture.md

# Hermes Memory Architecture

## Обзор

Hermes (Whale) использует **thread-scoped memory** + кастомную memory instruction. Глобальный профиль (`USER.md`) и thread-локальная память (`MEMORY.md`) — два независимых хранилища.

## Состав системного промпта

Собирается в `agent/system_prompt.py` из трёх слоёв: stable (кешируется на сессию), context (зависит от CWD), volatile (каждый раз свежий).

### Stable tier
1. **SOUL.md** — не существует (Whale), используется `DEFAULT_AGENT_IDENTITY`.
2. **HERMES_AGENT_HELP_GUIDANCE** — ссылка на `https://hermes-agent.nousresearch.com/docs`.
3. **TASK_COMPLETION_GUIDANCE** — «Finishing the job»: не фабриковать, не останавливаться на стабах.
4. **Tool-aware guidance**:
   - `MEMORY_GUIDANCE` — declarative facts, не imperative, не task progress.
   - `SESSION_SEARCH_GUIDANCE` — искать в прошлом session_search.
   - `SKILLS_GUIDANCE` — сохранять сложные подходы как skills, патчить устаревшие.
5. **Tool-use enforcement** — `TOOL_USE_ENFORCEMENT_GUIDANCE` + per-model operational guidance (deepseek → `OPENAI_MODEL_EXECUTION_GUIDANCE`).
6. **Skills prompt** — список доступных скиллов из `~/.hermes/skills/`.
7. **Environment hints** — macOS, home, cwd.
8. **Active profile hint** — «default», +предупреждение не лезть в чужие профили.
9. **Platform hints** — зависит от платформы (zulip/telegram/webhook/webui...).

### Context tier
10. **system_message** — от платформы (например, содержимое входящего сообщения).
11. **Context files** — `AGENTS.md`, `.cursorrules`, `.hermes.md` из `TERMINAL_CWD`.

### Volatile tier (не кешируется)
12. **Memory** — thread-scoped MEMORY.md.
13. **USER.md** — глобальный профиль.
14. **Custom memory instruction** — `~/.hermes/hermes-whale/review/memory_prompt.md`.
15. **Таймстемп** — дата старта, session ID, model, provider.

### Файлы конфигурации и кастомные промпты
- `~/.hermes/hermes-whale/review/skill_prompt.md` — инжектится в background review (skill review).
- `~/.hermes/hermes-whale/review/memory_prompt.md` — memory instruction.
- `prefill_messages_file` — не задан.
- `personalities` — пусто.
- `hooks` — пусто.


## Конфигурация

Файл: `~/.hermes/hermes-whale/config.yaml`

```yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 3000
  user_char_limit: 1375
  provider: ''
  nudge_interval: 10
  flush_min_turns: 6
  thread_scoped: true                          # изолированная память по треду
  prompt_path: ~/.hermes/hermes-whale/review/memory_prompt.md  # кастомная инструкция
```

## Файловая структура

```
~/.hermes/hermes-whale/memories/
├── MEMORY.md                          # глобальная (fallback для CLI/старых сессий)
├── USER.md                            # глобальная (всегда)
└── threads/
    ├── agent:main:webhook:webhook:webhook:whale/
    │   └── MEMORY.md                  # память конкретного треда
    └── ...
```

## Memory prompt

Файл: `~/.hermes/hermes-whale/review/memory_prompt.md`

### Что запоминать
1. Документы — file paths, что изменено, почему.
2. **После загрузки Obsidian docs** — извлекать ключевые факты в memory.
3. Команды и инструменты — нетривиальные CLI вызовы, форматы конфигов.
4. Статус проекта — completed, pending, blockers, next steps.
5. Предпочтения пользователя — коррекции, фидбек.
6. Факты окружения — пакеты, порты, пути до credentials (не сами secrets).
7. Решения и обоснование выбора подхода.
8. Конфиг изменения — ключи/значения/пути.

### Что НЕ запоминать
- Временный debugging noise.
- "Сейчас в процессе задачи X" — session_search покрывает.
- Очевидные факты (rediscover за 2 сек).
- Negative claims о сломанных инструментах — становятся persistent self-imposed constraints.

### Особенности редактирования
- `patch()` для точных замен, но не перенумеровывает списки.
- После вставки пункта mid-list — проверить нумерацию, делать второй clean patch.

## Команды

```bash
# Проверить текущую память
cat ~/.hermes/hermes-whale/memories/USER.md
cat ~/.hermes/hermes-whale/memories/MEMORY.md

# Структура файлов памяти
find ~/.hermes/hermes-whale/memories -type f -name "*.md"

# Редактировать prompt (через patch или write_file)
```

## 🔴 Лимиты и падение агента (наблюдение 2026-09-29)

**Симптом:** агент не отвечает в треде, в `errors.log` — серия:
```
Tool memory returned error: Memory at 2,899/3,000 chars.
  Adding this entry (781 chars) would exceed the limit. Replace or remove existing entries first.
[Tool loop warning: same_tool_failure_warning; count=3; memory]
```
Итог: агент зацикливается на попытках записать факт и **не доходит до ответа**.

### Ключевой факт: USER.md — всегда глобальный

`_path_for("user")` → `memories/USER.md` **всегда**, независимо от `thread_key`.
В `threads/` уходит только `MEMORY.md`. Следствие: **забитый USER.md бьёт по всем
тредам одновременно** — `thread_scoped: true` от него не защищает.

| Файл | Лимит (конфиг) | Значение 2026-09-29 |
|---|---|---|
| `memories/USER.md` | `user_char_limit: 1375` | 2295 байт → **уже переполнен** |
| `memories/threads/<key>/MEMORY.md` | `memory_char_limit: 3000` | по треду |
| `memories/MEMORY.md` (fallback) | `memory_char_limit: 3000` | 0 байт |

⚠️ Расхождение лимитов: `user_char_limit: 1375` против `memory_char_limit: 3000`.
Сообщение об ошибке упоминает 3000 — **это лимит MEMORY.md, не USER.md**; при
диагностике смотреть оба значения в `config.yaml`.

### Диагностика

```bash
# размеры
wc -c ~/.hermes/hermes-whale/memories/USER.md ~/.hermes/hermes-whale/memories/MEMORY.md
# где именно падает
grep -n "memory returned error" ~/.hermes/hermes-whale/logs/errors.log | tail -10
```

**Лечение:** сжать USER.md (слить дубли, убрать устаревшее) до <1375, либо поднять
`user_char_limit` в `config.yaml`. Правка `config.yaml` — только скриптом с
YAML-roundtrip-валидацией (прямой `patch`/`write_file` заблокирован харнессом).

## Связанное

- [[thread-scoped-memory]] — план реализации.
- `personal/plans/thread-scoped-memory.md` — детали тестов, pitfalls, коммиты.