Beever Atlas

 Beever Atlas

Transforme os chats de Slack, Discord, Teams & Mattermost da sua equipe
em uma wiki automática — automaticamente.

---

O Beever Atlas puxa as conversas que sua equipe já tem no Slack, Discord, Microsoft Teams e Mattermost, extrai fatos atômicos, remove duplicatas e os agrupa em páginas de tópicos com citações. Um armazenamento de grafo conecta as pessoas, decisões e projetos mencionados nos canais. Faça perguntas em linguagem natural e obtenha respostas citadas de volta às mensagens de origem — pelo painel, ou via MCP no Claude Code e no Cursor.

Se você quer uma base de conhecimento que cresce sozinha a partir dos chats que sua equipe já tem, é isto.

---

✨ Recursos em ação

Seis clipes curtos — conecte um workspace, sincronize o histórico, veja a memória se construir, navegue pela wiki gerada automaticamente, faça perguntas, conecte agentes de IA externos via MCP.

Multi-Platform Conecte Slack, Discord, Teams, Mattermost ou importações de arquivos. Um bot, todos os workspaces.	Message Sync Puxe o histórico do canal sob demanda ou em um agendamento. Retomável e ciente de limites de taxa.	Memory Ingestion Pipeline ADK de 6 estágios destila mensagens em fatos atômicos, entidades e relacionamentos.
LLM Wiki Wiki automática por canal — visão geral, tópicos, pessoas, decisões, citações.	QA Agent Transmite respostas citadas via SSE. Roteador inteligente escolhe semântico ou grafo por pergunta.	MCP Server Conecte Claude Code / Cursor à sua base de conhecimento — 28 ferramentas, autenticação por agente.

---

🏗️ Arquitetura

Conversas de qualquer plataforma suportada fluem para um pipeline de ingestão unificado que produz dois sistemas de memória complementares — um armazenamento semântico de 3 camadas (canal / tópico / fato atômico) para busca híbrida rápida, e um armazenamento de grafo que extrai entidades e seus relacionamentos. Essas memórias alimentam duas superfícies de consumo: a LLM Wiki (destilada, automática) e os QA Agents (servidos pelo painel diretamente, ou via MCP no Claude Code / Cursor).

De plataformas de chat a agentes MCP — um caminho de ingestão, dois sistemas de memória, duas superfícies de entrega.

Por baixo dos panos, três serviços (backend, bot, frontend) são apoiados por quatro armazenamentos de dados (Weaviate, Neo4j, MongoDB, Redis). Veja a visão geral da arquitetura no site de documentação para o design completo — responsabilidades dos componentes, internals da memória dupla e o roteador de consultas inteligente.

---

💡 Por que Wiki-First RAG?

A maioria dos sistemas RAG responde perguntas recuperando trechos brutos de mensagens e alimentando-os diretamente a um LLM. O Beever Atlas adota uma abordagem diferente: ele continuamente destila conversas em uma wiki estruturada e automática — com páginas de tópicos, grafos de entidades, decisões e citações — antes de qualquer consulta ser feita. Quando você faz uma pergunta, a camada de recuperação trabalha com conhecimento limpo e deduplicado, em vez de histórico de chat ruidoso. Isso significa que as respostas são mais consistentes, as citações são rastreáveis até as mensagens de origem, e a própria wiki se torna um artefato útil que sua equipe pode navegar independentemente da interface de Q&A. A arquitetura de memória dupla (semântica + grafo) permite que o roteador de consultas escolha a estratégia de recuperação certa para cada pergunta, mantendo baixa latência e contexto preciso.

Uma wiki de canal gerada automaticamente ao vivo: visão geral, mapa conceitual, tópicos, FAQ, glossário — destilada de 246 mensagens do Slack, não escrita à mão.

A inspiração: LLMs leem wikis, não logs de chat

O conceito de wiki por canal é diretamente inspirado na observação de Andrej Karpathy de que LLMs são muito melhores em raciocinar sobre conteúdo curado e enciclopédico (livros, docs, wikis) do que sobre transcrições brutas de conversas. O histórico de chat é ruidoso, redundante, disperso no tempo e cheio de contexto implícito que só humanos resolvem. Uma wiki, por outro lado, é a forma já destilada desse conhecimento — deduplicada, estruturada, com citações e organizada por tópico, não por timestamp.

O Beever Atlas operacionaliza essa percepção: cada canal sincronizado ganha sua própria wiki gerada automaticamente e atualizada continuamente — seções para tópicos, entidades, decisões, perguntas em aberto e linhas do tempo — reconstruída incrementalmente à medida que novas mensagens chegam. O agente de QA recupera primeiro contra essa wiki, caindo para mensagens brutas apenas quando um fato ainda não foi destilado.

