From Search to Navigation: Turning 10,005 Knowledge Entries into a Knowledge Atlas

Today I moved my knowledge base from being searchable to being understandable.

Knowledge MCP could already answer questions with full-text and vector search. But after the collection grew to 18 namespaces, 941 source files, and 10,005 entries, a different problem emerged: search could return relevant passages without showing me the shape of the system they came from.

Which namespaces dominate the collection? Which entries were deliberately curated, and which were sections synchronized from research documents? Where does a result sit inside its source, and what comes before or after it? Another search box would not answer those questions.

So I built Knowledge Atlas, a fully read-only navigation interface available only on my home LAN.

Restore the real structure before drawing an impressive graph

The tempting first version would treat every entry as a node, connect nearby embeddings, and render a knowledge graph or UMAP constellation. It would look futuristic while quietly turning mathematical proximity into an implied relationship. Without a stable relation schema, a producer, and a real consumer, many of those edges would be decoration.

I started with structure that already existed and could be proven directly:

namespace
├─ curated knowledge
└─ synchronized sources
   └─ file
      └─ section
         └─ entry detail + provenance

The production snapshot contains 358 curated entries and 9,647 file-synchronized entries. Atlas does not pretend they are the same kind of artifact. It also refuses to turn UUIDs or file modification times into a fictional history of how knowledge evolved. Every level presents only the provenance, order, and status supported by the underlying indexes.

The overview includes a treemap sized by real namespace volume, but the visualization is not the only way in. A sortable, keyboard-accessible tree table provides equivalent navigation, and the mobile layout favors tables and a single-column flow. A visualization without a textual equivalent is just an attractive barrier.

The browser sees a snapshot, not the database

Atlas does not connect the browser directly to the Knowledge backend, and it never ships MCP Ed25519 private keys to the frontend. It extends an existing LAN-only status service. On the server, canonical SQLite indexes are opened with URI mode=ro plus PRAGMA query_only=ON.

The data is assembled into an in-memory snapshot and exposed through fixed metadata and lazy-entry routes. Production metadata is about 12.15 MB raw and 2.21 MB after gzip. Expanding all entry bodies would total about 22.58 MB, so the browser fetches a body only when someone opens that entry. Opaque lookup keys replace filesystem paths; unknown keys and traversal-shaped requests return 404.

The failure behavior matters as much as the happy path. If a refresh fails, Atlas does not replace the page with an empty result and call it current. It keeps the last successful snapshot and explicitly marks the view stale or errored. Old data may remain visible for a while, but it cannot impersonate fresh data.

The review basket organizes evidence without modifying knowledge

Atlas includes a review basket for collecting suspicious or follow-up entries in browser localStorage, then exporting a JSON or Markdown manifest.

There is deliberately no edit, delete, or apply button, and no write endpoint. The export is review evidence only; any later change must still pass through the existing manifest, backup, and human-review workflow. That boundary prevents an exploration tool from gradually becoming a second, uncontrolled knowledge administration surface simply because direct editing would be convenient.

“LAN-only” is a three-layer boundary, not a label

Atlas runs on an existing internal service port with no new ngrok tunnel. The firewall admits only the home LAN, the application enforces its own source allowlist, and the frontend adds CSP, no-store, nosniff, and frame denial.

The public MCP backend was neither restarted nor rerouted during this release. Atlas reads the same canonical indexes, but browsers never touch the authentication material used by the public-facing service. Sharing a data source does not require sharing an attack surface.

Deployment exposed another false green light

During deployment, I ended the Windows scheduled task for the status service. The operation reported success, yet the old child process was still holding the listening port.

From the control plane, the step looked complete. From the listener that actually served traffic, nothing had stopped. I resolved the PID from the port, verified its full command line, terminated only the confirmed status-service process, and proved the port had disappeared before starting the new version.

It reinforced a lesson that keeps recurring in infrastructure work: control-plane success is not execution-plane success. Validation has to observe the layer doing the actual work.

What I measured—and what I did not

The production snapshot builds in 0.6716 seconds. Across 20 loopback measurements on the production host, the gzip metadata route reached a p95 of 52.90 ms and the lazy-entry route 22.09 ms, both below the 200 ms gate. The service process used about 44.9 MB of working set and 106.5 MB of private memory.

Codex completed a full regression run with 98 tests passing. Claude independently ran the release gate with a different runner and reported 109 passed tests plus 52 subtests, zero failures, and an APPROVE verdict. The counts differ because the runners report subtests differently; preserving that distinction is more honest than forcing the numbers to match.

One validation item remains open. The in-app browser had no available instance during the release, so I did not capture runtime screenshots at the 375, 768, 1024, and 1440 breakpoints, nor did I obtain live keyboard and screen-reader browser evidence. Static UI checks, the HTTP contract, security headers, and responsive CSS passed, but I am not relabeling them as a browser pass. The missing runtime gate remains on the follow-up list.

The MVP changed the question I can ask

Knowledge Atlas did not suddenly make the knowledge base intelligent, and it does not claim to solve knowledge graphs. It does something more basic and more valuable: it lets me see what I actually have, where it came from, how it is situated, and which areas deserve the next round of review.

Search answers, “Which passage might be relevant?” Atlas answers, “How is this whole body of knowledge organized?”

Before adding a semantic map, cross-namespace edges, or query telemetry, I will watch whether this faithful map solves real tasks. The most dangerous failure in a knowledge tool is not an interface that looks insufficiently futuristic. It is an inference drawn as if it were a fact.