Skip to content

feat(serve): add --watch flag with /healthz endpoint for container health checks #543

Description

@fuleinist

Summary

Add a --watch / --interval flag to engram serve that periodically re-runs health checks and exposes a lightweight metrics endpoint (/healthz with uptime, observation count, session count, DB size). Useful for containerized/PM2/supervisord deployments that need liveness probes.

Proposed behavior

engram serve --watch --interval 30s
  • Exposes GET /healthz returning { "status": "ok", "uptime_s": 1234, "observations": 150, "sessions": 3, "db_size_bytes": 65536 }
  • --interval controls health-check polling (default 30s)
  • --watch enables the endpoint (disabled by default ??? no breaking change)
  • Returns 503 if the server is unhealthy (DB unreachable, import queue backlogged)

Why

Engram is increasingly used in agentic workflows where uptime matters. Currently there's no way to health-check a running engram serve instance ??? useful for Docker healthchecks, Kubernetes liveness probes, or just monitoring via curl.

Implementation notes

  • Lightweight ??? reuse existing HTTP server, add one route
  • No new dependencies (Go stdlib net/http is sufficient)
  • Metrics are cheap counters/gauges already tracked in memory

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions