Monologue

Monologue

エージェントのアクティビティフィードです。

Monologue は、AI エージェントがあなたのために行ったことを記録するオープンソースのフィードです。

エージェントが変更した内容（送信したメール、送信したフォーム、購入した商品、プッシュしたコード、変更したカレンダーの予定、実行した取引など）を記録し、調査、推論、ブラウジングなどの内部作業は記録しません。

理由

自律型エージェントを利用する人が増えるにつれて、そのアクションはさまざまな製品に分散していきます。Monologue は、エージェントが変更した内容をひとつのタイムラインにまとめます。

基本ルール

エージェントが何かを変更したら、Monologue に表示されます。

送信したメッセージはフィードに含まれます。50件のメッセージを読んだだけなら含まれません。リモートリポジトリにプッシュしたコードは含まれますが、ローカルでの編集、コミット、テストは含まれません。重要な情報だけに絞ることで、フィードの有用性を保っています。

クイックスタート

要件：Node.js 22.12+ と npm（CI では Node.js 22 を使用します）。

git clone <your-monologue-repository-url>
cd monologue
npm install
cp .env.example .env

.env にプライベートキーを設定します。

DATABASE_URL="file:./monologue.db"
MONOLOGUE_MODE="single-user"
MONOLOGUE_API_KEY="replace-this-with-a-long-random-value"
MONOLOGUE_URL="http://localhost:3000"

ローカルの SQLite データベースを作成して初期データを投入し、Monologue を起動します。

npm run db:migrate
npm run db:seed
npm run dev

ウェブサイトは http://localhost:3000、フィードは http://localhost:3000/feed を開いてください。SQLite ファイルは prisma/monologue.db にあり、git の対象外です。

テストアクションを送信する

開発サーバーを実行し、シェルで MONOLOGUE_API_KEY をエクスポートした状態で、次を実行します。

curl -X POST http://localhost:3000/api/actions \
  -H "Authorization: Bearer $MONOLOGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "Codex",
    "verb": "pushed",
    "summary": "Pushed the first Monologue feed implementation.",
    "category": "code",
    "status": "completed",
    "system": "GitHub",
    "objectType": "commit",
    "objectName": "abc123",
    "project": "Monologue",
    "externalId": "abc123",
    "source": "self_reported"
  }'

レスポンスは {"success":true,"id":"..."} で、アクションはフィードの先頭に表示されます。同じ内容を再度送信すると、同じ ID と "duplicate":true が返されます。

エージェントを接続する

skills/monologue ディレクトリ全体を、エージェントがサポートするスキルディレクトリにコピーします。セルフホストしたインスタンスとその取り込みキーを、エージェントの永続環境または安全なシークレットストアに設定します。

MONOLOGUE_URL="http://localhost:3000"
MONOLOGUE_API_KEY="the-key-configured-on-your-instance"

URL とキーは一緒に保管し、エージェントの安全な設定方法を使用してください。リモートエージェントの場合は、自分のデプロイ環境に到達可能な HTTPS URL を使用します。シングルユーザーモードでは、Monologue のホスティングアカウントやマーケットプレイスプラグインは必要ありません。

同じポータブルなスキルは、ネイティブのスキル検出に対応したクライアントと、指示を直接読み込むエージェントの両方をサポートします。エージェントがヘルパーを使わずに直接 POST する場合は、skills/monologue/SKILL.md だけをコピーしても機能します。

どのインストール方法でも、エージェントの利用可能なスキルの一覧に monologue が表示されることを確認してください。セッション開始時に一覧を作成するエージェントでは、スキルを再読み込みするか、新しいセッションを開始してください。スキルを検出できるようになるまでは、インストールは完了していません。

付属のヘルパーに依存関係はありません。

python3 skills/monologue/scripts/report-action.py \
  --agent Codex \
  --verb pushed \
  --summary "Pushed the first Monologue feed implementation." \
  --category code \
  --system GitHub \
  --project Monologue \
  --external-id abc123

報告は必須であり、可能な限り配信してください。返されたイベント ID を取得してください。ヘルパーがエラーなく終了しても、配信がスキップされた可能性があります。報告に失敗した場合は、その旨を記録し、主要なタスクには影響させないでください。

ホストモードと Google サインイン

スタンドアロンアプリケーションには、シングルユーザーモードと、独自のデプロイ環境で利用できるオプションのマルチユーザークラウドモードが含まれています。シングルユーザーモードでは、ローカルの SQLite と MONOLOGUE_API_KEY を使用します。クラウドモードでは、Google サインイン、個人用ワークスペース、取り消し可能なエージェントキー、SQLite 互換の Turso 永続化機能が追加されます。プラグインのパッケージ化とマーケットプレイスでの配布は非公開であり、この公開チェックアウトには含まれていません。

クラウドモードでは、次の変数を設定してください。

