How to Monitor Zep with Vigilmon

Zep is long-term memory infrastructure for AI assistants and agents — it automatically extracts facts, preferences, and entities from conversations and stores them as a knowledge graph. Production AI applications rely on Zep to maintain context beyond a single session, surface relevant memories via semantic search, and run built-in PII detection. When your Zep server goes down, your AI loses its persistent context layer entirely. Vigilmon lets you monitor the Zep API server, track knowledge graph health, and get instant alerts so your agents never lose their memory silently.

What You'll Set Up

• HTTP uptime monitor for your self-hosted Zep server or managed instance
• Cron heartbeat for memory extraction and graph update workers
• SSL certificate expiry alerts for production Zep deployments
• Alert channels for immediate notification on Zep failures

Prerequisites

• Zep running locally or on a VPS (docker compose up or the managed Zep Cloud)
• A Zep API endpoint accessible over HTTP/HTTPS
• A free Vigilmon account

Step 1: Confirm Your Zep Server Health Endpoint

The self-hosted Zep server exposes a built-in health endpoint at /healthz. Confirm it's responding before setting up Vigilmon:

curl https://zep.yourdomain.com/healthz
# {"status":"ok"}

If you're running Zep behind a reverse proxy (nginx, Caddy, Traefik), ensure /healthz is proxied correctly. Here's a minimal nginx configuration:

server {
    listen 443 ssl;
    server_name zep.yourdomain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # /healthz must not require authentication
    location /healthz {
        proxy_pass http://localhost:8000/healthz;
    }
}

For Zep Cloud (managed), monitor your application's API gateway endpoint that calls Zep — or add a lightweight health wrapper in your application (see Step 3).

Step 2: Monitor Your Zep Server

With /healthz confirmed, add a Vigilmon monitor:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Zep health URL: https://zep.yourdomain.com/healthz
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Vigilmon will probe /healthz every minute. If the Zep server process crashes, the database connection fails, or the Docker container exits, the probe returns a non-200 response and Vigilmon fires an alert.

Step 3: Deep Health Check with a Memory Round-Trip

The built-in /healthz confirms Zep is running but not that the knowledge graph pipeline is working end-to-end. Add a round-trip probe to your application that exercises the Zep memory API:

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from zep_python.client import Zep
import uuid, os

app = FastAPI()
zep = Zep(api_key=os.environ["ZEP_API_KEY"])

@app.get("/health/deep")
async def deep_health():
    probe_session_id = f"__vigilmon_probe_{uuid.uuid4().hex[:8]}__"
    try:
        # Create a probe session
        await zep.memory.add_session(session_id=probe_session_id, user_id="__probe__")

        # Write a message and wait for extraction
        from zep_python.memory import Message
        await zep.memory.add(
            session_id=probe_session_id,
            messages=[Message(role="user", content="probe: health check")]
        )

        # Search memory to confirm retrieval works
        results = await zep.memory.search(
            session_id=probe_session_id,
            text="health check",
            limit=1
        )

        # Clean up
        await zep.memory.delete_session(probe_session_id)

        return {"status": "ok", "memory_pipeline": "healthy"}
    except Exception as e:
        return JSONResponse(status_code=503, content={"status": "error", "detail": str(e)})

Monitor /health/deep in Vigilmon with a 5-minute interval — it's more expensive than the lightweight check but catches graph extraction failures that /healthz misses.

Step 4: Heartbeat Monitoring for Memory Extraction Workers

Zep automatically extracts entities and facts from conversations in background workers. If you run additional custom workers — batch memory summarization, knowledge graph enrichment, PII scanning — monitor them with Vigilmon heartbeats:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your worker schedule (e.g. 30 minutes).
3. Copy the heartbeat URL.

Add the ping to your worker after successful completion:

import httpx
from zep_python.client import Zep
import os

zep = Zep(api_key=os.environ["ZEP_API_KEY"])

async def enrich_user_graphs():
    """Run nightly knowledge graph enrichment for all active users."""
    users = await get_active_users()
    for user in users:
        sessions = await zep.memory.list_sessions(user_id=user.id)
        for session in sessions:
            await process_session_entities(session.session_id)

    # Signal successful completion to Vigilmon
    async with httpx.AsyncClient() as client:
        await client.get("https://vigilmon.online/heartbeat/abc123", timeout=5)

If a worker dies before the ping — due to an exception, OOM kill, or graph database timeout — Vigilmon alerts after the missed interval. This catches the kind of silent background failures that don't appear in application logs.

Step 5: SSL Certificate Alerts

Zep's gRPC and HTTP endpoints both require valid TLS in production. Add SSL monitoring for your Zep server domain:

1. Open the HTTP monitor for your Zep endpoint (created in Step 2).
2. Enable Monitor SSL certificate under the SSL section.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

An expired Zep certificate breaks every connected AI assistant and agent simultaneously — the entire memory layer becomes inaccessible. A 21-day alert gives you time to renew before the cascade failure hits production.

Step 6: Monitor the Zep Database Backend

Zep uses PostgreSQL (with pgvector) as its storage layer. Monitor the database host's TCP port to catch Postgres failures before they surface as Zep API errors:

1. In Vigilmon, click Add Monitor → TCP Port.
2. Enter your Postgres host and port: db.yourdomain.com:5432.
3. Set Check interval to 1 minute.
4. Click Save.

A TCP-level failure on port 5432 means Zep's knowledge graph reads and writes will fail even if the Zep process itself is still running. Monitoring TCP separately lets you isolate whether the problem is Zep or its database.

Step 7: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 — Zep graph extraction can be CPU-intensive and may cause brief probe timeouts during heavy load.
3. For multi-tenant Zep deployments, add separate monitors per tenant namespace and tag them clearly.

# Add a maintenance window during Zep upgrades
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 10}'

# Upgrade Zep
docker compose pull && docker compose up -d

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP endpoint | /healthz | Zep process crash, container exit | | Deep health check | /health/deep | Graph extraction failure, API error | | Cron heartbeat | Heartbeat URL | Background worker crash, missed job | | TCP port | Postgres :5432 | Database connection failure | | SSL certificate | Zep API domain | Certificate expiry |

Zep's knowledge graph is what makes your AI assistants contextually intelligent across sessions. With Vigilmon watching every layer — the Zep API server, the memory pipeline, the Postgres backend, and background workers — you'll catch failures before your agents start responding as if they've never met your users before.