beever-atlas

 Beever Atlas

チームの Slack、Discord、Teams、Mattermost のチャットを
自動で更新される Wiki に変換します。

---

Beever Atlas は、チームが Slack、Discord、Microsoft Teams、Mattermost ですでに交わしている会話を取り込み、個々の事実を抽出して重複を除去し、出典を付けたトピックページにまとめます。グラフストアが、各チャンネルで言及された人々、決定事項、プロジェクトを相互に関連付けます。自然言語で質問すると、ダッシュボードから、または MCP を介して Claude Code や Cursor から、元のメッセージを出典として示す回答を得られます。

チームがすでに交わしているチャットから自動で成長するナレッジベースをお探しなら、これがその答えです。

---

✨ 動作中の機能

6本の短い動画で、ワークスペースへの接続、履歴の同期、メモリの構築、自動生成された Wiki の閲覧、質問、MCP 経由での外部 AI エージェントの接続をご紹介します。

マルチプラットフォーム Slack、Discord、Teams、Mattermost、またはファイルのインポートで接続できます。1つのボットですべてのワークスペースに対応します。	メッセージ同期 必要に応じて、またはスケジュールに従ってチャンネル履歴を取得します。中断したところから再開でき、レート制限にも対応しています。	メモリの取り込み 6段階の ADK パイプラインが、メッセージを原子的な事実、エンティティ、関係性に抽出します。
LLM Wiki チャンネルごとに自動更新される Wiki を提供します。概要、トピック、人物、決定事項、引用を確認できます。	QA エージェント 出典付きの回答を SSE 経由でストリーミングします。スマートルーターが質問ごとにセマンティック検索またはグラフ検索を選択します。	MCP サーバー Claude Code / Cursor をナレッジベースに接続できます。28個のツールとエージェントごとの認証に対応しています。

---

🏗️ アーキテクチャ

サポート対象のあらゆるプラットフォームの会話が、統合された取り込みパイプラインに流れ込み、相互補完する2つのメモリシステムを生成します。高速なハイブリッド検索を実現する3階層のセマンティックストア（チャンネル／トピック／原子的な事実）と、エンティティおよびその関係性を抽出するグラフストアです。これらのメモリは、2つの利用者向け機能、すなわちLLM Wiki（要約され、自動的に更新）とQA エージェント（ダッシュボードから直接、または MCP 経由で Claude Code / Cursor を通じて提供）を支えます。

チャットプラットフォームから MCP エージェントまで、1つの取り込み経路、2つのメモリシステム、2つの提供先です。

内部では、3つのサービス（バックエンド、ボット、フロントエンド）が4つのデータストア（Weaviate、Neo4j、MongoDB、Redis）によって支えられています。全体設計（コンポーネントの役割、デュアルメモリの内部構造、スマートクエリルーター）については、ドキュメントサイトのアーキテクチャの概要をご覧ください。

---

💡 Wiki ファースト RAG を選ぶ理由

ほとんどの RAG システムは、質問に答えるために生のメッセージの断片を検索し、そのまま LLM に渡します。Beever Atlas は異なるアプローチを採用しています。クエリを発行する前に、会話をトピックページ、エンティティグラフ、決定事項、引用を備えた、構造化され自動で保守される Wiki に継続的にまとめます。質問すると、検索レイヤーはノイズの多いチャット履歴ではなく、整理され重複が除かれたナレッジを対象に処理します。これにより、回答の一貫性が高まり、引用元をソースメッセージまでたどれるようになり、Wiki 自体も Q&A インターフェースとは別にチームが閲覧できる便利な成果物になります。デュアルメモリアーキテクチャ（セマンティック＋グラフ）により、クエリルーターは質問ごとに適切な検索戦略を選択でき、低レイテンシーと正確なコンテキストを維持できます。

246 件の Slack メッセージからまとめられた、実際に自動生成されたチャンネル Wiki。手書きではなく、概要、コンセプトマップ、トピック、FAQ、用語集を備えています。

インスピレーション：LLM が読むのはチャットログではなく Wiki

チャンネルごとの Wiki というコンセプトは、LLM は生の会話記録よりも、編集・整理された百科事典的なコンテンツ（書籍、ドキュメント、Wiki）を使った推論がはるかに得意だという Andrej Karpathy の指摘から直接着想を得ています。チャット履歴にはノイズや重複が多く、時系列に散らばっており、人間だけが解消できる暗黙のコンテキストも多く含まれています。一方 Wiki は、そのナレッジをすでにまとめた形です。重複が除かれ、構造化され、引用を含み、タイムスタンプではなくトピック別に整理されています。

