cosmicstack-labs/mercury-agent

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI or Telegram.

Mercury — 「魂に駆られた」AIエージェント

何であるか – Mercuryはローカルで実行され、権限が厳格に制御されたAIアシスタントです。コマンドライン、Webダッシュボード、Telegramから会話できます。大規模言語モデルプロバイダ（OpenAI、Anthropic、DeepSeek、Ollamaなど）とやり取りでき、ファイルの読み書き、シェルコマンドの実行、URLの取得、Gitの管理、タスクのスケジューリングなども可能です。すべての操作は明示的な権限モデルによって制限されており、エージェントはあなたのマシン上に永続的で検索可能な「第二の脳」の記憶を保持します。

コアとなるアイデア

アイデア	Mercuryがどのように実装しているか
権限が厳格に制御されたツール	すべての組み込みツール（ファイル、シェル、Git、Webなど）は、危険な操作（例：`sudo`、`rm -rf /`）に対してデフォルトでブロックされます。各操作ごとにプロンプトを表示する「聞く」か、セッション全体で「すべて許可」を選択できます。
第二の脳の記憶	SQLite + FTS5が10種類のタイプ（アイデンティティ、目標、習慣…）に分類された事実を保存します。会話のたびに高信頼度の事実を自動抽出し、1時間ごとに統合し、LLMコンテキストに上位5件の関連記憶を注入します。
魂に駆られた個性	あなたのマーカドファイル（`soul.md`、`persona.md`、`taste.md`、`heartbeat.md`）がエージェントの性格を定義し、企業のサービスに依存せずに「個性」を保持します。
トークンに配慮した予算管理	日次トークン予算を追跡。使用量が70 %を超えると、自動的に返信を短縮します。`/budget`コマンドで予算の確認、リセット、上書きが可能です。
常に稼働するデーモン	`mercury up`でユーザー単位のシステムサービス（LaunchAgent、systemdユーザー単位、Windowsタスクスケジューラ）をインストールし、クラッシュ時に再起動、起動時に自動起動します。デーモンモードではTelegramが主なチャットチャネルになります。
拡張可能なスキル	コミュニティが貢献した「スキル」（ミニエージェント）はAgent Skills仕様に従い、1つのコマンドでインストール可能（`mercury skills install …`）。スキルは追加ツールとして表示され、チャットから呼び出したりスケジュールしたりできます。

クイックスタート（Node.js不要）

# macOS / Linux – 自己完結型バイナリをダウンロード
curl -fsSL https://mercuryagent.sh/install.sh | sh

# Windows PowerShell
irm https://mercuryagent.sh/install.ps1 | iex

インストーラーは~/.local/bin（Windowsでは同等の場所）にmercury実行ファイルを配置します。初回起動時に名前、LLMプロバイダのAPIキー、オプションのTelegramペアリングを設定するウィザードが起動します。

Node 20+が既にインストールされている場合、次のように実行できます：

npx @cosmicstack/mercury-agent   # 一時実行
npm i -g @cosmicstack/mercury-agent && mercury   # グローバルインストール

主なコマンドラインインターフェース

コマンド	機能
`mercury` / `mercury start`	インタラクティブなInk TUIチャットセッションを起動。
`mercury up`	必要に応じてユーザー単位のサービスをインストールし、バックグラウンドデーモンを起動。
`mercury stop / restart / status / logs`	デーモンの管理。
`mercury doctor`	セットアップウィザードを再実行するか、設定を確認。
`mercury telegram …`	Telegramユーザーのペアリング、承認、管理（管理者／メンバー権限）。
`mercury skills …`	コミュニティスキルの検索、表示、インストール、更新、削除。
`mercury upgrade`	最新リリース（バイナリまたはnpm）を取得。

チャット中はLLMトークンを消費しないスラッシュコマンドが使用できます。例：

/tools – 読み込まれたツールの一覧
/budget – 日次トークン使用量の表示
/memory – 第二の脳の閲覧
/code agent <task> – コーディング作業をバックグラウンドで処理するサブエージェントを起動
/tasks – スケジュールされたジョブの一覧

Webダッシュボードとカンバンボード

mercury doctorを実行すると、http://127.0.0.1:6174にローカルWeb UIが有効になります。以下を提供します：

サーバーサイドイベントストリーミングによるチャット
Mercuryが自動処理できる各カードを持つ視覚的なカンバンボード
第二の脳記憶グラフの表示
コード編集タスク用の軽量IDE風ワークスペース

ダッシュボードはデフォルトの認証情報（mercury / Mercury@123）で保護され、ローカルホストのみにバインドされます。

Mercuryの拡張

スキル – ツールセットとマーカドファイルSKILL.mdを記述するパッケージ。mercury skills install <category>/<slug>でインストール。スキルは~/.mercury/skills/に保存され、次回起動時に読み込まれます。
プロバイダ – ~/.mercury/mercury.yamlにOpenAI互換エンドポイントを追加。Mercuryは順番に試行し、自動的にフォールバックします。
カスタムツール – コアはVercel AI SDKとシンプルなツールディスパッチループで構成されているため、TypeScriptモジュール（run関数を公開）を追加し、設定ファイルに登録できます。

ソースからのインストール

git clone https://github.com/cosmicstack-labs/mercury-agent.git
cd mercury-agent
npm install               # Node ≥ 20
npm run build             # dist/バンドルを生成
npm start                 # ソースから実行

エンドユーザーにNodeランタイムを必要としない完全に独立したバイナリを生成するには、このリポジトリではBunを使用しています：

npm run build:bin          # プラットフォーム固有の実行可能ファイルをrelease/に生成

リリース構成には、macOS（arm64 & x64）、Linux（arm64 & x64）、Windows用の別々のバイナリに加え、Web UIのtarballとSHA‑256チェックサムが含まれます。

ライセンスとセキュリティ

ライセンス: MIT（LICENSEを参照）。
セキュリティモデル: 潜在的に破壊的な操作はシェルブロックリストでブロックされ、明示的なユーザー承認が必要です。エージェントは、fetch_urlなど特定のツールを呼び出した場合を除き、ローカルファイルやコマンド出力をリモートサービスに送信しません。
データのローカル性: すべての記憶、ログ、設定は~/.mercury/に保存され、クラウドストレージは使用されません（リモートLLMプロバイダを設定した場合を除く）。

どんな人に役立つでしょうか？

シェルアクセスを制限せずにコード編集、ビルド実行、Git管理ができる個人用AIアシスタントを求める開発者。
ローカルに完全に保存され、検索可能で自動整理される「第二の脳」を好む知識労働者。
TelegramやプライベートWeb UI用に自己ホスト型で権限制御可能なボットが必要なチーム。

結論：Mercuryは、安全（権限プロンプト、トークン予算）、永続性（SQLiteベースの記憶とカンバンボード）、拡張性（コミュニティスキル、マルチプロバイダフォールバック）を重視した、完全機能のローカルAIエージェントです。1行インストーラーで即座に利用可能、またはソースからビルドしてより深いカスタマイズも可能です。