# Beever Atlas: a wiki-first knowledge base built from Slack, Discord, Teams and Mattermost chats

> Beever Atlas ingests team chat, distils it into atomic facts and topic pages, and answers questions with citations. It is a Python service stack backed by four data stores, and it is heavier to run than a plain RAG demo.

**Beever-AI/beever-atlas** — Your First LLM-Wiki Conversation Knowledge Base

- Repository: https://github.com/Beever-AI/beever-atlas
- Website: https://docs.beever.ai/atlas
- Stars: 448 · Forks: 52
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/beever-ai-beever-atlas

## The problem Beever Atlas targets: chat history that nobody can search

Team knowledge in Slack, Discord, Microsoft Teams and Mattermost decays in a predictable way. A decision gets made in a thread, restated in a standup, contradicted two weeks later in a DM, and the only durable record is a scroll-back that nobody performs. Beever Atlas is aimed at teams that want a knowledge base to grow out of conversations they already had, rather than out of documents someone has to write.

The project's own framing is that most RAG systems retrieve raw message snippets and hand them to a model. Beever Atlas instead distils conversations into a structured wiki before any query is issued, so retrieval works against deduplicated knowledge rather than the noise of chat. The audience is therefore teams with a real chat archive and an operator willing to run infrastructure: the README describes three services (backend, bot, frontend) backed by four data stores (Weaviate, Neo4j, MongoDB, Redis). That is not a laptop-scale footprint, and the repository says so indirectly through its compose file, which caps the API container's memory and explains why.

## How the ingestion pipeline and dual memory actually fit together

Conversations from any supported platform flow into one ingestion path. The README describes a six-stage ADK pipeline that distils messages into atomic facts, entities and relationships. From there the system maintains two complementary stores. The first is a three-tier semantic store (channel, topic, atomic fact) used for hybrid search. The second is a graph store that extracts entities and their relationships, which is what lets the system link people, decisions and projects mentioned across different channels.

Two consumer surfaces sit on top. The LLM Wiki is generated per channel with an overview, topics, people, decisions and citations. QA Agents answer questions over SSE, and the README states a smart router picks semantic or graph retrieval per question. The same knowledge base is exposed through an MCP server, which the README says carries 28 tools with per-agent authentication, so Claude Code or Cursor can query it directly.

The design choice worth noting is the split between semantic and graph memory. It costs you Neo4j in addition to a vector store, and it means two write paths to keep consistent. The payoff is that entity-centric questions (who owns this, what did we decide about that) do not have to be answered by embedding similarity alone. Whether that trade is worth it depends on how much of your chat is about people and ownership rather than topics.

## Installing Beever Atlas with Docker Compose and running a first sync

The .env.example header gives the shortest path: copy the file, fill two keys in section 1.8, and bring the stack up. The two required values are GOOGLE_API_KEY for Gemini and JINA_API_KEY for Jina v4 embeddings. Both are marked as required before first boot.

```bash
cp .env.example .env
docker compose up
```

After the containers start, the API listens on port 8000 (the compose file maps 8000:8000) and the four backing stores must report healthy before it launches, because each dependency uses a service_healthy condition. The compose file also requires WEAVIATE_API_KEY and NEO4J_PASSWORD to be set; it will refuse to start without them rather than fall back to a default.

For a first real use, the repository ships a demo directory with seed scripts and a Discord conversation corpus. The demo compose file is the one to read if you want to see the pipeline work before pointing it at a live workspace.

```bash
cd demo
python seed_discord.py
```

The seed script loads the bundled conversations, after which the memory ingestion pipeline distils them into facts and the wiki pages appear per channel. Expect the first run to be the slowest, because extraction, embedding and OCR work all happen during ingestion.

Before any production deployment, the .env.example lists a rotation checklist: set BEEVER_ENV=production, rotate BEEVER_API_KEYS and BEEVER_ADMIN_TOKEN, rotate NEO4J_AUTH and NEO4J_PASSWORD, and regenerate CREDENTIAL_MASTER_KEY.

```bash
python -c "import secrets; print(secrets.token_hex(32))"
```

That command is the one the environment file itself suggests for generating the credential master key. The VITE_BEEVER_API_KEY and VITE_BEEVER_ADMIN_TOKEN values in section 1.4 must match one of the BEEVER_API_KEYS values, and changing them requires rebuilding the web bundle.

## Where Beever Atlas breaks: memory limits, required keys and empty catalogs

The most concrete limitation is documented in the compose file. The ExtractionWorker runs in-process with the API under uvicorn, and during multi-channel syncs its memory footprint scales with concurrent LLM batches, image OCR and embeddings. The comment states that on a small host, such as a 4 GiB demo box, this can exhaust system RAM: the kernel OOM-kills uvicorn first, and without a restart policy the site stays down. The compose file addresses this with mem_limit and memswap_limit defaults of 2048m and 3072m, both overridable through ATLAS_API_MEM_LIMIT and ATLAS_API_MEMSWAP_LIMIT, plus restart: unless-stopped. If you lower those limits to fit a small machine, ingestion throughput drops, and the environment file points to section 3.8 for low-memory tuning. This is a genuine capacity constraint, not a configuration footnote.

A second failure mode is visible in the Dockerfile. The image copies only two modules from scripts/: migrate_to_endpoint_catalog and reembed_facts. The comment explains that without the first, the first-boot migration fails with ModuleNotFoundError and the operator's UI shows an empty Endpoint catalog. Anyone who trims the Dockerfile or repackages the app has to preserve those two imports.

