memo-bank

Your specs are contracts. This makes an agent read them before it edits your code — and tells you when they rot.

memo-bank is a read-only MCP server over a git-native markdown corpus, plus two maintenance loops that keep that corpus honest. Point it at a repo and an agent can answer "what rules govern this file?" in about two reads, at a predictable cost.

It is not a token-savings tool. We A/B'd that claim and it did not hold — see Measured: what it does and doesn't buy.

MIT licensed · Python ≥3.11 · three dependencies (mcp, python-frontmatter, PyYAML).

Why

Documentation rots in two distinct ways, and most tooling addresses neither:

• Missing — code exists that no doc governs. → the coverage loop surfaces uncovered code that is actually being edited as a ranked "spec-wanted" backlog.

• Stale — a doc exists but the code moved on. → the drift check flags any governing doc whose governed files changed after its last_reviewed.

Both run non-blocking on pre-commit. Neither invents content: they tell you what to write and when to revisit, and the corpus stays plain markdown in git.

Related MCP server: cardloom-mcp

Install

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

Use

Adopting the memo-bank in a new project? See 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 writes only what the project owns — .island-slices.json, AGENTS.md, the corpus skeleton, and the authoring templates. No engine code is copied, so a project can never carry a forked engine that ages out of sync.

See it work

You're about to edit a file. Ask what governs it:

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

Two reads, and the rule that would have bitten you is in hand. Ask about a topic instead, and expansion is what makes lexical search land:

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

Same corpus, same intent — the second query uses the words the docs actually use.

Then the loops keep it honest:

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

The agent skill

skills/memo-bank-query/ is a Claude Code skill that teaches an agent when and how to query the corpus — resolve-before-edit, expand topic queries with domain synonyms, and treat a miss as "undocumented", not "unconstrained". Install it once and it applies to every project you work in:

cp -r skills/memo-bank-query ~/.claude/skills/     # user-global
# or, per project:  cp -r skills/memo-bank-query <project>/.claude/skills/

The MCP tools work without it; the skill is what stops an agent from grepping docs by hand or inventing a rule when none exists.

The corpus model

Each slice (a repo, or a subproject within one) owns docs/{specs,state,archive}/:

Frontmatter is a validated schema; applies_to globs are the precedence surface (closest glob wins), and cross-references are stable kind:id handles rather than paths. Specs are written implementation-independent — five sections (Problem · Contract · Restrictions · Open threads · Code references), with concrete file references confined to the last one, so the contract survives refactors.

The tools (MCP surface)

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

They form an incremental-load ladder: pointers → one section → one doc → ranked search → a budget-bounded bundle. Retrieval is lexical (bag-of-words, no embeddings, no vendor lock) — so expand a topic query with domain synonyms before searching; docs.search_live's own description says so. Expansion raises the top hit's relevance score markedly (3.0 -> 32.0 on one measured query); that is a ranking improvement, not a token saving.

docs.resolve_term reads project vocabulary through spec-source adapters (below); with no source present it reports absent rather than failing. The engine depends on no other tool.

Spec-source adapters

Most projects already keep their vocabulary and decisions in whatever methodology they use. The engine hardcodes no list of locations — each ecosystem is an adapter that declares where its artifacts live, and everything downstream (terms, and the drift check) works off that.

Built in:

Why this matters beyond terms: the drift check needs to know which document governs which code. memo-bank's own specs declare that in frontmatter (applies_to + last_reviewed). Foreign artifacts — an ADR, a design doc — declare neither. So an adapter reports the file paths the document mentions as its governed set, and the document's own last commit date stands in for the review date. The result: memobank drift flags a stale ADR or design in any registered ecosystem, not just memo-bank specs.

