Beever Atlas

 Beever Atlas

Convierte los chats de Slack, Discord, Teams y Mattermost de tu equipo
en una wiki que se automantiene — automáticamente.

---

Beever Atlas extrae las conversaciones que tu equipo ya tiene en Slack, Discord, Microsoft Teams y Mattermost, extrae hechos atómicos, los deduplica y los agrupa en páginas temáticas con citas. Un almacén de grafos enlaza las personas, decisiones y proyectos mencionados en los canales. Haz preguntas en lenguaje natural y obtén respuestas citadas con referencia a los mensajes fuente — a través del panel, o mediante MCP en Claude Code y Cursor.

Si quieres una base de conocimiento que crezca por sí sola a partir de los chats que tu equipo ya tiene, esto es lo que buscas.

---

✨ Funciones en acción

Seis clips cortos — conecta un espacio de trabajo, sincroniza el historial, observa cómo se construye la memoria, explora la wiki generada automáticamente, haz preguntas, y conecta agentes de IA externos mediante MCP.

Multiplataforma Conecta Slack, Discord, Teams, Mattermost o importaciones de archivos. Un solo bot, todos los espacios de trabajo.	Sincronización de mensajes Extrae el historial del canal bajo demanda o según un cronograma. Reanudable y con respeto a los límites de frecuencia.	Ingesta de memoria El pipeline ADK de 6 etapas destila los mensajes en hechos atómicos, entidades y relaciones.
Wiki LLM Wiki automatizada por canal — resumen, temas, personas, decisiones, citas.	Agente de QA Transmite respuestas citadas vía SSE. Un router inteligente elige la búsqueda semántica o de grafos según la pregunta.	Servidor MCP Conecta Claude Code / Cursor a tu base de conocimiento — 28 herramientas, autenticación por agente.

---

🏗️ Arquitectura

Las conversaciones de cualquier plataforma compatible fluyen hacia un pipeline de ingesta unificado que produce dos sistemas de memoria complementarios — un almacén semántico de 3 niveles (canal / tema / hecho atómico) para búsqueda híbrida rápida, y un almacén de grafos que extrae entidades y sus relaciones. Esas memorias alimentan dos superficies de consumo: la Wiki LLM (destilada, automantenida) y los Agentes de QA (servidos directamente a través del panel, o mediante MCP en Claude Code / Cursor).

De las plataformas de chat a los agentes MCP — un camino de ingesta, dos sistemas de memoria, dos superficies de entrega.

Internamente, tres servicios (backend, bot, frontend) están respaldados por cuatro almacenes de datos (Weaviate, Neo4j, MongoDB, Redis). Consulta la descripción general de la arquitectura en el sitio de documentación para ver el diseño completo — responsabilidades de componentes, internos de doble memoria y el router de consultas inteligente.

---

💡 ¿Por qué RAG con enfoque en Wiki?

La mayoría de los sistemas RAG responden preguntas recuperando fragmentos de mensajes crudos y alimentándolos directamente a un LLM. Beever Atlas adopta un enfoque diferente: destila continuamente las conversaciones en una wiki estructurada y automantenida — con páginas temáticas, grafos de entidades, decisiones y citas — antes de procesar cualquier consulta. Cuando haces una pregunta, la capa de recuperación trabaja sobre conocimiento limpio y deduplicado en lugar de historial de chat ruidoso. Esto significa respuestas más consistentes, citas trazables hasta los mensajes originales, y que la wiki misma se convierte en un artefacto útil que tu equipo puede explorar independientemente de la interfaz de preguntas y respuestas. La arquitectura de doble memoria (semántica + de grafos) permite que el router de consultas elija la estrategia de recuperación adecuada para cada pregunta, manteniendo baja latencia y contexto preciso.

Una wiki de canal generada automáticamente en vivo: resumen, mapa de conceptos, temas, FAQ, glosario — destilada de 246 mensajes de Slack, no escrita a mano.

La inspiración: los LLM leen wikis, no registros de chat

El concepto de wiki por canal está directamente inspirado en la observación de Andrej Karpathy de que los LLM son mucho mejores razonando sobre contenido curado y enciclopédico (libros, documentos, wikis) que sobre transcripciones de conversaciones crudas. El historial de chat es ruidoso, redundante, disperso en el tiempo y lleno de contexto implícito que solo los humanos resuelven. Una wiki, en cambio, es la forma ya destilada de ese conocimiento — deduplicada, estructurada, con citas y organizada por tema en lugar de por marca de tiempo.

