The web UI inside the binary

Running it #

$ ns-brain ui
yours brain  http://127.0.0.1:7788/?k=<one-time key>
brain   LOCAL FILE /home/you/projects/yours/brain/brain.db
...
ctrl-c to stop

$ ns-brain ui --port 8100 --no-open
$ ns-brain ui --host 127.0.0.1

It listens only on your own machine (loopback), serves its files from inside the binary and exits when you stop it. Nothing keeps running in the background and starting it writes nothing to disk.

What it shows #

View	What it answers
Brief	Exactly what a session gets when it opens, shown as a page instead of terminal text.
Memories	Search and browse with the same ranking as the CLI. Filter by scope, type, tier and project.
Tree	Every scope as a tree. The quickest way to spot a scope somebody created with a typo.
Activity	The events log: what happened, by kind and by date.
Measures	Numbers tracked over time with their expected ranges. Much easier to read as a chart than as a column.
Leads	The sales pipeline, for the projects that use it.
Map and stats	Scopes, kinds, pinned memories, counts and which database file you are really using.

Why it has no SQL #

An older viewer had its own copy of the search code in a Node server.js. Three fixes made in the CLI (to ranking, to the project filter and to snoozing) never reached it. The page kept looking fine while showing the wrong results.

So the rule is: if the UI needs data the CLI can't give it, we add it to the CLI. Never to the viewer. We also moved the viewer into the binary. The Node version was the only part of the product you had to install separately and in practice nothing ever installed it.

The one thing it writes #

The UI does write, but only one thing: forget, by running ns-brain forget. So when it refuses to delete a pinned memory, a guardrail or a memory that replaced others, you see the CLI's own message, with the same wording and the same rules.

Everything else only reads.

How the page is protected #

A page on your own machine is still a web page. Any other browser tab can send requests to localhost. So every request that touches the brain, reads included, has to prove it came from this page:

A key made fresh each time the UI starts. The link ns-brain ui prints opens the page once in one browser and leaves the key in that browser's cookie. Every request carries it and it is checked in constant time.
An Origin check on every request, so another tab can't use it.
A Content-Security-Policy, nosniff and a host allowlist that takes only the loopback names.
Bodies capped at 64KB.
innerHTML is only ever used to clear an element. Content goes in through textContent, so text in a memory can never turn into HTML.