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

Общая и проектная память

Agent Hub хранит устойчивые знания в локальном Markdown и предоставляет один сервис через CLI, локальный UI и необязательный MCP stdio. Записи — справочные данные, не исполняемые инструкции. Автоматизация импортирует выбранные заметки и запрашивает смысловые checkpoints активного агента. Проверьте реальное чтение и запись в клиентах: само подключение MCP не гарантирует поведение модели.

Области и хранение

Общая память предназначена для осознанно переиспользуемых знаний. Проектная принадлежит явно зарегистрированному checkout. CLI выбирает одну область: текущий проект, другой зарегистрированный checkout через --workspace <directory> либо явно --shared. Запросы MCP и UI не задают произвольные ID проектов и пути.

hub/memory/
  MEMORY.md                     # shared index, personal text preserved
  projects.json                 # private, local checkout bindings
  shared/
    index.json                  # index block ownership
    records/<id>.md
  projects/<project-id>/
    MEMORY.md                   # project index
    index.json
    records/<id>.md

Все записи остаются в Hub; регистрация ничего не пишет в репозиторий проекта. Для команды отдельно решите, какие файлы публиковать. Разные Hub могут разделять рабочие и личные данные. Области ограничивают доступ через Hub, но не изолируют агента с независимым доступом к диску.

YAML-метаданные записи включают версию, стабильный ID, заголовок, область, вид (fact, preference, decision, lesson), теги, необязательный источник и UTC-время создания и изменения. Тело — Markdown. Ревизия хеширует реальные байты, включая правки редактора. Управляемые пути отвергают ссылки ниже выбранного Hub. Лимит записи с метаданными — 128 KiB, коллекции — 2000 записей. Поиск сопоставляет все слова запроса с ID, заголовком, видом, тегами и телом, без embeddings и внешних сервисов.

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

Работа через CLI

Используйте установленный ahub либо вызовы из исходников. Сначала инициализируйте Hub.

ahub memory project register example-project /path/to/project --dry-run

Примените точную команду из preview. Регистрация связывает канонический Git-checkout и идентичность его локальной Git-папки со стабильным ID. Повтор той же привязки ничего не меняет. Другой явно зарегистрированный checkout того же ID разделяет факты; папка с совпадающим именем не присоединяется автоматически. Замена репозитория по старому пути блокирует доступ. Проверяйте project register <same-id> <directory> --rebind только если новый репозиторий должен унаследовать знания. Привязка к другому проекту конфликтует и с --rebind. Перед переназначением восстановите копию привязки; перемещённые checkout требуют явной регистрации. Идентичность файловой системы защищает от случайного переиспользования, но не является криптографической или переносимой между машинами.

ahub memory add retry-rule --workspace /path/to/project \
  --title 'Use idempotency keys for API retries' --kind lesson \
  --file /path/to/selected-note.md --source 'Issue or document reference' --dry-run
ahub memory ls --workspace /path/to/project --json
ahub memory search 'API retries' --workspace /path/to/project --json
ahub memory get retry-rule --workspace /path/to/project --json

Создание требует заголовка и тела из локального UTF-8 файла. Теги повторяются через --tag. Для общих знаний замените --workspace ... на --shared. Источник — строка атрибуции: URL не загружается и скрипт не исполняется.

ahub memory update retry-rule --workspace /path/to/project \
  --file /path/to/revised-note.md --record-revision <revision-from-get> --dry-run
ahub memory rm retry-rule --workspace /path/to/project \
  --record-revision <revision-from-get> --dry-run

Обновление сохраняет неуказанные метаданные. --clear-tags и --clear-source очищают значения. Изменение и удаление требуют текущей ревизии записи; применение — точной ревизии плана. Созданная команда содержит фиксированное время --at, чтобы повтор не создавал другой план. Сохраняйте его; после изменения входа нужен новый preview. Источники перечитываются и при планировании, и при применении.

memory import <id> --title ... --file ... копирует явно выбранные знания в тело одной новой записи, по умолчанию указывает путь источника и сохраняет оригинал. Совпадающие ID конфликтуют: повторный импорт не дублирует и не заменяет запись незаметно. Для автоматического Markdown и текущего диалога есть автоматизация. Разделяйте независимые факты намеренно. Обмен графовым JSONL, перенос нативного хранилища и массовый разбор архивных диалогов не реализованы.

Найдите и импортируйте существующую память клиентов

После регистрации checkout проверьте источники перед новым диалогом:

ahub memory discover --workspace /path/to/project
ahub memory onboard --workspace /path/to/project --follow --dry-run

Поиск не импортирует записи и не меняет клиентов. Он показывает стабильные ID, формат, физический путь, сведения о checkout и известный ID Hub. Проверяются источники политики, локальные папки проекта и клиентов, коллекции Claude и пользовательский autoMemoryDirectory. Проект Claude определяется по ограниченным cwd-метаданным сессий, а не неточному декодированию имени папки. Текст диалога не выдаётся и не архивируется. Неясные, отсутствующие и превышающие бюджет сведения остаются неразрешёнными. Checkout одного явно зарегистрированного проекта могут разделять источники.

По умолчанию onboarding выбирает поддерживаемые источники этого проекта. Для неясного источника используйте ID поиска:

ahub memory onboard --workspace /path/to/project \
  --source source-<id> --follow --dry-run

