memo-bank

당신의 spec은 계약입니다. 이 덕분에 에이전트가 코드를 편집하기 전에 그 spec을 읽게 되고, spec이 낡아지는 시점도 알려줍니다.

memo-bank는 git-네이티브 markdown 말뭉치를 대상으로 하는 read-only MCP 서버이며, 그 말뭉치를 정직하게 유지해 주는 유지보수 루프 두 개가 함께 제공됩니다. 저장소 하나를 가리키면 에이전트는 매번 수십 개 파일에서 답을 다시 끌어내는 대신 "이 파일에는 어떤 규칙이 적용되나요?" 같은 질문에 대략 두 번의 읽기만으로 답할 수 있습니다.

MIT 라이선스 · Python ≥3.11 · 의존성 3개 (mcp, python-frontmatter, PyYAML).

왜

문서는 두 가지 방식으로 달라지지만, 대부분의 도구는 그 어느 쪽도 다루지 못합니다:

• **누락(Missing) — 문초. → **커버리지 루프(coverage loop)**가 실제로 편집되고 있는 문서로 다뤄지지 않은 코드를 순위가 매겨진 "spec-wanted" 백로그로 표면화합니다.

• 낡음(Stale) — 문서기는 존재하나 코드는 이동했음. → **드리프트 검사(drift check)**는 last_reviewed 이후 관리 대상 파일이 변경된 모든 관장 문서에 플래그를 답니다.

둘 다 pre-commit의 non-blocking으로 실행됩니다. 어느 쪽도 콘텐츠를 지어내지는 않습니다. 무엇을 쓸지, 언제 다시 살펴볼지만 알려줄 뿐이고, 말뭉치는 git 속에서 평범한 markdown 그대로 유지됩니다.

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."

두 번 읽으면, 당신에게 달려들 대장 규칙이 내 손안에 있습니다. 말파일이 아닌 주제로 질문해 보세요. 그러면 검색어 확장(expansion)이 단어 표기를 lexical 검색으로 만듭니다:

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은 우선순위를 표면화하며 (가장 가까운 glob이 우선합니다), 상호 참조는 경로가 아니라 안정적인 kind:id 핸들이 됩니다.

Specs는 구현에 의존하지 않도록 다섯부분 — Problem · Contract · Restrictions · Open threads · Code references 로 작성하며, 구체적인 파일 참조는 될 수 있는 뒤 마지막 문으로 모아두어 계약이 리팩토링을 살아남습니다.

도구 (MCP 인터페이스)

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

이들은 점증적 로딩 사다리를 형성입니다. 포인터 → 한 섹션 → 문서 하나 → 랭킹 검색 → 예산 한계의 번들 순으로 이어집니다. 검색은 어휘 기반(lexical, 보통 bag-of-words, 임베딩 없음, board 종속이 없음)이므로, 검색 전에 도메인 동의어로 주제를 넓혀두어야 합니다 — docs.search_live의 설sed는 그 점을 이미 안내하고 있으며, 실제로 top hit 점수를 약 10배(10×)가량 높여 왔습니다.

docs.resolve_term은 .haft/specs/term-map.md 또는 문서-네이티브 docs/_terms/term-map.md에서 term map을 읽습니다. 둘 다 없으면 실패가 아닌 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"
}

island-slices.json — 실제로 필요한 것은 slices뿐이며, 나머지는 기본값입니다. 엔진이 프로젝트 리터럴을 가지고 다니는 일은 없습니다.

상태

실제 프로젝트에서 쓰이는 실동 소프트웨어이며 완성품 양식은 아닙니다. 알려진 거친 부분island·slices 어휘는 그 기준을 처음 사용한 프로젝트 것이 그대로 옮겨 왔고;memobank init은 git hook을 설치하지 않으며 (hooks/pre-commit을 직접 복사하세요);; last_reviewed는 일자 단위라 동일 날짜를 갱신한 뒤의 변경은 다시 플래그 될 수 있습니다;. mcp는 <2로 고정되어 있으므로(2.x는 Server API를 바꿔 — 미검증).

Contributions welcome — CONTRIBUTING.md.

라이선스

MIT — LICENSE 참조.