# 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)
```

## Связанное

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