mcp-memorybank

# mcp-memorybank

An MCP server for a `memory_bank` knowledge base. It seeds one from nothing, gates every write
against the rules the bank itself declares, routes to the right document without reading the bank,
and reports where the code has moved on without the documents.

It writes nothing on its own initiative. Every document arrives from a deliberate call carrying a
purpose, an upstream dependency and an index entry; what the end-of-session hook collects lands in
a quarantine that only a human empties.

Spec — [specification.md](specification.md), plan — [implementation-plan.md](implementation-plan.md),
what a seeded bank is made of and where it strains — [architecture.md](architecture.md).

Everything in the plan is done: **E0** index, **E1** reads, **E2** validation, **E3** graph,
**E4** search and delta, **E5** writes.

## How it works

There is no database, no daemon and no configuration. A directory of markdown files is the entire
state, and the server is a reader of it that happens to speak MCP. Everything it knows it re-derives
from the files; delete its process and nothing is lost, because nothing was ever kept anywhere else.

### The index, and why there is no watcher

On startup the server walks the bank once, and on every call it walks it again: `readdir`, `stat`,
and a parse only for the files whose `mtime` moved. A cold build of a 368-document bank takes about
85 ms; the walk before an unchanged call costs 11–13 ms.

That is why there is no file watcher. A watcher would save those milliseconds and buy an error class
in exchange — an index that has quietly diverged from the disk, in a tool whose whole job is to be
trusted about what the disk says. The cheap check wins on both counts.

### What a document becomes

Each file is parsed once into a record: the frontmatter fields, the second-level section headings
with their line spans, byte size, mtime — and one thing the file does not contain, a **layer**
computed from the path (`dna`, `knowledge`, `decision`, `delivery`, `flow`, `inbox`, `other`).

Frontmatter goes through `gray-matter` in exactly one place. When the YAML is invalid — an unquoted
colon in `purpose` is the common case — the document does not fall out of the index: its metadata is
recovered line by line and the parse error is kept for `bank_validate` to report. A document that
disappears from routing because of a typo is worse than one that ranks badly.

### The contract comes from the bank

`doc_kind`, `doc_function`, `status`, whether `derived_from` is mandatory, which document is the
declared root — all of it is read out of the bank's own `dna/frontmatter.md` and `dna/governance.md`
at refresh time. Nothing is hardcoded, and the sets are open.

This is not politeness: banks disagree about their own vocabulary, and a fixed enum rejects a
sizeable minority of real documents by `doc_kind` alone. A bank with no `dna/` still works: the server runs in degraded mode — reading,
routing, search and the structural rules — and says so instead of enforcing a contract nobody
declared.

### Routing: ranking the header, never the prose

`bank_route` answers "what should I read about this", and it reads only what a human wrote by hand
about each document — never the body. Four fields, with fixed weights:

| Field | Weight | Scored as |
|---|---|---|
| `canonical_for` | 5 | how much of a fact key the question covers, not whether one word of it matched |
| `purpose` | 3 | word overlap |
| `title` | 2 | word overlap |
| section headings | 1 | the best-matching heading, which is also returned so the answer can be read section-scoped |

The raw score is then multiplied, and the multipliers are where the ranking actually gets its
judgement:

- **Layer.** `knowledge` ×1.5, `decision` ×1.2, `dna` / `flow` / `other` ×1.0, `delivery` ×0.6,
  `inbox` ×0.2. Delivery is damped because in a bank that has been in use for a while it is most of
  the documents; without this a question about a rule returns the closed features that mention it.
- **Status.** `active` ×1, `draft` ×0.7, `archived` ×0.2.
- **Closed work.** `delivery_status: done` or `cancelled` halves the score again. A finished feature
  is history, not an answer.
- **Intent.** A question containing *why*, *rationale*, *instead of*, *почему*, *вместо* reweights
  the whole run toward decisions: `decision` ×1.6, `knowledge` ×1.2. "Why X" and "what is X" are
  different questions and should not return the same document first.

Templates never appear in results: they are structurally identical to real documents and would
flood every list.

### Search: a different index for a different question

