Vigil — Cognitive Infrastructure for AI Agents

Vigil

AI エージェントのためのオブザーバビリティと認識基盤。

Vigil は、1 つのパッケージに 2 つのレイヤーを備えています。

• MCPWatch — MCP サーバーのサイレント障害を監視するウォッチドッグです。あらゆる Python MCP サーバー（FastMCP と低レベルの mcp.server.lowlevel.Server）に 1 行で計測を追加できます。ゲートウェイやダッシュボードでは、すでにレイテンシーやエラーのチャートを確認できます。誰も検出できていないのは、成功したように見えるのに何も返さない呼び出しです。エラーが発生していないにもかかわらず、コンテンツが空、null、または空白になります。MCPWatch は、ツールごとのレイテンシー（p50/p95/p99）、エラー率、isError 応答に加えて、これらを固有の silent ステータスとして検出します。本番環境で 95 以上の MCP ツールに利用されています。
• 認識プラットフォーム — デーモンによるコンテキストのコンパイル、シグナルプロトコル、セッションの引き継ぎ、フレームベースのツールフィルタリング、MCP サーバーを備えています。ほとんどのエージェントフレームワークが省略している神経系レイヤーです。

ほとんどのエージェントメモリツールは書類棚です。Vigil は聴診器であり、神経系です。

課題

MCP サーバーは気づかれないまま失敗します。 ツールが空のコンテンツを返し、SDK が例外を握りつぶし、エージェントは「結果が見つかりませんでした」と扱います。そして 3 日後に、顧客からの問い合わせで初めてそのことがわかります。レイテンシーとエラーの監視は、今や必須です（ゲートウェイ、OpenTelemetry、FastMCP 自体が出力します）。しかし、エラーはないものの応答が空という、エージェントがひそかに幻覚で補ってしまう障害モードを検出できるものはありません。MCPWatch は、このギャップを埋めるために存在します。

エージェントはセッション間の記憶をすべて失います。 コンテキストに関係なくすべてのツールを読み込み（50K 以上のトークンを浪費します）、セッションをまたいで連携したり、互いに作業を引き継いだりできません。会話を始めるたびに、何もない状態からのスタートになります。

Vigil の機能

MCPWatch — MCP のサイレント障害を監視するウォッチドッグ — あらゆる Python MCP サーバー（FastMCP または低レベルの mcp.server.lowlevel.Server）を 1 行でラップします。主な機能は、エラーが発生していないにもかかわらず空、null、または空白のコンテンツを返す呼び出しをサイレント障害として検出し、ヘルス情報、ツールごとの統計、アラートに表示される固有の silent ステータスとして記録することです。また、ツール呼び出しのレイテンシー（p50/p95/p99）、ツールごとのエラー率、isError 応答、時間経過に伴う呼び出し量も追跡します。REST API、CLI、アラートフックを備えています。MIT ライセンスで、設定は不要です。

Awareness Daemon — バックグラウンドプロセスが 90 秒ごとにシステムの状態をコンパイルします。エージェントは 1 秒未満でコンパイル済みのコンテキストを使って起動します。起動時のレイテンシーも、「何をしていたか思い出させて」というやり取りもありません。

フレームベースのツールフィルタリング — ツールにコンテキストフレームを付けます。「バックエンド」モードのエージェントには、95 個ではなく 14 個のツールが表示されます。セッションごとのツール定義トークンを 50～90％削減できます。

シグナルプロトコル — コンテンツ量の上限を設けた軽量イベントバスです。エージェントがシグナル（タイプごとに最大 300～800 文字）を出力し、デーモンがそれらを認識情報に統合します。エージェントは直接通信せずに連携できます。

セッションの引き継ぎ — エージェントはセッションの終了時に、構造化された要約（変更したファイル、決定事項、次の手順）を残します。次のエージェントは、これまでの経緯と次に行うことをすべて把握して起動します。

シグナルの圧縮 — 古いシグナルは削除せず、要約します。階層化された保持方式（raw → daily → weekly → monthly）により、履歴を失わずにコンテキストを最新の状態に保ちます。

