foundation

個人用の長期記憶基盤。Obsidian Vault・Claude Code のセッション履歴・会議録などを PostgreSQL + Qdrant に取り込み、MCP (Model Context Protocol) サーバー経由で Claude / ChatGPT 等の LLM クライアントから検索・書き込みできるようにする。 GPU を要するモデル (埋め込み・リランカ・文字起こし・OCR) は専用スケジューラに集約し、 複数サービスから排他制御された状態で共有する。

このリポジトリは個人利用向けに開発されたものの公開用コピーであり、大学 LMS 連携など 一部モジュールは公開版から除外されている。詳細は本文末尾の「注意事項」を参照。

目次

• アーキテクチャ

• 主要機能 (MCP ツール)

• 技術スタック

• セットアップ

• 設定

• ディレクトリ構成

• 注意事項

Related MCP server: engram

アーキテクチャ

構成要素とその役割:

                    ┌─────────────────────────────────────────┐
                    │      Claude Code / claude.ai / ChatGPT   │
                    └───────────────────┬───────────────────────┘
                                        │ MCP (stdio / streamable-http)
                                        ▼
                    ┌─────────────────────────────────────────┐
                    │   src/mcp_server.py  (140 tools)         │
                    │   ・OAuth 2.0 Authorization Server        │
                    │     (src/oauth_provider.py, Google Sign-In)│
                    └──────┬───────────────┬──────────┬────────┘
                            │               │          │
                            ▼               ▼          ▼
                    ┌───────────┐   ┌────────────┐  ┌─────────────┐
                    │ PostgreSQL │   │   Qdrant    │  │ gpu-scheduler│
                    │ (turns,    │   │ (knowledge / │  │  :9400 HTTP  │
                    │  facts,    │   │  sessions    │  │  FastAPI     │
                    │  tasks...) │   │  collections)│  │ (排他キュー) │
                    └───────────┘   └────────────┘  └──────┬───────┘
                                                             │
                                    ┌────────────────────────┼───────────────────┐
                                    ▼                        ▼                    ▼
                            埋め込み/リランカ           音声認識/話者分離        OCR
                       (Ruri-v3, embedder.py /     (Kotoba-Whisper, NeMo    (Surya OCR)
                        reranker.py)                TitaNet, Silero-VAD)

他に、以下の常駐/バッチプロセスが同じ DB / Qdrant / gpu-scheduler を共有する。

• src/meeting_server.py + src/meeting_pipeline.py (FastAPI, port 8315): 会議録音の WebSocket ストリーミング取り込みから話者分離・構造化要約・矛盾検出までを行う。

• src/session_watcher.py / src/session_ingest.py / src/conversation_indexer.py: Claude Code の JSONL セッションログを監視・解析し、ファクト抽出とベクトル化を行う。

• src/indexer.py: Obsidian Vault の Markdown を差分検知 → チャンク分割 → 埋め込み → PostgreSQL/Qdrant への upsert を行う定期インデクサ。

• src/orchestrator/: tmux 上に Claude Code エージェントを spawn し、長期記憶を 注入した状態で走らせ、完了後に結果を回収する (agent_* MCP ツール群)。

• src/dashboard_server.py (port 8600): PostgreSQL を読み取り専用で参照する管理コンソール。

• src/morning_digest/: Slack/Discord/Teams 等のメッセージを DSL ルールに基づき スコアリングし、朝刊として Discord に配信するバッチジョブ。

• src/deep_research.py: MCP ツール呼び出しをトリガーに Web 検索・要約を行い、 結果を Vault に保存する自律調査エンジン。

• src/defrag.py: 週次メンテナンス (vacuum, orphan cleanup, embedding integrity check)。

• frontend-meeting/ (React + Vite): meeting-app 用フロントエンド。

主要機能 (MCP ツール)

src/mcp_server.py に @mcp.tool() で登録されている MCP ツールは 140 個 (実カウント)。 src/mcp_categories.py により、ツール名のプレフィックスで以下のカテゴリに分割され、 ChatGPT 等のツール数上限に合わせて複数のコネクタ (/ops/mcp, /sheets/mcp, ...) として 公開することもできる (FOUNDATION_MCP_SPLIT=1)。フル機能の単一エンドポイント (/mcp) は Claude Code / claude.ai 向けに常時提供される。