Beever Atlas はこの考え方を実用化しています。同期されたすべてのチャンネルに、トピック、エンティティ、決定事項、未解決の質問、タイムラインのセクションを持つ、自動生成され継続的に更新される Wikiが用意され、新しいメッセージが届くたびに段階的に再構築されます。QA エージェントはまずこの Wiki を対象に検索し、事実がまだまとめられていない場合に限り、生のメッセージを検索します。

実際に得られること

• より良い回答と、より少ないハルシネーション — 検索対象は、断片化されたターンごとのチャットではなく、エンティティ間の関係が明示された、事実密度の高い文章です。
• 追跡可能な引用 — Wiki 内のすべての主張は、その根拠となったソースメッセージにリンクされているため、回答を元の Slack／Discord／Teams スレッドまで監査できます。
• Q&A ボックスだけではなく、閲覧できる成果物 — Wiki はそれ自体が役立ちます。チャンネルに参加した新しいチームメンバーは、3 か月分の履歴をスクロールする代わりに、整理された Wiki を読めます。
• クエリ実行時の推論コストを削減 — コストのかかる情報の整理は、取り込み時に一度だけ行われます。クエリは、リクエストのたびに生ログを再要約するのではなく、コンパクトに事前処理されたコンテキストを参照します。
• グラフを活用した推論 — Wiki とともに構築されるエンティティグラフにより、純粋なベクトル RAG では苦手な関係性に関する質問（「X について Y と一緒に作業したのは誰か？」など）にも、クエリルーターが回答できます。

他の LLM ナレッジツールとの詳しい比較については、ドキュメントサイトの比較ページをご覧ください。

---

🚀 クイックスタート

Beever Atlas は Docker Compose スタック（バックエンド＋ボット＋Web＋4 つのデータストア）として提供されます。まずはキー不要で 30 秒でシード済みデモを試し、その後、3 つのデプロイオプションから選んで実際にインストールできます。

1. コードを取得する

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

2. まずデモを試す（任意。シードにキーは不要です）

make demo

make demo を実行すると、公開されている Wikipedia コーパス（Ada Lovelace と Python の歴史）があらかじめ読み込まれたフルスタックが起動します。シードには事前計算済みのフィクスチャを使用するため、API キーは必要ありません。/api/ask 経由で質問するには、QA エージェントが Gemini を呼び出すため、無料枠の GOOGLE_API_KEY が必要です。curl の使用例は demo/README.md をご覧ください。

実際にインストールする準備ができている場合は、この手順をスキップしてください。

3. 始める前に：API キーを取得する

インストール前に、無料のキーを2つ用意する必要があります。どちらも無料枠が充実しており、小規模なチームのチャンネルをテスト用に同期するには十分です。

キー	用途	取得先
GOOGLE_API_KEY	Gemini — 抽出、エンティティグラフ、回答	aistudio.google.com/apikey
JINA_API_KEY	セマンティック検索用 Jina v4 埋め込み（2048 次元）	jina.ai/api-dashboard

任意（必要だとわかっている場合を除き、設定を省略してください）：

キー	有効になる機能
TAVILY_API_KEY	QA 検索の信頼度が低い場合の外部ウェブ検索 — tavily.com
OLOSTEP_API_KEY	Olostep ウェブ検索（Tavily の代替）。.env に WEB_SEARCH_PROVIDER=olostep を設定してください — olostep.com/dashboard
Slack / Discord / Teams のボットトークン	セットアップ後にウェブ UI から設定します。.env ではありません — ボットはプラットフォームの認証情報を暗号化して MongoDB に保存します

ヒント： 始める前に、必須の2つのキーを手元に用意してください。オプション1では対話形式で入力を求められます。オプション2と3では、キーを .env に貼り付ける必要があります。

4. デプロイオプションを選択する

オプション	用途	起動までの時間
1. 1行インストール（推奨）	スタックを最速で稼働させたい場合。	初回は約2分
2. Docker の手動設定	CI/CD、運用環境、または各手順を明示的に制御したい場合。	初回は約3分
3. ローカル開発	バックエンドとフロントエンドのホットリロードが必要なアクティブなコントリビューター向け。	環境によって異なります

オプション1 — 1行インストール（推奨）

./atlas

atlas インストーラーが、5つの手順からなるガイド付きチェックリストを表示します。

