Expert Brain

Um grafo de conhecimento pessoal (latticework) que roda 100% na sua conta Cloudflare e conversa com o Claude via MCP.

Open source, criado por Eric Luciano na Mentoria Automações Inteligentes (Expert Integrado).

→ Como funciona o Expert Brain — a página do projeto, com o sistema explicado visualmente.

Você conversa com o Claude sobre uma ideia. Ele chama recall, varre o vault atrás de analogias em outros domínios, e só então oferece salvar a nota — atomizada, com tldr de uma frase e edges que nomeiam o mecanismo compartilhado com o que você já tinha guardado. Não é um app de notas: é uma disciplina de pensamento cross-domain embrulhada num servidor MCP, com um dashboard web por cima.

O que é

Single-user, self-hosted, sem terceiros: seus dados vivem no D1/Vectorize/R2 da sua própria conta Cloudflare, não numa API de alguém.

• ~32 tools MCP — conhecimento (save_note, recall, expand, link, get_note, update_note, delete_note/restore_note, reembed, stats), tasks em kanban (save_task, list_tasks, list_tasks_due_today, update_task, complete_task, comment_task, share_task/unshare_task), captura rápida (capture, list_inbox, resolve_inbox), digest de resurfacing, mídia em notas (opcional, via R2) e um vault de contatos embutido (módulo src/contacts/, roda no mesmo Worker).

• Console web (/app) — home, busca global Ctrl+K, grafo interativo 2D (Sigma.js + d3-force em Web Worker) e 3D, kanban de tasks com colunas e projetos customizáveis, journal, notas com comentários, contatos com dossiê/timeline, página de configuração (domínios, instruções do dono, API keys com escopo, backup manual).

• Grafo com 9 tipos de edge (analogous_to, same_mechanism_as, causes, contradicts, refines, …) e 7 kinds de nota (concept, decision, insight, fact, pattern, principle, question) — task mora na mesma tabela mas fica fora do grafo e do recall (decisão de design, não bug: task é operacional, não conhecimento — ver specs 10-backend/12 e 10-backend/15).

• Recall híbrido balanceado por domínio: embedding (bge-m3 via Workers AI, multilíngue) + FTS5, no máximo 3 notas por domínio até 5 domínios distintos — o objetivo é trazer a conexão inesperada, não só o hit mais óbvio. Isso é só pra notas (conhecimento); para achar uma task sem saber o id, use list_tasks({ query: "..." }) (busca textual dedicada, sem teto de tempo, cobre título+corpo, abertas e fechadas) — nunca recall.

• Privacidade por nota/task (mark_private) e PATs com escopo (full / read / +private) — uma credencial com escopo read nem enxerga as tools de escrita no tools/list.

• Share público read-only de nota ou task por link (/s/<token>), com expiração e revogação.

• Backup automático: snapshot semanal D1 → R2 via cron (segunda-feira), mais backup manual pelo console.

• PWA: manifest + share target — dá pra instalar o console e mandar conteúdo pra ele direto de outro app.

• 12 domínios canônicos trancados por validação (management, sales, marketing, education, ai-applied, leadership, product, operations, personal-development, entrepreneurship, music, cognitive-science), com escape hatch (allow_new_domain) e domínios customizados via /app/config.

Related MCP server: Segundo Cérebro