Повторяйте --source для нескольких коллекций, максимум 20 в плане. Явно выбранный неясный источник назначается показанному проекту при проверке; известные чужие источники отклоняются. Не назначайте общую многопроектную коллекцию целиком одному проекту. SQLite и другие неподдерживаемые форматы явно отвергаются, а не упрощаются незаметно: сначала экспортируйте выбранные знания в Markdown. Внешние графы и архивные диалоги остаются отдельной работой.

Примените точную команду с --expect и --at. Факты, привязки, индекс и необязательная политика записываются одной восстанавливаемой операцией. Правка источника делает план устаревшим; неизменённый повтор не дублирует записи. Нативные оригиналы не переписываются.

Без --follow импорт одноразовый. С --follow источники и клиенты добавляются во включённую политику будущего сканирования. Hooks это не устанавливает: существующий обработчик может активироваться; иначе используйте проверенный memory auto enable или watcher. Смысловым checkpoints всё ещё нужны события клиента и разрешения. Выключение политики сохраняет знания.

MEMORY.md тоже проверяется. Факты и fenced-примеры сохраняются. Пропускаются только чистые навигационные ссылки на существующие видимые локальные Markdown-файлы внутри области; сами файлы читаются отдельно. Внешние, отсутствующие и скрытые ссылки, а также строки со ссылкой и текстом сохраняются. Пропуски навигации — сведения, а не повторяющиеся предупреждения синхронизации.

В UI доступны Memory → Manage records → Find existing client memory, выбор источников, необязательное отслеживание и тот же защищённый preview/apply. До применения импорта проект должен быть зарегистрирован.

Работа через MCP

ahub memory serve --workspace /path/to/project

Workspace уже должен быть зарегистрирован. Настройте команду как stdio MCP выбранного клиента с тем же AGENT_HUB_HOME, что CLI. Используйте подходящие абсолютные пути исполняемых файлов и проекта. Не выбирайте проект через случайную рабочую папку процесса MCP.

По умолчанию доступны memory_list, memory_search и memory_get привязанного проекта. --include-shared разрешает явно scoped-чтение scope: "shared". --allow-write открывает memory_preview и memory_apply для проектной памяти. Общая запись дополнительно требует --include-shared --allow-shared-write. --allow-auto отдельно открывает memory_checkpoint по включённой политике и активному одноразовому токену. Ни один serve-флаг не устанавливает сервер клиентам и не меняет нативную автопамять.

План записи принимает operation, id, необязательную scope, метаданные и тело, а для изменения и удаления — recordRevision. Применение требует непрозрачный ID и ревизию. Планы принадлежат процессу сервера, действуют пять минут и одноразовые; перезапуск их теряет. Проверьте знание и область. Разрешения инструментов и запросы подтверждения принадлежат MCP-клиенту; само разделение preview/apply не доказывает согласия человека.

Процессы используют общую блокировку Hub и перечитывают данные под ней. Правка коллекции или индекса другим писателем делает план устаревшим: получите актуальные данные. Так предотвращается тихая перезапись последним писателем.

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

Локальный UI и доставка индекса

Откройте Memory → Manage records, выберите проект или общие знания, найдите запись или создайте новую, проверьте сохранение либо удаление и примените с копией. Правки формы сбрасывают preview. Проект выбирается среди проверенных зарегистрированных привязок либо через стартовую папку; неподключённая область сообщает о необходимости привязки. Для неё по умолчанию доступны общие знания. Старые Markdown-документы верхнего уровня читаются отдельно.

Изменение обновляет свой блок индекса и владение вместе с фактом. Личный текст сохраняется; изменённые, удалённые, повторные и чужие блоки блокируют запись. Индекс показывает до 60 записей с общим бюджетом 24 KiB; для остальных используйте поиск по области. Правки редактора сразу видны при чтении; производные заголовки обновятся следующей проверенной операцией. Не редактируйте созданные блоки вручную.

sync --area context доставляет только общий индекс, не все проектные индексы в глобальные инструкции. Claude импортирует источник; Codex/DSH получают текст и требуют повторного context sync для его обновления. Проектные записи читаются через привязанный MCP, CLI или локальный индекс. MCP видит актуальные файлы без перезапуска клиента.

Восстановление и оставшиеся ограничения

Запись начинается с preview и использует общую управляемую операцию, ревизии, закрытые копии и первые оригиналы. restore <content-backup-id> --dry-run показывает совместный откат записей, индекса и владения. Внешние правки блокируют restore. Reset возвращает сохранённый baseline и архивирует нынешние данные, включая память; это не команда выборочного удаления знаний. См. восстановление.

Копии и привязки локальны и не зашифрованы. Последовательность замен восстанавливается компенсирующим откатом, но не является общей транзакцией диска или гарантией при потере питания. Внешний редактор не соблюдает блокировку. Отдельный @modelcontextprotocol/server-memory использует графовую модель: не направляйте его на Markdown и не создавайте два независимо записываемых оригинала коллекции. Адаптер обмена пока запланирован.

Выбор и отключение проекта

UI показывает общие записи, если проект не подключён, отличает число записей от Markdown-документов и позволяет выбирать проверенные зарегистрированные проекты. Переключение сбрасывает планы и создаёт новую привязанную сессию памяти.

ahub project disconnect <id> показывает отключение всех checkout проекта, политики и временных токенов. Факты, источники и заметки остаются. Доступ проекта, включая фиксированный MCP, отказывает отключённой привязке. Повторный project connect проверяет Git и использует прежние ID и знания. Общие hooks сохраняются для других проектов.