Документация

Устройство Agent Hub

Agent Hub — локальный источник основных MCP-настроек, навыков и общего контекста для Claude Code, Codex CLI и DeepSeek Harness. Нужен Node.js ≥22.13. Целевые платформы — macOS/Linux; Windows экспериментальна. Кандидат 0.1.0-beta.1 распространяется как проверенные архивы исходников и пакета; публикация в реестре npm отключена.

Принципы

Канонические описания находятся в Hub, файлы клиентов — явные проекции.
Сначала план, потом применение. Посторонние записи и личный текст сохраняются.
До записи сохраняются оригиналы и закрытые копии. Устаревшие входы, неизвестное владение и изменённые привязки блокируют действие.
Секреты локальны и не копируются в созданные MCP-конфигурации. Закрытый контекст не попадает в JSON плана.
Различия клиентов изолированы в адаптерах, планирование и применение общие для CLI/UI.
Контекст проекта живёт в репозитории, отдельно от глобальных настроек и истории диалогов.

Структура Hub

hub/
  hub.yaml
  skills/<name>/SKILL.md
  mcp/servers.yaml
  instructions/AGENTS.md
  memory/MEMORY.md
  memory/shared/records/<id>.md
  memory/projects/<project-id>/records/<id>.md
  memory/projects/<project-id>/MEMORY.md
  memory/projects.json
  templates/repo/
  .env
  backups/
  state/
hub.recovery/
  baseline/
  artifacts/
  archives/

AGENT_HUB_HOME выбирает Hub. Переопределения путей описаны в README. Абсолютные локальные привязки в созданных файлах и восстановлении намеренны: recovery не является переносимым облачным backup-форматом.

Доставка

Область	Источник	Проекция
MCP	Реестр и ссылки на .env	Нативная конфигурация с общим запускателем
Навыки	Полные папки Hub	Отдельные ссылки, включая проверенные локальные копии
Инструкции	instructions/AGENTS.md	Свой блок: импорт Claude, текст Codex/DSH
Общая память	memory/MEMORY.md и факты	Индекс и путь папки в блоке инструкций
Передача проекта	Шаблоны Hub или встроенные	AGENTS.md, PROJECT.md, NOW.md и импорт Claude в Git-репозитории

Подходящие проекту нативные Markdown-заметки импортируются с сохранением оригиналов. Архивные разговоры и SQLite не поддерживаются. Общие факты читаются по необходимости. Профиль DSH может выключить плагины инструкций и навыков; доставка этого не меняет.

Сценарий quick

quick управляет только общим Hub: недостающие файлы, сбор MCP и навыков, затем глобальная доставка выбранным клиентам. План не зависит от cwd и Git-проекта. Необязательный project connect [directory] требует готовый Hub и проверенный Git-checkout; отдельно планирует память, контекст, подходящие источники и hooks проекта. Общие инструменты и инструкции он не собирает и не доставляет.

Оба сценария переиспользуют существующие сервисы. Preview фиксирует область и входы; применение проверяет ревизию и перестраивает зависимые планы. Независимые этапы могут завершиться при конфликте другого. Единой транзакции и unattended-сервиса MCP/навыков нет. Применение удерживает повторно используемую этапами блокировку и сохраняет отдельный undo-снимок вне Hub. Поздние правки блокируют undo. Disconnect сохраняет привязки и знания за явным запретом доступа. См. быстрый старт.

Сервисы и восстановление

MCP использует свой планировщик, сохраняющий формат writer, хеши владения и sync-копии. Контент — артефакты файловой системы: файлы, полные каталоги, конечные ссылки и отсутствие. План содержит отпечатки источников и целей, публичная проекция не содержит файлы.

Все записи разделяют блокировку Hub. Перед записью данные проверяются; поздний сбой запускает компенсирующий откат завершённых изменений. Временные данные рядом с целью сохраняют права и бинарные материалы. У замены каталога есть короткий промежуток rename. Внешние клиенты блокировку не соблюдают. Общей транзакции диска и гарантии при потере питания нет.