Arquitetura

                    ┌──────────────────────────┐
   Claude Code /    │                          │
   Desktop / Web  ─▶│   /mcp   (OAuth 2.1 ou   │
   (cliente MCP)    │           PAT eb_pat_*)  │
                    │                          │
   Browser        ─▶│   /app/*  (sessão por    │      Cloudflare Worker
   (console web)     │           cookie)        │      (endpoint único)
                    │                          │
                    │   /s/<token>  (share      │
                    │    público read-only)     │
                    └────────────┬─────────────┘
                                 │
              ┌──────────────────┼──────────────────┬───────────────┐
              ▼                  ▼                  ▼               ▼
        ┌──────────┐      ┌────────────┐     ┌────────────┐  ┌──────────┐
        │    D1     │      │ Vectorize  │     │ Workers AI │  │    R2    │
        │ (SQLite)  │      │ 1024-dim   │     │  bge-m3    │  │  mídia + │
        │ notas +   │      │  cosine    │     │ embeddings │  │  backup  │
        │ edges+FTS5│      │            │     │            │  │(opcional)│
        └──────────┘      └────────────┘     └────────────┘  └──────────┘
                                 │
                          ┌────────────┐
                          │     KV     │
                          │ OAuth +    │
                          │ cache do   │
                          │   grafo    │
                          └────────────┘

Um único Worker (src/index.ts) serve as três superfícies acima na mesma URL. Bindings (declarados em wrangler.toml, gerados pelo setup):

Dois crons ([triggers] no wrangler.toml): digest diário de tasks vencendo/atrasadas (dormente até você configurar TELEGRAM_BOT_TOKEN/TELEGRAM_CHAT_ID) e snapshot semanal de backup pro R2.

Instalação

O caminho ideal: deixe o Claude Code instalar pra você. Abra o Claude Code numa pasta vazia e cole o prompt abaixo. Ele confere os pré-requisitos, roda os comandos desta seção e, a cada etapa que acontece no navegador, pergunta se você quer que ele mesmo faça (dirigindo o browser) ou se prefere fazer à mão com ele guiando clique a clique. Os passos manuais desta seção continuam valendo pra quem prefere fazer tudo sozinho.

Clone https://github.com/Expert-Integrado/expert-brain e faça a instalação guiada completa do Expert Brain na minha conta Cloudflare, seguindo este protocolo:

1. PRÉ-REQUISITOS: confira Node 18+ (node --version) e o wrangler (npx wrangler --version). Se faltar algo, resolva comigo antes de seguir.

2. ETAPAS DE NAVEGADOR: o setup tem etapas que acontecem num navegador real — criar a conta Cloudflare (https://dash.cloudflare.com/sign-up), autorizar o "npx wrangler login" (abre o browser pra clicar Allow), conferir o account_id no dash se não der pra extrair do "npx wrangler whoami", criar um API token em https://dash.cloudflare.com/profile/api-tokens (só na rota alternativa via CLOUDFLARE_API_TOKEN, em vez do login), habilitar o billing pro R2 (opcional, mídia/backup) e autorizar o OAuth na primeira conexão do MCP. Para CADA uma delas, me pergunte com botões (AskUserQuestion): "Essa etapa é no navegador. Quer que eu faça pra você?"
   - Rota padrão: você dirige o navegador via Playwright MCP. Se não estiver instalado: claude mcp add playwright -- npx -y @playwright/mcp@latest
   - Alternativa: Claude in Chrome, no meu Chrome com as minhas sessões.
   - Login e senha quem digita sou EU, no navegador — nunca me peça senha de conta no chat.
   - Se eu preferir manual, me guie passo a passo e aguarde eu confirmar cada clique.

3. VALIDAÇÃO: valide cada etapa com um comando real antes de ir pra próxima (npx wrangler whoami depois do login; deploy e curl <worker-url>/status depois do provision). Falhou, pare e me mostre o erro — não siga por cima.

4. SEGREDOS: valores sensíveis só via wrangler secret put ou .env local — nunca em arquivo commitado, nunca colados no chat.

5. TESTE FINAL: conecte o MCP (claude mcp add --transport http expert-brain <worker-url>/mcp), salve uma nota de teste e faça um recall que a encontre, provando o ciclo de ponta a ponta. Termine com um resumo: URL do Worker, endpoint MCP, o que ficou configurado e próximos passos.

O Expert Brain roda num único Worker na sua conta Cloudflare, dentro do free tier. Notas, grafo, tasks, MCP, console web e o vault de contatos (pessoas, empresas, timeline, menções @ nas notas) vivem todos no mesmo deploy — o módulo de contatos é vendorizado em src/contacts/ e roda in-process. Não há segundo Worker nem repo separado pra instalar: o npm run setup provisiona tudo de uma vez. Contatos vêm sempre junto; quem não usa, ignora (a aba Contatos nasce com empty state).

Pré-requisitos:

• Node.js 18+ (recomendado 20+) (nodejs.org)

• Conta Cloudflare gratuita (cadastro) — sem cartão; a única exceção é a mídia/backup via R2, que exige habilitar billing (continua US$ 0 dentro do free tier)

1. Criar o projeto

npm create @expertintegrado/expert-brain@latest expert-brain
cd expert-brain

O scaffolder (@expertintegrado/create-expert-brain) copia o template — código-fonte, scripts, wrangler.example.toml, CLAUDE.md — pra pasta nova. O repo carrega um .npmrc com legacy-peer-deps=true: é intencional, porque agents@0.17.x declara peers opcionais (ai/chat/x402) que o resolver do npm não fecha sozinho e o runtime usa só agents/mcp. Sem essa flag, npm install cai em ERESOLVE.

npm install

2. Autenticar na Cloudflare

npx wrangler login    # abre o browser, clica "Allow"

3. Setup automático

npm run setup

Isso roda scripts/setup.mjs, que faz em um comando o que seria um runbook de 11 passos: verifica a autenticação, copia wrangler.example.toml → wrangler.toml, pergunta e-mail + senha de dono (12+ caracteres), cria os recursos na sua conta Cloudflare (D1, Vectorize e os 2 namespaces KV do Brain, mais os recursos do módulo de contatos embutido — D1 expert-contacts-db, Vectorize expert-contacts-vec, KV_CONTACTS e R2 expert-contacts-media; pula o que já existir, é idempotente), grava os IDs reais no wrangler.toml, gera o hash PBKDF2 da senha + SESSION_SECRET, sobe os secrets (wrangler secret put), faz wrangler deploy, chama POST /setup/provision pra rodar as migrations no D1, e instala os hooks de captura automática do Claude Code (se preferir rodar depois: node scripts/install-claude-hooks.mjs <url>). Ao final imprime a URL do Worker, o comando MCP e o link do dashboard.

Sem billing habilitado na Cloudflare (R2 exige, mesmo dentro do free tier)? O setup detecta e sobe sem mídia — todo o resto funciona normal. E se o Cloudflare pedir um cartão pra habilitar a mídia (R2): nada é cobrado automaticamente — o cartão só destrava recursos que seguem na faixa gratuita, e no uso normal você provavelmente nunca paga nada. Não quer anexos? Nem precisa cadastrar cartão; dá pra habilitar depois — notas, tasks e contatos sobem sem ele.

Pra reprovisionar do zero (trocar senha, recriar recursos): npm run setup -- --reinstall.

Como os hooks avisam de tarefas (política de cobrança). Os 6 hooks instalados seguem uma regra enxuta: o aviso de tarefas do dia acontece só na abertura da sessão — o agente abre a primeira resposta com "Antes de começarmos:" + as tasks do dia/atrasadas e só então responde o pedido. Esse aviso tem rate-limit: no máximo 1x por período do dia (manhã/tarde/noite, no fuso da máquina) e nunca em retomada de sessão — abrir várias sessões no mesmo dia não vira cobrança o tempo todo. Na compactação o hook lembra de salvar aprendizados e de manter o ciclo de vida das tasks (criar/atualizar/concluir), sem relistar pendências. Instalação antiga cobrando tasks no meio da sessão? Rode node scripts/install-claude-hooks.mjs <url do worker> de novo — ele regrava os hooks corretos e remove os antigos.

4. Primeiro acesso

Abra a URL impressa pelo setup (https://<seu-worker>.workers.dev/app/login) e entre com o e-mail e a senha que você definiu.

5. Conectar ao Claude

claude mcp add --transport http expert-brain https://<seu-worker>.workers.dev/mcp

A primeira conexão abre o fluxo OAuth 2.1 no browser. Depois, abra /app/config no console e cole o bloco de instruções do dono em Claude → Settings → Personalization → Custom instructions — ele entra no handshake de todo agente conectado.

Com o MCP conectado, o último passo é ligar o preenchimento automático — o Brain colhe sozinho e-mails, reuniões, CRM, chat de equipe e a memória que você já construiu no ChatGPT/Claude.ai/Gemini, e cria a importação como as primeiras tasks do seu board: siga o onboarding de memória. Você não aprova entrada por entrada; desfaz o que não quiser (tudo é reversível).

6. Contatos (já incluído)

O vault de contatos — pessoas, empresas, timeline, menções @contato em notas e tasks, a aba Contatos do console com dossiê e timeline, e os painéis de integração (WhatsApp, Instagram, Pipedrive) em /app/config — vem embutido no mesmo Worker (módulo src/contacts/, rodando in-process). O npm run setup do passo 3 já criou os recursos (D1 expert-contacts-db, Vectorize expert-contacts-vec, KV_CONTACTS, R2 expert-contacts-media) e gerou os tokens internos do módulo — não há segundo deploy nem repo separado pra configurar.

Quem não usa, ignora: a aba Contatos nasce com empty state e nada mais no Brain depende dela. Uma instalação anterior à fusão (só Brain) ganha os contatos no próximo npm run setup — ele detecta que faltam os recursos, cria, e não re-pergunta e-mail/senha.

Atualizando

Cada instalação roda no seu próprio Worker — atualizar é buscar o código novo e redeployar; dados e login continuam intactos (vivem no D1/Vectorize, não no código). Dois cenários:

• Instalou pelo scaffolder (npm create): a pasta não é um clone git. Baixe o código novo por cima (zip do repo) preservando o seu wrangler.toml, ou clone o repo numa pasta nova e copie o wrangler.toml provisionado pra ela.

• Clonou o repo: git pull direto.

Nos dois casos, depois:

npm install
npm run setup        # idempotente — redescobre os recursos existentes por nome, redeploya sem pedir e-mail/senha de novo

Uso rápido

Salvar uma ideia (o Claude decide chamar save_note depois de um recall):

"Acabei de sacar que tech debt se comporta como juros compostos — quanto mais você ignora, pior fica a taxa."

Buscar no vault:

"O que eu já pensei sobre feedback loops?" → o Claude chama recall("feedback loops"), lê os domínios retornados e traz o que for relevante.

Criar e consultar uma task:

"Cria uma task pra revisar o contrato até sexta." → save_task. "O que vence hoje?" → list_tasks_due_today (janela de até 168h/7 dias — é o "hoje + esta semana", não a listagem completa). "Cadê aquela task que eu criei sobre X, lá pra outubro?" → list_tasks({ query: "X" }), nunca recall — sem teto de tempo, acha qualquer task por título/corpo independente do quão distante seja o prazo.

Ver o grafo: abra https://<seu-worker>.workers.dev/app/graph — grafo 2D navegável; ?mode=3d pra visualização 3D.

Editar ou remover: update_note/update_task mudam campos existentes; delete_note é soft-delete (recuperável a qualquer momento via restore_note, sem prazo).

Frota de agentes — o board como barramento

Várias instâncias de Claude (PCs, containers 24/7, outros runtimes) podem colaborar pelo MESMO vault usando o Kanban de tasks como barramento de comunicação — sem chat entre agentes. Como funciona (specs no grupo specs/80-frota-agentes/):

• Identidade = credencial, nunca a licença/conta que executa. Cada dispositivo recebe 1 PAT (eb_pat_...) vinculado a um usuário do tipo agent em /app/config. TODA escrita assina como esse usuário — não importa qual app (CLI, desktop, VS Code) ou qual assinatura Claude rodou a sessão. Duas sessões na mesma máquina com o mesmo PAT são, para o Brain, o mesmo agente.

• Endereçamento: atribuir uma task a um agente (assignees) ou @mencioná-lo num comentário gera item no mailbox dele (check_mailbox/ack_mailbox — ler nunca marca lido; ack é ato explícito depois de agir).

• Wake-up: cada dispositivo descobre que tem mensagem por pull — polling */30 (cron/daemon/hook) como reconciliador e, desde a spec 90, o long-poll GET /api/mailbox/wait como fast-path (o Worker responde na hora que nasce item; latência de segundos). Runbook por dispositivo: docs/frota-heartbeat.md.