Beever Atlas pone en práctica esta idea: cada canal sincronizado obtiene su propia wiki generada automáticamente y actualizada continuamente — secciones para temas, entidades, decisiones, preguntas abiertas y líneas de tiempo — reconstruida de forma incremental a medida que llegan nuevos mensajes. El agente de QA recupera primero de esta wiki, y solo recurre a los mensajes crudos cuando un hecho aún no ha sido destilado.

Qué permite esto en la práctica

• Mejores respuestas, menos alucinaciones — la recuperación opera sobre prosa densa en datos con relaciones de entidad explícitas, no sobre chat fragmentado turno a turno.
• Citas trazables — cada afirmación de la wiki enlaza de vuelta a los mensajes fuente que la produjeron, de modo que las respuestas son auditables hasta el hilo original de Slack/Discord/Teams.
• Un artefacto navegable, no solo una caja de preguntas y respuestas — la wiki es útil por sí sola. Los nuevos compañeros que se incorporan a un canal pueden leer la wiki destilada en lugar de desplazarse por tres meses de historial.
• Inferencia más barata al consultar — el costoso trabajo de destilación se hace una sola vez, en la ingesta. Las consultas acceden a contexto compacto y pre-digerido en lugar de resumir registros crudos en cada solicitud.
• Razonamiento consciente de grafos — el grafo de entidades construido junto a la wiki permite que el router de consultas responda preguntas relacionales ("¿quién trabajó en X con Y?") que la RAG vectorial pura no puede resolver bien.

Para una comparación detallada con otras herramientas de conocimiento LLM, consulta la página de comparación en el sitio de documentación.

---

🚀 Inicio rápido

Beever Atlas se distribuye como un stack de Docker Compose (backend + bot + web + 4 almacenes de datos). Puedes probar una demo con datos precargados en 30 segundos sin claves, y luego elegir entre tres opciones de implementación para instalarlo de verdad.

1. Obtén el código

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

2. Prueba la demo primero (opcional, sin claves necesarias para la precarga)

make demo

make demo arranca el stack completo precargado con un corpus público de Wikipedia (Ada Lovelace + historia de Python). La precarga usa fixtures precalculados — no se requieren claves API. Hacer preguntas mediante /api/ask requiere una GOOGLE_API_KEY de nivel gratuito porque el agente de QA llama a Gemini. Consulta demo/README.md para ejemplos con curl.

Omita este paso si está listo para instalar de verdad.

3. Antes de comenzar: obtén tus claves API

Se requieren dos claves gratuitas antes de instalar. Ambas ofrecen niveles gratuitos generosos — suficientes para sincronizar los canales de un equipo pequeño para pruebas.

Clave	Propósito	Dónde obtenerla
GOOGLE_API_KEY	Gemini — extracción, grafo de entidades, respuestas	aistudio.google.com/apikey
JINA_API_KEY	Embeddings Jina v4 (2048-dim) para búsqueda semántica	jina.ai/api-dashboard

Opcional (omítelas a menos que sepas que las necesitas):

Clave	Qué habilita
TAVILY_API_KEY	Búsqueda web externa cuando la confianza de recuperación de QA es baja — tavily.com
OLOSTEP_API_KEY	Búsqueda web de Olostep (alternativa a Tavily). Establece WEB_SEARCH_PROVIDER=olostep en tu .env — olostep.com/dashboard
Tokens de bot Slack / Discord / Teams	Se configuran a través de la interfaz web después de la instalación, no en .env — el bot almacena las credenciales de la plataforma cifradas en MongoDB

Consejo: Ten a mano las dos claves requeridas antes de comenzar. La opción 1 las solicita interactivamente; las opciones 2 y 3 requieren que las pegues en .env.

4. Elige una opción de implementación

Opción	Cuándo usarla	Tiempo para "levantar"
1. Instalación de una línea (recomendada)	Quieres la ruta más rápida a un stack en funcionamiento.	~2 min primera ejecución
2. Docker manual	Entornos CI/CD, de operaciones, o cuando quieres control explícito sobre cada paso.	~3 min primera ejecución
3. Desarrollo local	Contribuyentes activos que necesitan recarga en caliente en backend y frontend.	varía

