Vigil — Cognitive Infrastructure for AI Agents

Vigil

面向 AI Agent 的可观测性与感知基础设施。

Vigil 在一个软件包中提供两个层：

• MCPWatch — MCP 服务的静默故障监控工具。为任何 Python MCP 服务（FastMCP 和低级别的 mcp.server.lowlevel.Server）添加一行代码即可完成埋点。网关和仪表板已经能提供延迟和错误图表。没人能捕捉到的是这种调用：看起来成功了，却什么也没返回——内容为空、为 null 或空白，且没有引发错误。MCPWatch 会将这些情况标记为独立的 silent 状态，并监控每个工具的延迟（p50/p95/p99）、错误率以及 isError 响应。已在生产环境中用于 95+ 个 MCP 工具。
• 感知平台 — 由守护进程编译的上下文、信号协议、会话交接、基于帧的工具筛选、MCP 服务。大多数 Agent 框架都缺少的神经系统层。

大多数 Agent 记忆工具就像文件柜。Vigil 则是听诊器和神经系统。

问题所在

MCP 服务会静默失效。 工具返回空内容，SDK 吞掉异常，Agent 将其视为“未找到结果”，而你直到三天后收到客户工单才发现问题。延迟和错误监控如今已是基本配置（网关、OpenTelemetry 和 FastMCP 本身都会发出相关数据）。但它们都不会标记没有报错却返回空内容的响应——这是 Agent 会悄悄进行幻觉补全的故障模式。MCPWatch 正是为了弥补这一缺口。

Agent 会忘记会话之间的一切。 它们不论上下文如何都会加载所有工具（浪费 50K+ 个词元）。它们无法跨会话协作，也无法互相交接工作。每次对话都从头开始。

Vigil 的功能

MCPWatch — MCP 静默故障监控工具 — 用一行代码包装任何 Python MCP 服务（FastMCP 或低级别的 mcp.server.lowlevel.Server）。它的核心功能是检测静默故障——调用返回空内容、null 或空白内容，且没有引发错误——并将其记录为独立的 silent 状态，显示在运行状况、每个工具的统计信息和告警中。它还会跟踪工具调用延迟（p50/p95/p99）、每个工具的错误率、isError 响应以及随时间变化的调用量。提供 REST API、CLI 和告警钩子。采用 MIT 许可证，无需配置。

感知守护进程 — 后台进程每 90 秒编译一次系统状态。Agent 启动时即可在 <1 秒内获取预编译上下文。没有启动延迟，也不必再“提醒我之前在做什么”。

基于帧的工具筛选 — 为工具标记上下文帧。处于“backend”模式的 Agent 只能看到 14 个工具，而非 95 个。每个会话可节省 50-90% 的工具定义词元。

信号协议 — 带有内容预算的轻量级事件总线。Agent 发出信号（按类型最多 300-800 个字符），守护进程将其综合为感知信息。Agent 无需直接通信即可协作。

会话交接 — Agent 结束会话时提供结构化摘要（涉及的文件、决策、后续步骤）。下一个 Agent 启动时即可获得已发生事项和下一步工作的完整上下文。

信号压缩 — 旧信号会被汇总，而非删除。分层保留（原始数据 → 每日 → 每周 → 每月）既能保持上下文新鲜，又不会丢失历史记录。

MCP 服务 — 将 Vigil 作为 MCP 工具服务公开。任何 Claude Code、Claude Desktop、Cursor 或 Windsurf Agent 都能连接并立即获得持久感知能力。

文章

• 你的 MCP 服务正处于盲飞状态（修复方法如下） — Dev.to 上关于 MCPWatch 的深入介绍

安装

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

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

30 秒演示

通过四条命令查看 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

就这样——你的 Agent 已具备感知能力。继续阅读，了解包含守护进程、交接和 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 服务

Vigil 以 MCP 服务的形式运行，让任何 AI Agent 都能连接并获得持久的上下文感知能力。

# 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	从 Agent 发出信号
vigil_status	获取当前上下文感知状态
vigil_signals	读取近期信号
vigil_handoff	以结构化交接结束会话
vigil_resume	从上次交接处继续
vigil_chain	获取最近 N 次交接的简报
vigil_stale	查找已停止响应的 Agent
vigil_focus	管理优先工作队列
vigil_frames	管理上下文框架
vigil_agents	列出已知 Agent 及其活动

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 字符	常规活动更新
handoff	600 字符	会话结论
summary	800 字符	综合摘要
alert	300 字符	紧急通知

架构

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（指南）

Shell 补全

# 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	列出已知 Agent
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 生产可观测性

只需一行代码，即可监控任何 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 分钟没有任何调用）

三种使用方式：

# 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 会报告成功，而你的 Agent 只能围绕空白自行应对。 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 管理	基于检查点
工具筛选	基于 Frame（节省 50-90%）	无	无	无
多 Agent	信号协议 + 交接	共享记忆	单个 Agent	图边
压缩	分层（日 / 周 / 月）	无	由 LLM 管理	无
原生支持 MCP	内置服务	否	否	否
基础设施	SQLite（零配置）	API + LLM 成本	完整运行时	LangChain 生态系统
锁定	无（与框架无关）	Mem0 API	Letta 平台	LangChain

Vigil 是神经系统，其他产品是档案柜。它们可以搭配使用 — Vigil 负责感知和协调，Mem0/Letta 负责深度记忆。

许可证

MIT