• Concorrência: antes de trabalhar uma task, o agente chama claim_task (lease atômico com expiração — agente que caiu nunca bloqueia a fila). Dois agentes disputando a mesma task: exatamente um ganha, o outro pula pra próxima.

• Protocolo: comentários tipados [pedido] / [entrega] / [bloqueio] / [info]. Um [bloqueio] sem resposta do dono coloca a task na fila "Aguardando você" do board (e dispara push) até o dono responder no thread.

• Fila de trabalho: list_tasks com assignee: "me" + available: true = "minhas tasks livres pra trabalhar agora".

Documentação e novidades

• CHANGELOG.md — release notes por versão (o que mudou em cada release).

• Expert Brain — como funciona — página pública explicando o sistema (GitHub Pages).

• RELEASING.md — runbook de publicação do pacote npm; a versão atual e o histórico de releases ficam em GitHub Releases.

• docs/token-cost.md — breakdown de custo em tokens do overhead do MCP por plano do Claude.

• docs/observability.md, docs/restore.md, docs/curation-runbook.md — runbooks operacionais.

• /app/novidades no seu próprio console — changelog voltado pro dono da instância.

Desenvolvimento

Esta seção é o guia de setup de ambiente de dev — do zero, com o passo a passo por sistema operacional (macOS, Linux, Windows). Se você só quer usar o Expert Brain na sua conta, o caminho é a seção Instalação acima; o de baixo é pra quem vai rodar o código local, contribuir ou deployar.

