Memória compartilhada para agentes de IA e times de desenvolvimento.
Em vez de copiar documentação para prompts ou depender de Confluence, Jira e READMEs espalhados, os agentes recuperam apenas o contexto necessário, atualizam especificações durante a implementação e compartilham conhecimento entre múltiplos repositórios — tudo direto do IDE, sem sair do fluxo.
O SpecHub armazena todos os artefatos do ciclo de vida de uma feature: PRD → Spec Técnica → Design → Tarefas. O PRD é o ponto de partida; a partir dele, skills como grill-me, grill-with-docs ou cy-create-techspec geram a spec técnica e o design, que também são persistidos. As tarefas nascem da spec e são rastreadas por repositório até a conclusão.
flowchart LR
subgraph Agentes
Cursor
Claude
Codex
Windsurf
end
Agentes <-->|MCP| SpecHub[(SpecHub)]
SpecHub --> PG[(PostgreSQL + pgvector)]
SpecHub --> Emb[paraphrase-multilingual-MiniLM-L12-v2]
Todos os agentes compartilham a mesma memória. Quando um agente termina, o próximo continua exatamente de onde o anterior parou.
- Contexto não cabe no prompt — jogar uma spec inteira no prompt consome tokens e degrada a qualidade das respostas. O SpecHub entrega só o trecho relevante.
- Documentação espalhada — specs vivem em Confluence, Jira, Google Docs e READMEs de repositórios diferentes. Ninguém sabe onde está a versão canônica.
- Cross-repo é doloroso — uma feature toca 3+ repositórios. Cada repo tem seu próprio backlog de tarefas, sem visão unificada do que falta fazer.
- Documentação morre após o planejamento — specs são escritas no início e nunca mais atualizadas. O SpecHub foi desenhado para que a documentação evolua junto com o código, durante semanas de implementação.
O SpecHub armazena todos os artefatos do ciclo de vida de uma feature — do PRD inicial até a doc atualizada durante a implementação. O fluxo típico:
Nova feature (ex: "Adicionar pagamento PIX")
│
▼
┌─────────────────────────────────────────┐
│ 1. Salvar PRD │ save_spec
│ Documento de requisitos do produto. │
│ É o ponto de partida. │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 2. Gerar Spec Técnica e Design │ grill-me / grill-with-docs
│ A partir do PRD, usando AI-assisted │ tdd / cy-create-techspec
│ skills para refinar e produzir: │
│ • Documento de especificação técnica │ save_spec
│ • Documento de design/arquitetura │ save_spec
│ Cada artefato é salvo no SpecHub. │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 3. Gerar tarefas por repo │ update_task_status
│ A partir da spec, decompor em tarefas │
│ rastreáveis: │
│ api: criar endpoint cobrança │
│ worker: processar webhook │
│ frontend: tela de pagamento │
│ terraform: novas env vars │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 4. Agente busca contexto relevante │ search_spec_context
│ "Como funciona o webhook?" │ → só a seção sobre webhook
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 5. Implementa e atualiza progresso │ update_task_status
│ api: cobrança PIX → done │
│ worker: webhook → in_progress │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 6. Atualiza documentação │ update_spec_chunk
│ "Durante implementação, o PSP │
│ exige header X-IDEMPOTENCY..." │
└─────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────┐
│ 7. Próximo agente continua │ get_repo_tasks
│ "Quais tarefas faltam?" │ → worker: webhook (in_progress)
│ "O que mudou desde o planning?" │ → frontend, terraform (pending)
└─────────────────────────────────────────┘
O SpecHub centraliza PRD, spec técnica, design e tarefas — tudo versionado, buscável e conectado. O conhecimento acumulado por um agente fica imediatamente disponível para os próximos.
- Não é só busca vetorial — é edição contínua. A documentação não é estática; ela evolui durante a implementação.
- Entende features como unidade de trabalho — cada spec agrupa tarefas distribuídas por repositório, com rastreamento de progresso.
- Mantém histórico de alterações — toda mudança na spec ou nas tarefas gera entrada no changelog. Dá pra saber quem alterou o quê e quando.
- Memória compartilhada entre agentes — Cursor, Claude Code, Windsurf e outros leem e escrevem no mesmo lugar.
- Busca híbrida — combina similaridade vetorial com full-text search, com boost por repositório. Retorna as 3 seções mais relevantes, não o documento inteiro.
- Embeddings locais —
paraphrase-multilingual-MiniLM-L12-v2roda 100% local via@xenova/transformers. Sem chamadas de API externa, sem custo de token para gerar embeddings.
| Ferramenta | O que faz |
|---|---|
save_spec |
Persiste uma spec com embedding vetorial. UPSERT por source_type + source_key. |
| Ferramenta | O que faz |
|---|---|
list_card_documents |
Lista todos os documentos de um card (PRD, spec, design, etc.) a partir do source_key. Use para descobrir o que já existe antes de buscar. |
search_spec_context |
Busca semântica dentro de uma spec. Top-3 seções mais relevantes para a query. Retorna snippets truncados em ~300 chars para eficiência de tokens. |
get_feature_overview |
Retorna metadados + estrutura de headings da spec. Ideal para o agente se localizar antes de buscar. |
get_section |
Retorna o conteúdo completo de uma seção por heading (sem truncamento). Use quando o snippet do search_spec_context for cortado e você precisar da seção inteira. |
| Ferramenta | O que faz |
|---|---|
get_repo_tasks |
Lista tarefas ativas vinculadas à spec, agrupadas por repositório. Use o spec_id do documento spec (não do tasks). |
update_task_status |
Atualiza status (pending → in_progress → done) ou cria nova tarefa vinculada à spec. |
| Ferramenta | O que faz |
|---|---|
update_spec_chunk |
Edita uma seção específica da spec por heading. Re-indexa o embedding automaticamente. |
Toda operação de escrita registra entrada no changelog.
- Desenvolvimento cross-repo — PRD → Spec Técnica → Design → Tarefas. Feature tocando API, worker, frontend e infra, com tarefas rastreáveis por repositório.
- PRDs e RFCs — armazenamento centralizado com busca semântica. O agente encontra o trecho exato que precisa, sem ler 30 páginas. Use
grill-meoucy-create-techspecpara refinar o PRD em spec técnica. - ADRs (Architecture Decision Records) — documentação de decisões de arquitetura indexada e buscável.
- Runbooks e playbooks — procedimentos operacionais que evoluem com o tempo.
- Migrações grandes — documentação viva do que foi migrado, o que falta e decisões tomadas no caminho.
- Onboarding — novos engenheiros (ou agentes) consultam o SpecHub para entender o estado atual de qualquer feature.
- Compartilhamento de contexto entre agentes — múltiplos agentes trabalhando em sequência ou em paralelo, lendo e escrevendo na mesma base de conhecimento.
Autenticação por token estático para agentes de IA que não conseguem fazer o fluxo interativo do Google OAuth.
O que mudou:
SPECHUB_ACCESS_TOKENS— nova env var com lista de tokens separada por vírgula- Agentes autenticam via
Authorization: Bearer <token>sem login no navegador - Estratégias de autenticação compõem com semântica OR: token estático OU Google OAuth
- Comparação de tokens com
timingSafeEqual(SHA-256 hash) — resistente a timing attacks
Como ativar:
SPECHUB_ACCESS_TOKENS=token-para-agente-1,token-para-agente-2Sem SPECHUB_ACCESS_TOKENS e sem GOOGLE_*, o servidor permanece sem autenticação.
Adicionada autenticação opcional via Google OAuth 2.0 com Authorization Code flow.
O que mudou:
- Servidor Express próprio substituiu o auto-server do Mastra, permitindo middlewares customizados
POST /register,GET /authorize,GET /callback,POST /token— authorization server completo para fluxo OAuth com redirect no navegador/.well-known/oauth-protected-resourcee/.well-known/oauth-authorization-server— descoberta automática de metadados OAuthcreateOAuthMiddlewaredo@mastra/mcpprotegendo os endpoints MCP com validação de Google ID TokenGET /health— health check para probes de containercontext.mcp.extra.authInfo— email e domínio do usuário autenticado disponível nas tools
Como ativar:
GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxxx
GOOGLE_ALLOWED_DOMAINS=sua-empresa.comSem essas env vars, o comportamento é idêntico ao anterior (sem autenticação).
Comandos:
npm run dev # Dev server com hot reload (Express)
npm run start # Produção (Express + auth se configurado)Correções no fluxo OAuth que impediam autenticação com contas pessoais do Google e clientes MCP.
O que mudou:
- Validação de domínio usando
payload.emailcomo fallback quandopayload.hdestá ausente — contas@gmail.com(sem hosted domain) agora são aceitas - Implementado PKCE (Proof Key for Code Exchange) com S256 —
code_challengearmazenado na sessão ecode_verifiervalidado no token endpoint authorizationServersalterado para URL raiz, corrigindo descoberta de metadados OAuth (RFC 8414)code_challenge_methods_supported: ['S256']adicionado ao well-known do authorization serverexpress.urlencoded()middleware adicionado — token endpoint agora parseiaapplication/x-www-form-urlencoded(padrão RFC 6749)grant_types_supportedincluirefresh_token
Workflows do SpecHub agora expostos como MCP Resources, eliminando dependência de skills .cursor/ locais. Adicionado pipeline de validação local.
O que mudou:
spechub://workflows/save-artifacts— skill de publicação de artefatos exposta como MCP Resource endereçávelsrc/mastra/workflows/— novo módulo para expor workflows como resources URI-addressablenpm run lint— pipeline completo:typecheck → check:circular → eslint → testeslint+madge— detectano-duplicate-importse dependências circulares automaticamente- Circular import entre módulos de workflow removido
Comandos:
npm run lint # typecheck + circular + eslint + test
npm run lint:eslint # ESLint only
npm run check:circular # madgeNova ferramenta get_section que retorna o conteúdo Markdown completo de uma seção identificada por heading, sem truncamento. Resolve o problema onde search_spec_context cortava snippets de ~300 chars e o agente não conseguia ler seções inteiras.
O que mudou:
get_section(spec_id, section_heading)— retorna{ spec_id, section, content, status }com conteúdo completo da seção (sem limite de caracteres)status: 'found' | 'not_found'— consistente comupdate_spec_chunk- Atualizado
serverInstructionsemmcp.tspara orientar uso da nova tool quando snippets estiverem truncados - README atualizado com a nova ferramenta na seção "Recuperar contexto"
Motivação: #4 — documentos curtos como open-questions tinham listas cortadas no meio, impedindo o agente de ler todas as perguntas.
- Node.js 22+
- Docker
- npm
docker compose up -dPostgreSQL 17 + pgvector na porta 5434.
npm installcp .env.example .envO padrão funciona com o docker-compose:
DATABASE_URL=postgresql://spechub:spechub@localhost:5434/spechub
PORT=3456
SPECHUB_ACCESS_TOKENS=token1,token2 # opcional: autenticação por token fixo para agentes de IA
npm run devNo primeiro start as migrações rodam automaticamente, o modelo de embeddings é baixado (~90 MB, cache local), e o servidor MCP sobe em http://localhost:3456.
Adicione ao config do seu cliente MCP (Cursor, Claude Code, Windsurf, etc.):
{
"mcpServers": {
"spechub": {
"url": "http://localhost:3456/api/mcp/spechub/mcp"
}
}
}┌────────────────────────────────────────────────┐
│ Interface (Mastra/MCP) │
│ src/mastra/ — HTTP SSE endpoint em :3456 │
├────────────────────────────────────────────────┤
│ Application (Use Cases) │
│ src/application/use-cases/ — 7 casos de uso │
├────────────────────────────────────────────────┤
│ Domain (Interfaces) │
│ src/domain/ — entidades, repositórios, │
│ IEmbeddingService │
├────────────────────────────────────────────────┤
│ Infrastructure (Adapters) │
│ src/infrastructure/ │
│ ├── database/ — Sequelize + Umzug + pgvector│
│ ├── repositories/ — implementações repositórios│
│ └── services/ — XenovaEmbeddingService │
├────────────────────────────────────────────────┤
│ Container (Awilix DI) │
│ src/container/ — buildContainer(), singletons│
└────────────────────────────────────────────────┘
Clean Architecture com injeção de dependência (Awilix PROXY mode). Domínio não depende de frameworks — infraestrutura implementa contratos.
Busca híbrida: 0.4 × cosine_similarity + 0.6 × full-text_score + repo_boost. Índice HNSW (pgvector) para similaridade vetorial + índice GIN para tsvector. O conteúdo é segmentado por headings (##, ###) e cada seção é pontuada independentemente.
Migrações: Umzug v3 com SequelizeStorage. Executadas automaticamente no startup.
npm run dev # Dev server com hot reload
npm run build # Build de produção
npm run start # Iniciar em produção
npm run test # Vitest run
npm run typecheck # tsc --noEmit# Ver pendentes
node -e "import('./src/infrastructure/database/umzug.js').then(m => m.umzug.pending().then(p => console.log(p.map(x => x.name))))"
# Rodar pendentes
node -e "import('./src/infrastructure/database/umzug.js').then(m => m.umzug.up())"
# Reverter última
node -e "import('./src/infrastructure/database/umzug.js').then(m => m.umzug.down())"A imagem pública está disponível no Docker Hub: cezarpretto/spechub-mcp.
Multi-plataforma: linux/amd64 e linux/arm64 — funciona em Intel/AMD e Apple Silicon.
docker pull cezarpretto/spechub-mcp:latestO container precisa de acesso ao PostgreSQL (com pgvector) e de um volume para cache do modelo de embedding:
docker run -d \
--name spechub \
-p 3456:3456 \
-e DATABASE_HOST=host.docker.internal \
-e DATABASE_PORT=5434 \
-e DATABASE_USER=spechub \
-e DATABASE_PASSWORD=spechub \
-e DATABASE_NAME=spechub \
-v spechub-model-cache:/app/.cache \
cezarpretto/spechub-mcp:latestOpcionalmente, ative autenticação. Qualquer combinação é válida (OR):
# Token estático para agentes de IA
-e SPECHUB_ACCESS_TOKENS=token1,token2
# Google OAuth para humanos (browser login)
-e GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com \
-e GOOGLE_CLIENT_SECRET=xxxx \
-e GOOGLE_ALLOWED_DOMAINS=sua-empresa.comO modelo de embedding paraphrase-multilingual-MiniLM-L12-v2 (~470 MB) é baixado automaticamente no primeiro start e armazenado em /app/.cache. O volume spechub-model-cache persiste o cache entre restarts, evitando re-download.
As migrações do banco rodam automaticamente no startup — zero configuração manual de schema.
curl http://localhost:3456/healthO container tem HEALTHCHECK embutido (intervalo de 30s, timeout de 5s, 3 retries).
| Camada | Tecnologia |
|---|---|
| MCP Framework | Mastra v1 (@mastra/core, @mastra/mcp) |
| ORM | Sequelize v6 |
| Banco | PostgreSQL + pgvector |
| Embeddings | @xenova/transformers (paraphrase-multilingual-MiniLM-L12-v2, 384d) |
| DI | Awilix |
| Migrations | Umzug v3 |
| Validação | Zod v3 |
| Testes | Vitest v4 |
MIT