Adding an ecosystem is a new adapter, never an engine edit. A markdown glossary in a fenced ```yaml term-map block is four lines:

from pathlib import Path
from spec_sources import FencedTermMapSource, register_source

class MyMethodSource(FencedTermMapSource):
    name = "my-method"
    rel_paths = (Path("my-method") / "glossary.md",)

register_source(MyMethodSource())      # register_source(..., first=True) to win precedence

A different shape subclasses SpecSource and implements detect(root), plus read_terms(root) and/or artifacts(root) — see spec_sources.py and the tests for worked examples. Sources are merged; registration order breaks ties. Adapters for other methodologies are welcome; that is the intended way to grow support.

Optional: semantic re-ranking

Lexical search misses when the question's words differ from the doc's, and it always returns some top hit. --rerank jev fixes both, at the cost of a network call to TypeSafe's Jev model:

export TYPESAFE_API_KEY=...          # from your environment or secret store
memobank serve --federation .island-slices.json --rerank jev

docs.search_live then re-sorts the lexical top 20 by relevance (on a smaller corpus the shortlist is padded with the remaining docs, so a doc sharing no words with the query can still win). Each hit gains a relevance score from 0 to 1, and the response gains a verdict:

docs.search_live("how is dark mode implemented")
  → rerank: {status: ok, top_relevance: 0.02, governing_doc_found: false}

governing_doc_found: false means no hot doc covers the topic: the agent should treat it as undocumented, not unconstrained. The tool description tells it so.

On a real 16-doc project corpus (eval), re-ranking lifted hard-query top-1 accuracy from 0.20 to 0.80 on a gold set labelled before the experiment. Its "no governing doc" verdict made no false calls in 40 queries. A search takes about 0.8 s and roughly $0.0008.

What leaves the machine: the search query, plus the title, tags and first 4,000 characters of each shortlisted hot doc, sent to api.typesafe.ai. Archive entries are never sent. The mode is off by default, and without the flag nothing is sent anywhere. Failure is safe: if the API errors, times out or the key is wrong, search returns the plain lexical results with rerank.status: failed and the reason. Flags: --rerank-shortlist N (calls per search), --rerank-threshold P (the verdict's cut-off, default 0.5), --rerank-model.

Configuration

One file, .island-slices.json, is the whole adoption contract:

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

Only slices is required; everything else defaults. The engine carries no project literals.

Measured: what it does and doesn't buy

We ran a real A/B — 32 headless agent runs, retrieval vs. plain search over the same corpus, asking "what governs this file?" (method and raw numbers).

Correctness: 32/32 in both arms. Search found the right spec too; retrieval did not make the answer more reachable.

Tokens: no measurable saving. +3.5% raw, +6.3% cache-weighted, sd 14.4pp across tasks — inside the noise. Retrieval was cheaper on 4 of 8 tasks.

What did hold — predictability:

Search is a lottery; retrieval is consistent. Predictable context cost, not lower.

Why: ~92% of a run is per-turn context reload, and cached reads cost ~0.1×. That makes "just put the whole corpus in the cached prefix" a strong alternative — it wins below roughly 20–23k corpus tokens. The corpus we measured was 20,364, i.e. exactly at the crossover.

So: if your corpus is small, skip retrieval and put your specs in the system prompt. memo-bank earns its keep when the corpus outgrows what you want resident in context — and for the maintenance loops, which have nothing to do with retrieval. That larger-corpus case is a prediction we have not yet tested.

Retrieval quality: semantic re-ranking helps. A separate A/B (eval/jev-ab) found that opt-in --rerank jev beats lexical search and synonym expansion on vocabulary-mismatch queries, and reliably reports "no doc governs this". See Optional: semantic re-ranking.

Status

Working software, used on real projects — not a polished product. Known rough edges: the island/slices vocabulary is inherited from the first project that used it; memobank init doesn't install the git hook (copy hooks/pre-commit yourself); last_reviewed is date-granular, so same-day edits after a refresh re-flag; mcp is pinned <2 (2.x changes the Server API — untested).

Contributions welcome — see CONTRIBUTING.md.

License

MIT — see LICENSE.