convez.ai
MCP ServerDevOps & InfraestruturaAvançado
bejranonda

External Brain — Memória Persistente para Agentes de Codificação

bejranonda/ExternalBrain

Memória durável para IA: captura, extrai e reutiliza conhecimento entre sessões

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP auto-hospedável que captura aprendizados de sessões de codificação (Claude Code, Cursor, Windsurf) e os transforma em skills reutilizáveis com recuperação semântica. Inclui um Oráculo citado que responde perguntas sobre o codebase e conhecimento acumulado. Roda em uma única VM com Docker Compose, agnóstico a provedores (Gemini, GLM, OpenAI, Claude) e é MIT-licensed.

Instalação

$npx convez-ai bejranonda/ExternalBrain

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 2 dias
Versão
v2.24.0
Issues abertas
5
Contribuidores
1

Casos de uso

  • Acumular padrões e recipes de código entre sessões e projetos
  • Consultar decisões arquiteturais e anti-padrões documentados via Oracle
  • Distribuir conhecimento tácito entre membros do time via skills indexadas
  • Reduzir re-explicação de contexto para agentes de IA em cada novo chat

Veredito

Solução sofisticada e bem pensada para um problema real: agentes de IA sem memória entre sessões. O design é limpo (MCP nativo, Docker Compose, sem overhead), a recuperação semântica é robusta, e a citação de fontes diferencia de caches cegos. Exige autohospedagem e configuração de LLM provider, mas oferece soberania de dados e composição elegante sobre ferramentas populares (Claude Code, Cursor, Windsurf).

README

A tradução para o português deste README ainda está na fila.

External Brain — persistent memory for AI coding agents

Stop re-teaching your AI the same things. External Brain captures what you learn in every AI coding session — across Claude Code, Cursor, Windsurf, and any MCP client — turns it into reusable skills, and serves it back automatically the next time you code.

External Brain is a self-hostable MCP (Model Context Protocol) server + webapp that gives your AI coding tools a long-term memory. It ingests your coding sessions, extracts durable knowledge (skills, rules, recipes, anti-patterns), retrieves it by meaning when you start a new task, and answers questions about your own codebase through a grounded Oracle — every answer cited back to the sessions and skills that support it.

Provider-agnostic (Gemini, GLM, OpenAI, Claude), runs on a single VM, and MIT-licensed — fork it and build your own.

How External Brain works


Why External Brain?

AI coding tools are stateless. Every new chat, every new repo, every teammate starts from zero — the hard-won context ("we use Zod not Yup", "the deploy breaks if you skip the migration step", "this service owns auth") evaporates when the session ends. You re-explain. The AI re-discovers. The team re-learns.

External Brain is the missing memory substrate:

  • 🧠 Captures knowledge automatically — finished sessions are mined for durable, reusable lessons. No manual note-taking.
  • 🔌 Works with every AI tool — it's an MCP server, so Claude Code, Cursor, Windsurf, and any MCP-capable agent are first-class clients.
  • 🔎 Semantic retrieval — relevant skills are injected into context before the model generates, by meaning, not keyword match.
  • 💬 Grounded Oracle — ask "how did we fix the deploy bug?" in plain English and get an answer with citations to the real sessions and skills.
  • 📈 Compounds over time — a daily pipeline synthesizes cross-session knowledge; low-value skills decay; useful ones surface. The brain gets sharper the more you use it.
  • 🏠 Self-hosted & private — your knowledge stays in your Postgres, on your infrastructure. Secure-by-default auth, Bearer-gated MCP.
  • 🪶 Quiet by default — a clean dashboard that opens into depth only when you ask. Progressive disclosure, not a wall of dials.

What it is not: another AI coding tool. External Brain doesn't write code — it's the substrate that makes whatever tool you already use smarter over time.


Quickstart — run your own in minutes

Requires Docker Engine 24+ and one LLM provider key (Google Gemini has a free tier and is the easiest start). Full guide: docs/QUICKSTART.md.

git clone https://github.com/bejranonda/ExternalBrain.git external-brain
cd external-brain

cp .env.example .env          # add one provider key (e.g. GOOGLE_GEMINI_API_KEY)
./scripts/dev-up.sh           # build · migrate · seed · start — idempotent

