Vigil

Vigil

Infraestrutura de observabilidade e consciência para agentes de IA.

Vigil é duas camadas em um único pacote:

• MCPWatch — o vigia de falhas silenciosas para servidores MCP. Instrumentação de uma linha para qualquer servidor MCP em Python (FastMCP e mcp.server.lowlevel.Server de baixo nível). Gateways e dashboards já fornecem gráficos de latência e erros. O que ninguém detecta é a chamada que parece bem-sucedida, mas não retorna nada: conteúdo vazio, nulo ou em branco sem erro levantado. MCPWatch sinaliza esses casos como um status distinto de silent, além da latência por ferramenta (p50/p95/p99), taxas de erro e respostas isError. Usado em produção em mais de 95 ferramentas MCP.
• Plataforma de consciência — contexto compilado por daemon, protocolo de sinais, transferência de sessão, filtragem de ferramentas baseada em quadros, servidor MCP. A camada de sistema nervoso que a maioria dos frameworks de agentes ignora.

A maioria das ferramentas de memória para agentes são arquivos. Vigil é um estetoscópio e um sistema nervoso.

O Problema

Servidores MCP falham silenciosamente. Uma ferramenta retorna conteúdo vazio, o SDK engole a exceção, o agente trata como "nenhum resultado encontrado" e você descobre três dias depois por um ticket de cliente. Monitoramento de latência e erros agora é o básico (gateways, OpenTelemetry e o próprio FastMCP emitem isso). Mas nenhum deles sinaliza a resposta vazia-mas-sem-erro — o modo de falha em torno do qual seu agente alucina silenciosamente. Essa lacuna é o que MCPWatch existe para fechar.

Agentes esquecem tudo entre sessões. Eles carregam todas as ferramentas independentemente do contexto (gastando 50K+ tokens). Não conseguem coordenar entre sessões nem transferir trabalho uns para os outros. Cada conversa começa do zero.

O Que Vigil Faz

MCPWatch — o vigia de falhas silenciosas do MCP — Uma linha envolve qualquer servidor MCP em Python (FastMCP ou mcp.server.lowlevel.Server de baixo nível). Sua principal função: detectar falhas silenciosas — chamadas que retornam conteúdo vazio, nulo ou em branco sem erro levantado — e registrá-las como um status distinto de silent que aparece na saúde, estatísticas por ferramenta e alertas. Também rastreia latência de chamadas de ferramenta (p50/p95/p99), taxas de erro por ferramenta, respostas isError e volume de chamadas ao longo do tempo. API REST, CLI e hooks de alerta. MIT, sem configuração necessária.

Daemon de Consciência — Um processo em segundo plano compila o estado do sistema a cada 90 segundos. Agentes iniciam com contexto pré-compilado em menos de 1 segundo. Sem latência de inicialização, sem "me lembre do que estávamos fazendo."

Filtragem de Ferramentas Baseada em Quadros — Marque ferramentas com quadros de contexto. Um agente em modo "backend" vê 14 ferramentas, não 95. Economiza 50-90% dos tokens de definição de ferramentas por sessão.

Protocolo de Sinais — Barramento de eventos leve com orçamentos de conteúdo. Agentes emitem sinais (máx. 300-800 caracteres por tipo), o daemon os sintetiza em consciência. Agentes coordenam sem comunicação direta.

Transferência de Sessão — Agentes encerram sessões com resumos estruturados (arquivos tocados, decisões, próximos passos). O próximo agente inicia com contexto completo do que aconteceu e do que fazer em seguida.

Compactação de Sinais — Sinais antigos são resumidos, não excluídos. Retenção em camadas (bruto → diário → semanal → mensal) mantém o contexto fresco sem perder histórico.

Servidor MCP — Exponha Vigil como um servidor de ferramentas MCP. Qualquer agente Claude Code, Claude Desktop, Cursor ou Windsurf conecta e obtém consciência persistente instantaneamente.

Artigos

• Seus Servidores MCP Estão Voando às Cegas (Veja Como Corrigir) — Análise aprofundada do MCPWatch no Dev.to

Instalação

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

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

Demonstração de 30 Segundos

Veja Vigil funcionar em quatro comandos:

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

Saída esperada:

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

É isso — seu agente tem consciência. Continue lendo para o quickstart completo com daemon, transferência e servidor MCP.

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

Servidor MCP

Vigil roda como um servidor MCP para que qualquer agente de IA possa conectar e obter consciência persistente.

# stdio (Claude Code, Claude Desktop)
vigil serve

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

Configuração do Claude Desktop (claude_desktop_config.json):

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

12 ferramentas MCP disponíveis:

Ferramenta	Descrição
vigil_boot	Inicie com contexto quente pré-compilado
vigil_compile	Force uma nova compilação de consciência
vigil_signal	Emita um sinal de um agente
vigil_status	Obtenha o estado atual de consciência
vigil_signals	Leia sinais recentes
vigil_handoff	Encerre sessão com transferência estruturada
vigil_resume	Retome da última transferência
vigil_chain	Obtenha briefing das últimas N transferências
vigil_stale	Encontre agentes que ficaram silenciosos
vigil_focus	Gerencie fila de trabalho prioritária
vigil_frames	Gerencie quadros de contexto
vigil_agents	Liste agentes conhecidos e atividade

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

Filtragem de Ferramentas Baseada em Quadros

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)

