# Репозиторная память + система хабов для Claude Code

> Инструкция по организации памяти AI-агента: быстрый доступ, минимальный расход токенов, единая точка входа, перенаправления и полные ссылки на конечные файлы. Под Claude Code.
> Версия 1.0 · подготовил Константин Любимов (экосистема ВОСХОЖДЕНИЕ) для Дмитрия (Атма Гуру).

---

## 1. Проблема, которую это решает

Без структуры память агента растекается по десяткам файлов в разных местах (память, заметки, переписки, конфиги). При касании темы агент не знает, куда смотреть, — грепает вслепую, жжёт токены и время, выдаёт неточности.

Решение — **репозиторная память**: знания лежат в git-репозитории как обычные `.md`-файлы, у каждой темы один хаб-файл (точка входа), а доступ идёт по маршрутам, а не сплошным чтением. Принципы:

- **Одна точка входа на тему** — хаб. Новый факт по теме вшивается в хаб сразу, не растекается.
- **Перенаправления вместо дублей** — один факт живёт в одном месте, остальные ссылаются.
- **Полные ссылки на конечные файлы** — маршрут ведёт прямо к нужному файлу, без поиска.
- **Прогрессивное раскрытие** — агент читает только нужный файл под задачу, не всю базу.

---

## 2. Структура на диске

Claude Code хранит память по пути проекта:

```
~/.claude/projects/<хеш-пути-проекта>/memory/
├── MEMORY.md                     # индекс-карта: одна строка на файл (грузится каждую сессию)
├── reference_hubs_index.md       # мастер-индекс хабов — точка входа №1
├── hub_<тема>.md                 # хабы по темам (один на тему)
├── project_<имя>.md              # детальная фактура по проектам
├── reference_<тема>.md           # справочники
└── feedback_<правило>.md         # правила работы, выводы из ошибок
```

Соглашение по именам — префиксы по типу узла:

| Префикс | Что | Пример |
|---------|-----|--------|
| `hub_` | хаб темы (точка входа) | `hub_bots.md` |
| `project_` | конкретный проект, фактура | `project_secretary_bot.md` |
| `reference_` | справочник, не меняется часто | `reference_api_keys.md` |
| `feedback_` | правило/урок «как работать» | `feedback_token_economy.md` |

---

## 3. Три уровня доступа (как не жечь токены)

```
CLAUDE.md (routing)  →  MEMORY.md (индекс)  →  hub_*.md  →  конечный файл
   что за проект         где что лежит          тема          детали
```

1. **`CLAUDE.md` проекта** — таблица маршрутов «задача → куда идти». Грузится всегда, маленький.
2. **`MEMORY.md`** — индекс: одна строка на файл (название + крючок-описание). Никакого контента, только указатели.
3. **Хаб темы** — суть + канон + карта источников. Открывается, когда тема всплыла.
4. **Конечный файл** — детали, читается только когда реально нужно.

Агент не читает всю папку. Он идёт по маршруту: маршрут → индекс → хаб → один файл. Это и есть экономия токенов.

---

## 4. Шаблон хаба (все хабы одинаковы)

Создавай каждый хаб по этой структуре — единообразие важнее красоты:

```markdown
---
name: hub_<тема>
description: "Одна строка: что за тема, когда читать этот хаб. Используется для поиска релевантности."
metadata:
  type: reference
  updated: 2026-06-08
---

# HUB · <Тема>
> Единая точка входа. Новый факт по теме → СРАЗУ сюда. Снято: <дата>.

## 1. СУТЬ (3-5 строк)
Что это, зачем, текущий статус.

## 2. КАНОН (факты, врать нельзя)
Жёсткие факты. Динамику (цены, ID, метрики) помечать маркером LIVE и держать в одном живом файле.

## 3. КАРТА ИСТОЧНИКОВ
| Файл | Что там | Свежесть |
|------|---------|----------|
| [[project_xxx]] | детали X | 2026-06-08 |
| [[reference_yyy]] | справка Y | 2026-06-01 |

## 4. ОТКРЫТЫЕ ХВОСТЫ
- [ ] следующий шаг

## 5. ПРАВИЛО ПОДДЕРЖКИ
Триггеры темы (по каким словам открывать хаб).
Новый факт → сразу сюда. >21 дня без обновления → пометить STALE и проверить.
```

Обязательны: дата снятия, отдельная секция КАНОН (защита от дрейфа фактов), свежесть по каждому источнику.

---

## 5. Мастер-индекс хабов (точка входа №1)

Один файл `reference_hubs_index.md` — реестр всех хабов. При любой теме агент сначала открывает его, находит нужный хаб, идёт в хаб. Не грепает вслепую.

```markdown
# Мастер-индекс хабов — точка входа в знания
> Правило: касание любой темы → сначала этот индекс → найти хаб → открыть хаб.
> Нет хаба, но по теме ≥6 файлов → завести хаб по шаблону, потом отвечать.
> Статусы: ✅ готов · 🔧 апгрейд · ⬜ каркас.

| Тема | Хаб | Что внутри | Статус |
|------|-----|------------|--------|
| Боты | `hub_bots` | реестр ботов, токены, деплой | ✅ |
| Клиенты | `hub_clients` | воронки, договорённости | ✅ |
| Инфра | `hub_infra` | серверы, деплой, доступы | 🔧 |
```