# Webapp:  http://localhost:3000
# MCP HTTP: http://localhost:3100/mcp

dev-up.sh runs an auth-posture audit at the end and prints PASS/FAIL. For a public-internet server deployment (Caddy + auto-TLS, real auth enforced, nightly backups), use ./scripts/deploy.sh instead — see docs/DEPLOY_CHECKLIST.md.

Connect your AI tool

After signing in, the /welcome flow walks you through it: pick your tool, copy a one-line installer, run any task. For Claude Code:

curl -fsSL https://<your-host>/api/onboard.sh | bash -s 'bp_<your-token>'

The installer wires the MCP server, smoke-tests the round-trip, and seeds your first session so the brain starts learning from day zero. Manual wiring for Cursor / Windsurf / any MCP client: docs/CLIENTS.md.


How it works

  AI coding tool ──MCP──▶  External Brain  ──▶  Postgres + pgvector
   (Claude Code,            ├─ retrieve relevant skills (before you code)
    Cursor, …)              ├─ log the session + outcome (after you code)
                            ├─ extract durable knowledge (background worker)
                            └─ answer questions via the Oracle (cited)
  1. Before a task, your tool calls brain_retrieve_knowledge and relevant past skills are injected into context.
  2. After a task, the session + outcome are reported and queued for extraction.
  3. A background worker mines sessions into typed skills, embeds them for semantic search, and decays the stale ones.
  4. Anytime, ask the Oracle in plain language and get grounded, cited answers from your own knowledge.

Full walkthrough with examples: docs/HOW_IT_WORKS.md.


Tech stack

ConcernChoice
RuntimeNode 20 LTS · TypeScript (strict)
WebappNext.js · React · Tailwind
DatabasePostgres + pgvector
EmbeddingsProvider-agnostic via EMBEDDING_BASE_URL (Gemini / OpenAI / Qwen3 — any OpenAI-compatible endpoint)
LLMClaude / GLM / OpenAI / Gemini (swap via env)
Background jobspg-boss (no Redis required)
ProtocolModel Context Protocol (@modelcontextprotocol/sdk)
PackagingTurborepo + pnpm workspaces · Docker Compose

Repo layout

apps/
  web/         Next.js webapp — dashboard, Oracle, Skills, settings
  mcp-server/  MCP server (stdio + HTTP transport)
  worker/      Background jobs: extraction, decay, embeddings
packages/
  core/        Intelligence layer (extraction, retrieval, Oracle)
  db/          Prisma schema + client
  types/       Cross-package TypeScript types
deploy/        Docker Compose, Caddy, Dockerfile
docs/          Documentation

Documentation

DocWhat it covers
EVIDENCEDoes it actually help? — the capture→retrieve loop demonstrated on a real instance
QUICKSTARTZero to a running instance
HOW_IT_WORKSEnd-to-end mental model with examples
ARCHITECTURESystem design, layers, data flow
MCP_TOOLSThe brain_* MCP tools + resources
REST_APIHTTP endpoints
CLIENTSWiring Claude Code / Cursor / Windsurf
USING_BRAINDaily workflow, trigger phrases, recipes
KNOWLEDGEThe knowledge model (normative)
SECURITYAuth modes, MCP gating, threat model
DEPLOY_CHECKLISTProduction deploy on a public VM
CICDCI checks + the two deploy scripts, for forkers
CONTRIBUTING · GUIDELINESHow to contribute, code style
DESIGN_PRINCIPLESUI philosophy (progressive disclosure)
KNOWN_ISSUESTracked risks & gotchas

Diagrams (Mermaid sources + rendered PNGs) live in docs/assets/illustrations/.


Contributing

Contributions and forks are welcome. Fork the repo, branch from main (feature/<slug>, bugfix/<slug>, docs/<slug>), and open a PR — see docs/CONTRIBUTING.md and AGENTS.md (the guide for AI assistants working in this repo). Be kind — we follow a Code of Conduct.

Every PR runs three required checks: typecheck · test · build, a fresh-DB migration (the day-zero deploy path), and — when an onboarding/ unauth surface changes — an anonymous e2e gate. How CI and the two deploy scripts fit together is one short page: docs/CICD.md.

License

MIT © External Brain contributors. Fork it, run it, build on it.

Ver o original no GitHub

Bom para

Relacionados