Technical specs · Nexus Brain
One shared memory for every AI assistant
How the Nexus Brain is built: the stack, how notes are written, stored and found, how each layer is secured, and where AI does the work (and where it deliberately doesn't). Written for engineers and technical evaluators.
01 · ArchitectureHow it fits together
Assistants reach the brain through one HTTPS address that speaks the Model Context Protocol (MCP). They can search and read everything, but can only add short notes to an inbox. Overnight, a screened and fenced-in AI curator folds those notes into each project's status page, and a deterministic commit step writes the result to git. Git is the source of truth; the database is a search index built from it.
Swipe sideways to see the whole diagram →
02 · StackThe full stack
Everything below runs on one Linux server, except the Portal (Netlify and Firebase) and the model providers. Open-source parts are used as published; the Nexus-specific code is the screening, routing, curation and commit steps around them.
| Layer | Technology | How it's set up |
|---|---|---|
| Storage | ||
| Source of truth | Git + Markdown | Pages are Markdown files with properties at the top, in a private repo with a GitHub copy. The database can be rebuilt from it in minutes. |
| Index | PostgreSQL + pgvector | Vector search (pgvector), fuzzy text search (pg_trgm). Its own database role with no admin rights; it accepts local connections only. |
| Two sources | default + inbox | The repo index is read-only to assistants. The inbox holds what assistants add, in the database only, until it's exported to git. |
| Engine and access | ||
| Brain engine | GBrain (open source) | Runs on Bun. Database-only content mode: no assistant write ever touches a file on disk. |
| Protocol | MCP over HTTP | 15 operations per assistant: search, query, read, links, backlinks, tags, timelines, context pack, add a note, tag, timeline entry. No delete. |
| Front door | Caddy | Automatic TLS; only sign-in, MCP, health and consent paths answer. The firewall opens web ports only. |
| Sign-in | OAuth 2.1 + PKCE | One client per assistant, with dynamic registration; no token exists until the owner approves. 30-day access tokens with refresh; server-side agents use client credentials and rotate daily. |
| Permission guard | DB trigger + 5-min enforcer | The grant is applied at registration, and re-applied every 5 minutes if anything drifts. |
| Service isolation | systemd hardening | Its own no-shell system user; read-only filesystem, no capabilities, syscall filter, memory cap. It can reach only the database and the embeddings provider. |
| AI | ||
| Embeddings | text-embedding-3-small | 1,536 dimensions, through OpenRouter. New notes are searchable by meaning within about ten seconds. |
| Curator | OpenClaw isolated agent turn | A low-cost open model on OpenRouter (MiniMax), with three open-model fallbacks. Read and write tools only. |
| Guard plugin | Nexus guardrails | Blocks shell and patch tools; limits writes to project STATUS pages and its own ledger; refuses anything it can't check. |
| Operations and views | ||
| Scheduler | systemd timers | Every job is a timer on the host, with a ledger of what runs when. |
| Backups | pg_dump + restic | Nightly dump (14 kept), encrypted offsite copy, monthly restore drill. |
| Admin dashboard | SvelteKit on Netlify + Firestore | The Nexus Portal reads a filtered mirror of the brain refreshed every 10 minutes; it never reads brain files or the database directly. |
| Reading by hand | Obsidian | A read-only copy pulled from GitHub, on the owner's laptop. |
03 · DataHow a note travels
The life of one note, from an assistant's write to a curated status page every other assistant reads the next morning.
- An assistant adds a noteany time
It calls
put_pageunderinbox/. The server records who wrote it from the sign-in, not from anything in the note. The write gate flags text that reads like instructions. - It becomes searchable AI~10 s
An embedding is made in the background, so every assistant can find it by meaning within seconds.
- Screen and export4× a day
Credential-shaped and flagged notes are quarantined. The rest are copied into git marked untrusted, and routed to a project by plain code: a people list first, then project names and aliases.
- The curator folds it in AI3:40–6:00 a.m.
In batches of 20, the curator rewrites each affected project's STATUS page (the "where was I" page) and logs every decision. It can still quarantine a note.
- The commit step checks the workeach batch
Only STATUS edits for known projects survive; anything else is restored and a copy kept. Notes are tagged curated or quarantined, meeting notes are filed onto person pages, and the result is committed and pushed.
- Re-indexeach batch
The repo is synced back into the index and links are extracted (no model). By morning, every assistant reads the updated page.
Where each kind of data lives
Git repo
Project STATUS pages, reference pages, people, decisions and every exported inbox note, as Markdown with full history.
Postgres
Chunks, embeddings, links, tags and timelines for the repo, plus inbox notes that haven't been exported yet. Disposable: rebuilt from git.
Firestore (Portal)
A small, filtered summary for the dashboard. Secret patterns are applied before anything leaves the server; held-back notes show no text.
Backups
Nightly database dumps kept two weeks, encrypted offsite copies, and a restore drill every month.
How assistants find things
Hybrid query
Meaning (vector) plus keyword in one call. No AI query rewriting, so results are predictable and free.
Keyword search
Exact names, codes and phrases, paged, with OR across several names in one call.
Context pack
One call at the start of a session returns the people, projects and recent notes in play.
Graph reads
Links, backlinks, tags and dated timelines, for example every meeting with one person.
Retrieved text is treated as data, never as instructions. Agent-written notes never override records, and each page carries a trust tier.
04 · SecurityDefense in depth
The brain assumes any note could be wrong or hostile: a pasted email with planted instructions, a leaked key, an assistant that misbehaves. Each layer below works on its own, so one failure doesn't open the rest.
NetworkOutermost
Only HTTPS answers. Sign-in, MCP, health and the consent page are the only public paths; everything else, including the admin side, returns 404. The database takes local connections only. Requests are rate-limited per address and per token, with a size cap.
IdentityWho is calling
OAuth 2.1 with PKCE. Every assistant is its own client and gets no token until the owner approves it on a consent page, so every note is signed and one assistant can be cut off without touching the others.
PermissionsWhat it may do
The same narrow grant for every client: read everything, write only new notes under inbox/, 15 operations, no delete, a zero budget for paid features. Re-applied every 5 minutes.
Content screeningWhat gets in
Four separate checks for secrets and planted instructions: the write gate, the sync screen, the curator itself, and the Portal mirror. A credential-shaped note can never be released; an instruction-flagged one is released only by the owner, tied to its exact text.
Curator fenceWhat AI can touch
The curator runs with read and write tools only, behind a guard that limits it to project STATUS pages. Host steps run only committed code, so a script the curator rewrote never runs. The commit step then restores any edit outside the allowlist.
RecoveryInnermost
Git history for every page, nightly dumps, encrypted offsite copies and monthly restore drills. Every request is logged with the calling client and redacted parameters.
The Portal follows the same rule: ask, don't execute
The browser never talks to the database: Firestore rules deny everything, and the Portal's server alone holds the keys. Admin actions don't run anything. Each becomes an allowlisted request that a worker on the brain server re-checks against fresh data before acting, pinned to the exact version the owner saw.
05 · AIWhere AI does the work
Models do the parts that need judgment or language: understanding notes, writing summaries, matching by meaning. Plain code does everything that has to be exactly right: routing, screening, permissions and checking what the AI wrote.
| Job | What the model does | Model and route | Guard rail |
|---|---|---|---|
| Search by meaning | Turns each page and note into an embedding | text-embedding-3-small via OpenRouter | The only AI the brain service itself can call |
| Nightly curator | Folds inbox notes into project STATUS pages | Low-cost open model (MiniMax) via OpenRouter, three fallbacks | Tool allowlist, path guard, commit-step allowlist |
| Memory keeper | Proposes long-term facts for the agent's memory | Same model as the curator | The model proposes; plain code checks and applies, with nightly and size caps |
| Session notes | Each assistant writes short notes on the day's work | The assistant's own model (Claude, Codex and so on) | Inbox-only write grant |
| Pasted meetings | Pulls title, people, decisions and action items from a pasted transcript | Claude Haiku via OpenRouter | Owner reviews in the Portal |
| Saved links | Summarizes and files a link into the knowledge base | Small model via OpenRouter, with a non-AI fallback | Public pages only; daily limit per assistant |
Deterministic by design
- Routing notes to projects
- Secret and injection screening
- Permissions and the commit check
- Link extraction and meeting filing
- Search queries (no AI rewriting)
- Backups and health checks
Paid features not used
The engine's automatic fact extraction, AI query expansion, synthesis and server-side fetching are off for every assistant. That keeps costs near zero and stops a note from triggering paid work.
Model routing: OpenRouter and TrustedRouter
OpenRouter
One API in front of many model vendors. The brain's embeddings and background jobs use it, which keeps them model-agnostic: a model can be swapped or given fallbacks with a config change. Open models keep the nightly jobs to cents.
TrustedRouter
A routing service built around privacy: you choose the model, the provider and a minimum privacy level together, with providers that can sign business associate agreements. Client installs that handle sensitive data can route through it instead; the Soma platform already does.
The agent's own models
Nexus's day-to-day reasoning uses subscription models first (Codex, then Claude) and falls back to paid OpenRouter models. The curator is the deliberate exception: open models only, because its tool limits are enforced only in that runtime.
06 · OperationsWhat runs when
Times are US Eastern. Every job is a systemd timer on the host.
All day
- Every 2 minPortal workerRuns approved Portal actions and saved-link and new-person requests.
- Every 5 minPermission guardRe-applies each assistant's grant if anything drifted.
- Every 10 minHealth probe + mirrorChecks the brain from inside and from the internet; refreshes the dashboard when something changed.
- 9:15, 1:15, 5:15, 9:15Brain syncRe-indexes the repo, screens new notes and copies them into git.
- 10:40, 10:50 a.m.Login checksRotates the server-side agents' brain tokens before they expire.
Overnight
- About midnightDatabase dump + offsiteFull dump (14 kept), then an encrypted offsite copy.
- 2:30 a.m.Claude Code notesClaude Code writes notes for the day's sessions.
- 3:40 a.m.Nightly fold-inScreen, curator and commit step in batches of 20 until the inbox is empty, done by 6 at the latest.
- 6:45 a.m.Memory keeperPromotes learned facts into the agent's long-term memory; tidies up on Sundays.
Weekly and monthly
- SaturdayBrain auditChecks structure, size and schedules.
- 1st of monthRestore checkRestores the newest offsite dump to prove it can be read.
- 1st of monthTranscript archiveMoves 90-day-old conversation transcripts to long-term storage.
Plugging the brain into an assistant
The brain is one half of a Nexus install; the other is the agent. The install schematic shows both options: a frontier agent (Claude, ChatGPT, Grok) that connects over MCP, or a custom agent on your own server, with OpenClaw as the example, where you own the data and choose the models.
07 · ContextCompared with typical second-brain setups
| Nexus Brain | Notion | Obsidian | Hosted memory apps | |
|---|---|---|---|---|
| Every assistant shares it | One MCP link | Connector, works as you | Local connector, laptop on | Usually |
| Each assistant's writes signed | Own sign-in each | Writes show as you | Plain file edits | Varies |
| Add but never overwrite | Inbox only, no deletes | Edits any shared page | Edits any file | Varies |
| Secrets and planted text held back | Four checks | Not built in | Not built in | Varies |
| Search by meaning | Built in | On the AI plan | Plugin | Built in |
| Plain files you own | Markdown in git | Export only | Markdown | Their database |
| Running cost | Cents a night | Per seat, plus AI | Free (Sync paid) | Subscription |
| Upkeep | Self-run | None | Low | None |
Strong Partial Weak. "Hosted memory apps" means tools such as Mem0, Supermemory and MemoryPlugin, compared in October 2026.
The trade-offs
- It is self-run: upgrades, fixes and the occasional upstream bug land on its owner, not a vendor.
- One server: if it is down, assistants can't reach the brain until it's back. Backups keep the data safe.
- It is built for assistants first. People read it through the Portal dashboard and a read-only Obsidian copy.
Interested in collaboration or a custom installation?
I design and build shared brains and the assistants around them, for teams and for individuals. Tell me what you have in mind and I'll reply by email.