---

## 6. CLAUDE.md проекта — маршрутизатор

В корне проекта `CLAUDE.md` — таблица маршрутов. Это первое, что читает агент. Держи её короткой.

```markdown
# Роутинг (читать в начале сессии)

| Задача | Куда идти |
|--------|-----------|
| Любая содержательная тема | memory/reference_hubs_index.md → нужный хаб |
| Статус проекта / следующий шаг | memory/MEMORY.md |
| Боты, токены, деплой | hub_bots |
| Клиенты, воронки | hub_clients |

# Правила
- Новый факт по теме → СРАЗУ в её хаб, тем же ходом.
- Не грепать вслепую — идти по маршруту индекс → хаб → файл.
- Читать только нужный файл под задачу (прогрессивное раскрытие).
- Нетривиальная задача → план в plans/, фазы [ ]/[x], коммит после фазы.
```

---

## 7. MEMORY.md — индекс, не свалка

`MEMORY.md` грузится в каждую сессию, поэтому в нём только указатели — одна строка на файл:

```markdown
# MEMORY — индекс
> Детали — в topic-файлах. Здесь только указатели.

## Хабы
- [reference_hubs_index](reference_hubs_index.md) — мастер-индекс, точка входа №1.
- [hub_bots](hub_bots.md) — реестр ботов, токены, деплой.

## Правила
- [feedback_token_economy](feedback_token_economy.md) — читать только нужное под задачу.
```

Держи его компактным. Если разрастается — выноси детали в topic-файлы, в индексе оставляй крючок.

---

## 8. Перенаправления и единый источник правды

Главное правило целостности: **один факт = один файл-владелец**, остальные ссылаются.

- Если та же информация нужна в двух местах — не копируй, ставь ссылку на файл-владельца.
- Если по техническим причинам файл нужен в нескольких папках (например, разные проекты Claude Code) — делай **симлинк** на канон, а не дубль. Дубли молча разъезжаются при правке.

```bash
# канон лежит в основной памяти, второй проект видит его через симлинк
ln -s /полный/путь/к/канону/hub_shared.md  ./hub_shared.md
```

- Если файл устарел и переехал — не удаляй молча, оставь **файл-редирект**: «Канон → новый путь».

Проверка целостности ссылок (находит битые `[[ссылки]]`):

```bash
for link in $(grep -rhoE "\[\[[a-z0-9_]+\]\]" *.md | sed -E 's/\[\[|\]\]//g' | sort -u); do
  [ ! -f "$link.md" ] && echo "битая ссылка: [[$link]]"
done
```

---

## 9. Когда заводить новый хаб

Не плодить хабы заранее. Правило: касаешься темы → проверь, есть ли хаб. Нет, но по теме уже **≥6 файлов** в памяти → сначала заведи хаб по шаблону, потом отвечай. Один хаб на постоянную тему, не больше.

---

## 10. Синхронизация между машинами (если их несколько)

Память — это git-репозиторий, поэтому синк простой: `git` либо `rsync`. Если агент работает на нескольких машинах (ноут + сервер), держи один скрипт `sync.sh`:

```bash
# пример: память push на сервер
rsync -az ~/.claude/projects/<проект>/memory/  user@server:~/.claude/projects/<проект>/memory/
```

Правила синка: коммить память в git после значимых правок; не тащить в синк секреты и `.env`; на сервере прогонять замену абсолютных путей на `$HOME`, если пути машинно-зависимые.

---

## 11. Зеркало для человека (опционально)

Память оптимизирована под агента. Если хочешь читать её глазами — заведи параллельную человекочитаемую папку (например, в заметочнике) с теми же темами и INDEX-ом на каждую. Канон остаётся в репо-памяти, зеркало синкается из неё. Не наоборот.

---

## 12. Чек-лист внедрения (≈30 минут)

- [ ] Создать `~/.claude/projects/<проект>/memory/`.
- [ ] Положить `CLAUDE.md` в корень проекта с таблицей маршрутов.
- [ ] Завести `MEMORY.md` — пустой индекс с разделами.
- [ ] Завести `reference_hubs_index.md` — мастер-индекс (пока пустой).
- [ ] Создать первый хаб по шаблону на самую частую тему.
- [ ] Добавить в `MEMORY.md` указатель на хаб, в индекс — строку.
- [ ] Прописать правило: «новый факт → сразу в хаб».
- [ ] Настроить git-коммит памяти и (если нужно) `sync.sh`.

---

## Резюме одной фразой

Память — это git-репозиторий маленьких `.md`-файлов; у каждой темы один хаб-владелец; доступ идёт по маршруту `CLAUDE.md → MEMORY.md → хаб → файл`; дубли заменяются ссылками и симлинками; новый факт всегда вшивается в хаб сразу. Это даёт быстрый доступ и минимальный расход токенов.