Vigil

Vigil

Observability and awareness infrastructure for AI agents.

Vigil is two layers in one package:

• MCPWatch — the silent-failure watchdog for MCP servers. One-line instrumentation for any Python MCP server (FastMCP and low-level mcp.server.lowlevel.Server). Gateways and dashboards already give you latency and error charts. The thing nobody catches is the call that looks successful but returns nothing: empty, null, or blank content with no error raised. MCPWatch flags those as a distinct silent status, on top of per-tool latency (p50/p95/p99), error rates, and isError responses. Used in production across 95+ MCP tools.
• Awareness platform — daemon-compiled context, signal protocol, session handoff, frame-based tool filtering, MCP server. The nervous system layer most agent frameworks skip.

Most agent memory tools are filing cabinets. Vigil is a stethoscope and a nervous system.

The Problem

MCP servers fail silently. A tool returns empty content, the SDK swallows the exception, the agent treats it as "no results found" and you find out three days later from a customer ticket. Latency and error monitoring is now table stakes (gateways, OpenTelemetry, and FastMCP itself emit it). But none of them flag the empty-but-not-errored response — the failure mode your agent quietly hallucinates around. That gap is what MCPWatch exists to close.

Agents forget everything between sessions. They load all tools regardless of context (wasting 50K+ tokens). They can't coordinate across sessions or hand off work to each other. Every conversation starts cold.

What Vigil Does

MCPWatch — the MCP silent-failure watchdog — One line wraps any Python MCP server (FastMCP or low-level mcp.server.lowlevel.Server). Its headline job: detect silent failures — calls that return empty, null, or blank content with no error raised — and record them as a distinct silent status that shows up in health, per-tool stats, and alerts. It also tracks tool-call latency (p50/p95/p99), per-tool error rates, isError responses, and call volume over time. REST API, CLI, and alert hooks. MIT, no config required.

Awareness Daemon — A background process compiles system state every 90 seconds. Agents boot with pre-compiled context in <1 second. No startup latency, no "remind me what we were doing."

Frame-Based Tool Filtering — Tag tools with context frames. An agent in "backend" mode sees 14 tools, not 95. Saves 50-90% of tool-definition tokens per session.

Signal Protocol — Lightweight event bus with content budgets. Agents emit signals (max 300-800 chars by type), the daemon synthesizes them into awareness. Agents coordinate without direct communication.

Session Handoff — Agents end sessions with structured summaries (files touched, decisions, next steps). The next agent boots with full context of what happened and what to do next.

Signal Compaction — Old signals get summarized, not deleted. Tiered retention (raw → daily → weekly → monthly) keeps context fresh without losing history.

MCP Server — Expose Vigil as an MCP tool server. Any Claude Code, Claude Desktop, Cursor, or Windsurf agent connects and gets persistent awareness instantly.

Articles

• Your MCP Servers Are Flying Blind (Here's How to Fix It) — MCPWatch deep dive on Dev.to

Install

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

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

30-Second Demo

See Vigil work in four commands:

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

Expected output:

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

That's it — your agent has awareness. Read on for the full quickstart with daemon, handoff, and MCP server.

Quickstart

# 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 runs as an MCP server so any AI agent can connect and get persistent awareness.

# stdio (Claude Code, Claude Desktop)
vigil serve

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

Claude Desktop config (claude_desktop_config.json): ``json { "mcpServers": { "vigil": { "command": "vigil", "args": ["serve"] } } } ``

12 MCP tools available:

| Tool | Description | |------|-------------| | vigil_boot | Boot with pre-compiled hot context | | vigil_compile | Force a fresh awareness compilation | | vigil_signal | Emit a signal from an agent | | vigil_status | Get current awareness state | | vigil_signals | Read recent signals | | vigil_handoff | End session with structured handoff | | vigil_resume | Resume from last handoff | | vigil_chain | Get briefing of last N handoffs | | vigil_stale | Find agents that have gone silent | | vigil_focus | Manage priority work queue | | vigil_frames | Manage context frames | | vigil_agents | List known agents and activity |

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': [...]}

Frame-Based Tool Filtering

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)

Signal Compaction

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")

Signal Types & Budgets

| Type | Budget | Use | |------|--------|-----| | observation | 400 chars | Regular activity updates | | handoff | 600 chars | Session conclusions | | summary | 800 chars | Comprehensive summaries | | alert | 300 chars | Urgent notifications |

