memo-bank

あなたの spec は契約です。この仕組みは、エージェントがコードを編集する前に spec を読ませ、そして spec が腐ったときにあなたに知らせてくれます。

memo-bank は、git ネイティブな markdown コーパス上で動作する読み取り専用の MCP サーバーであり、さらにそのコーパスを正直に保つ 2 つのメンテナンスループを備えています。リポジトリを向けるだけで、エージェントは「このファイルを支配するルールは何か?」という問いに、毎回 40 個のファイルから答えを引き出し直す代わりに、およそ 2 回の読み取りで答えてくれます。

MIT ライセンス · Python ≥3.11 · 依存は 3 つ（mcp, python-frontmatter, PyYAML）。

なぜ

ドキュメントは、はっきりと異なる 2 つの形で腐化しますが、ほとんどのツールはどちらにも対応していません。

• Missing（欠落） — それを支配するドキュメントがないコードが存在する。→ **coverage loop（カバレッジループ）**が、実際に編集されている未カバーコードを、ランク付けされた spec-wanted バックログとして浮かび上がらせる。

• Stale（陳腐化） — ドキュメントはあるが、コードの方が進んでしまっている。→ **drift check（ドリフトチェック）**が、last_reviewed の後に支配下のファイルが変更された、統治しているドキュメントにフラグを立てる。

どちらも pre-commit のタイミングで非ブロッキングに実行されます。どちらもコンテンツを作り出したりしません。何を書くべきか、いつ見直すべきかを伝えるだけです。コーパスは 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."

2 回の読み取りで、あなたを害してしまうかもしれなかったルールを手にできます。代わりにトピックについて尋ねるなら、語彙を展開（expansion）してみてください。それこそが、語彙による検索（lexical search）を hit させる鍵です:

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

同じコーパス、同じ意図 — 2 つ目のクエリは、ドキュメントが実際に使っている言葉を使っています。

そして、ループたちがそれを正直なままに保ってくれます:

$ 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}/ を所有します。

フロントマターはバリデーション済みスキーマです。applies_to グロブが優先を決めるサーフェス（いちばん近いグロブが勝つ）となり、相互参照はパスではなく、安定した kind:id ハンドルです。spec は実装非依存で書きます — 5 つのセクション（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`

これらは段階ロードの ступениです：ポインター → 1 セクション → 1 ドキュメント → ランキング検索 → 予算に収まるバンドル。検索は語彙ベース（bag-of-words）で、埋め込みも、ベンダロックもありません — だから、検索する前にトピックのクエリをドメインの同義語で展開してください。それ実際、docs.search_live の説明にも書いてあります。そして実際には、トップヒットのスコアを約 10 倍にしていました。

docs.resolve_term は、.haft/ specs/term-map.md か、ドキュメンタ付属の docs/_terms/term-map.md から用語マップを読み取ります。どちらもなければ、失敗する代わりに absent を返します。それ以外のツールには一切依存しません。

設定

設定ファイルは .islan-slices.json の 1 つだけで、それが需要採択契約の全体です：

{
  "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 hook をインストールしません（hooks/pre-commit は自分でコピーしてください）。last_reviewed は日単位の精度なので、変更後に当日にもう一度編集すると再度フラグが出ます。mcp は <2 にピン留めされています（2.x では Server API が変わっていて、未検証のため）。

コントリビューション歓迎 — CONTRIBUTING.md を参照。

ライセンス

MIT — LICENSE を参照します。

I see some issues in my draft: There are some typos ("docs.resolve" path, "バージ" etc.). Need to clean.

Also, I accidentally wrote "spec-でしょう, sub-products", "非感動" errors. Let me one more careful pass in final output later. But in the above draft, I noticed:

• "docs.resolve_path" should be "docs.resolve_path" exactly, not "docs.resolve" — I must ensure in final.

• "spec"的方 etc.

Let me now final green-light a clean, carefully typed version.

Also, should I keep "でも" in tools line etc.

Before final, double-check "authoring templates": "最终稿テンプレート" maybe. I'll render "記載用テンプレート"?

I'll use "著述用テンプレート" — hmm "オーサリングテンプレート" maybe too English. "書くためのテンプレート" — Let me simply say "執筆用テンプレート".

Now final.

One more: "the spec documents, doc's metadata tr... " "frontmatter" we can use "フロントマター" because it's the YAML header term. Good.

Also, "matter" term as technical, fine.

"Implementation-independent" — hmm I translated "実装に依存しない"? True. Wait I'll use "実装独立性". "implementation-independent" translation: "実装に依存しない". But the sentence "Specs are written implementation-independent" — "specは実装に依存しない形で書かれる". Good.

Also "width" etc.

Now, in the "## コーパスのモデル" table, "indexed" header: "インデックス化される" or "索引". I'll use "インデックス".

I will avoid "ホット" giving jay.

Also the Miscorrect "schema" plus "applies_to" — keep as block.

" " weapons? Good.

Ok.

Also, italic emphasis in "an agent can answer "what rules govern this file? "" — should keep the italic * around the question. Interesting: original: "can answer "what rules govern this file?"" Here asterisk around the quoted phrase, i.e., "...". So I'll write 「エージェントは "このファイルを支配するルールは何か?" に回答できる」.

Prouggestion: with Japanese brackets: 「このファイルを支配するルールは何か?」 need keep asterisk markers around.

Similarly topic italic on the "トピック" translation: use トピック.

In bullets: actually being edited -> 実際に編集されている should keep marks.

Ok.

Now C — Complex output after final.

One more time, the original first paragraph after title: The user's input has "Your specs are contracts. This makes an intelligent read them ..." So I will do the final:

あなたの spec は契約です。これにより、エージェントはコードを編集する前に spec を読み、spec が腐ったときにはあなたに知らせてくれます。

Good.

Now, the "Project" notation "memo-bank" in body not changed.

Now for "coverage loop" with (カバレッジループ) in bold — format: "coverage loop（カバレッジループ）" good. "drift check（ドリフトチェック）**" similarly.

Missing/Stale: "Missing（欠落）", "Stale（陳腐化）".

Now, at the section "Use" we have:

"引く ..." fine.

Now the final text length is okay.

Let me now produce the final answer text, being careful to keep all code spans exactly as source:

Files:

• "SCAFFOLDING.md"

• "AGENTS.md"

• ".island-slices.json"

• "docs/{specs,state,archive}/"

• "last_reviewed"

• "island" and "slices"

• "memobank init"

• "hooks/pre-commit"

• "mcp"

• "Server"

• ". etc."

• "docs.list etc."

• "labels:" "spec-wanted" "kind:id"

• "term_map": ".haft/specs/term-map.md", "docs/"_terms/term-map.md"

• absent

Make sure the phrase "docs-n" "docs-native" — I might translate "ドキュメント同梱" but better "docs 側の".

Now about "It is a term map reading from..." — "read a term map from .haft/specs/term-map.md or the docs-native docs/_terms/term-map.md" — write "用語マップを .haft/specs/term-map.md、またはドキュメンテーション側の docs/_terms/term-map.md から読み取ります".

Ok.

And