memo-bank

Deine Specs sind Verträge. Genau das bringt einen Agenten dazu, sie zu lesen, bevor er deinen Code ändert – und sagt dir, wenn sie veralten.

memo-bank ist ein schreibgeschützter MCP-Server über einem git-nativen Markdown-Korpus, plus zwei Wartungsschleifen, die dieses Korpus ehrlich halten. Richte es auf ein Repo aus, und ein Agent kann die Frage „Welche Regeln gelten für diese Datei?“ in ungefähr zwei Lesevorgängen beantworten, statt die Antwort jedes Mal aus vierzig Dateien neu abzuleiten.

MIT-lizenziert · Python ≥3.11 · drei Abhängigkeiten (mcp, python-frontmatter, PyYAML).

Warum

Dokumentation verrottet auf zwei verschiedene Arten, und die meisten Werkzeuge gehen keine davon an:

• Fehlend – es existiert Code, den kein Dokument regiert. → die Coverage-Schleife fördert nicht abgewickelte Code zutage, der tatsächlich bearbeitet wird, als eingestuftes „Spec-gewünscht“-Backlog.

• Veraltet – ein Dokument existiert, aber der Code hat sich weitbewegt. → der Drift-Check markiert jedes regierende Dokument, dessen regierte Dateien sich nach seinem last_reviewed geändert haben.

Beide laufen nicht-blockierend im Pre-Commit. Keines erfindet Inhalte: Sie sagen dir, was du schreiben und wann du es überarbeiten solltest – und das Korpus bleibt schlichtes Markdown in git.

Related MCP server: cardloom-mcp

Installation

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

Verwendung

Willst du memo-bank in einem neuen Projekt einführen? Sieh in SCAFFOLDING.md nach.

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 schreibt nur das, was dem Projekt gehört – .island-slices.json, AGENTS.md, das Korpus-Grundgerüst und die Authoring-Vorlagen. Es wird kein Engine-Code kopiert, damit ein Projekt nie einen Fork des Motors mit sich führen kann, der aus dem Takt altert.

So funktioniert sie

Du bist gerade dabei, eine Datei zu bearbeiten. Frag, was sie regelt:

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

Zwei Lesungen, und die Regel, die dich sonst gebissen hätte, liegt verborgen in deiner Hand. Frag stattdessen nach einem Thema, und genau die Erweiterung sorgt dafür, dass die Begriffssuche trifft:

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

Gleiches Korpus, gleiche Frage – die zweite Anfrage benutzt die Wörter, die die Doku tatsächlich verwendet.

Und dann halten die Schleifen sie ehrlich:

$ 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: …

Das Korpus-Modell

Ein Slice (ein Repo oder ein Teilprojekt darin) besitzt docs/{specs,state,archive}/:

Die Frontmatter ist ein validiertes Schema; die applies_to-Globs sind die Präfteden?eher – der nächste Glob gewinnt – und Querverweise sind stabile kind:id-Handles, keine Pfade. Specs werden implementierungsunabhängig geschrieben: fünf Abschnitte (Problem · Vertrag · Einschränkungen · Offene Themen · Code-Referenzen), wobei konkrete Dateiverweiße auf den letzten Abschnitt beschränkt bleiben, damit der Vertrag Refactorings übersteht.

Die Tools (MCP-Oberfläche)

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

Sie bilden eine Treppe des inkrementellen Ladens: Verweise → ein Abschnitt → ein Dokument → eine bewertete Suche → ein budgetbegrenztes Bündel. Der Abruf ist lexikalisch (Bag-of-Words, keine Embeddings, kein Vendor-Lock) – erweitere also eine Themenanfrage zuerst um Domänen-Synonyme, bevor du suchst; das sagt auch die eigene Beschreibung von docs.search_live, und es hat in der Umgangssprache die Top-Treffer ungefähr verzehnfacht.

docs.resolve_term liest eine Begriffskarte aus .haft/specs/term-map.md oder aus den Doku-eigenen docs/_terms/term-map.md; fehlt beides, meldet es absent statt Fehler. Es gibt keine Abhängigkeit von irgendeinem anderen Werkzeug.

Konfiguration

Eine einzige Datei, .island-slices.json, ist der gesamte Einführungsvertrag:

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

Nur slices ist Pflicht; alles andere hat Standardwerte. Die Engine trägt keine projektbezogenen Konstanten.

Status

Lauffähige Software, eingesetzt in echten Projekten – kein poliertes Produkt. Bekannte Kantenrisiken: die island/slices-Terminologie stammt aus dem ersten Projekt, das sie verwendet hat; memobank init installiert den Git-Hook nicht (kopiere hooks/pre-commit selbst); last_reviewed ist auf Tagesgranularität gestoppt, sodass Bearbeitungen am selben Tag nach einer Aktualisierung erneut markiert werden; mcp ist auf <2 gefixt (2.x ändert die Server-API – ungetestet).

Beiträge sind willkommen – siehe CONTRIBUTING.md.

Lizenz

MIT – siehe LICENSE.