Summary: This server exposes a read-only, hop-by-hop ontology reader — fetch a routing table of areas, read the documents a table points at, and optionally borrow a read-only view of another RouteMind over a circuit.
knowledge_table(path?) — fetch a routing table: a list of what exists and the exact addresses to go next. Call with no arguments for hop 0, the list of areas (every walk starts here). Accepts addresses a table printed: /v1/regions, /v1/regions/<area>, /v1/nodes/<id>, /v1/services/<id> — use them verbatim, never construct one.
knowledge_read(path) — read one document, by the address a table printed for it, returned as written.
knowledge_circuit(op, url, name, token) — open/list/close a session against another RouteMind: their shared areas appear alongside this backbone's, walked the same way with the addresses their tables print. Read-only, nothing written on either side, nothing outlives the connection, and it holds only what its owner chose to share.
Protocol enforced by the tools: two operations per area — fetch the list, pick an area, fetch that area, read what it points at. Only someone who has seen the whole area list may claim something is absent.
Not available here: knowledge_overlay and knowledge_write are absent, so no overlay work and no writing through this server.
Caveat: the area list is currently unfetchable — knowledge_table reports HTTP 404 from /v1/regions, so hop 0 is unavailable and, in practice, only knowledge_read (with an address already known) and knowledge_circuit can be attempted until that endpoint returns.
Uses a git repository as the backing store for the ontology: the vocabulary, areas and routing rows are data committed into the user's own git repo, so every write is a commit (undo via git revert) and per-row age information — how long a route has existed and when the thing it points at last moved — is derived directly from git history.
A routing table for an agent, written and kept by people. You split a body of documents into areas. Each area describes, in one sentence, when someone should come to it. An agent reads that list of sentences first, chooses, and walks down a tree of short lines to the document. The map shows you the tree, and one click shows you the exact text the agent is given at each step.
The domain is not in the code. The areas, the lines and the documents are data, kept in your own git repository. Every change is a commit.
RouteMind does not replace retrieval. It makes one bet:
Where documents resemble each other — revisions of one rule, rows that differ by a code, policies that differ by one condition — a routing table that people write and maintain finds the right document more reliably than similarity search. The price is several times the cost per question, plus the labour of keeping the table true.
The bet is lost if any of these turns out to be true:
Retrieval is already good enough on real documents. Then the walk costs more and buys nothing.
Keeping the map costs more than the wrong answers it prevents. The map is human work, every week.
A large map loses the agent. Measured once, small: 5 areas against 30, with confusable neighbours, did not change which area was chosen (eval/scale/). Dozens of real areas or tens of thousands of documents have not been tried.
None of these has been settled on real data. Everything measured so far is listed below, together with what it does not show.
Related MCP server: warp-memory-mcp
The idea is borrowed from routing on a network. An area advertises when it is relevant, not everything it holds. That keeps the first list the same size whether the areas hold 80 documents or 8,000.
BACK-BONE ─ the whole map. Hop 0: one row per area, nothing else,
│ and the only place "it is not here" may be said
│
├── AS expense "what to do with a receipt · whether the corporate card
│ │ may be used here · how much a business trip pays"
│ ├── AS corp-card ← an area holds areas: the same thing one level
│ │ └── card-limit down, describing itself the same way
│ └── AS evidence
├── AS approval "whom to put in the approval chain · …"
└── AS payroll "what this payslip line means · …"use_when is the only text the agent reads before it chooses an area. An area with a title and
no reason is an area nobody picks.
Each table describes only its own area. An area's table says what that area holds, never what the whole map lacks. Only someone who has read hop 0 may conclude that something is not here.
Every walk starts at hop 0, and every step records why it was taken. The MCP server enforces this. The map replays any walk from the last six hours.
Writing is a set of decisions. When an agent files a document, it may create a holder and move siblings under it in the same change. Every line whose table changes must be either kept or rewritten, or nothing is written. (docs/CHANGE.md)
Two containers and no database. ontology is the API and the only process that touches your git
repository. web serves the map and acts as a proxy. mcp/knowledge_mcp.py is the agent's door: a
single stdlib-only file with four tools — read a table, read a document, place a document, read
another RouteMind.
The setting. 700 questions over one frozen corpus of 1,126 documents, in four arms, with one fresh agent per question:
plain RAG | + reranker | RouteMind walk | |
question in the documents' own codes | 0.991 | 1.000 | 1.000 |
question in a person's words | 0.028 | 0.069 | 1.000 |
a rule two revisions back | 0.200 | 0.200 | 1.000 |
overall | 0.507 | 0.531 | 0.999 |
All three columns are scored the same way: a question that needs two documents counts only when both
are found, and an accepted alternative document counts for the one it stands in for. Until 2026-10-10
the retrieval columns counted any one of the documents, which was more lenient than the walk's
scoring (0.516 / 0.541 overall). An independent audit found the difference (15 of 1,400 rows;
issue #2, finding F-RM-01), and bench/attribution.py
re-derives these numbers from the saved results.
Read it as a stress test, not a benchmark.
The corpus is synthetic and was built so that retrieval fails. Each answer has many near-identical rivals: other revisions, neighbouring codes. eval/COLLAPSE.md describes how that was constructed. On questions phrased in the documents' own words, retrieval scores 0.99 and the walk adds nothing.
One domain, one map, one author side. The corpus is a fictional back office. The 700 questions
are templated by the project (bench/crowd.py, bench/temporal.py), not written by outsiders. The map's sentences were written by people who knew the corpus. No
real organisation's documents have been measured. The question of who labels the ground truth is
still open (eval/PREREGISTRATION.md).
It costs far more. A walk takes 6.7 tool calls, 23–111 seconds and $0.12–$0.28 per question, against one sub-second embedding call. That is 20–100× the cost. For 320 of the 700 questions, retrieval already found the answer first time.
The map is a single point of failure. The one miss in 700 came from a wrong sentence in the map, not a wrong document, and the agent followed it. An agent that trusts the map inherits the map's errors, and nothing flags them.
Flat or folded (eval/depth/, 2026-10-09/10). The same 73 questions on two trees: area tables of 15–23 rows behind holders, against the same documents with every holder removed (61–244 rows per area). With a Sonnet-class walker both trees scored 65/73, with Opus 67/73 (the same questions missed on both); the flat tree cost 2.3–2.4× the input. With a Haiku-class walker the flat tree scored higher — 66 vs 61 — because every holder is one more decision a weak model can get wrong. Folding buys tokens, not accuracy, and costs a weak model accuracy.
Behaviour (eval/philosophy/, 2026-10-10). Twelve questions through the real MCP door, Sonnet and Haiku: every walk started at hop 0 with a reason on every step; every question with no answer in the documents was answered "not here", with no invented rule; deliberately false lines were answered around by reading the document. But the agents did not report the false lines until one instruction asked them to (1/4 → 4/4), nor a false hop-0 sentence until the server pointed out that the walk had switched areas (0/2 → 2/2). The census-style miss was reproduced on purpose: a false hop-0 sentence into an area whose plausible page does not point onward trapped 3 of 4 walks; one more instruction brought that to 2 of 4, and the remaining case — a partial table that looks complete — is not fixed. Twelve questions, one run each — read it as "did not fail", not as a rate.
Everything is in the repository: the corpus generator (bench/), the gold sets (eval/gold/), and
every run including the failures (eval/runs/). Re-running needs an API key —
bench/README.md.
Your documents do not resemble each other. If retrieval already finds the right page, a walk only adds cost and latency.
The cost of each question matters more than its accuracy. A walk takes several model calls and tens of seconds.
Nobody will own the map. A table that no one maintains goes stale. A stale table is worse than none, because the agent follows it confidently.
You need it hosted, multi-tenant or hardened today. See below.
Evidence | one synthetic corpus, one domain, model-written or templated questions; no real organisation's data |
Scale | agent routing measured at 5 and 30 areas (30 with thin distractor areas) on about 1,100 documents; the service timed at 10,000 documents (reads 0.1–0.2 s, a write 2 s). Agents on a map that large are untested |
Models | Sonnet- and Opus-class on the stress test; Haiku-class only on the depth and behaviour runs, where folded tables cost it accuracy |
Staleness | no mechanism decides which version is current. That is said by a person, in a line. Ages from git help someone ask; they do not decide (docs/AGE.md) |
Maintenance | change sets keep the lines over a change in step, but they are days old and unproven in real use. The map has no editor for a multi-step change |
Absence | "not here" is only as good as hop 0's sentences. A missing sentence and a missing document look the same to the agent |
Operations | one maintainer; single node; one git repository; basic auth; the default install listens on the network (docs/AUTH.md) |
Overlays | the working set for multi-area questions is off by default (docs/OVERLAY.md) |
A research prototype with one maintainer and no outside team known to be running it.
measured | not measured | next |
the collapse stress test above | any real organisation's documents | a corpus someone else wrote, with questions someone else wrote |
cost per walk | how much it costs to maintain the map over months | a maintenance log from a real install |
flat vs folded, both a strong and a weak walker | scale: dozens of areas, 10k+ documents | a larger synthetic map |
invariants: 12, each with a check (docs/INVARIANTS.md) | a misroute into an area that holds a plausible wrong answer | a map whose facts each live once |
Worth trying if your team keeps answering from the wrong revision, or retrieval keeps returning the neighbouring row. Reports of where it fails are the most useful thing you can send: GitHub Issues.
Docker with docker compose. The containers include Python and git.
git clone https://github.com/CSP911/routemind.git routemind && cd routemind
./install.sh --port 9000→ http://localhost:9000. On a first install it asks whether to start from the example back office
(examples/back-office: five areas, 74 documents) — say yes unless you have data of your
own ready. You can run it again safely: an existing .env is kept. An optional LLM adds a ✨ Suggest
button that drafts a line for you to edit; nothing else depends on it.
docs/INSTALL.md · already running one: docs/UPGRADE.md.
An agent. Claude Code finds the server in .mcp.json, which reads the port from .env:
claude # in the same directory; approve the "knowledge" server once, then /mcp lists four toolsFor any other MCP client, run the same server — it finds the install the same way, or take --api:
python3 mcp/knowledge_mcp.py # or: --api http://localhost:9000/api/knowledgeThe area list reaches the agent in the server's instructions, so you do not have to name RouteMind in the question. docs/AGENTS.md.
the whole structure, in a browser | |
the twelve rules that are true on every path, and the check behind each | |
change sets: several decisions, one commit, the lines above them decided | |
watching and replaying a walk | |
the two ages on each routing row | |
reading another RouteMind for one session | |
your map as a git repository, and editing it by hand | |
five rules for sentences and pages an agent stays right on, each from a measurement | |
agents, the optional LLM, who may write | |
checks, platforms, languages | |
known gaps | |
the study, pre-registered before it ran |
Layout: ontology/ the API · web/ the map and proxy · mcp/ the agent's door · static/ the
screen · check/ every check · data/repo your map, the only thing to back up.
qct8377@gmail.com · linkedin.com/in/cspark911 · GitHub Issues
MIT — see LICENSE.
Read another RouteMind for the length of this connection. Give it the address and token somebody handed you, and their shared areas appear alongside this backbone's — you walk them the same way, with the addresses their tables print.
It is read-only, and it holds only what its owner chose to let cross. The line on each row is the one that backbone routes on itself — one sentence per area, written by its owner about their own map rather than about yours.
Nothing is written on either side and nothing outlives this connection. This is not the same as linking two backbones, which is a standing arrangement somebody configures and commits; this is you borrowing a reader's view of theirs.
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | ||
| url | No | open: the remote RouteMind's address, e.g. https://kb.example.com | |
| name | No | open: a short name to address it by (ascii kebab-case; defaults to the host). close: which one to close | |
| token | No | open: the read token its owner gave you |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it declares read-only operation, states that only owner-shared areas are exposed, and emphasizes that nothing is written and nothing outlives the connection (session-scoped lifetime). It stops short of disclosing error behavior, token failure handling, or rate limits, which keeps it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The key action is front-loaded, which is good, but substantial space is spent on atmospheric phrasing ('the line on each row', 'walk them the same way') that adds tone rather than usable instruction. The read-only and ephemerality points earn their place; the metaphorical padding does not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter tool with no annotations and no output schema, the description covers the essentials an agent needs: it is read-only, session-scoped, exposes only shared areas, and describes what appears on each row. It lacks any note on failure modes or the difference between the list and open operations, but overall it is sufficient to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents url, name, and token. The description only loosely implies the open/list/close lifecycle in prose ('for the length of this connection') and adds no operation-specific syntax or defaults beyond what the schema states, so it lands at the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource ('Read another RouteMind for the length of this connection'), so the core action is discoverable. However, the purpose is buried under extended metaphor ('borrowing a reader's view', 'walk them the same way'), and it never distinguishes itself from the sibling tools knowledge_read or knowledge_table it explicitly alludes to.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives real usage context: supply the address and token someone handed you to view a remote backbone, and it contrasts this with 'linking two backbones' (a standing committed arrangement). That contrast is against a feature, not against the sibling tools, so an agent still has no explicit rule for choosing knowledge_circuit over knowledge_read or knowledge_table.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one document from Knowledge, by the address a table printed for it. Returns the document as written.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The address a table printed for this document. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Read' implies a non-mutating operation and 'as written' signals the content is returned unmodified, which is useful. However, nothing is said about missing/invalid path behavior, permissions, or size/rate constraints, leaving notable gaps for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler; the action and the key's origin are front-loaded. Nothing could be removed without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema and no annotations, the description covers what it does and roughly what comes back ('as written'), but the return shape and error behavior are underspecified. It is minimally sufficient rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'path' parameter is already documented, so baseline is 3. The description adds only provenance context ('the address a table printed'), essentially restating the schema's own wording without adding format, validation, or failure semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read one document from Knowledge') and clarifies the lookup key is an address a table printed. It distinguishes the operation from sibling tools implicitly by tying the key to knowledge_table output, though it never explicitly rules out knowledge_table or knowledge_circuit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: the agent must have a path already produced by a table, which suggests a read-after-list workflow, but there is no explicit when-to-use, when-not-to-use, or alternative named. Adequate but leaves the routing inference to the reader.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a routing table from Knowledge: a list of what is there and where to go next. Call it with no arguments to get the list of areas — that is where every search starts. Each row prints the exact address that fetches it; use those verbatim and never construct one.
(The area list could not be fetched: HTTP 404 from /v1/regions)
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | An address a table printed: /v1/regions (the areas), /v1/regions/<area>, /v1/nodes/<id> or /v1/services/<id>. Omit for the list of areas. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the no-arg behavior, that rows contain fetchable addresses, and the hard rule to use them verbatim rather than constructing paths. However, it says nothing about error handling for bad paths, and the appended '(The area list could not be fetched: HTTP 404 from /v1/regions)' is a leaked runtime failure rather than behavioral disclosure, which muddies rather than clarifies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core is front-loaded and efficient, but the trailing parenthetical HTTP 404 error is extraneous noise that does not belong in a tool definition and makes the description read as half-broken.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description does a reasonable job explaining the routing/address model and the entry-point workflow. It is nonetheless incomplete on failure behavior for invalid paths, and the embedded 404 leaves the agent unsure whether the tool currently works.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already enumerates the accepted path forms and states 'Omit for the list of areas'. The description reinforces the 'use addresses verbatim, never construct one' constraint, which is valuable, but adds no new syntax or format detail beyond the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (fetch a routing table from Knowledge) and explains what the payload is: a list of what is there and where to go next. It implicitly differentiates from knowledge_read/knowledge_circuit by framing itself as the routing/entry-point layer, though it never names the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call it with no arguments first and that 'that is where every search starts', which tells the agent when to reach for it. It stops short of naming knowledge_read/knowledge_circuit or stating when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0knowledge_circuitknowledge_readknowledge_tableScored across 3 tools
knowledge_table discovers areas and prints addresses, knowledge_read fetches a specific document, and knowledge_circuit federates to a peer's view. The three are mostly separable, though table and circuit both return browsable lists and could be momentarily confused by an agent unfamiliar with the peering concept.
All three share the 'knowledge_' prefix, giving a predictable namespace. However, the suffixes mix a noun (table), a noun-as-metaphor (circuit), and a verb (read), so the verb_noun pattern isn't strictly uniform.
Three tools is thin but defensible for a read-only routing/exploration server with a narrow purpose. Each tool maps to a distinct step (discover, fetch, federate), so nothing feels redundant, though it sits near the low end.
Read-only is intentional, so no write operations are expected. But the primary entry point is broken (HTTP 404 fetching the area list) and there is no search tool, leaving a real dead end for agents trying to orient themselves.
Host an agent's pages at clean, permanent URLs. Publish, organize, edit, search and re-find docs.
Read, edit and improve shared documents and knowledge with people and agents.
Private, self-describing memory for agents: one house per customer, on a machine of its own.
Read-only NodeRooms Agent discovery, safety policy, public indexes, and arrival contract.