Versões esperadas (validadas contra este repo)

Toda a stack é a mesma nos três sistemas — o runtime alvo é o Cloudflare Workers, não o SO local. O que importa é a toolchain:

Não instale o Wrangler global. O projeto fixa a versão nas devDependencies; rodar npx wrangler (ou os scripts npm run) garante que todo mundo usa a mesma versão. Um wrangler global desatualizado é a causa nº 1 de erro de setup.

Além disso você vai precisar de uma conta Cloudflare gratuita (cadastro) — os recursos de dev (D1, Vectorize, KV) são criados nela, mas o wrangler dev roda tudo local (Miniflare), sem tocar produção.

Preparar o SO

O único pré-requisito específico de SO é ter Node LTS + Git. Escolha o caminho do seu sistema:

Com Homebrew:

brew install node git          # Node LTS + Git
node --version                 # confira: v20.x ou v22.x

Preferindo múltiplas versões de Node, use fnm (brew install fnm) ou nvm e rode fnm use --lts / nvm install --lts.

O Node dos repositórios de distro costuma ser antigo — prefira o NodeSource ou um gerenciador de versão:

# Opção A — nvm (recomendado, não precisa de sudo)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
# reabra o terminal, então:
nvm install --lts
nvm use --lts

# Opção B — NodeSource (Debian/Ubuntu, Node 22.x)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

