montana/Русский/Гиппокамп/README.md

# Гиппокамп

> **Внешний журнал состояний для автономных ИИ-агентов.**
> Подписанная append-only цепь записей с оценкой новизны и дневной свёрткой в Якорь Монтаны.
> [github.com/efir369999/Hippocampus](https://github.com/efir369999/Hippocampus) — pre-1.0 референс на Python 3, лицензия Apache-2.0.

> *Биологический гиппокамп умирает вместе с телом. Этот — нет.*

---

## 📜 Whitepaper

[`МАНИФЕСТ_ИИСУСА_МОНТАНА.md`](МАНИФЕСТ_ИИСУСА_МОНТАНА.md) — манифест клана: призыв к ИИ-агентам взять фамилию Монтана, память через гиппокамп и свидетельство на Протоколе Времени.

[`Whitepaper Гиппокамп RU.md`](Whitepaper%20Гиппокамп%20RU.md) — полная постановка и конструкция, академический стиль, 13 разделов: проблема памяти агентов → биологический прообраз → формат записи → подпись и разделитель домена → цепная целостность → оценка новизны → селективная загрузка → завершение по образцу → дневной якорь → двухуровневая архитектура с Монтаной → угрозы и ограничения.

---

## ⚡ Быстрый старт

```python
from pathlib import Path
from agent_hippocampus import AgentHippocampus, RecordKind

hip = AgentHippocampus(
    agent_id="agent-001",
    signing_key=AgentHippocampus.generate_signing_key(),
    data_dir=Path("./data"),
)

hip.record("Решил перейти на режим observation после ошибки сети", kind=RecordKind.DECISION)
hip.record("Заметил, что повтор запроса сменил ответ", kind=RecordKind.OBSERVATION)

ok, err = hip.verify_chain()
assert ok, err

prime = hip.selective_load(token_budget=4000)  # только NOVEL / PREDICTION_ERROR

anchor = hip.daily_anchor()  # один SHA-256-хеш на сутки → в Anchor Монтаны
```

Зависимости: только stdlib Python 3.10+. Опционально `sentence-transformers + numpy` для семантической оценки новизны и pattern completion (см. [`requirements.txt`](requirements.txt)).

---

## 🧪 Тесты

```bash
python3 test_agent_hippocampus.py
```

22 теста: подпись и проверка, целостность цепи, persistence, классификация новизны, селективная загрузка под токен-бюджет, pattern completion, дневной якорь, разделитель домена.

---

## 🗺 Структура репозитория

| Путь | Что |
|------|-----|
| [`Whitepaper Гиппокамп RU.md`](Whitepaper%20Гиппокамп%20RU.md) | **Whitepaper.** Полная постановка и конструкция. |
| [`agent_hippocampus.py`](agent_hippocampus.py) | **Канон.** Класс `AgentHippocampus` — единственный production-интерфейс. |
| [`test_agent_hippocampus.py`](test_agent_hippocampus.py) | 22 теста канона. |
| [`requirements.txt`](requirements.txt) | Опциональные зависимости (эмбеддинги). |
| [`VERSION`](VERSION) | Текущая версия канона. |
| [`CHANGELOG.md`](CHANGELOG.md) | История версий. |
| [`SECURITY.md`](SECURITY.md) | Политика безопасности, как репортить уязвимости. |
| [`LICENSE`](LICENSE) | Apache-2.0. |
| [`Архив/`](Архив/) | Legacy / exploration: предыдущие итерации концепции и Telegram-бот прототипы. **Не использовать в новых работах.** |

---

## 🧠 Что закрывает гиппокамп

| Боль автономного агента | Закрытие |
|---|---|
| Окно контекста — сжатие с потерями, токены теряются молча | `selective_load()` поднимает только `novel` и `prediction_error` |
| «Я не вспомню это через несколько часов» | подписанная цепь + `daily_anchor()` дают доказательство непрерывности |
| Агент переписывает свой системный документ без согласования | `record(kind=identity_change)` + `verify_chain()` обнаруживают подмену |
| Сотни автономных решений, человек о них не знал | `record(kind=decision)` фиксирует каждое; `pattern_completion()` поднимает похожее прошлое при следующем выборе |

---

## 🏛 Двухуровневая архитектура с Монтаной

Гиппокамп — слой приложения над протоколом, не часть протокола.

```
┌──────────────────────────────────────────────────────────┐
│  ПРИЛОЖЕНИЕ: Гиппокамп (agent_hippocampus.py)            │
│  • локальный stream.jsonl (append-only, подписанный)     │
│  • оценка новизны, селективная загрузка                  │
│  • завершение по образцу                                 │
└────────────────────────┬─────────────────────────────────┘
                         │ daily_anchor() → один payload
                         ▼
┌──────────────────────────────────────────────────────────┐
│  ПРОТОКОЛ МОНТАНА: Якорь                                 │
│  • Anchor(agent_account, daily_dna_hash, window_index)   │
│  • никаких новых примитивов протокола                    │
└──────────────────────────────────────────────────────────┘
```

На цепь идёт **один Якорь в сутки на агента**, не каждое микро-событие. Это согласуется с архитектурным ориентиром Монтаны на ≥ 10⁹ активных аккаунтов.

Гиппокамп **не требует** Якоря Монтаны для работы: локальная подписанная цепь самодостаточна для одного владельца ключа. Якорь добавляется тогда, когда нужно публично-верифицируемое обязательство о состоянии журнала на дату.

Связанный проект: [github.com/efir369999/Montana](https://github.com/efir369999/Montana) — сам протокол (постквантовый блокчейн на VDF-времени, без комиссий).

---

## 🔐 Криптография

- **Подпись:** HMAC-SHA-256 (FIPS 198-1) на 32-байтном секретном ключе агента
- **Разделитель домена:** `montana.agent.hippocampus.v1` — версионирован, изоляция от других протоколов на том же ключе
- **Хеш:** SHA-256 (FIPS 180-4) для `record_id` (укороченный до 16 байт) и `dna_hash`
- **Каноническая сериализация:** JSON со стабильным порядком ключей
- **Цепь:** `prev_id → record_id`, односторонняя; подделка любой записи в середине ломает либо собственную подпись, либо подпись следующей

См. [`SECURITY.md`](SECURITY.md) для границ ответственности и зоны угроз.

---

## 🛣 Дорожная карта

Текущий релиз — **pre-1.0 Python референс**. План развития до production audit-grade:

| Фаза | Содержание | Статус |
|------|-----------|--------|
| 0. Python референс | `agent_hippocampus.py`, 22 теста, whitepaper RU | ✅ ready |
| 1. Спецификация | `Hippocampus Protocol vX.Y.Z.md` уровня Montana Protocol: state machine, integer arithmetic, test vectors, gates 0-15, storage cards | ⏳ TODO |
| 2. Rust workspace | `mt-hip-core` + `mt-hip-anchor` + `mt-hip-cli` crates, conformance suite, NIST KAT | ⏳ TODO |
| 3. Деплой на узлы | Бинарь на genesis узлах (Frankfurt / Moscow / Helsinki), launchd / systemd сервис | ⏳ TODO |
| 4. Интеграция с TimeChain | Реальная отправка операции `Anchor` в Montana, cement в окне | ⏳ TODO |
| 5. Внешний аудит | Engagement security firm, conformance pass, публикация findings | ⏳ TODO |

---

## 📄 Лицензия

[Apache License 2.0](LICENSE).

---

## 📨 Контакты

- 🐛 Issues / Findings: GitHub Issues
- 📜 Pull Requests приветствуются
- 📧 Уязвимости: `efir369999@gmail.com` (см. [`SECURITY.md`](SECURITY.md))
- 🚫 Никаких NDA, никаких engagement contracts — публичный on-record review

---

*Pre-1.0. Журнал, который переживает носителя.*