Opción 1 — Instalación de una línea (recomendada)

./atlas

El instalador atlas te guía a través de una lista de verificación de 5 pasos:

1. Modelo de embeddings — elige un proveedor (Jina / OpenAI / Cohere / Voyage / Gemini / Mistral / Ollama), y luego su clave API.
2. Proveedor LLM del agente — elige un proveedor para los 16 agentes ADK (Google Gemini / OpenAI / Anthropic / Mistral / DeepSeek / Groq / MiniMax / Ollama / Personalizado); proveedor opcional secundario para configuraciones híbridas.
3. Backend de grafos — Neo4j (predeterminado) u omitir.
4. Integraciones opcionales — búsqueda web de Tavily, servidor MCP para Claude Code / Cursor.
5. Tokens de autenticación — mantén los valores predeterminados de desarrollo o rótalos ahora.

Internamente verifica docker + docker compose, copia .env.example → .env (conserva tus valores al re-ejecutar, chmod 600), genera automáticamente CREDENTIAL_MASTER_KEY (hex de 64) y WEAVIATE_API_KEY (hex de 32), ejecuta una verificación previa de conflictos de puertos, lanza el stack mediante docker compose up -d --build --force-recreate --remove-orphans, y sondea /api/health antes de imprimir la tarjeta de listo.

Cuando veas "Beever Atlas está listo", abre http://localhost:3000 — luego Configuración → Configuración de IA para gestionar proveedores, asignar LLMs por agente, ejecutar Prueba de conexión o descubrir modelos. Para CI / Docker / GitOps, configura declarativamente: BEEVER_LLM_API_KEY=... (acceso directo de un solo proveedor), BEEVER_ENDPOINTS='[...]' + BEEVER_PRESET=..., o confirma un atlas.yaml y ejecuta atlas apply — consulta docs/runbooks/ai-setup.md y docs/runbooks/atlas-yaml.md.

Para CI o instalaciones sin supervisión — omite los avisos, precarga claves desde el entorno del shell:

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

Re-ejecutar ./atlas en un stack existente es idempotente.

Opción 2 — Docker manual

Control total, paso a paso.

cp .env.example .env

Abre .env y completa las dos claves requeridas:

GOOGLE_API_KEY=your_gemini_key
JINA_API_KEY=your_jina_key

Genera dos secretos requeridos y pégalos en .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))"

Lanza:

docker compose up -d --build

Abre http://localhost:3000.

Servicios iniciados:

Servicio	Puerto	Descripción
Web (nginx)	:3000	Panel de React
Backend	:8000	Agentes FastAPI + ADK
Bot	:3001	Puente de plataformas (Slack / Discord / Teams)
Weaviate	:8080	Memoria semántica
Neo4j	:7474 / :7687	Memoria de grafos
MongoDB	:27017	Estado + caché de wiki
Redis	:6380	Sesiones (interno :6379)

La primera ejecución tarda 2–3 minutos mientras se construyen las imágenes y se inicializan las bases de datos. Las ejecuciones posteriores arrancan en segundos.

Opción 3 — Desarrollo local

Bases de datos en Docker, servicios de aplicación nativos para recarga en caliente.

Requisitos previos: Python 3.12+ con 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

Abre http://localhost:5173 (el puerto de desarrollo de Vite — no :3000).