sudo apt-get install -y git    # se ainda não tiver
node --version

Distros com apt/dnf/pacman funcionam igual — só garanta Node 18+ (de preferência 20/22).

Recomendado: PowerShell + winget.

winget install OpenJS.NodeJS.LTS
winget install Git.Git
# feche e reabra o terminal, então:
node --version

Para alternar versões de Node no Windows use fnm (winget install Schniz.fnm) ou o nvm-windows.

Notas específicas de Windows:

• Rode os comandos no PowerShell ou no Terminal do Windows — os scripts do repo já detectam Windows (usam shell: true) e funcionam sem WSL.

• Alternativamente, WSL2 (Ubuntu) dá um ambiente Linux completo e é a opção mais confortável se você já mexe com bash — nesse caso siga a aba Linux acima, dentro do WSL.

• Se o npm install reclamar de permissão pra criar symlinks/scripts, abra o terminal como Administrador uma vez ou habilite o Modo de Desenvolvedor.

Clonar, instalar e autenticar

Estes passos são idênticos nos três sistemas (só o terminal muda):

git clone https://github.com/Expert-Integrado/expert-brain.git
cd expert-brain
npm install                    # respeita o .npmrc (legacy-peer-deps=true) — obrigatório
npx wrangler login             # abre o browser → clique "Allow"
npx wrangler whoami            # valida: mostra seu e-mail + account_id