MCP サーバー — Vigil を MCP ツールサーバーとして公開します。Claude Code、Claude Desktop、Cursor、Windsurf のいずれのエージェントも接続でき、すぐに永続的な認識情報を利用できます。

記事

• MCP サーバーは何も見えていない（解決方法はこちら） — Dev.to の MCPWatch 詳細解説

インストール

# Core library (daemon, signals, handoff, compaction)
pip install vigil-agent

# With MCP server support
pip install vigil-agent[mcp]

30 秒デモ

4 つのコマンドで Vigil の動作を確認できます。

pip install vigil-agent
vigil init
vigil signal my-agent "Hello from Vigil!"
vigil status

出力例：

Current Awareness
─────────────────
  Agents:  my-agent (1 signal)
  Latest:  "Hello from Vigil!" (just now)
  Frame:   default
  Status:  active — 1 unacknowledged signal

これで完了です。エージェントが認識情報を利用できるようになりました。デーモン、引き継ぎ、MCP サーバーを含むクイックスタート全編は、続きをご覧ください。

クイックスタート

# Initialize
vigil init

# Emit a signal
vigil signal my-agent "Deployed new API endpoint"

# Start the daemon (compiles awareness every 90s)
vigil daemon start

# Check awareness
vigil status

# See what agents boot with
vigil boot --json

# End a session with a structured handoff
vigil handoff my-agent "Shipped auth module" --files "auth.py, tests.py" --next-steps "Write docs"

# Resume from where the last agent left off
vigil resume next-agent

# Start as an MCP server (Claude Code / Claude Desktop)
vigil serve

# Run signal compaction manually
vigil compact --dry-run

MCP Server

Vigil は MCP サーバーとして動作するため、あらゆる AI エージェントが接続して、永続的な状況認識を得られます。

# stdio (Claude Code, Claude Desktop)
vigil serve

# SSE (remote clients)
vigil serve --transport sse --port 8300

Claude Desktop の設定（claude_desktop_config.json）：

{
  "mcpServers": {
    "vigil": {
      "command": "vigil",
      "args": ["serve"]
    }
  }
}

利用可能な 12 個の MCP ツール：

ツール	説明
vigil_boot	コンパイル済みのホットコンテキストを使って起動します
vigil_compile	状況認識を新たにコンパイルします
vigil_signal	エージェントからシグナルを送信します
vigil_status	現在の状況認識状態を取得します
vigil_signals	最近のシグナルを読み取ります
vigil_handoff	構造化された引き継ぎを行ってセッションを終了します
vigil_resume	前回の引き継ぎから再開します
vigil_chain	直近 N 件の引き継ぎの概要を取得します
vigil_stale	応答が途絶えたエージェントを見つけます
vigil_focus	優先作業キューを管理します
vigil_frames	コンテキストフレームを管理します
vigil_agents	既知のエージェントとそのアクティビティを一覧表示します

Python API

from vigil import VigilDB, SignalBus, AwarenessCompiler, HandoffProtocol

# Initialize
db = VigilDB("vigil.db")
bus = SignalBus(db)
compiler = AwarenessCompiler(db)
proto = HandoffProtocol(db)

# Emit signals from agents
bus.emit("backend-agent", "Deployed auth service v2")
bus.emit("frontend-agent", "Updated dashboard layout")

# Compile awareness
compiler.synthesize()
context = compiler.compile()
# {'frame': 'backend', 'awareness': '...', 'focus': [...], 'compiled_at': '...'}

# Boot an agent with pre-compiled context (<1 second)
hot_context = compiler.boot()

# Structured session handoff
proto.end_session(
    agent_id="backend-agent",
    summary="Shipped auth v2 with JWT tokens",
    files_touched=["auth.py", "middleware.py"],
    decisions=["Switched from session cookies to JWT"],
    next_steps=["Add rate limiting", "Write integration tests"],
)