O que isso desbloqueia na prática

• Melhores respostas, menos alucinações — a recuperação opera em prosa densa em fatos com relações explícitas de entidades, não em chat fragmentado turno a turno.
• Citações rastreáveis — cada afirmação da wiki liga de volta às mensagens de origem que a produziram, então as respostas são auditáveis até o thread original do Slack/Discord/Teams.
• Um artefato navegável, não apenas uma caixa de Q&A — a wiki é útil por si só. Novos colegas entrando em um canal podem ler a wiki destilada em vez de rolar três meses de histórico.
• Inferência mais barata no momento da consulta — o trabalho caro de destilação acontece uma vez, na ingestão. As consultas atingem contexto compacto e pré-digerido, em vez de re-resumir logs brutos a cada solicitação.
• Raciocínio ciente de grafo — o grafo de entidades construído junto com a wiki permite que o roteador de consultas responda perguntas relacionais ("quem trabalhou em X com Y?") que RAG vetorial puro tem dificuldade.

Para uma comparação detalhada com outras ferramentas de conhecimento LLM, veja a página de comparação no site de documentação.

---

🚀 Início Rápido

O Beever Atlas é distribuído como uma pilha Docker Compose (backend + bot + web + 4 armazenamentos de dados). Você pode testar uma demo com dados de exemplo em 30 segundos sem nenhuma chave, e depois escolher uma das três opções de implantação para instalar de verdade.

1. Obtenha o código

git clone https://github.com/beever-ai/beever-atlas.git
cd beever-atlas

2. Experimente a demo primeiro (opcional, sem chaves necessárias para o seed)

make demo

make demo sobe a pilha completa pré-carregada com um corpus público da Wikipedia (Ada Lovelace + história do Python). O seed usa fixtures pré-computadas — nenhuma chave de API é necessária. Fazer perguntas via /api/ask requer uma GOOGLE_API_KEY de nível gratuito porque o agente de QA chama o Gemini. Veja demo/README.md para exemplos de curl.

Pule esta etapa se você estiver pronto para instalar de verdade.

3. Antes de começar: obtenha suas chaves de API

Duas chaves gratuitas são necessárias antes de instalar. Ambas oferecem níveis gratuitos generosos — suficientes para sincronizar os canais de uma equipe pequena para testes.

Chave	Propósito	Onde obter
GOOGLE_API_KEY	Gemini — extração, grafo de entidades, respostas	aistudio.google.com/apikey
JINA_API_KEY	Embeddings Jina v4 (2048-dim) para busca semântica	jina.ai/api-dashboard

Opcional (pule a menos que saiba que precisa):

Chave	O que habilita
TAVILY_API_KEY	Busca web externa quando a confiança da recuperação QA é baixa — tavily.com
OLOSTEP_API_KEY	Busca web Olostep (alternativa ao Tavily). Defina WEB_SEARCH_PROVIDER=olostep no seu .env — olostep.com/dashboard
Tokens de bot Slack / Discord / Teams	Configurados via interface web após a configuração, não .env — o bot armazena credenciais da plataforma criptografadas no MongoDB

Dica: Mantenha as duas chaves necessárias à mão antes de começar. A Opção 1 as solicita interativamente; as Opções 2 e 3 precisam que elas sejam coladas no .env.

4. Escolha uma opção de implantação

Opção	Quando usar	Tempo para "subir"
1. Instalação de uma linha (recomendada)	Você quer o caminho mais rápido para uma pilha em execução.	~2 min na primeira execução
2. Docker manual	CI/CD, ambientes de operação, ou quando você quer controle explícito sobre cada etapa.	~3 min na primeira execução
3. Desenvolvimento local	Contribuidores ativos que precisam de hot-reload no backend e frontend.	varia

Opção 1 — Instalação de uma linha (recomendada)

./atlas

O instalador atlas guia você por uma checklist interativa de 5 etapas:

1. Modelo de embedding — escolha um provedor (Jina / OpenAI / Cohere / Voyage / Gemini / Mistral / Ollama) e depois sua chave de API.
2. Provedor LLM do agente — escolha um provedor para os 16 agentes ADK (Google Gemini / OpenAI / Anthropic / Mistral / DeepSeek / Groq / MiniMax / Ollama / Custom); provedor opcional secundário para setups híbridos.
3. Backend de grafo — Neo4j (padrão) ou pule.
4. Integrações opcionais — busca web Tavily, servidor MCP para Claude Code / Cursor.
5. Tokens de autenticação — mantenha os padrões de desenvolvimento ou rotacione agora.