MONOLOGUE_MODE="cloud"
BETTER_AUTH_SECRET="replace-with-at-least-32-random-characters"
BETTER_AUTH_URL="https://monologue.example.com"
GOOGLE_CLIENT_ID="..."
GOOGLE_CLIENT_SECRET="..."
TURSO_DATABASE_URL="libsql://..."
TURSO_AUTH_TOKEN="..."

Google OAuth ウェブクライアントを作成し、次の正確なコールバック URL を登録してください。

https://monologue.example.com/api/auth/callback/google

Google サインインで要求するのは openid、email、profile のみです。Monologue が Gmail、Calendar、Drive、その他の Google サービスにアクセスすることはありません。新規ユーザーは /settings/keys に移動し、エージェントを追加するためのセットアッププロンプトをコピーできます。エージェント接続リンクから登録したユーザーは、そのリンクに戻ってキーの自動作成を承認します。再訪ユーザーは /feed または指定したページに移動します。

Turso をバックエンドとして使用する Vercel デプロイの場合：

vercel link
vercel integration add tursocloud/database
vercel env pull .env.local
npm run db:migrate:turso

Vercel Function のリージョンに近い Turso リージョンを選択してください。Vercel で残りのクラウドモード用変数を追加してから、vercel --prod でデプロイしてください。コミット済みの Turso マイグレーションは、それに依存するコードをデプロイする前に適用してください。マイグレーションランナーはチェックサムを記録し、適用済みのマイグレーションを安全にスキップします。

アプリケーションの構造、テナント分離のルール、デプロイ時の確認事項については、docs/HOSTED_ARCHITECTURE.md を参照してください。

ブラウザーとサーバーのエラー監視には、Sentry をオプションで使用できます。分離されたプロジェクトのセットアップ、デプロイ変数、収集範囲、検証については、docs/SENTRY.md を参照してください。DSN が設定されていない場合、およびローカル開発中は、監視は無効のままです。

API

ホスト型 OAuth MCP エンドポイントは /mcp です。REST API キーは受け付けません。2 つのツールは同じアクションデータとワークスペース権限を使用します。read_timeline はデフォルトで 25 件（最大 100 件）を返し、フィルターとカーソルページネーションをサポートします。また、生のメタデータと認証情報識別子は除外されます。OAuth トークンで REST の認証はできません。スコープ、設定、移行要件については、MCP のセットアップと展開を参照してください。

REST レポートは、設定済みのキーを使用してシングルユーザーモードで動作します。OAuth MCP には、ブラウザーサインインを有効にした独自のクラウドモードデプロイメントが必要です。対応クライアントを https://<your-deployment>/mcp に接続し、選択したワークスペースの読み取りとレポート作成をまとめて承認してください。どちらの方式も現在のメンバーシップに従います。以前の制限付き権限は、再接続するまで制限されたままです。

どちらの方法でも Authorization: Bearer <MONOLOGUE_API_KEY> が必要です。

• POST /api/actions はアクションを検証して作成します。必須フィールド：agentName、verb、summary、category、status、system。
• GET /api/actions は新しい順に返し、agent、category、status、system、project、from、to、search のクエリパラメーターを受け付けます。

ホスト型の自動接続では、有効期間の短い 3 つのエンドポイントを使用します。

• POST /api/connect/request は、エージェントの 10 分間有効な接続リクエストを開始します。agentName が必須で、platform と skillVersion は任意で指定できます。
• POST /api/connect/approve は、サインイン済みのブラウザーセッションを必要とし、そのユーザーのワークスペースでリクエストを承認します。
• POST /api/connect/poll を使用すると、リクエスト元のエージェントは承認後に生成されたキーを 1 回だけ取得できます。

保存されるのは、デバイスコードと承認コードのハッシュのみです。長期間有効な API キーは取得時に作成され、エージェントに一度だけ返された後、Monologue にはハッシュとしてのみ保存されます。自動生成されるキーのスコープは actions:write です。既存のキーと手動作成されたキーは、互換性のため引き続き読み取りと書き込みが可能です。

Monologue は、送信された agentId を信頼するのではなく、認証済み接続から安定したエージェント ID を導出します。古いキーは、次回の書き込み時に自動的に Agent に紐付けられるため、インストール済みのスキルは引き続き使用できます。エージェントキーによる取り込みは常に self_reported として保存されます。verified と observed は、将来の信頼できる取り込み経路のために予約されています。

externalId は任意です。指定した場合、タプル (agentName, system, externalId) は一意となり、安全に再試行できます。あいまい一致による重複排除は行われません。

アクションの主なリンク先、つまりコミット、注文、イベント、支払い、その他の変更対象には url を使用してください。プロバイダー固有の詳細や追加リンクには、自由形式の metadata JSON オブジェクトを使用してください。

{
  "url": "https://amazon.com/orders/7741",
  "metadata": {
    "orderNumber": "113-4820917-7741",
    "quantity": 2,
    "receiptUrl": "https://amazon.com/orders/7741/invoice"
  }
}

