memo-bank

Спецификации — это контракты. Это заставляет агента прочитать их перед тем, как править ваш код, — и сообщает вам, когда они устаревают.

memo-bank — это MCP-сервер только для чтения поверх git-нативного markdown-корпуса, плюс два обслуживающих цикла, которые не дают этому корпусу врать. Наведите его на репозиторий — и агент сможет ответить на вопрос «какие правила действуют для этого файла» примерно за два чтения, вместо того чтобы каждый раз заново собирать ответ из сорока файлов.

Лицензия MIT · Python ≥3.11 · три зависимости (mcp, python-frontmatter, PyYAML).

Зачем

Документация портится двумя разными способами, и большинство инструментов не работают ни с одним из них:

• Отсутствует — код существует, но никакой документ им не управляет. → цикл покрытия поднимает непокрытый код (который действительно редактируется) как ранжированный список «нужна спецификация».

• Устарела — документ есть, но код ушёл вперёд. → проверка расхождения отмечает любой управляющий документ, чьи управляемые файлы изменились после last_reviewed.

Оба цикла работают без блокировок на pre-commit. Ни одна из них не выдумывает содержание: они подсказывают, что писать и когда пересмотреть, а сам корпус остаётся обычным markdown в git.

Related MCP server: cardloom-mcp

Установка

pip install -e '.[dev]'      # from a clone; PyPI publishing not set up yet
memobank --help

Использование

Внедряете memo-bank в новый проект? Смотрите SCAFFOLDING.md.

memobank init --target ../my-project --island my-project --slice umbrella=.
memobank validate ../my-project --index docs/index.json
memobank serve    --federation ../my-project/.island-slices.json   # the MCP server
memobank coverage --mode staged                                    # missing specs
memobank drift    --registry .island-slices.json                   # stale specs
memobank benchmark --federation .island-slices.json                # time-to-context

init записывает только то, чем владеет сам проект: .island-slices.json, AGENTS.md, скелет корпуса и шаблоны для авторинга. Код движка не копируется, поэтому проект никогда не сможет понести с собой форкнутый движок, который со временем рассинхронизируется.

Посмотрите, как работает

Вы собираетесь отредактировать файл. Спросите, какие правила к нему применяются:

$ memobank serve … →  docs.resolve_path("src/services/api.ts")

  hmac-signing-client   (matched glob: src/services/api.ts)
  → docs.get("hmac-signing-client") → the contract you must satisfy:
      "NEVER log the server token, even partially."
      "NEVER sign a path that differs from what the server receives."

Два чтения — и правило, которое могло бы вас зацепить, уже у вас в руках. Спросите вместо этого про тему — и расширение запроса это то, что помогает лексическому поиску попасть точно в цель:

docs.search_live("crawling reviews")                      →  top hit, score  3.0
docs.search_live("refresh fetch ingest cache stale quota") →  top hit, score 32.0

Тот же корпус, тот же смысл — второй запрос использует слова, которыми документация реально говорит.

А циклы следят за тем, чтобы этот корпус не врал:

$ memobank coverage --mode staged
⚠ 1 changed file(s) have no governing spec — added to the spec-wanted backlog:
  - src/services/audio.ts

$ memobank drift --registry .island-slices.json
⚠ 1 governing doc(s) may be stale — governed code changed since their last_reviewed:
  - review-ingestion-status (last_reviewed 2026-06-27) — 7 changed: …

Модель корпуса

Каждый slice (репозиторий или подпроект внутри него) владеет каталогами docs/{specs,state,archive}/:

Frontmatter валидируется по схеме; applies_to-глобы являются поверхностью приоритетов (побеждает ближайший glob), а кросс-ссылки — это стабильные ссылки вида kind:id, а не пути. Спецификации пишутся независимо от реализации — из пяти разделов (Проблема · Контракт · ограничения · Незакрытые обсуждения · Ссылки на код), все вещные ссылки на файлы — в последнем. Такой контракт переживает рефакторинги.

Инструменты (поверхность MCP)

docs.list · docs.get · docs.get_section · docs.resolve_path · docs.search_live · docs.search_archive · docs.resolve_term · docs.compose_context

Они образуют лестницу инкрементальной загрузки: указатели → один раздел → один документ → ранжированный поиск → набор в пределах бюджета. Поиск — лексический (мешок слов, без эмбеддингов, без привязки к вендору), поэтому прежде искать запрос по теме расширяйте синонимами из предметной области; описание самого docs.search_live прямо об этом говорит, и на практике это примерно в десять раз повышало оценки топ-совпадений.

docs.resolve_term читает карту терминов либо из .haft/specs/term-map.md, либо из живущего прямо в документации docs/_terms/term-map.md; если нет ни того ни другого — возвращает absent, а не падает. От других инструментов зависимости нет.

Конфигурация

Один файл — .island-slices.json — это весь контракт внедрения:

{
  "island": "my-project",
  "slices": [{ "name": "umbrella", "root": "." },
             { "name": "api", "root": "services/api" }],
  "source_globs": ["src/**"],
  "schema": "docs/specs/schema-frontmatter-v1.md"
}

Обязателен только slices; всё остальное — значения по умолчанию. Движок не содержит никаких строковых литералов проекта.

Статус

Работающий инструмент, используется в настоящих проектах, — но не отполированный продукт. Известные шероховатости: терминология island/slices пришла от первого проекта, который её использовал; memobank init не устанавливает git-хук (скопируйте hooks/pre-commit самостоятельно); last_reviewed имеет гранулярность в один день, поэтому изменения в тот же день после обновления снова вызовут предупредительное срабатывание; зависимостов mcp способа меньше <2 (в 2.x меняется Server API — не проверено).

Вклада ждём — см. CONTRIBUTING.md.

Лицензия

MIT — см. LICENSE.