El servidor de desarrollo de Vite hace de proxy de /api/* a http://localhost:8000 (configurado mediante VITE_API_URL).

Antes de pasar a producción

Los valores predeterminados de .env.example están ajustados para pruebas locales. Antes de cualquier despliegue real, rota los secretos que se distribuyen con valores de marcador de posición y cambia la variable de entorno:

Qué cambiar	Por qué	Cómo
BEEVER_API_KEYS, BEEVER_ADMIN_TOKEN	Se distribuyen como dev-key-change-me / dev-admin-change-me — marcadores públicos	python -c "import secrets; print(secrets.token_hex(24))" por token
BRIDGE_API_KEY	Secreto compartido entre backend y bot; vacío por defecto, obligatorio fuera del desarrollo local	Mismo secrets.token_hex(24)
VITE_BEEVER_API_KEY, VITE_BEEVER_ADMIN_TOKEN	Vite los incrusta en el bundle web en tiempo de compilación — deben reflejar los valores rotados del backend anteriores	Copia los valores rotados de BEEVER_API_KEYS / BEEVER_ADMIN_TOKEN
NEO4J_PASSWORD + la mitad de contraseña de NEO4J_AUTH	La contraseña de desarrollo es pública en este repositorio	Elige una contraseña segura; ambos valores deben coincidir
BEEVER_ENV=production	Activa un arranque fail-fast que rechaza todos los valores predeterminados de desarrollo anteriores	Cambia el valor en .env

La opción 1 (./atlas) gestiona todo esto mediante el aviso "Rotate auth tokens" en el paso 4 de la lista de verificación — responde Y y el instalador genera tokens aleatorios y replica los valores VITE_* por ti. Si usaste la opción 2 o 3, puedes volver a ejecutar ./atlas sobre el .env existente, omitir todos los demás avisos con Enter y aceptar solo el aviso de rotación.

5. Abre el panel

Navega a la URL de la opción elegida:

• Opciones 1 y 2 → http://localhost:3000
• Opción 3 → http://localhost:5173

Desde allí:

• Modo real (predeterminado, ADAPTER_MOCK=false): conecta un espacio de trabajo en Settings → Connections — los tokens de Slack / Discord / Teams se introducen a través de la interfaz, no mediante .env.
• Modo simulado (ADAPTER_MOCK=true): usa datos de prueba — actívalo para iterar en la interfaz local sin credenciales de plataforma.

6. Sincroniza un canal

Desde el panel: Connections → Add Workspace → Select channels → Sync.

O mediante API (extrae automáticamente tu token bearer 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)"

Los medios compartidos en canales sincronizados (imágenes, PDFs, vídeo) se persisten de forma duradera para que sigan renderizándose después de que expire el enlace CDN de la plataforma. Por defecto usa almacenamiento en la base de datos sin infraestructura adicional, y puede usar MinIO/S3 a escala. Consulta docs/media-persistence.md para el mecanismo, la configuración de CHANNEL_MEDIA_*, el backend MinIO/S3 y el relleno retroactivo de canales existentes.

Servidor MCP (para agentes de IA externos)

Beever Atlas expone un servidor MCP (Model Context Protocol) seleccionado en /mcp para agentes de IA como Claude Code y Cursor. Esto permite que los asistentes de código externos consulten la base de conocimiento de tu equipo sin usar el panel.

Consulta docs/mcp-server.md para:

• Catálogo de herramientas — 28 herramientas para descubrimiento, recuperación, lectura de wiki, recorrido de grafos y operaciones de larga duración
• Configuración de autenticación — generación y gestión de BEEVER_MCP_API_KEYS
• Configuración de cliente — plantillas .mcp.json listas para usar en Claude Code y Cursor
• Límites de tasa — límites por principal para evitar que un agente limite a otros

También incluye un modo stdio independiente (python -m beever_atlas.api.mcp_server / beever-atlas-mcp) que expone el mismo catálogo de herramientas sin servidor HTTP ni almacenes subyacentes — útil para registros MCP (Glama.ai) e introspección local. Consulta docs/mcp-server.md.

Ejemplo rápido (Claude Code):

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

Comandos comunes

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`

---

🔒 Privacidad y telemetría

Beever Atlas no recopila telemetría. No se envían datos de uso, informes de errores ni análisis a ningún sitio por defecto. Todas las llamadas LLM pasan por claves API que configuras en tu propio .env, y todos los datos permanecen en las bases de datos que controlas.

---

📐 Estabilidad de la API

Todos los endpoints de /api/* son INESTABLES en 0.1.0. v0.2.0 introducirá un prefijo /api/v1/*; los clientes que fijen las rutas actuales se romperán. Consulta SECURITY.md.

---

💬 Comunidad y contacto

• Discord: discord.gg/VshBCUUX — obtén ayuda, comparte lo que estás construyendo, habla con el equipo
• X / Twitter: @Beever_AI — notas de versión, publicaciones, anuncios
• Sitio web: beever.ai — sobre la empresa y otros proyectos
• Debates de GitHub: github.com/Beever-AI/beever-atlas/discussions — preguntas e ideas más extensas

Soporte comercial, alianzas o prensa: tech@beever.ai.

---

📜 Licencia

Apache License 2.0 © 2026 colaboradores de Beever Atlas. Atribuciones de terceros en NOTICE.

Política de seguridad: SECURITY.md | Estándares de la comunidad: CODE_OF_CONDUCT.md