A third boundary is scope. Beever Atlas is the wrong tool for a team whose knowledge lives in documents, tickets or code rather than chat, and for a single person who wants to query a handful of PDFs. The four-store requirement is disproportionate at that size. It is also the wrong choice if you cannot commit to running Neo4j: the graph memory is not optional decoration, it is one of the two retrieval paths the query router selects between.

## How this differs from a plain RAG pipeline over exported chat logs

The obvious alternative is exporting channel history and feeding it to a general RAG stack: chunk the messages, embed them, store the vectors, retrieve top-k at query time. That approach is simpler to stand up and needs one store instead of four. The difference in behaviour is where the work happens. A plain pipeline defers all distillation to query time, so every question re-derives structure from raw snippets, and the same fact can surface in five near-duplicate chunks.

Beever Atlas moves that work to ingestion. Facts are extracted and deduplicated once, clustered into topic pages, and linked in a graph. The wiki becomes an artifact you can read without asking anything, which a raw vector index does not give you. Citations also come out traceable to source messages by construction, because the wiki pages carry them.

The cost of that choice is latency and operational weight on the write path. Ingestion is where the LLM calls, OCR and embeddings pile up, which is exactly the memory pressure described above. A plain RAG pipeline over the same logs would push that cost to read time and keep the ingest job cheap. If your chat volume is modest and your questions are ad hoc, the simpler design is defensible. If your team keeps re-asking the same questions and wants a browsable record, the wiki-first approach earns its infrastructure.

## Maintenance, upgrade cost and what Apache-2.0 means here

The repository is not archived, and the last push was on 2026-09-09, so the codebase is being touched recently. Release history shows v0.1.1 as the open-source launch in April 2026, v0.1.2 adding the MCP server, and v0.2.0 in May 2026 bringing the wiki narrative engine, an Obsidian-style graph and pluggable embeddings. The pyproject.toml declares version 0.3.0, so the working tree is ahead of the newest published release listed. Treat that gap as a reason to pin a tag or a commit rather than tracking main.

Upgrade cost concentrates in two places. First, the embedding endpoint: the Dockerfile ships reembed_facts because switching an endpoint to a new dimension requires a re-embed pass over stored facts. Changing embedding models is therefore a migration, not a config edit. Second, the dependency graph is pinned tightly. The pyproject.toml comment warns that aioboto3 transitively pins aiobotocore and a compatible botocore, and that adding boto3 or the sync minio SDK alongside it can break imports. Python 3.12 or newer is required.

On licensing, the project is Apache-2.0, which permits commercial use and modification with the usual attribution and notice obligations, and includes a patent grant. The repository also carries a NOTICE file and a separate TRADEMARK.md, so the name and marks are governed separately from the code licence. That is a normal arrangement, but it means a fork can reuse the code without reusing the Beever Atlas name. Nothing here is legal advice; read LICENSE, NOTICE and TRADEMARK.md before redistributing.

## Conclusion

Adopt Beever Atlas if your team already runs Slack, Discord, Teams or Mattermost, you can host Weaviate, Neo4j, MongoDB and Redis, and you want a browsable wiki artifact rather than a chat-over-PDF demo. Do not adopt it if you need a single-binary tool, if your chat history is small enough to read directly, or if you cannot supply GOOGLE_API_KEY and JINA_API_KEY, since the .env.example marks both as required before first boot. Before committing, verify the ingestion memory ceiling on your host by reading section 3.8 of .env.example and the ATLAS_API_MEM_LIMIT defaults in docker-compose.yml, and confirm that your embedding endpoint's dimension matches what reembed_facts expects, because switching it later triggers a re-embed job.

## FAQ

### Is Beever Atlas open source?

Yes. The repository is licensed under Apache-2.0, and the release notes list v0.1.1 as the open-source launch. The code is on GitHub under Beever-AI/beever-atlas with the web, bot, server and deployment files included.

### What is Beever Atlas?

It is a wiki-first knowledge base that pulls conversations from Slack, Discord, Microsoft Teams and Mattermost, extracts atomic facts, deduplicates them and clusters them into cited topic pages. It answers questions through a dashboard or through an MCP server used by Claude Code and Cursor.

### What do I need to run Beever Atlas for the first time?

The .env.example marks GOOGLE_API_KEY and JINA_API_KEY as required before first boot, and the compose file requires WEAVIATE_API_KEY and NEO4J_PASSWORD to be set. The stack also needs Weaviate, Neo4j, MongoDB and Redis running, which docker-compose.yml starts for you.

### How much memory does Beever Atlas need?

The compose file defaults the API container to mem_limit 2048m and memswap_limit 3072m, both overridable via ATLAS_API_MEM_LIMIT and ATLAS_API_MEMSWAP_LIMIT. Its comment states that during multi-channel syncs the in-process ExtractionWorker can exhaust RAM on a small host, which is why those caps exist.

### Can I change the embedding model in Beever Atlas after ingesting data?

The Dockerfile ships scripts/reembed_facts.py as the re-embed worker used when an operator switches the embedding Endpoint to a new dimension, so the change is handled as a migration job rather than a config edit. The pyproject.toml and release notes describe embeddings as pluggable.

## Sources

- [Beever-AI/beever-atlas on GitHub](https://github.com/Beever-AI/beever-atlas)
- [License: Apache-2.0](https://github.com/Beever-AI/beever-atlas/blob/main/LICENSE)
- [Project website](https://docs.beever.ai/atlas)
- [README](https://github.com/Beever-AI/beever-atlas/blob/main/README.md)
- [Releases](https://github.com/Beever-AI/beever-atlas/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/beever-ai-beever-atlas