Klear-Team-Brain

Your team's collective memory for AI-assisted coding. Self-hosted, ultra-light, zero extra effort for the people doing the work.

English | 中文

The problem

Your team codes with Claude Code / Codex — but the context that actually matters (the reasoning, the why-it-changed, the dead ends) is trapped in each person's local AI chat, and it's gone the moment they close the tab. So:

• "Why was this feature designed this way?" — not in any PR; the discussion happened inside someone's chat, not the commit message.
• "Who's working on this refactor, and how far along is it?" — you ask around, or wait for standup.
• A teammate goes on leave or quits, and last week's reasoning leaves with them.

Knowledge depends on "ask the right person." The moment they're busy or gone, the context breaks.

Klear-Team-Brain automatically pools your whole team's AI sessions into one shared memory, fused with live GitHub code state and your team's docs. Then you ask straight from your editor, or browse in a web UI:

"Where did the auth refactor land?" "How was the billing schema decided?" "Who's been touching the ETL this week?"

You get an answer synthesized across the team's sessions + code + docs, with citations. People doing the work do nothing; people who want to understand just ask — or open the dashboard.

Highlights

• Zero-effort capture — everyone keeps using CC/Codex; a background collector flows sessions into the memory automatically, no manual steps.
• Two ways to query — ① ask in natural language from your editor (MCP); ② browse a web dashboard (filter sessions by person/repo/time, see progress and usage stats).
• Ultra-light, self-hosted — the server is just one git repo + one Node process + a static frontend: no database, no queue, no vector store. One small VPS (runs fine on low memory) is enough. Queries run on git grep with zero server-side LLM calls — the understanding happens in the agent inside your editor.
• Privacy-first — only allowlisted directories upload; secrets are redacted client-side before upload; all data stays on your own infrastructure.

Quick start

Prerequisites: Node 22+, and an MCP-capable editor/CLI (Claude Code or Codex) to ask from.

No npm/SaaS install — it's self-hosted by design. There's no public package or hosted service: clone this repo to run the server (or to trial it locally), and your teammates pull the client straight from your server with curl …/get | bash — see Deploy for your team.

Try it locally first (≈5 min — no VPS, no HTTPS, no invite token)

Want to kick the tires before standing up a server? Run the whole thing on your own machine as a single user:

git clone https://github.com/Asklear/Klear-Team-Brain.git && cd Klear-Team-Brain
npm install
npm run quickstart        # one-time: mint a local identity + token, point the client at localhost, wire up MCP
npm run server            # starts the truth store on http://127.0.0.1:8787 — leave this running

Then, in a second terminal, capture your local sessions:

npm run sync -- --once    # capture once (or `npm run sync` to keep watching in the background)

Now ask from your editor, or open http://127.0.0.1:8787/ to browse. Everything stays on your machine. Prefer a containerized server? Use docker compose up -d — see DEPLOY.md.

Deploy for your team

1. Stand up a server (one small VPS) — manually or with one command via docker compose. See DEPLOY.md — install Node, clone, set TRUTH_DIR, add a roster + tokens, put HTTPS in front, run as a service.
2. Onboard each member — point the client at your server:

   curl -fsSL https://your-server.example.com/get | bash   # downloads the client + registers the `brain` command
   brain join <YOUR_INVITE_TOKEN>                           # verify + pick workspaces + wire up MCP + first sync + install resident
   

3. Start using it — ask from your editor, or open https://your-server.example.com/ to browse the dashboard.

Once onboarded, the collector watches your AI sessions in the background and uploads each one as it stabilizes — no manual steps after that.

Two ways to query

① Ask from your editor (MCP)

With MCP wired up, ask in plain language inside CC / Codex ("where did the auth refactor land?"). The agent treats the memory as a read-only folder and uses a handful of Unix-style primitives to locate, read, and synthesize — all tied together by a truth-store-relative path:

Server-side queries run via git grep / git ls-files / git log / fs — execFile, no shell, locked inside TRUTH_DIR, read-only — with zero server-side LLM calls.

Wiring other editors: the MCP server is a stdio server; the command is always <node> <install-dir>/mcp/server.mjs (brain mcp prints your exact path). Add that as a stdio MCP server in Claude Code, Codex, or any MCP-capable client (Gemini CLI / Cursor / Cline / opencode…).

Remote / cloud agents (HTTP transport): an agent that can't run the local stdio binary can mount the memory over HTTP instead — same tools, no local install. Point any MCP client at POST https://your-server/mcp with your member token as a Bearer header.

Claude Code:

claude mcp add --transport http team-brain https://your-server/mcp \
  --header "Authorization: Bearer <your-member-token>"

Cursor / Cline / any mcp.json:

{ "mcpServers": { "team-brain": {
  "type": "http",
  "url": "https://your-server/mcp",
  "headers": { "Authorization": "Bearer <your-member-token>" }
} } }

Smoke-test from a shell (the endpoint accepts plain JSON-RPC — no special Accept header needed):

curl -s https://your-server/mcp -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

It's a stateless, one-shot endpoint (POST in, JSON out — no session, no server-side LLM); multi-turn context stays on the calling agent's side.

② Browse the web UI

The server hosts a static dashboard at / (nothing extra to deploy) — for people who'd rather scan than type: see overall team progress, filter sessions by person/repo/time, view token-usage and activity stats, and skim mirrored docs.

Browse sessions — filter by person/repo/time, sorted by recent activity:

Usage stats — aggregate tokens, sessions, and turns by day/week/person/repo/tool:

How it works

each machine (client)                          your server (self-hosted)
┌────────────────────────┐            ┌──────────────────────────────────┐
│ ① collector client/sync │  gzip+token │ ② server/server.mjs (HTTP, HTTPS  │
│   resident, watches AI   │ ──────────▶ │   via a proxy like Caddy)         │
│   sessions; gated to the │            │   /ingest → git truth store        │
│   allowlisted circle     │            │   TRUTH_DIR + 4h repo poll →       │
│                          │            │   code-state                       │
│ query A: ask in editor   │  search+fetch│  /grep /find /read /ls /log       │
│ query B: open the web UI │ ◀────────── │   + static dashboard hosted at /  │
└────────────────────────┘            └──────────────────────────────────┘

The memory is a single git repository fusing three sources — each captured where it naturally lives:

Design trade-off: only the "truth" (raw material + metadata) is kept clean and complete — because it's expensive and can't be rebuilt; "views" (queries / indexes / the dashboard) are swappable and throwaway. Sessions enter distilled (inline images stripped, giant tool outputs truncated — signal, not bytes); the byte-exact original stays on the producer's machine (~/.codex / ~/.claude).

Privacy & security

• Scope gate: a session is uploaded only if its working direc