`bank_search` is not a fallback for routing, it answers the other half. Routing ranks the
hand-written header ("which document is *about* this"); search reads the prose ("where does this
string actually appear"). Identifiers, error messages and literals live only in bodies.

It builds an inverted index over document bodies, incrementally on the same mtime check. A query
matches in three tiers by confidence — the word as typed weighs 10, its equivalent in the other
language 6, a fragment of a compound token 1 — and documents matching every concept are ranked
before documents matching some. The fragment tier is what keeps `FT-042` from lifting the
`features/README.md` registry, with its seventy `FT-*` lines, above the feature itself.

### Writing: one operation, or none

`bank_create` writes the document, fills the frontmatter the contract asks for, and registers it in
the section index **in the same call** — so the registration step cannot be forgotten, which is the
single most common way a bank rots. Registration copies the shape of the last entry in that index,
table row or bullet or numbered item, so a hand-written file is not reformatted.

Before any of that it refuses, with the reason named: the path is taken, `derived_from` does not
resolve, `canonical_for` is already owned by another document, the path leaves the bank root, or it
does not end in `.md`. A refusal writes nothing at all — no partial file, no orphaned index line.

Two rules follow from those gates, and they are the reason the writes are worth having: an SSoT
conflict and a broken edge **cannot enter the bank through this server**. They can only arrive by
editing a file behind its back.

### The graph

`bank_graph` walks `derived_from` breadth-first with a node ceiling, so a hub document does not drag
in the whole bank and a cycle does not loop. Each edge lands in one of three outcomes: internal (a
node), `external` (it leaves the bank root — in a monorepo, banks nest), or `broken`. `up` is what a
document is built on; `down` is the blast radius of changing it.

An external edge is followed exactly one hop: the target's frontmatter is read and returned under
`neighbours`, and nothing else about it is. It is not indexed, not validated, not searchable, and its
own edges are not walked. The boundary stays where it was — but in a monorepo those edges carry real
decisions, and a blast radius that silently ends at the repository wall is wrong rather than partial.
Pass `neighbours: false` to skip the reads.

### Drift

`bank_drift` answers the question validation cannot: not "is something missing" but "has what we
wrote gone stale". A document that describes code lists it in `anchors:`, and the server compares the
last commit that touched the document against the last commit that touched the code. Where the code
is ahead by more than the threshold, it says so — and where an anchor points at a path that no longer
exists, it always says so, because that is the code moving out from under the document.

It never guesses which document owns which file. The pairing is hand-annotated or it does not exist,
which means a bank that has not been annotated gets an honest empty answer and a note saying why. And
it reports without editing: whether a six-month gap matters is not a judgement a timestamp can make.

### What a seeded bank contains

`bank_init` writes 24 files: the governance set in `dna/`, a root index, eight section registries,
the four flow documents, a pointer where the templates would be, and two drafts to fill in. Three more sections — `epics`, `prd`, `prompts` — are built
the first time a document needs one, index and root-index entry included, rather than standing empty
from the start.

The document templates are not copied. They ship with the server and `bank_create` reads them from
there, so a bank behaves exactly as if it held them; `--materialize-flows` copies them in for a
project that means to change one, and from then on the bank's own copies win. The prose flows *are*
copied, because people read them and routing answers with them.

`dna/` is copied too, and that one is not negotiable: it is the law the bank is judged by, and the
design rests on it travelling with the corpus. Every top-level directory's layer and ranking weight
is declared there as well — a bank that renames a section says so in that table and keeps its
weight, and a bank that declares nothing gets the built-in map.

### What it will not do

It does not create a document by editing — every new document goes through `bank_create`, so nothing
enters the bank without a path check, a `derived_from` that resolves and an index entry. It does not
promote anything out of `_inbox/` on its own. It does not invent a schema, and it does not enforce a
rule the bank has not declared. It does not delete a document outside `_inbox/`. And it does not
index, validate or search anything outside the bank root — the one hop `bank_graph` takes into a
neighbouring bank reads a header and stops there.

### What it costs in tokens

Wiring a server in is not free, and the cost is paid in two different currencies. All figures below
were measured on the shipped build, counting characters of the actual JSON-RPC payloads and
converting at 3.5 characters per token — dense JSON runs closer to that than the 4 that suits prose.

**The fixed half is paid