🐾 Booboo — the unified operational brain

Turn any AI system's data into one living, rooted 3D brain — structure + knowledge + memory + agents + automations fused into a single graph. Query it by REST or MCP, view it in your browser or as a desktop wallpaper, and boot your agents from it in one call.

See it before you install it → booboo.fractionalhq.uk · a live brain in your browser, no signup, nothing to clone.

Named after a dachshund who never forgets where the treats are buried. Fitting, because Booboo is about exactly that: memory and recall — seeing the whole system at once, fetching what's buried, never losing the thread.

Unretouched: booboo view --demo --nodes 50000 — 50k nodes, 4 layers, live in a browser tab, zero console errors. Try it yourself in one command.

Most tools show you one slice: a knowledge graph, an agent flow chart, a memory store, a trace viewer. Booboo fuses all of them into one graph rooted at a single point, so you can see — and query — how the whole system actually hangs together.

Status: alpha — eight packages published: @booboo-brain/spec (the contract), @booboo-brain/build (config-driven postgres/json adapters), @booboo-brain/serve (REST + MCP query layer), @booboo-brain/viewer (million-node 3D render), @booboo-brain/panel (the organigram), @booboo-brain/vault (wiki-linked markdown export), @booboo-brain/cli (the unified booboo command), and create-booboo (project scaffolder). Per-package semver — see each package.json. MIT.

The one idea

Booboo is a tiny JSON spec at the center, with adapters that feed it and consumers that render/serve/query it:

  your data ──▶  ADAPTERS  ──▶  GRAPH JSON ──▶  CONSUMERS
  (postgres,     (config-       (the spec,       (3D viewer ·
   json, neo4j,   driven,        ~1 KB            REST API ·
   mcp, …)        ~50 lines)     contract)        MCP server · wallpaper)

Emit the JSON → get the viewer, the API, and the MCP server for free. Weird data → a ~50-line adapter, not a fork. See SPEC.md.

Quickstart

One command. No database, no config, no signup. A synthetic brain, running on your machine:

npx @booboo-brain/cli view --demo --nodes 1000000

That's the headline flex: a million nodes at 60fps in a browser tab. Drop the count to --nodes 50000 on a modest laptop. See SCALE.md for how it holds up (one draw call over a single point cloud with a custom shader, plus tier-LOD on labels).

If it holds up on your machine, leave a star. There's no marketing behind this repo; stars are how the next builder finds it.

Then point it at your own stack:

# scaffold a project (json starter + postgres upgrade path)
npx create-booboo my-brain
cd my-brain
npm install
npm run build                    # booboo.config.yaml → brain.json (the snapshot)
npm run serve                    # REST API on http://localhost:8787
npm run mcp                      # MCP over stdio — point Claude / Cursor / Claude Code at it

Edit booboo.config.yaml to point at your own Postgres/Supabase (a commented example ships in the scaffold). Full reference: docs/CONFIG.md · stuck? docs/TROUBLESHOOTING.md.

Roadmap: a single all-in-one command bundling build + REST + MCP + the 3D viewer together, and an interactive scaffold wizard — tracked in LAUNCH_CHECKLIST.md.

What works today

booboo build --config booboo.config.yaml    # any postgres/json → one graph snapshot (privacy walls + parent spines)
booboo serve --snapshot my.booboo.json --port 8787   # REST: /graph /stats /search /nodes/:id /neighbors/:id /path/:a/:b
booboo mcp   --snapshot my.booboo.json --org org.booboo.json  # MCP over stdio (+ booboo_boot: agents boot FROM the org)
booboo view  --snapshot my.booboo.json               # 3D viewer in your browser — no monorepo, no build step
booboo panel --org org.booboo.json --snapshot my.booboo.json  # THE ORGANIGRAM — see below
booboo vault --snapshot my.booboo.json --org org.booboo.json --out vault  # the brain as a markdown vault — see below

booboo view serves the @booboo-brain/viewer 3D renderer as a standalone app — any snapshot (or ?n=1000000 synthetic) in your browser, no monorepo. The build engine was proven on a real 4,469-node production brain assembled straight from Supabase by config alone — privacy-walled, validated, served. See each package's README for the details.

Connect it to Claude / Cursor (MCP)

booboo mcp speaks MCP over stdio. Point any MCP client at it — no server to host, it runs on demand:

// Claude Desktop: claude_desktop_config.json · Cursor: .cursor/mcp.json · Claude Code: .mcp.json
{
  "mcpServers": {
    "booboo": {
      "command": "npx",
      "args": ["-y", "@booboo-brain/cli", "mcp",
               "--snapshot", "my.booboo.json", "--org", "org.booboo.json"]
    }
  }
}

Your agent can now query the whole system — search, neighbors, path, stats — booboo_boot('<agent-id>') returns an agent's rules, memory reach, and reports so it boots from the org, and booboo_remember / booboo_report let it write back durable memories and reports that persist across rebuilds (the live memory system). Point --snapshot/--org at absolute paths if the client's working directory differs.

Tools

booboo_remember / booboo_report are on by default — the live half of the memory system. Pass --no-write (or BOOBOO_READONLY=1) for a read-only server (public/locked-down deployments); it still reads the journal but refuses writes.

The Organigram — run your agents like a company

booboo panel opens your agent fleet as a real org chart — and the chart is not a diagram, it's the authority. Every agent is a card: its rules, skills, memory-bucket access, and latest reports. Drag an agent under a new parent, hit apply, and the org file changes — versioned in git, validated before every write (a cycle can never land). Agents that boot with booboo_boot obey the new shape on their next session. Reorganize your company at breakfast; the whole fleet knows by the first coffee.

the portfolio timeline	memory, bucket by bucket

Five tabs over one org file + one snapshot: organigram (drag-drop hierarchy) · buckets (who remembers what) · reports (what the fleet closed, newest first) · rules (who declares, who inherits) · graph (the 3D brain, embedded). Rules inherit top-down — declare once at a branch, everyone beneath is bound; every dossier shows the inherited stack in boot order.

Reports and buckets fill two ways: live, when an agent calls booboo_remember / booboo_report (durable journal writes, no rebuild), or in bulk from your own tables via config — see docs/CONFIG.md § Wiring fleet reports & memory.

The vault — your brain as plain markdown (Obsidian-ready)