Compactação de Sinais

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 Sinais e Orçamentos

Tipo	Orçamento	Uso
observation	400 caracteres	Atualizações regulares de atividade
handoff	600 caracteres	Conclusões de sessão
summary	800 caracteres	Resumos abrangentes
alert	300 caracteres	Notificações urgentes

Arquitetura

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

• Zero infraestrutura — Armazenamento SQLite, sem necessidade de Redis/Postgres/Docker
• Agnóstico de framework — Funciona com qualquer cliente compatível com MCP, ou standalone
• Leve — Python puro, sem dependências pesadas (mcp é opcional)

Integrações

Configurações prontas para uso em ferramentas de IA populares. Veja o diretório examples/ para guias completos de configuração.

Ferramenta	Configuração
Claude Code	claude mcp add vigil -- vigil serve (guia)
Claude Desktop	Adicione ao claude_desktop_config.json (guia)
Cursor	Adicione ao .cursor/mcp.json (guia)
GitHub Actions	Emita sinais de CI/CD (workflow)
Slack	Roteie alertas para o Slack via triggers (guia)
Discord	Roteie alertas para o Discord via triggers (guia)

Completar de Shell

# Bash
source completions/vigil.bash

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

Referência da CLI

Comando	Descrição
vigil init	Inicialize um novo projeto
vigil quickstart	Assistente de configuração interativo
vigil daemon start	Inicie o daemon de consciência
vigil daemon status	Verifique o status de compilação do daemon
vigil serve	Inicie como servidor MCP (stdio ou SSE)
vigil signal <agent> <msg>	Emita um sinal
vigil status	Mostre a consciência atual
vigil boot	Mostre o contexto quente compilado
vigil frames	Liste quadros registrados
vigil tools [--frame X]	Liste ferramentas (opcionalmente filtradas)
vigil handoff <agent> <summary>	Escreva uma transferência de sessão estruturada
vigil resume <agent>	Retome da última transferência
vigil history	Navegue pelo histórico de sinais compactados
vigil agents	Liste agentes conhecidos
vigil compact	Execute compactação de sinais manualmente
vigil know <key> <value>	Armazene uma entrada de conhecimento
vigil recall <query>	Pesquisa difusa de conhecimento
vigil knowledge	Liste todas as entradas de conhecimento
vigil forget <key>	Exclua uma entrada de conhecimento
vigil extract	Extraia conhecimento automaticamente de padrões de sinais
vigil export	Exporte o estado para markdown
vigil mcp-health	Saúde do servidor MCP (chamadas, erros, latência)
vigil mcp-health-check <cmd>	Teste o servidor MCP em CI (saída 0/1)
vigil doctor	Diagnostique problemas comuns
vigil version	Mostre a versão

Observabilidade de Produção MCP

Monitore qualquer servidor MCP com uma linha de código. Rastreia chamadas de ferramentas, latência, erros e emite alertas automaticamente.

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)

O que monitora:

• Falhas silenciosas — chamadas que retornam conteúdo vazio, nulo ou em branco sem erro levantado. Registradas como um status distinto de silent, exibidas na saúde e estatísticas, e alertadas. Este é o recurso principal.
• Cada chamada de ferramenta: nome, duração, sucesso / erro / silencioso
• Picos de latência (limite configurável, padrão 5s)
• Padrões de erro com tracebacks completos (incluindo respostas isError de baixo nível)
• Silêncio do servidor (nenhuma chamada por N minutos)

Três maneiras de usar:

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

Verifique a saúde a qualquer 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

Uma ferramenta que retorna "", None ou [] sem exceção é o ponto cego clássico do MCP — o SDK reporta sucesso, seu agente improvisa em torno do vazio. MCPWatch transforma isso em um sinal de primeira classe.

CLI:

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

API REST (6 endpoints):

Endpoint	Descrição
GET /mcp/health	Resumo de saúde do servidor (incl. taxa de silêncio)
GET /mcp/tools	Análises por ferramenta
GET /mcp/silent	Falhas silenciosas recentes (retornos vazios/nulos)
GET /mcp/errors	Erros recentes
GET /mcp/latency	Percentis p50/p95/p99
GET /mcp/volume	Volume de chamadas ao longo do tempo

Por Que Não Usar Apenas Mem0/Letta/LangGraph?

	Vigil	Mem0	Letta	LangGraph
Abordagem	Daemon de consciência	Recuperação de memória	Runtime com estado	Máquina de estados
Contexto	Pré-compilado, inicialização instantânea	Consulta sob demanda	Gerenciado por LLM	Baseado em checkpoints
Filtragem de ferramentas	Baseada em quadros (economia de 50-90%)	Nenhuma	Nenhuma	Nenhuma
Multi-agente	Protocolo de sinais + transferência	Memória compartilhada	Agente único	Arestas de grafo
Compactação	Em camadas (diário/semanal/mensal)	Nenhuma	Gerenciada por LLM	Nenhuma
Nativo MCP	Servidor integrado	Não	Não	Não
Infraestrutura	SQLite (zero configuração)	Custos de API + LLM	Runtime completo	Ecossistema LangChain
Aprisionamento	Nenhum (agnóstico de framework)	API Mem0	Plataforma Letta	LangChain

Vigil é o sistema nervoso. Os outros são o arquivo. Use-os juntos — Vigil cuida da consciência e coordenação, Mem0/Letta cuida da memória profunda.

Licença

MIT