Architecture

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

• Zero infrastructure — SQLite storage, no Redis/Postgres/Docker required
• Framework-agnostic — Works with any MCP-compatible client, or standalone
• Lightweight — Pure Python, no heavy dependencies (mcp is optional)

Integrations

Ready-to-use configs for popular AI tools. See the examples/ directory for full setup guides.

| Tool | Setup | |------|-------| | Claude Code | claude mcp add vigil -- vigil serve (guide) | | Claude Desktop | Add to claude_desktop_config.json (guide) | | Cursor | Add to .cursor/mcp.json (guide) | | GitHub Actions | Emit signals from CI/CD (workflow) | | Slack | Route alerts to Slack via triggers (guide) | | Discord | Route alerts to Discord via triggers (guide) |

Shell Completion

# Bash
source completions/vigil.bash

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

CLI Reference

| Command | Description | |---------|-------------| | vigil init | Initialize a new project | | vigil quickstart | Interactive setup wizard | | vigil daemon start | Start the awareness daemon | | vigil daemon status | Check daemon compilation status | | vigil serve | Start as MCP server (stdio or SSE) | | vigil signal <agent> <msg> | Emit a signal | | vigil status | Show current awareness | | vigil boot | Show compiled hot context | | vigil frames | List registered frames | | vigil tools [--frame X] | List tools (optionally filtered) | | vigil handoff <agent> <summary> | Write a structured session handoff | | vigil resume <agent> | Resume from last handoff | | vigil history | Browse compacted signal history | | vigil agents | List known agents | | vigil compact | Run signal compaction manually | | vigil know <key> <value> | Store a knowledge entry | | vigil recall <query> | Fuzzy-search knowledge | | vigil knowledge | List all knowledge entries | | vigil forget <key> | Delete a knowledge entry | | vigil extract | Auto-extract knowledge from signal patterns | | vigil export | Export state to markdown | | vigil mcp-health | MCP server health (calls, errors, latency) | | vigil mcp-health-check <cmd> | Probe MCP server in CI (exit 0/1) | | vigil doctor | Diagnose common issues | | vigil version | Show version |

MCP Production Observability

Monitor any MCP server with one line of code. Tracks tool calls, latency, errors, and emits alerts automatically.

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)

What it monitors:

• Silent failures — calls that return empty, null, or blank content with no error raised. Recorded as a distinct silent status, surfaced in health and stats, and alerted on. This is the headline feature.
• Every tool call: name, duration, success / error / silent
• Latency spikes (configurable threshold, default 5s)
• Error patterns with full tracebacks (including low-level isError responses)
• Server silence (no calls at all for N minutes)

Three ways to use it:

# 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)

Check health anytime: ```python 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 ```

A tool that returns "", None, or [] with no exception is the classic MCP blind spot — the SDK reports success, your agent improvises around the void. MCPWatch turns that into a first-class signal.

CLI: ``bash vigil mcp-health # All monitored servers vigil mcp-health -s my-server # Specific server ``

REST API (6 endpoints): | Endpoint | Description | |----------|-------------| | GET /mcp/health | Server health summary (incl. silent rate) | | GET /mcp/tools | Per-tool analytics | | GET /mcp/silent | Recent silent failures (empty/null returns) | | GET /mcp/errors | Recent errors | | GET /mcp/latency | p50/p95/p99 percentiles | | GET /mcp/volume | Call volume over time |

Why Not Just Use Mem0/Letta/LangGraph?

| | Vigil | Mem0 | Letta | LangGraph | |---|---|---|---|---| | Approach | Awareness daemon | Memory retrieval | Stateful runtime | State machine | | Context | Pre-compiled, instant boot | Query on demand | LLM-managed | Checkpoint-based | | Tool filtering | Frame-based (50-90% savings) | None | None | None | | Multi-agent | Signal protocol + handoff | Shared memory | Single agent | Graph edges | | Compaction | Tiered (daily/weekly/monthly) | None | LLM-managed | None | | MCP native | Built-in server | No | No | No | | Infrastructure | SQLite (zero setup) | API + LLM costs | Full runtime | LangChain ecosystem | | Lock-in | None (framework-agnostic) | Mem0 API | Letta platform | LangChain |

Vigil is the nervous system. Others are the filing cabinet. Use them together — Vigil handles awareness and coordination, Mem0/Letta handles deep memory.

License

MIT