Vigil

Vigil

Infraestructura de observabilidad y conciencia para agentes de IA.

Vigil son dos capas en un solo paquete:

• MCPWatch — el vigilante de fallos silenciosos para servidores MCP. Instrumentación de una línea para cualquier servidor MCP en Python (FastMCP y de bajo nivel mcp.server.lowlevel.Server). Las pasarelas y paneles ya te dan gráficos de latencia y errores. Lo que nadie detecta es la llamada que parece exitosa pero no devuelve nada: contenido vacío, nulo o en blanco sin que se lance ningún error. MCPWatch las marca como un estado silent distinto, además de la latencia por herramienta (p50/p95/p99), tasas de error y respuestas isError. Usado en producción en más de 95 herramientas MCP.
• Plataforma de conciencia — contexto compilado por demonio, protocolo de señales, traspaso de sesión, filtrado de herramientas por marcos, servidor MCP. La capa de sistema nervioso que la mayoría de los frameworks de agentes omiten.

La mayoría de las herramientas de memoria para agentes son archivadores. Vigil es un estetoscopio y un sistema nervioso.

El Problema

Los servidores MCP fallan en silencio. Una herramienta devuelve contenido vacío, el SDK se traga la excepción, el agente lo trata como "no se encontraron resultados" y te enteras tres días después por un ticket de cliente. El monitoreo de latencia y errores ya es algo básico (las pasarelas, OpenTelemetry y el propio FastMCP lo emiten). Pero ninguno marca la respuesta vacía pero sin error — el modo de fallo sobre el que tu agente alucina en silencio. Ese vacío es lo que MCPWatch existe para cerrar.

Los agentes lo olvidan todo entre sesiones. Cargan todas las herramientas sin importar el contexto (desperdiciando más de 50K tokens). No pueden coordinarse entre sesiones ni pasarse trabajo entre ellos. Cada conversación empieza en frío.

Qué Hace Vigil

MCPWatch — el vigilante de fallos silenciosos de MCP — Una línea envuelve cualquier servidor MCP en Python (FastMCP o de bajo nivel mcp.server.lowlevel.Server). Su trabajo principal: detectar fallos silenciosos — llamadas que devuelven contenido vacío, nulo o en blanco sin que se lance un error — y registrarlos como un estado silent distinto que aparece en salud, estadísticas por herramienta y alertas. También rastrea la latencia de llamadas a herramientas (p50/p95/p99), tasas de error por herramienta, respuestas isError y volumen de llamadas a lo largo del tiempo. API REST, CLI y enlaces de alerta. MIT, sin configuración requerida.

Demonio de Conciencia — Un proceso en segundo plano compila el estado del sistema cada 90 segundos. Los agentes arrancan con contexto precompilado en menos de 1 segundo. Sin latencia de inicio, sin "recuérdame qué estábamos haciendo".

Filtrado de Herramientas por Marcos — Etiqueta herramientas con marcos de contexto. Un agente en modo "backend" ve 14 herramientas, no 95. Ahorra 50-90% de tokens de definición de herramientas por sesión.

Protocolo de Señales — Bus de eventos ligero con presupuestos de contenido. Los agentes emiten señales (máximo 300-800 caracteres según tipo), el demonio las sintetiza en conciencia. Los agentes se coordinan sin comunicación directa.

Traspaso de Sesión — Los agentes terminan sesiones con resúmenes estructurados (archivos tocados, decisiones, próximos pasos). El siguiente agente arranca con contexto completo de lo que pasó y qué hacer después.

Compactación de Señales — Las señales antiguas se resumen, no se eliminan. Retención por niveles (crudo → diario → semanal → mensual) mantiene el contexto fresco sin perder historia.

Servidor MCP — Expón Vigil como un servidor de herramientas MCP. Cualquier agente de Claude Code, Claude Desktop, Cursor o Windsurf se conecta y obtiene conciencia persistente al instante.

Artículos

• Tus Servidores MCP Están Volando a Ciegas (Así Se Arregla) — Análisis profundo de MCPWatch en Dev.to

Instalación

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

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

Demo de 30 Segundos

Ve a Vigil funcionar en cuatro comandos:

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

Salida esperada:

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

Eso es todo — tu agente tiene conciencia. Sigue leyendo para el inicio rápido completo con demonio, traspaso y servidor MCP.

Inicio Rápido

# 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

Servidor MCP

Vigil se ejecuta como un servidor MCP para que cualquier agente de IA pueda conectarse y obtener conciencia persistente.

# stdio (Claude Code, Claude Desktop)
vigil serve

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

Configuración de Claude Desktop (claude_desktop_config.json):

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

12 herramientas MCP disponibles:

Herramienta	Descripción
vigil_boot	Arranca con contexto caliente precompilado
vigil_compile	Fuerza una compilación de conciencia nueva
vigil_signal	Emite una señal desde un agente
vigil_status	Obtén el estado actual de conciencia
vigil_signals	Lee señales recientes
vigil_handoff	Termina sesión con traspaso estructurado
vigil_resume	Reanuda desde el último traspaso
vigil_chain	Obtén informe de los últimos N traspasos
vigil_stale	Encuentra agentes que han quedado en silencio
vigil_focus	Gestiona la cola de trabajo prioritario
vigil_frames	Gestiona marcos de contexto
vigil_agents	Lista agentes conocidos y actividad

API de Python

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

Filtrado de Herramientas por Marcos

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)

Compactación de Señales

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