技術スタック

• 言語: Python 3.13 (バックエンド), TypeScript / React 19 + Vite (フロントエンド)

• MCP サーバー: mcp SDK (streamable-http / stdio 両対応)、独自 OAuth 2.0 Authorization Server

• Web フレームワーク: FastAPI + uvicorn (meeting-server / gpu-scheduler)

• データベース: PostgreSQL 17 (会話・ファクト・タスク等の構造化データ)

• ベクトル検索: Qdrant (knowledge / sessions コレクション、ハイブリッド検索 + RRF)

• 埋め込み/リランカ: cl-nagoya/ruri-v3-310m (sentence-transformers)

• 音声認識: Kotoba-Whisper (whisper.cpp 経由)、NeMo (TitaNet 話者ID / MSDD)、Silero-VAD

• OCR: Surya OCR (surya-ocr)

• LLM 呼び出し: ローカル (Ollama / llama-server, Qwen3.6 系) + 外部 OpenAI 互換 エンドポイント経由の外部モデル (任意設定)

• コンテナ: Docker Compose (postgres, qdrant, gpu-scheduler, meeting-app, caddy)

• リバースプロキシ: Caddy 2 (HTTPS, Tailscale tailnet 経由での公開を想定)

セットアップ

前提

• Docker / Docker Compose v2

• NVIDIA GPU + nvidia-container-toolkit (gpu-scheduler を Docker で動かす場合)

• ホスト側で Ollama (0.0.0.0:11434) が起動していること

• 外部 OpenAI 互換エンドポイント (既定 0.0.0.0:8317、OPENAI_COMPAT_URL で変更可) を 使う機能を有効にする場合は、そのエンドポイントが起動していること (ローカル LLM のみで運用する場合は不要)

• Python 3.13、Node.js 22 (ホストで直接実行する場合)

1. リポジトリ取得と依存インストール (ホストで直接実行する場合)

python3.13 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

GPU / meeting-app の各サービスを個別に Docker ビルドする場合は docker/requirements-gpu.txt / docker/requirements-meeting.txt がそれぞれのイメージでインストールされる (トップレベル requirements.txt はホストでの 直接実行・開発用の統合版)。

2. PostgreSQL / Qdrant

Docker Compose 経由で起動する場合は次の手順のみで済む (docker/init-db.sql が 初回起動時にスキーマを自動作成する)。ホストに直接インストールする場合は PostgreSQL 17 系と Qdrant を用意し、config.yaml の database セクションと config/qdrant.yaml に合わせて設定する。

3. 環境変数ファイル

docker/.env (gitignore 対象、リポジトリには含まれない) を作成し、最低限 POSTGRES_PASSWORD と DATABASE_URL を設定する。

cat > docker/.env <<'EOF'
POSTGRES_DB=foundation
POSTGRES_USER=user
POSTGRES_PASSWORD=change-me
DATABASE_URL=postgresql://user:change-me@postgres:5432/foundation
VAULT_OUTPUT_HOST_DIR=/path/to/your/obsidian/vault
MODEL_CACHE_HOST_DIR=/path/to/huggingface/cache
EOF

4. docker-compose での起動

# 全サービスをコンテナで起動 (GPU コンテナは nvidia-container-toolkit が必要)
docker compose --env-file docker/.env up -d

# PostgreSQL/Qdrant/gpu-scheduler をホスト側 systemd 等で既に動かしている場合は
# docker-compose.override.yml で該当コンテナを無効化できる
docker compose --env-file docker/.env -f docker-compose.yml -f docker-compose.override.yml up -d

HTTPS 終端が必要な場合は docker/Caddyfile.example を docker/Caddyfile にコピーし、 basic_auth のハッシュ等プレースホルダを実値に置き換える (docker/Caddyfile は gitignore 対象)。

5. Claude Code への MCP サーバー登録 (stdio)

