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, plan — implementation-plan.md, what a seeded bank is made of and where it strains — architecture.md.

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

What it is measurably good at, and what it is not

Counted across six banks in real use, by parsing the sessions rather than by impression:

writing into the bank, through the server     985 calls

reading the bank, through the server 187 calls reading the bank, around the server 1755 calls (cat, grep, Read) bank_route specifically 33 calls

The writing half works. bank_create, bank_edit and bank_update_section are used in every bank, with or without any instruction to do so, because writing a governed document by hand is harder than calling the tool: it would have to reproduce the frontmatter, resolve the derived_from, and register itself in a section index, and it would fail validation if it got any of that wrong. Ninety percent of all server calls are writes.

The reading half is mostly bypassed. Nine times out of ten an agent opens the bank with cat and grep instead of asking bank_route which documents matter. This is not a claim that routing answers badly — nobody has measured that. It is a claim that it does not get asked, because reaching for the shell is what a model does in every repository and nothing here outweighs the habit.

Two things follow, and neither is comfortable. Routing is the feature this README leads with and the one the token arithmetic below is built on, and it is the least used. Editing existing documents was written into the specification as something the server would *not* do — see §8 — and it turned out to be the half that carries the project.

The one lever with evidence behind it is the paragraph under Telling the agent to use it: the four banks that carry it route eight times more often than the two that do not, 32% of reads against 4%. That is a correlation across six projects, and it is being tested properly — see A-06 in backlog.md.

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:

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 on every request, whether a tool is called or not, because the definitions li