Tipos de Señal y Presupuestos

Tipo	Presupuesto	Uso
observation	400 caracteres	Actualizaciones regulares de actividad
handoff	600 caracteres	Conclusiones de sesión
summary	800 caracteres	Resúmenes completos
alert	300 caracteres	Notificaciones urgentes

Arquitectura

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

• Cero infraestructura — Almacenamiento SQLite, sin Redis/Postgres/Docker requeridos
• Independiente del framework — Funciona con cualquier cliente compatible con MCP, o de forma autónoma
• Ligero — Python puro, sin dependencias pesadas (mcp es opcional)

Integraciones

Configuraciones listas para usar para herramientas de IA populares. Consulta el directorio examples/ para guías completas de configuración.

Herramienta	Configuración
Claude Code	claude mcp add vigil -- vigil serve (guía)
Claude Desktop	Añadir a claude_desktop_config.json (guía)
Cursor	Añadir a .cursor/mcp.json (guía)
GitHub Actions	Emitir señales desde CI/CD (workflow)
Slack	Enrutar alertas a Slack mediante disparadores (guía)
Discord	Enrutar alertas a Discord mediante disparadores (guía)

Completado de Shell

# Bash
source completions/vigil.bash

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

Referencia de CLI

Comando	Descripción
vigil init	Inicializa un nuevo proyecto
vigil quickstart	Asistente de configuración interactivo
vigil daemon start	Inicia el demonio de conciencia
vigil daemon status	Comprueba el estado de compilación del demonio
vigil serve	Inicia como servidor MCP (stdio o SSE)
vigil signal <agent> <msg>	Emite una señal
vigil status	Muestra la conciencia actual
vigil boot	Muestra el contexto caliente compilado
vigil frames	Lista los marcos registrados
vigil tools [--frame X]	Lista herramientas (opcionalmente filtradas)
vigil handoff <agent> <summary>	Escribe un traspaso de sesión estructurado
vigil resume <agent>	Reanuda desde el último traspaso
vigil history	Navega por el historial de señales compactadas
vigil agents	Lista agentes conocidos
vigil compact	Ejecuta la compactación de señales manualmente
vigil know <key> <value>	Almacena una entrada de conocimiento
vigil recall <query>	Búsqueda difusa de conocimiento
vigil knowledge	Lista todas las entradas de conocimiento
vigil forget <key>	Elimina una entrada de conocimiento
vigil extract	Extrae conocimiento automáticamente de patrones de señales
vigil export	Exporta el estado a markdown
vigil mcp-health	Salud del servidor MCP (llamadas, errores, latencia)
vigil mcp-health-check <cmd>	Prueba el servidor MCP en CI (salida 0/1)
vigil doctor	Diagnostica problemas comunes
vigil version	Muestra la versión

Observabilidad de Producción MCP

Monitorea cualquier servidor MCP con una línea de código. Rastrea llamadas a herramientas, latencia, errores y emite alertas automáticamente.

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)

Lo que monitorea:

• Fallos silenciosos — llamadas que devuelven contenido vacío, nulo o en blanco sin que se lance un error. Registrados como un estado silent distinto, mostrados en salud y estadísticas, y alertados. Esta es la característica principal.
• Cada llamada a herramienta: nombre, duración, éxito / error / silencioso
• Picos de latencia (umbral configurable, por defecto 5s)
• Patrones de error con tracebacks completos (incluyendo respuestas isError de bajo nivel)
• Silencio del servidor (sin llamadas durante N minutos)

Tres formas de usarlo:

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

Comprueba la salud en cualquier momento:

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

Una herramienta que devuelve "", None o [] sin excepción es el punto ciego clásico de MCP — el SDK reporta éxito, tu agente improvisa alrededor del vacío. MCPWatch lo convierte en una señal de primera clase.

CLI:

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

API REST (6 endpoints):

Endpoint	Descripción
GET /mcp/health	Resumen de salud del servidor (incl. tasa de silencio)
GET /mcp/tools	Analíticas por herramienta
GET /mcp/silent	Fallos silenciosos recientes (retornos vacíos/nulos)
GET /mcp/errors	Errores recientes
GET /mcp/latency	Percentiles p50/p95/p99
GET /mcp/volume	Volumen de llamadas a lo largo del tiempo

¿Por Qué No Simplemente Usar Mem0/Letta/LangGraph?

	Vigil	Mem0	Letta	LangGraph
Enfoque	Demonio de conciencia	Recuperación de memoria	Runtime con estado	Máquina de estados
Contexto	Precompilado, arranque instantáneo	Consulta bajo demanda	Gestionado por LLM	Basado en checkpoints
Filtrado de herramientas	Basado en marcos (ahorro 50-90%)	Ninguno	Ninguno	Ninguno
Multi-agente	Protocolo de señales + traspaso	Memoria compartida	Agente único	Aristas de grafo
Compactación	Por niveles (diario/semanal/mensual)	Ninguna	Gestionada por LLM	Ninguna
MCP nativo	Servidor integrado	No	No	No
Infraestructura	SQLite (cero configuración)	Costos de API + LLM	Runtime completo	Ecosistema LangChain
Bloqueo	Ninguno (independiente del framework)	API Mem0	Plataforma Letta	LangChain

Vigil es el sistema nervioso. Los demás son el archivador. Úsalos juntos — Vigil maneja la conciencia y la coordinación, Mem0/Letta maneja la memoria profunda.

Licencia

MIT