python src/mcp_server.py              # stdio モード
python src/mcp_server.py http         # streamable-http + OAuth モード (claude.ai 等向け)

Claude Code の mcp 設定に、上記コマンドを stdio サーバーとして登録する。

設定

config.yaml

トップレベルの config.yaml は個人パス (~/Documents/obsidian/vault 等) や ユーザー名を汎用プレースホルダに置き換えたダミー値のみで構成されており、そのまま 利用開始できる。主な項目:

• vault: Obsidian Vault のルートパスと索引除外パターン

• database: PostgreSQL / Qdrant の接続先とコレクション定義

• embedding / search.rerank: 埋め込み・リランカモデルとハイブリッド検索のパラメータ

• gpu_scheduler: GPU メモリ管理の advisory 値

• llm: 用途別 (realtime / batch / meeting.*) の LLM モデル割当と生成パラメータ

• whisper: 音声認識モデルと言語設定

• maintenance: 週次メンテナンスのスケジュール

実運用のパス (Vault の実際の場所、モデルキャッシュの場所等) は環境変数 (VAULT_OUTPUT_HOST_DIR 等、docker-compose.yml 参照) または config.yaml 本体を 自分の環境に合わせて編集して指定する。

主な環境変数

これ以外にも WHISPER_* / RRF_* / MEETING_V2_* / RERANK_* 等、機能ごとの チューニング用環境変数が多数存在する。既定値は各モジュールのソース (os.getenv 呼び出し 箇所) を参照。

ディレクトリ構成

.
├── bin/                    運用スクリプト (Discord webhook 登録、通知用ラッパー等)
├── config/                 Qdrant 設定 (config/qdrant.yaml)
├── config.yaml             アプリケーション設定 (DB接続・モデル・スケジューラ等)
├── docker/                 Dockerfile 2 種、サービス別 requirements、Caddyfile 例、init-db.sql
├── docs/                   設計・レビュー・テスト計画ドキュメント
├── frontend-meeting/       meeting-app 用フロントエンド (React + Vite)
├── src/                    Python バックエンド一式
│   ├── mcp_server.py       MCP サーバー本体 (140 tools)
│   ├── meeting_server.py   会議録音処理サーバー
│   ├── meeting_pipeline.py 会議処理パイプライン (v2〜v5)
│   ├── gpu_scheduler_server.py  GPU タスクの排他スケジューラ
│   ├── indexer.py          Vault インデクサ
│   ├── orchestrator/       tmux エージェント spawn/管理
│   ├── morning_digest/     朝刊集約バッチ
│   └── ...
├── tests/                  pytest テスト一式 (レイヤ別統合テスト、PII マスキングテスト等)
├── docker-compose.yml       本番構成 (全サービスをコンテナで起動)
├── docker-compose.override.yml  ホスト常駐サービスを使う場合の上書き構成
├── requirements.txt         統合 Python 依存 (本リポジトリ整備で新規作成)
└── pytest.ini

注意事項

• 本リポジトリは個人 (1 ユーザー) の長期記憶基盤として開発されたものであり、 マルチテナント運用や不特定多数の同時利用は想定していない。OAuth の承認も 単一のメールアドレス allow-list (FOUNDATION_ALLOWED_EMAILS) を前提とした設計。

• 公開版では大学 LMS (TLMS) 連携モジュール等、個人・所属先に紐づく一部モジュールを 除外している。config.yaml や各モジュールのコメントに元機能への言及が残っている 箇所があるが、対応する実装ファイルは本リポジトリに含まれない。

• 公開版では iPhone PWA バックエンドと専用フロントエンドを除外している。 meeting-app 等の他機能が使う外部 LLM 呼び出しは、任意の外部 OpenAI 互換エンドポイント (OPENAI_COMPAT_URL) を指す汎用 HTTP クライアントに一般化済み。

• 実運用には GPU (音声認識/OCR/埋め込み用)、Tailscale 等の tailnet、ローカル LLM サーバー (Ollama / llama-server) など、このリポジトリ単体では完結しない周辺環境が 必要になる。