# Next agent resumes with full context
context = proto.resume("next-agent")
# {'awareness': ..., 'last_handoff': {...}, 'signals_since_handoff': [...], 'pending_next_steps': [...]}

フレームベースのツールフィルタリング

from vigil.registry import tool, get_tools, tool_count

# Tag tools with frames
@tool(name="deploy", description="Deploy to production", frames=["backend", "devops"])
async def deploy(args):
    return {"content": [{"type": "text", "text": f"Deployed {args['service']}"}]}

@tool(name="render", description="Render component", frames=["frontend"])
async def render(args):
    ...

@tool(name="health", description="Health check", frames=["core"])  # Always visible
async def health(args):
    ...

# Filter by context
tool_count()              # 3 (all tools)
tool_count("backend")     # 2 (deploy + health)
tool_count("frontend")    # 2 (render + health)

シグナルの圧縮

from vigil import SignalCompactor

compactor = SignalCompactor(db)

# Run compaction (tiered: raw → daily → weekly → monthly)
stats = compactor.compact()
# {'daily_summaries': 5, 'weekly_digests': 2, 'monthly_snapshots': 1, 'signals_compacted': 47}

# Browse compacted history
history = compactor.get_history(days=30, agent="backend-agent")

シグナルの種類と上限

種類	上限	用途
observation	400 chars	通常のアクティビティ更新
handoff	600 chars	セッションの結論
summary	800 chars	包括的な概要
alert	300 chars	緊急通知

アーキテクチャ

Agents emit signals → SQLite → Daemon compiles → Hot context → Agents boot instantly
                                    ↓
                            Frame detection
                            Awareness synthesis
                            Signal compaction
                            Focus queue

• インフラストラクチャ不要 — SQLite ストレージを使用し、Redis／Postgres／Docker は不要です
• フレームワークに依存しません — MCP 対応のクライアントや単体で動作します
• 軽量 — 純粋な Python で実装されており、重い依存関係はありません（mcp は任意です）

インテグレーション

一般的な AI ツール向けのすぐに使える設定を用意しています。セットアップガイドの全容については、examples/ ディレクトリをご覧ください。

ツール	セットアップ
Claude Code	claude mcp add vigil -- vigil serve を実行します（ガイド）
Claude Desktop	claude_desktop_config.json に追加します（ガイド）
Cursor	.cursor/mcp.json に追加します（ガイド）
GitHub Actions	CI/CD からシグナルを送信します（ワークフロー）
Slack	トリガーを使ってアラートを Slack に転送します（ガイド）
Discord	トリガーを使ってアラートを Discord に転送します（ガイド）

シェル補完

# Bash
source completions/vigil.bash

# Zsh
cp completions/vigil.zsh ~/.zsh/completions/_vigil

CLI リファレンス

コマンド	説明
vigil init	新しいプロジェクトを初期化します
vigil quickstart	対話型セットアップウィザード
vigil daemon start	状況認識デーモンを起動します
vigil daemon status	デーモンのコンパイル状態を確認します
vigil serve	MCP サーバーとして起動します（stdio または SSE）
vigil signal <agent> <msg>	シグナルを送信します
vigil status	現在の状況認識を表示します
vigil boot	コンパイル済みのホットコンテキストを表示します
vigil frames	登録済みフレームを一覧表示します
vigil tools [--frame X]	ツールを一覧表示します（必要に応じてフィルタリング）
vigil handoff <agent> <summary>	構造化されたセッションの引き継ぎを記録します
vigil resume <agent>	前回の引き継ぎから再開します
vigil history	圧縮済みのシグナル履歴を参照します
vigil agents	既知のエージェントを一覧表示します
vigil compact	シグナルの圧縮を手動で実行します
vigil know <key> <value>	ナレッジ項目を保存します
vigil recall <query>	ナレッジをあいまい検索します
vigil knowledge	すべてのナレッジ項目を一覧表示します
vigil forget <key>	ナレッジ項目を削除します
vigil extract	シグナルパターンからナレッジを自動抽出します
vigil export	状態を Markdown にエクスポートします
vigil mcp-health	MCP サーバーの健全性（呼び出し、エラー、レイテンシ）
vigil mcp-health-check <cmd>	CI で MCP サーバーを検査します（終了コード 0／1）
vigil doctor	よくある問題を診断します
vigil version	バージョンを表示します

