@hippo-digital/hippocampus

A design-knowledge base for NHS Prototype Kit projects. It holds the research a service is built on - rounds, participants, insights, design actions - alongside the user needs, scenarios, journeys and screens those findings justify, and renders the whole thing as a viewer inside your prototype.

The point is that a screen can be traced back to the reason it exists: from a route, to the needs it meets, to the insights that evidenced them, to the people who said so, and forward again to the design actions still open against it.

Install

npm install @hippo-digital/hippocampus

nhsuk-prototype-kit and nhsuk-frontend are peer dependencies - your project already has them, and two copies of the frontend sass in one build is a lost afternoon.

Set it up

npx hippocampus init

writes hippocampus.config.json and an empty knowledge base, then makes the two host edits for you. Both live between markers and are backed up first; a block you have since edited is reported and left alone rather than overwritten. --dry-run shows the diff and writes nothing, --no-wire writes the data and prints the edits for you to paste, and npx hippocampus eject takes the edits back out and leaves every byte of your knowledge base where it is.

It also adds .gitignore lines that keep hippocampus/inbox and hippocampus/imports out of git: research files and import drafts hold participants' words. A folder that .gitignore already names, or whose files are already committed, is left alone, with a message saying why. doctor warns when research files or drafts are committed. The guide's Data and governance page has the detail.

npx hippocampus doctor        # what is wired, what is not, and where it looked
npx hippocampus skills install  # copy the skills, agents and instructions in

skills install writes three directories: .github/skills (the skill catalog), .github/agents (role wrappers naming who runs each skill) and .github/instructions. They install together because every agent's preferred skills point into .github/skills, and every skill names its owners by agent, so either half on its own is a set of dangling references. --no-agents installs the skills alone for a host whose agent runtime is not Copilot.

It records a hash of what it wrote, so a later upgrade can tell a stale copy from one your team has edited - the edited one is left alone and named.

Working on the viewer against a real project

Designing the viewer needs real data in it - a page that looks fine against three fictional records falls over against a hundred and thirty. Symlink this package into the project you want to preview against:

cd <your-project>
rm -rf node_modules/@hippo-digital/hippocampus
ln -s ../../../nhs-prototype-hippocampus/packages/hippocampus \
  node_modules/@hippo-digital/hippocampus
npm start

That relative path assumes the two repositories are siblings. Use a relative link rather than an absolute one: an absolute path is correct on exactly the machine it was typed on, and a link made anywhere else - by a colleague, in a container, or by a tool working through a mount - dangles with Cannot find module '@hippo-digital/hippocampus'.

What reloads, and what does not:

| You change | Effect | | --- | --- | | views/** (.html, .njk) | Live. Refresh the page. | | hippocampus/source/*.json in the project | Live. Refresh the page. | | lib/**, scripts/** (JavaScript) | Restart npm start. |

The symlink leaves the project's package.json and lockfile untouched, so there is nothing to commit by accident, and npm install removes it - which is how you go back to the released version.

doctor says when a project is linked rather than installed. Worth reading before you conclude a page works: while linked, the viewer is running code nobody else has.

Wiring it by hand

Two lines in app/routes.js:

const { createHippocampus } = require('@hippo-digital/hippocampus')

const hippocampus = createHippocampus()
router.use(hippocampus.router)

and one entry in app.js:

const hippocampus = require('@hippo-digital/hippocampus').createHippocampus()

viewsPath: ['app/views/', hippocampus.viewsPath]

That is all of it. The viewer serves its own stylesheet, client JS and layout from its router, so there is no sass entry point to add, no stylesheet link to paste into your template, and nothing to re-copy when you upgrade.

Point it at a project

Add hippocampus.config.json at the root of your prototype:

{
  "configVersion": 1,
  "dataDir": "hippocampus",
  "artefactsDir": "artefacts"
}

and a hippocampus/source/project.json. Everything else is optional - a knowledge base with nothing in it boots, renders every route, and tells you what to add next.

Commands resolve the project the same way every time:

--root <dir>  >  HIPPOCAMPUS_ROOT  >  nearest hippocampus.config.json
              >  nearest package.json outside node_modules  >  cwd

A root that resolves inside node_modules is an error, not a guess - it would otherwise produce an empty knowledge base and no explanation.

Commands

npx hippocampus doctor              # wiring, integrity and routes - start here
npx hippocampus validate            # parse, check integrity, report coverage gaps
npx hippocampus validate --strict   # and fail on warnings
npx hippocampus known "topic"       # what is already known, what was built on it, what nobody asked
npx hippocampus consequences <id>  # run a new journey against the users we already know
npx hippocampus mcp                 # serve the knowledge base to agents over MCP
npx hippocampus research triage     # rank a research folder before importing anything
npx hippocampus research sync       # inbox artefacts to reviewable drafts
npx hippocampus source index        # record what was ingested, before the copies go
npx hippocampus migrate             # write a schema upgrade back to disk
npx hippocampus --help

validate reports in three tiers. Errors are broken references. Warnings are gaps worth filling - and on a new project, a list of what to do next. Info is coverage: nothing is wrong, something is thin.

hippocampus: knowledge data is valid
  info    51 of 108 insights link to no user need
  info    108 of 132 needs (82%) sit at priority "medium"

Serving it to agents over MCP

npx hippocampus mcp            # HTTP on http://127.0.0.1:3100/mcp
npx hippocampus mcp --stdio    # for a client that starts the server itself

Read-only, localhost only. The tools are design_brain_brief (start here: one brief for a role, scenario, journey or build spec, with record ids), design_brain_known, design_brain_consequences, design_brain_overview, design_brain_read and design_brain_ask. Only ask uses a model; it needs GEMINI_API_KEY, DESIGN_BRAIN_MODEL and npm install @google/genai, and reports that it is off otherwise.

To add it to Claude Code:

claude mcp add --transport http design_brain http://127.0.0.1:3100/mcp

DESIGN_BRAIN_MCP_PORT changes the port. DESIGN_BRAIN_MCP_LOG=<file> logs each call. design_brain_read never serves .env, .git, .npmrc or node_modules.

Documentation

The guides are served by the viewer at {basePath}/docs, so they always describe the version you have installed. Nothing is copied into your repo - a copied guide goes stale within a release, and the stale one is the copy people read, because it is the one sitting in their editor.

The list is grouped into sections - Start here, Task recipes, Data and governance, Reference, For contributors - by front matter at the top of each guide:

---
section: recipes     # start, recipes, governance, reference or contributors
order: 20            # within the section; leave gaps of 10
audience: [viewer, cli]
summary: One sentence for the card on the list.
---

All of it is optional. A guide without it is listed in Reference, titled by its first heading. Diagrams go in docs/images (SVG or PNG, lower-case hyphenated names) and are linked relatively, ![...](images/name.svg), so the same markdown works in the viewer and on GitHub; their Mermaid sources are in docs/diagrams.

skills install is the deliberate exception: an agent reads skills, agent definitions and instructions as repo files, so those are copied, with hashes so an upgrade can tell a stale copy from one your team has edited. Everything they reference that is not a repo file is read from the installed package, so those references cannot go stale either.

Keeping research material out of the repo

If your shared drive is the system of record - download into the inbox, extract the knowledge, delete the copy - then run:

npx hippocampus source index

first. It writes hippocampus/manifests/source-index.json and a readable .md beside it: every artefact's exact filename, size, sha256, which round it belongs to, where it was recorded as coming from, and which knowledge records cite it. The hash is the part that cannot be recovered later - it is what proves a file you find on the drive in a year is the one the findings were drawn from, rather than an edited descendant.

It also names the artefacts whose origin was never written down, which is the list worth clearing before anything is deleted.

init --private-artefacts gitignores the copies once the index exists.

Data contract

Within a schemaVersion, changes are additive and unknown fields survive a read and a write - so data written by a newer version of this package still loads in an older one. hippocampus/source/_meta.json records the version; absent means version 1. Data newer than the code is refused rather than read partially, because reading forward is how a knowledge base gets destroyed by the next write.