1. 埋め込みモデル — プロバイダー（Jina / OpenAI / Cohere / Voyage / Gemini / Mistral / Ollama）を選び、API キーを入力します。
2. エージェント LLM プロバイダー — 16個の ADK エージェント用のプロバイダー（Google Gemini / OpenAI / Anthropic / Mistral / DeepSeek / Groq / MiniMax / Ollama / Custom）を選びます。ハイブリッド構成用に、2つ目のプロバイダーを追加することもできます。
3. グラフバックエンド — Neo4j（デフォルト）を選ぶか、省略します。
4. 任意の連携機能 — Tavily ウェブ検索、Claude Code / Cursor 用 MCP サーバー。
5. 認証トークン — 開発用のデフォルト値を使うか、ここで変更します。

内部では、docker と docker compose を確認し、.env.example を .env にコピーします（再実行時は既存の値を保持し、chmod 600 を実行します）。CREDENTIAL_MASTER_KEY（64桁の16進数）と WEAVIATE_API_KEY（32桁の16進数）を自動生成し、ポート競合の事前チェックを行ったうえで、docker compose up -d --build --force-recreate --remove-orphans によりスタックを起動します。その後、/api/health をポーリングして、準備完了カードを表示します。

「Beever Atlas is ready」 と表示されたら、http://localhost:3000 を開き、Settings → AI Setup からプロバイダーを管理したり、エージェントごとに LLM を割り当てたり、接続テストを実行したり、モデルを検出したりできます。CI / Docker / GitOps では、宣言的に設定してください。BEEVER_LLM_API_KEY=...（単一プロバイダー用の簡易設定）、BEEVER_ENDPOINTS='[...]' + BEEVER_PRESET=... を指定するか、atlas.yaml をコミットして atlas apply を実行します。詳しくは docs/runbooks/ai-setup.md と docs/runbooks/atlas-yaml.md を参照してください。

CI または無人インストールの場合は、プロンプトを省略し、シェル環境からキーを事前設定します。

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

既存のスタックに対して ./atlas を再実行しても、冪等に処理されます。

オプション 2 — Docker を手動で使用

手順に沿って、すべてを自分で管理できます。

cp .env.example .env

.env を開き、必須の 2 つのキーを入力します。

GOOGLE_API_KEY=your_gemini_key
JINA_API_KEY=your_jina_key

必須のシークレットを 2 つ生成し、.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))"

起動します。

docker compose up -d --build

http://localhost:3000 を開きます。

起動するサービス：

サービス	ポート	説明
Web（nginx）	:3000	React ダッシュボード
バックエンド	:8000	FastAPI + ADK エージェント
Bot	:3001	プラットフォームブリッジ（Slack / Discord / Teams）
Weaviate	:8080	セマンティックメモリ
Neo4j	:7474 / :7687	グラフメモリ
MongoDB	:27017	状態 + wiki キャッシュ
Redis	:6380	セッション（内部ポート :6379）

初回起動では、イメージのビルドとデータベースの初期化に 2～3 分かかります。2 回目以降は数秒で起動します。

オプション 3 — ローカル開発

データベースは Docker で、アプリのサービスはホットリロード可能なネイティブ環境で実行します。

前提条件： Python 3.12+ と 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

http://localhost:5173 を開きます（Vite の開発ポートです。:3000 ではありません）。