Неизменяемый baseline и дополняемые первые оригиналы находятся вне активного Hub. Reset возвращает их и архивирует текущее. Существующая установка получает снимок доступного состояния, неизвестная история не восстанавливается. См. восстановление и контент.

Текущий этап

Реализованы quick через CLI/UI, init, MCP import/launcher/sync/doctor, restore/reset, локальный UI, операции навыков, доставка правил и индекса, шаблоны репозитория и scoped-память CLI/UI/MCP. Явные записи требуют preview и точной ревизии. После проверенного включения автоматизация использует политику, общий сервис записи и recovery без отдельного плана каждого факта. Обычный sync — только MCP; --area skills и --area context выбирают остальные проекции.

До публикации нужно пройти настоящее рабочее испытание: извлечение моделью и передача памяти между клиентами, визуальную проверку и удалённый CI macOS/Linux. Пакет и настоящий установщик проверяются в изолированных профилях; RELEASE.md описывает артефакты кандидата и оставшиеся условия. Обмен с графовой памятью остаётся будущей работой. Лендинг и документация поддерживают английский/русский через языковые файлы; доменом, хостингом и деплоем управляет сопровождающий.

Минимальная версия памяти

CLI/UI/MCP используют один реализованный сервис записей. Точные команды и лимиты — в памяти. Описанный ниже обмен графами запланирован, не реализован.

Начальное архитектурное решение

Для первой версии единственный оригинал — управляемый Hub Markdown. Небольшой встроенный MCP предоставляет тот же сервис CLI/UI. Повторно используются managed-plan, блокировка и восстановление артефактов; гарантии проверяются на совместной записи факта и индекса. Пока backend один, общий framework хранилищ не нужен.

Внешний @modelcontextprotocol/server-memory — будущий необязательный импорт/экспорт, не runtime-зависимость и не второй оригинал. Импорт должен сохранять атрибуцию и источник, распознавать повторы по стабильной идентичности и требовать решения при изменении. Сущности и связи сохраняются либо неподдерживаемые данные явно отклоняются: тихое уплощение недопустимо. Экспорт — отдельный снимок без перезаписи графа другого процесса. Ручной импорт сохраняет выбранный UTF-8 текст одной записью, onboarding — нативный Markdown; структурированный граф они не импортируют.

Не следует автоматически синхронизировать два записываемых оригинала. Графовый backend можно рассмотреть, если реальный сценарий потребует обхода графа: он заменит основное хранилище коллекции, а не станет зеркалом. Совместимость встроенного API с внешними графовыми инструментами не заявлена.

Назначение и границы

Память сохраняет полезные знания между сессиями и клиентами. Одна запись — независимо поддерживаемый факт, предпочтение, решение или урок. Инструкции остаются инструкциями, процедуры — навыками, PROJECT.md — контекстом репозитория, NOW.md — текущей работой. Transcript — источник для проверки, а не запись по умолчанию. Вместо дублирования документации предпочтительны ссылки.

Начальные области:

Общая: знания, осознанно доступные проектам выбранного Hub. Добавление и перенос сюда явные.
Проектная: знания одного зарегистрированного проекта. Допустимы его записи и явно разрешённая общая область. Остальные проекты не попадают в обычное чтение, поиск и стартовые индексы.

Оригиналы по умолчанию локальны в Hub: публичный репозиторий не публикует личные заметки автоматически. Экспорт выбранных знаний в репозиторий — отдельное действие. Выбранный Hub задаёт начальную границу; метка scope сама не реализует рабочие и личные профили или ACL.

Хранение и идентичность

UTF-8 Markdown с проверяемым YAML, одна запись в файле. Метаданные включают стабильный ID, заголовок, область и проект, даты, теги и источник. Тело хранит знание и нужный контекст. Ревизия вычисляется по байтам, поэтому редактор делает старый план недействительным.