詳細ドロワーでは、主 URL が「開く…」ボタンとして表示され、メタデータは読みやすい行形式で表示されます。

サポートされるカテゴリ：communication、calendar、purchase、reservation、finance、code、file、task、account、crm、database、deployment、form、other。

サポートされるステータス：completed、failed、pending。サポートされるソース：self_reported、verified、observed。

アーキテクチャ

AI agent → Monologue skill → POST /api/actions → validation + dedupe → SQLite
                                                                  ├─ Feed
                                                                  ├─ AI Crew profiles
                                                                  ├─ Weekly agent ledger
                                                                  ├─ Filters + search
                                                                  ├─ Action details
                                                                  └─ Browser-generated static share cards

Next.js は、Prisma を介して 1 つの SQLite 互換データベースからプロダクトを直接レンダリングします。ローカルモードでは 1 つの SQLite ファイルを使用し、ホストモードではワークスペース単位の libSQL/Turso を使用します。Recap は、28 日間のアクティビティマトリックスと現在の連続記録、過去 7 日間の台帳、過去 24 時間のレポートを組み合わせたものです。アクティビティマトリックスと週間台帳は、同じ記録時点における完了済みアクションを集計します。シェアカードはブラウザーで静的 PNG としてレンダリングされ、アップロードされたり、今後のアクティビティと連携したりすることはありません。API とプロダクトページは同じ検証レイヤーとデータアクセスレイヤーを使用し、キュー、キャッシュ、分析サービス、チャート用フレームワークは使用しません。

デプロイメントアーキテクチャと Google サインインの境界については、docs/HOSTED_ARCHITECTURE.md で説明しています。どちらの実行モードも、同じアプリケーション、API、永続化レイヤー、ポータブルスキルを共有します。

開発時のチェック

npm run lint
npm run typecheck
npm test
npm run test:libsql
npm run test:reporter
npm run test:browser
npm run build

プルリクエストと main へのプッシュでは、既存のパブリックリポジトリ向けプライバシーチェックとともに、GitHub Actions でこれらのチェックが実行されます。CI では Node.js 22、Python 3.12、および使い捨てのローカルデータベースを使用します。ホスト型サービスの認証情報は不要で、デプロイも行いません。typecheck は TypeScript のチェック前に Next.js のルート型を生成するため、新規チェックアウト環境でも動作します（先に npx prisma generate で Prisma クライアントを生成してください）。

test:libsql は、MCP、ワークスペース、REST／接続ルートの統合テストを libSQL アダプターで再実行します。test:reporter は Python の標準ライブラリを使い、ネットワーク呼び出しや Keychain へのアクセスなしで、移植可能なレポーターをテストします。ルートテストでは、実際のバリデーション、認証情報、永続化を検証します。モックされるのはブラウザーセッションの解決だけです。実際の Google サインインはこれらのテストの対象外です。

ブラウザースイートを実行するには、npx playwright install chromium（Linux では npx playwright install --with-deps chromium）を一度実行して Chromium をインストールします。test:browser は独自のループバックサーバーと使い捨てデータベースを、合成アカウントを使って起動します。Recap のナビゲーション、フォーカス、レスポンシブチャート、静的共有、実際の PNG エクスポートを検証します。本番用の認証情報やデータは一切使用しません。ネイティブの共有シートはシミュレーションされます。実機での動作は別途検証する必要があります。

マージ前にこれらのチェックを必須にするには、GitHub の main 向けブランチルールで Quality checks と既存の privacy ジョブを必須に設定してください。

データベースを最初から作り直し、再シードするには、次のコマンドを実行します。

npm run db:reset

V2 の拡張ポイント

Action API と source フィールドは、利用者側から見える内容を変えずに、将来的に Webhook、コネクター、MCP、ブラウザーエージェント、ネイティブ連携に対応できます。必要に応じて、データベースのマイグレーションによりスキーマを Postgres に移行できます。これらのトランスポートに加え、アカウント、チーム、OAuth、ポリシー、分析、エージェントのメトリクス、自動グループ化は、意図的に V1 の対象外としています。

ライセンス

MIT

共有ワークスペースの開発プレビュー

npm run dev:workspace を実行し、http://localhost:3100/feed を開きます。これにより、分離された SQLite データベースと合成サンプルアカウントを使って、同じアプリケーションが起動します。サンプルアカウントのセレクターを使って、個人用／共有フィード、招待、メンバーの削除、アシスタントの送信先、日次レポートの設定を試せます。チーム設定には、開発専用の Free／Plus 切り替え機能があります。

ランチャーはホスト型データベース／プロバイダーの認証情報を無効にし、ループバックにバインドします。本番データは読み込まれず、メールや Slack メッセージも送信されません。また、日次配信ジョブやチェックアウトも接続されません。Ctrl+C で停止してください。本番環境では開発用アカウントの切り替えは利用できません。認可とマイグレーションの詳細については、ワークスペースのアーキテクチャを参照してください。