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-

... View full README on GitHub