Por baixo dos panos, ele verifica docker + docker compose, copia .env.example → .env (preserva seus valores em re-execução, chmod 600), gera automaticamente CREDENTIAL_MASTER_KEY (64 hex) e WEAVIATE_API_KEY (32 hex), executa uma verificação de conflito de porta, inicia a pilha via docker compose up -d --build --force-recreate --remove-orphans e faz polling de /api/health antes de imprimir o cartão de pronto.

Quando você vir "Beever Atlas está pronto", abra http://localhost:3000 — depois Configurações → Configuração de IA para gerenciar provedores, atribuir LLMs por agente, executar Teste de Conexão ou descobrir modelos. Para CI / Docker / GitOps, configure declarativamente: BEEVER_LLM_API_KEY=... (atalho de provedor único), BEEVER_ENDPOINTS='[...]' + BEEVER_PRESET=..., ou envie um atlas.yaml e execute atlas apply — veja docs/runbooks/ai-setup.md e docs/runbooks/atlas-yaml.md.

Para CI ou instalações não assistidas — pule prompts, pré-popule chaves do ambiente shell:

GOOGLE_API_KEY=... JINA_API_KEY=... ./atlas --non-interactive

Re-executar ./atlas em uma pilha existente é idempotente.

Opção 2 — Docker manual

Controle total, passo a passo.

cp .env.example .env

Abra .env e preencha as duas chaves necessárias:

GOOGLE_API_KEY=your_gemini_key
JINA_API_KEY=your_jina_key

Gere dois segredos necessários e cole-os no .env:

# CREDENTIAL_MASTER_KEY — AES-256-GCM key for stored platform credentials (64 hex chars)
python -c "import secrets; print(secrets.token_hex(32))"

# WEAVIATE_API_KEY — auth between backend and Weaviate (required by docker-compose)
python -c "import secrets; print(secrets.token_hex(16))"

Inicie:

docker compose up -d --build

Abra http://localhost:3000.

Serviços iniciados:

Serviço	Porta	Descrição
Web (nginx)	:3000	Painel React
Backend	:8000	FastAPI + agentes ADK
Bot	:3001	Ponte de plataforma (Slack / Discord / Teams)
Weaviate	:8080	Memória semântica
Neo4j	:7474 / :7687	Memória de grafo
MongoDB	:27017	Estado + cache de wiki
Redis	:6380	Sessões (interno :6379)

A primeira execução leva de 2 a 3 minutos enquanto as imagens são construídas e os bancos de dados são inicializados. Execuções subsequentes iniciam em segundos.

Opção 3 — Desenvolvimento local

Bancos de dados no Docker, serviços de aplicação nativos para hot-reload.

Pré-requisitos: Python 3.12+ com uv, Node.js 20+

cp .env.example .env
# Fill in GOOGLE_API_KEY, JINA_API_KEY, CREDENTIAL_MASTER_KEY, WEAVIATE_API_KEY (same as Option 2)

# Start just the databases
docker compose up -d weaviate neo4j mongodb redis

# Backend (terminal 1)
uv sync
uv run uvicorn beever_atlas.server.app:app --reload --port 8000

# Bot (terminal 2)
cd bot && npm install && npm run dev

# Web (terminal 3) — Vite dev server with HMR
cd web && npm install && npm run dev

Abra http://localhost:5173 (a porta de desenvolvimento do Vite — não :3000).

