Team Brain

The Team Brain is one shared service per team. Every contributor’s workspace pushes tier-tagged content to it via the aios CLI; the brain turns that stream into a live dashboard of what the team is doing and deciding, and answers natural-language questions over the whole corpus with cited sources.

You run one instance per team. It’s a Next.js + Postgres app you can self-host anywhere.

---

What you see

The brain opens on Pulse — the team’s home surface. It leads with the brain’s synthesized understanding (the story of the team right now), not raw analytics.

📸 Screenshot to add — Pulse (hero)

A full-width capture of the Pulse home on the demo team, top-of-page: the “Pulse” title + ask bar, the Narrative arcs hero showing 3–4 populated storylines, and the Working on band beneath it with two or three people and their nested work. Light + dark. This is the flagship shot — the arcs must be populated (needs the graph + a demo arc set), not the empty state.

Pulse answers “what is my team’s brain telling me right now?” in about ten seconds:

• Narrative arcs (the hero) — the brain reads across everyone’s synced work and writes the current storylines: what’s moving, who’s driving it, what it connects to.
• Working on — per person, their most recent day of work, with the evidence (tasks, decisions, deliverables) nested underneath.
• Timeline — the same work broken down day by day (collapsed by default).
• Metrics — knowledge growth, brain usage, and the task funnel (open for admins).
• Evidence trail — the raw events and atomic facts the arcs are built from.

A slim ask bar sits at the top of Pulse and hands any question straight to Chat.

Chat

Chat is a grounded question-and-answer over the team’s shared memory — Slack, decisions, tasks, code, meeting transcripts, and the knowledge graph. Every answer cites its sources, so you can trace a claim back to the item it came from.

📸 Screenshot to add — Chat

The Chat surface mid-answer: a real question in the composer (e.g. “what decisions were made about auth last sprint?”) with the streamed answer and its inline source citations visible — the point of the shot is the citations, so frame to include at least one linked source chip. Light + dark.

Ask things like “what decisions were made about auth last sprint?” or “who owns onboarding, and what’s blocked?” — the answer streams in with the decisions, tasks, and documents it drew on linked inline.

Meetings

Meetings collects synced call transcripts and pulls out the action items and decisions from each one, so the follow-ups from a call become tracked work in the brain rather than dying in someone’s notes.

Codebases

Codebases shows the health, test coverage, and AI-transformation progress across the team’s repos, plus on-demand GitHub scans — the engineering surface of the same brain.

Settings & Admin

Everyone has an Account page to manage their own API keys. Admins additionally get an Admin area to invite members, issue and revoke keys, wire integrations, and pick the team’s active answering model (see Pluggable LLM).

---

How content gets in

Contributors never write to the brain by hand. Each workspace runs aios push, which sends its content to the narrow, audited ingest path:

Contributor workspaces (N×)
        │
        │  aios push  (POST /api/v1/items)
        ▼
  ┌──────────────┐
  │  Team Brain   │  Next.js 16 + Postgres
  │  ingest lib   │  narrow, audited write path
  │  query lib    │  FTS + structured context + LLM streaming
  │  dashboard    │  Pulse · Chat · Meetings · Codebases
  └──────────────┘

Every item carries an access tier, and the brain enforces tier filtering on every read — in app code, since there is no row-level security backstop.

Tier	Who can see it
team	All authenticated team members
external	All team members — it’s the outward-facing surface for clients/collaborators
admin	Rejected at the ingest API with 422 — never stored

Danger

Admin-tier content is rejected at the ingest API with a 422 status and is never written to the database. If a push returns 422, check the audience frontmatter of the file you’re pushing.

Auth model:

• People sign in with magic-link or OAuth — invite-only (an admin creates the member row first).
• Machines authenticate with per-member API keys (aios_<key_id>_<secret>, SHA-256 at rest, shown once at creation).

The brain is organized internally as eight organ systems — knowledge, ingestion, context, actions, identity, policy, audit, and feedback. See The 8 organ systems for the anatomy reference with shipped / partial / planned status.

---

Run your own

The brain is self-host portable — plain SQL migrations, Postgres-backed rate limiting, no host-only dependencies. Any Postgres works; deploy anywhere that runs Next.js.

The fastest path is the official one-click Railway template. It creates the Team Brain app and a managed Postgres service together, generates the application secrets, and asks only for your team and first-admin details. Railway shows the resources and estimated charges before you deploy. No GitHub fork or local Railway CLI is required. An active Railway plan in the workspace that will own the deployment is a prerequisite; an expired trial cannot create the project.

The first-admin password must be at least 10 characters. Railway’s form accepts a shorter one, and the deployment then fails while bootstrapping the admin, after Postgres has already been provisioned.

After the deployment is healthy, sign in with the admin credentials you supplied, create an API key under Account, then return to aios onboard and connect the workspace with the deployed Brain URL and that key.

For a local or non-Railway install, use the manual steps below.

1. Clone and install

   git clone https://github.com/aiosbrain/aios-team-brain
   cd aios-team-brain
   npm install

2. Start a Postgres database

   Any Postgres works. For a local throwaway DB, use the repo’s ephemeral test Postgres:

   npm run db:test:up   # ephemeral Postgres on port 5434

3. Configure environment

   cp .env.example .env.local

   DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5434/postgres
   PGSSL=require            # only for a managed Postgres with TLS
   AUTH_SECRET=<random string — signs the session cookie>
   APP_URL=http://localhost:3000
   ANTHROPIC_API_KEY=<your key>
   # email (magic-link login): either Resend…
   RESEND_API_KEY=<your key>
   RESEND_FROM="Team Brain <brain@example.com>"
   # …or SMTP
   # SMTP_URL=smtp://user:pass@host:587
   # SMTP_FROM="Team Brain <brain@example.com>"

4. Load the schema

   npm run pg:schema   # loads postgres/schema.sql into DATABASE_URL

5. Seed demo data

   npx tsx --conditions react-server scripts/seed-demo.ts

   The seed prints a demo API key once. Save it.

6. Run the dev server

   npm run dev
   # → http://localhost:3000

Deploying to production

For Railway, use the official Team Brain template; it provisions the app, Postgres, schema bootstrap, public URL, and required secrets as one reviewed bundle. For another host, provision a managed Postgres, point DATABASE_URL at it (PGSSL=require), and run npm run pg:schema to load the schema. Add the required env vars (AUTH_SECRET, APP_URL, email, ANTHROPIC_API_KEY) to your host, then deploy the aios-team-brain repo. Point each workspace’s aios.yaml at the production URL.

Pluggable LLM

Answering is provider-agnostic. Admins choose the team’s active answering model from the Admin area — Anthropic, OpenRouter, or any OpenAI-compatible backend — and it applies to the whole team’s chat and synthesis (arcs, meeting extraction, and so on) through one switch. No rebuild required.

To run fully on-machine (no API cost), point the default at a local endpoint:

.env.local

LLM_BASE_URL=http://localhost:11434/v1   # Ollama endpoint
LLM_MODEL=llama3.1                       # any local model

Embeddings and the reranker are a separate model class with their own configuration. See docs/PROVIDERS.md.

---

Query from the terminal

Chat is also available over the CLI — the same tier-filtered, cited pipeline the dashboard uses:

aios query "what decisions were made about auth in sprint 1?"
# → SSE stream: delta chunks, source citations, done signal

The pipeline: FTS retrieval over tier-filtered content → structured context injection (decisions, tasks, knowledge-graph entities) → LLM streaming, with per-member and per-team daily cost guards.