Рукописные документы остаются читаемыми. Принятие в структурированные записи требует preview; MEMORY.md не переписывается незаметно, каждый Markdown не объявляется управляемым автоматически. Производный индекс имеет явное владение и сохраняет личный текст.

Реестр назначает локальный стабильный ID с явными checkout. Имя папки и remote URL недостаточны. Worktree могут разделять зарегистрированный проект, другой clone не подключается автоматически, перемещённый или неизвестный checkout требует привязки. Чужие имена и snippets не выдаются за пределами разрешённой области.

Markdown — источник истины, MEMORY.md — компактный производный индекс. Поиск текстовый по области и метаданным. Embeddings, графы и постоянный индекс возможны при измеренной необходимости; производный индекс всегда должен пересобираться из записей.

Один сервис, три интерфейса

CLI, UI и необязательный stdio MCP вызывают один сервис валидации, областей, поиска, планирования, ревизий и восстановления. Адаптер MCP не вводит другой формат и не обходит блокировку.

Сначала реализованы список, получение и поиск, затем создание, обновление, удаление и импорт. Записи используют preview/apply, проверенные ревизии и оригиналы, включая индекс. Конкурентные писатели перечитывают под блокировкой; старый план отклоняется. Повреждённые метаданные и неясный импорт показываются с источником, без скрытого исправления. Нужны проверки редактора и нескольких процессов CLI/MCP.

MCP стартует с явным workspace и разрешёнными областями. Переданные клиентом пути и ID их не расширяют. Чтение доступно сразу, проверенные write-tools включаются отдельно. Автоматические checkpoints требуют --allow-auto, политики и активного одноразового токена. Это граница сервиса Hub, а не sandbox агента с собственным доступом к диску.

Стартовый контекст — небольшой индекс и подсказка использования, не все факты всех проектов. Данные читаются по необходимости через файлы или MCP. Подключённый MCP сам не заставляет агента помнить: инструкции объясняют поиск и сохранение, настоящее поведение нужно проверять.

Порядок реализации и приёмки

Валидация записей, привязки проектов, scoped-чтение и поиск, CLI.
Проверенные записи и импорт, индекс, конфликты ревизий и восстановление.
Тот же сервис через MCP и UI с настоящими протокольными вызовами; это покрыто независимыми stdio-клиентами.
Рабочее испытание модели: сохранить факт, прочитать из другого клиента, безопасно изменить, отвергнуть старую запись и исключить чужой проект. Fixtures протокола не доказывают соблюдение процесса моделью.

Нативная автопамять сохраняется. Автоматизация копирует выбранный Markdown и запрашивает подтверждённые checkpoints активного контекста. Привязки обнаруживают дубликаты и правки, конфликты сохраняются закрыто. Watcher может работать между сессиями. Хранилище не переносится, знания не становятся общими, архивные разговоры не импортируются массово. Hooks сохраняют чужие настройки и используют проверяемую установку и копии; доверие и разрешения остаются клиентскими.

Архитектурные ориентиры: MCP memory server описывает сущности, связи и наблюдения; спецификация MCP tools — интерфейс адаптера. Это не зависимости и не заявление реализованной совместимости.

Дальнейшие этапы

Добавление и удаление MCP в реестре; пока явные заглушки.
Профили и теги рабочих и личных областей.
Системные хранилища секретов вместо .env.
Индекс и поиск сессий, передача контекста с помощью истории.
Службы ОС и массовый разбор архивов.
Другие адаптеры клиентов и самостоятельная раздача публичных навыков и шаблонов.

Подготовка репозитория создаёт обычные файлы. Она не запускает агентов, не обновляет NOW.md постоянно и не гарантирует следование модели инструкциям. Windows, большие деревья, сетевые файловые системы, ACL/xattrs и потеря машины требуют отдельной проверки.