MCP の本番環境オブザーバビリティ

1 行のコードで任意の MCP サーバーを監視できます。ツール呼び出し、レイテンシ、エラーを追跡し、アラートを自動的に発行します。

from mcp.server.fastmcp import FastMCP
from vigil.mcpwatch import instrument

mcp = FastMCP("my-server")

@mcp.tool()
async def search(query: str) -> str:
    return "results"

# One line — all tools are now monitored
watch = instrument(mcp)

監視対象：

• サイレント障害 — エラーが発生せず、空、null、または空白のコンテンツを返す呼び出しです。独立した silent ステータスとして記録され、ヘルスと統計に表示され、アラートの対象になります。これが主な機能です。
• すべてのツール呼び出し：名前、所要時間、成功／エラー／サイレント
• レイテンシの急増（しきい値を設定可能。デフォルトは 5s）
• 詳細なトレースバックを含むエラーパターン（低レベルの isError 応答を含む）
• サーバーの無応答（N 分間、呼び出しがまったくない状態）

3 つの使用方法：

# 1. Local Vigil — store in same DB as your signals
watch = instrument(mcp, db_path="vigil.db")

# 2. Vigil Cloud — send to your hosted instance
watch = instrument(mcp, api_key="vgl_...")

# 3. Memory-only — just in-process stats
watch = instrument(mcp)

いつでもヘルスを確認できます：

health = watch.health()
# {'server': 'my-server', 'status': 'degraded', 'total_calls': 1247,
#  'total_errors': 25, 'error_rate': 0.02,
#  'total_silent': 140, 'silent_rate': 0.112,   # <- the failures nobody else flags
#  'tools': {'search': {'avg_ms': 42, 'p95_ms': 180, 'silent_count': 140}}}

watch.recent_silent()   # the actual empty/null calls, per tool

例外が発生せずに ""、None、または [] を返すツールは、MCP における典型的な盲点です。SDK は成功を報告し、エージェントは何もない状況をなんとか埋め合わせます。 MCPWatch はこれを、一級のシグナルとして扱います。

CLI：

vigil mcp-health              # All monitored servers
vigil mcp-health -s my-server # Specific server

REST API（6 つのエンドポイント）：

エンドポイント	説明
GET /mcp/health	サーバーのヘルス概要（サイレント率を含む）
GET /mcp/tools	ツールごとの分析
GET /mcp/silent	最近のサイレント障害（空／null の戻り値）
GET /mcp/errors	最近のエラー
GET /mcp/latency	p50／p95／p99 パーセンタイル
GET /mcp/volume	時間経過に伴う呼び出し量

Mem0／Letta／LangGraph だけではだめなのですか？

	Vigil	Mem0	Letta	LangGraph
アプローチ	アウェアネスデーモン	メモリ検索	ステートフルランタイム	ステートマシン
コンテキスト	事前コンパイル済み、即時起動	必要に応じてクエリ	LLM による管理	チェックポイントベース
ツールのフィルタリング	フレームベース（50〜90%の節約）	なし	なし	なし
マルチエージェント	シグナルプロトコル＋引き継ぎ	共有メモリ	単一エージェント	グラフのエッジ
コンパクション	階層型（日次／週次／月次）	なし	LLM による管理	なし
MCP ネイティブ	サーバーを内蔵	いいえ	いいえ	いいえ
インフラストラクチャ	SQLite（セットアップ不要）	API＋LLM のコスト	フルランタイム	LangChain エコシステム
ロックイン	なし（フレームワークに依存しない）	Mem0 API	Letta プラットフォーム	LangChain

Vigil は神経系であり、その他はファイリングキャビネットです。併用してください。Vigil がアウェアネスと連携を担い、Mem0／Letta が深いメモリを担います。

ライセンス

MIT