Vite 開発サーバーは /api/* を http://localhost:8000 にプロキシします（VITE_API_URL で設定）。

本番環境に移行する前に

.env.example のデフォルト値はローカルテスト用に調整されています。実際にデプロイする前に、プレースホルダー値が設定されたシークレットを必ずローテーションし、環境フラグを切り替えてください。

変更する項目	理由	方法
BEEVER_API_KEYS、BEEVER_ADMIN_TOKEN	dev-key-change-me / dev-admin-change-me が設定されています。これらは公開プレースホルダーです	トークンごとに python -c "import secrets; print(secrets.token_hex(24))" を実行
BRIDGE_API_KEY	バックエンドと Bot 間の共有シークレットです。デフォルトでは空で、ローカル開発以外では必須です	同じ secrets.token_hex(24) を使用
VITE_BEEVER_API_KEY、VITE_BEEVER_ADMIN_TOKEN	Vite はビルド時にこれらを Web バンドルに埋め込むため、ローテーション後の上記バックエンドの値と一致させる必要があります	ローテーション後の BEEVER_API_KEYS / BEEVER_ADMIN_TOKEN の値をコピー
NEO4J_PASSWORD と NEO4J_AUTH のパスワード部分	開発用パスワードはこのリポジトリで公開されています	強力なパスワードを設定します。両方の値を一致させてください
BEEVER_ENV=production	これを有効にすると起動時に即座にエラーとなり、上記の開発用デフォルト値がすべて拒否されます	.env の値を切り替えます

オプション 1（./atlas）では、チェックリストの手順 4 にある 「認証トークンをローテーション」 のプロンプトで、これらすべてに対応できます。Y と答えると、インストーラーがランダムなトークンを生成し、VITE_* の値も合わせて設定します。オプション 2 または 3 を使用した場合は、既存の .env に対して ./atlas を再実行し、ほかのすべてのプロンプトでは Enter を押してスキップしてから、ローテーションのプロンプトだけに同意してください。

5. ダッシュボードを開く

選択したオプションに応じた URL に移動します。

• オプション 1 と 2 → http://localhost:3000
• オプション 3 → http://localhost:5173

ここから次の操作を行えます。

• 実モード（デフォルト、ADAPTER_MOCK=false）：設定 → 接続 でワークスペースを接続します。Slack / Discord / Teams のトークンは .env ではなく、UI から入力します。
• モックモード（ADAPTER_MOCK=true）：フィクスチャデータを使用します。プラットフォームの認証情報なしでローカルの UI を試したい場合に有効にしてください。

6. チャンネルを同期する

ダッシュボードで、接続 → ワークスペースを追加 → チャンネルを選択 → 同期 を選択します。

または、API を使用します（.env から Bearer トークンを自動抽出します）。

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)"

同期したチャンネルで共有されているメディア（画像、PDF、動画）は永続的に保存されるため、プラットフォームの CDN リンクの有効期限が切れた後も表示されます。デフォルトでは追加のインフラを必要としないデータベース内ストレージを使用し、大規模環境では MinIO/S3 を使用できます。仕組み、CHANNEL_MEDIA_* の設定、MinIO/S3 バックエンド、既存チャンネルのバックフィルについては、docs/media-persistence.md を参照してください。

MCP サーバー（外部 AI エージェント向け）

Beever Atlas は、Claude Code や Cursor などの AI エージェント向けに、厳選された MCP（Model Context Protocol）サーバーを /mcp で公開しています。これにより、外部のコーディングアシスタントはダッシュボードを使わずに、チームのナレッジベースを検索できます。

以下をご覧ください：docs/mcp-server.md：

• ツールカタログ — 検索、取得、Wiki の閲覧、グラフのたどり、長時間実行される操作に対応する 28 個のツール
• 認証の設定 — BEEVER_MCP_API_KEYS の生成と管理
• クライアントの設定 — Claude Code と Cursor 向けのすぐに使える .mcp.json テンプレート
• レート制限 — 1 つのエージェントがほかのエージェントの利用を妨げないようにする、プリンシパル単位の制限

HTTP サーバーやバックエンドストアを必要とせず、同じツールカタログを公開するスタンドアロンの stdio モード（python -m beever_atlas.api.mcp_server / beever-atlas-mcp）も付属しています。MCP レジストリ（Glama.ai）やローカルでのイントロスペクションに便利です。詳しくはdocs/mcp-server.mdをご覧ください。

簡単な例（Claude Code）：

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

よく使うコマンド

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`

---

🔒 プライバシーとテレメトリ

Beever Atlas はテレメトリを収集しません。使用状況データ、エラーレポート、分析データがデフォルトで外部に送信されることはありません。すべての LLM 呼び出しは、ご自身の .env で設定した API キーを通じて行われ、すべてのデータはご自身が管理するデータベースに保存されます。

---

📐 API の安定性

0.1.0 のすべての /api/* エンドポイントは不安定です。v0.2.0 では /api/v1/* プレフィックスが導入されます。現在のパスを固定しているクライアントは動作しなくなります。SECURITY.mdをご覧ください。

---

💬 コミュニティとお問い合わせ

• Discord：discord.gg/VshBCUUX — サポートを受けたり、開発中のものを共有したり、チームと話したりできます
• X / Twitter：@Beever_AI — リリースノート、投稿、お知らせ
• ウェブサイト：beever.ai — 会社やその他のプロジェクトについて
• GitHub Discussions：github.com/Beever-AI/beever-atlas/discussions — 詳細な質問やアイデア

商用サポート、パートナーシップ、報道に関するお問い合わせは、[email protected] までご連絡ください。

---

📜 ライセンス

Apache License 2.0 © 2026 Beever Atlas の貢献者。サードパーティの著作権表示は NOTICE に記載されています。

セキュリティポリシー：SECURITY.md | コミュニティ基準：CODE_OF_CONDUCT.md