O servidor de desenvolvimento do Vite faz proxy de /api/* para http://localhost:8000 (configurado via VITE_API_URL).

Antes de ir para produção

.env.example os padrões são ajustados para testes locais. Antes de qualquer implantação real, rotacione os segredos que vêm com valores de espaço reservado e alterne o sinalizador de ambiente:

O que alterar	Por quê	Como
BEEVER_API_KEYS, BEEVER_ADMIN_TOKEN	Enviados como dev-key-change-me / dev-admin-change-me — espaços reservados públicos	python -c "import secrets; print(secrets.token_hex(24))" por token
BRIDGE_API_KEY	Segredo compartilhado entre backend e bot; em branco por padrão, obrigatório fora do desenvolvimento local	Mesmo secrets.token_hex(24)
VITE_BEEVER_API_KEY, VITE_BEEVER_ADMIN_TOKEN	O Vite incorpora estes no pacote web no momento da compilação — devem espelhar os valores de backend rotacionados acima	Copie os valores rotacionados de BEEVER_API_KEYS / BEEVER_ADMIN_TOKEN
NEO4J_PASSWORD + metade da senha de NEO4J_AUTH	A senha de desenvolvimento é pública neste repositório	Escolha uma senha forte; ambos os valores devem corresponder
BEEVER_ENV=production	Habilita inicialização fail-fast que rejeita todos os padrões de desenvolvimento acima	Alterne o valor em .env

A Opção 1 (./atlas) lida com tudo isso por meio do prompt "Rotacionar tokens de autenticação" na etapa 4 da lista de verificação — responda Y e o instalador gera tokens aleatórios e espelha os valores VITE_* para você. Se você usou a Opção 2 ou 3, pode executar novamente ./atlas no .env existente, pular todos os outros prompts com Enter e aceitar apenas o prompt de rotação.

5. Abra o painel

Navegue até a URL da sua opção escolhida:

• Opções 1 e 2 → http://localhost:3000
• Opção 3 → http://localhost:5173

A partir daí:

• Modo real (padrão, ADAPTER_MOCK=false): conecte um workspace em Configurações → Conexões — tokens do Slack / Discord / Teams são inseridos pela interface, não por .env.
• Modo simulado (ADAPTER_MOCK=true): usa dados de fixture — opte por isso para iteração local da interface sem credenciais de plataforma.

6. Sincronize um canal

No painel: Conexões → Adicionar workspace → Selecionar canais → Sincronizar.

Ou via API (extrai automaticamente seu token de portador de .env):

curl -X POST http://localhost:8000/api/channels/C12345/sync \
  -H "Authorization: Bearer $(grep -E '^BEEVER_API_KEYS=' .env | cut -d= -f2 | cut -d, -f1)"

A mídia compartilhada em canais sincronizados (imagens, PDFs, vídeos) é persistida de forma durável para que continue renderizando após o link do CDN da plataforma expirar. O padrão é armazenamento em banco de dados com zero infraestrutura extra, e pode usar MinIO/S3 em escala. Consulte docs/media-persistence.md para o mecanismo, configuração de CHANNEL_MEDIA_*, o backend MinIO/S3 e o preenchimento retroativo de canais existentes.

Servidor MCP (para agentes de IA externos)

O Beever Atlas expõe um servidor MCP (Model Context Protocol) selecionado em /mcp para agentes de IA como Claude Code e Cursor. Isso permite que assistentes de código externos consultem a base de conhecimento da sua equipe sem usar o painel.

Consulte docs/mcp-server.md para:

• Catálogo de ferramentas — 28 ferramentas para descoberta, recuperação, leitura de wiki, travessia de grafo e operações de longa duração
• Configuração de autenticação — geração e gerenciamento de BEEVER_MCP_API_KEYS
• Configuração do cliente — modelos .mcp.json prontos para uso para Claude Code e Cursor
• Limites de taxa — limites por chave principal para evitar que um agente limite outros

Também inclui um modo stdio autônomo (python -m beever_atlas.api.mcp_server / beever-atlas-mcp) que expõe o mesmo catálogo de ferramentas sem servidor HTTP ou armazenamentos de suporte — útil para registros MCP (Glama.ai) e introspecção local. Consulte docs/mcp-server.md.

Exemplo rápido (Claude Code):

{
  "mcpServers": {
    "beever-atlas": {
      "url": "https://atlas.example.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer ${BEEVER_MCP_KEY}"
      }
    }
  }
}

Comandos comuns

docker compose up -d                     # Start in background
docker compose logs -f beever-atlas      # Tail backend logs
docker compose down                      # Stop (keeps data)
docker compose down -v                   # Stop and DELETE all indexed data
make demo                                # Full stack + seeded demo corpus
make docker-up                           # Shortcut for `docker compose up -d`

---

🔒 Privacidade e Telemetria

O Beever Atlas não coleta telemetria. Nenhum dado de uso, relatório de erro ou análise é enviado a qualquer lugar por padrão. Todas as chamadas de LLM passam por chaves de API que você configura na sua própria .env, e todos os dados permanecem nos bancos de dados que você controla.

---

📐 Estabilidade da API

Todos os endpoints de /api/* são INSTÁVEIS na versão 0.1.0. A v0.2.0 introduzirá um prefixo /api/v1/*; clientes que fixarem os caminhos atuais quebrarão. Consulte SECURITY.md.

---

💬 Comunidade e Contato

• Discord: discord.gg/VshBCUUX — obtenha ajuda, compartilhe o que você está construindo, fale com a equipe
• X / Twitter: @Beever_AI — notas de versão, posts, anúncios
• Site: beever.ai — sobre a empresa e outros projetos
• Discussões no GitHub: github.com/Beever-AI/beever-atlas/discussions — perguntas e ideias mais detalhadas

Suporte comercial, parcerias ou imprensa: tech@beever.ai.

---

📜 Licença

Licença Apache 2.0 © 2026 Contribuidores do Beever Atlas. Atribuições de terceiros em NOTICE.

Política de segurança: SECURITY.md | Padrões da comunidade: CODE_OF_CONDUCT.md