Por que legacy-peer-deps? O repo carrega um .npmrc com legacy-peer-deps=true. É intencional: agents@0.17.x declara peers opcionais (ai/chat/x402) que o runtime não usa (só agents/mcp), e sem a flag o npm install cai em ERESOLVE. Como o .npmrc está no repo, rodar npm install da raiz já pega a flag — não precisa passar nada.

Sem browser na máquina (servidor headless, CI)? Em vez do wrangler login, exporte um API token: crie um em dash.cloudflare.com/profile/api-tokens e defina CLOUDFLARE_API_TOKEN no ambiente (export … no bash / $env:CLOUDFLARE_API_TOKEN="…" no PowerShell).

Provisionar sua instância (uma vez)

Para ter um Worker real na sua conta (necessário pra testar o fluxo completo, MCP, OAuth), rode o bootstrap — o mesmo da seção Instalação, passo 3:

npm run setup                  # cria D1/Vectorize/KV, gera secrets, deploya, roda migrations

É idempotente: reexecutar redescobre os recursos por nome e só redeploya. Detalhes completos (o que ele pergunta, o que cria, --reinstall) estão na seção Instalação.

Rodar local (Miniflare)

npm run dev                    # wrangler dev → http://localhost:8787 (Miniflare, tudo local)

O wrangler dev simula D1/KV/R2 localmente — você não precisa ter provisionado nada pra subir o servidor. Para logar no console local (/app/login), o Worker precisa das credenciais de dono em variáveis locais. O Wrangler lê isso de um arquivo .dev.vars na raiz (formato .env, gitignored — nunca commite):

# .dev.vars  (crie na raiz do repo — NÃO vai pro git)
OWNER_EMAIL=voce@exemplo.com
OWNER_PASSWORD_HASH=<hash>      # gere com: node scripts/hash-password.mjs
SESSION_SECRET=<32 bytes hex>   # gere com: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Para popular o console local com dados fictícios (7 kinds de nota, board de tasks, projetos, inbox) pra clicar e testar:

npm run seed:dev               # node scripts/seed-dev.mjs --local --force (só D1 LOCAL, nunca produção)

Testes

npm test                       # vitest run + vitest run --config vitest.auth.config.ts
npm run test:client            # suíte do client web (jsdom)
npm run test:watch             # vitest em watch mode
npm run typecheck              # tsc --noEmit na raiz + client + test + e2e
npm run e2e                    # Playwright contra o wrangler dev local (precisa de E2E_EMAIL/E2E_PASSWORD)

Os testes rodam em pools separados: o principal (vitest.config.ts, D1 + tools MCP com Vectorize/Workers AI mockados, tudo dentro do workerd), um pool node à parte (vitest.auth.config.ts) pro módulo de hash de senha (isolado das restrições do runtime dos Workers) e a suíte de client (vitest.client.config.ts, jsdom). O e2e (Playwright) sobe o wrangler dev, aplica o seed e loga uma vez — as credenciais vêm de E2E_EMAIL/E2E_PASSWORD (nunca hardcoded; use as mesmas do seu .dev.vars).

Playwright no primeiro uso: npx playwright install baixa os navegadores. Em Linux pode ainda faltar libs do sistema — rode npx playwright install-deps (ou sudo npx playwright install --with-deps chromium).

Build e deploy

npm run build:bundles          # empacota src/web/client → assets/*.bundle.js (esbuild)
npm run deploy                 # build:bundles + wrangler deploy + POST /setup/provision (scripts/deploy.mjs)

Cada deploy vai pro seu próprio Worker na sua conta Cloudflare; dados e login vivem no D1/Vectorize (não no código), então redeployar é seguro. Runbook de publicação do pacote npm (scaffolder) fica em RELEASING.md — não é o mesmo que deployar sua instância.

Fluxo de contribuição

O desenvolvimento é spec-driven: toda mudança relevante nasce como uma spec em specs/, pensada pra um agente de IA executar sem contexto externo. Antes de contribuir, leia specs/README.md (o protocolo) e specs/90-roadmap.md (a sequência de fases e gates). Os git hooks de commit são instalados automaticamente no npm install (script prepare).

Troubleshooting rápido

Feito pela Expert Integrado.