hermes-memory-installer: Memory Sidecar v3.5.1

Memory Sidecar v3.5.1 is an operational hardening release for the public agent‑agnostic memory layer. If you already use the sidecar pattern to give your AI agents robust, persistent memory without coupling them to a specific framework, this update focuses on making that infrastructure more resilient in production. The accompanying hermes-memory-installer gets targeted improvements to match.

What Memory Sidecar Does

Memory Sidecar runs as a standalone HTTP service that translates generic memory operations (store, recall, update) into your chosen backend – PostgreSQL, Redis, SQLite, or a custom store. Agents connect via a lightweight agent‑SDK or raw HTTP, which makes the sidecar framework‑agnostic. This release (v3.5.1) does not add new endpoints; it hardens existing ones.

Operational Hardening at a Glance

Every change in this release addresses real failure modes observed in long‑running deployments:

• Connection pooling fixes: The HTTP keep‑alive pool used for agent→sidecar communication could leak sockets under high concurrency. v3.5.1 replaces the custom pool with a bounded, reuse‑aware implementation that drains idle connections on shutdown. Memory pressure from lingering connections is gone.

• Backend store retry logic: When the underlying store (e.g., Redis Cluster) becomes briefly unreachable, the sidecar now applies jittered exponential backoff. The default window is 10 s with a maximum of 3 retries – configurable via MEMORY_STORE_RETRY_MAX and MEMORY_STORE_RETRY_BASE_MS. Stale connection errors from the driver layer are caught and retried transparently.

• Health check improvements: The /health endpoint now checks the actual backend connection, not just the HTTP server state. A new optional header X-Health-Timeout lets monitoring tools control check duration. Failed checks now include a structured JSON body with the failing component (store, cache, crypto).

• Memory footprint: Pre‑allocated buffers are used for request serialization, reducing GC pressure. The baseline resident set size dropped ~12 % in our benchmarks under 100 concurrent sessions.

• Graceful shutdown: SIGTERM (and SIGINT on non‑Windows) initiates a draining phase: in‑flight requests complete, health checks return 503, and the backend store connection flushes pending writes. The sidecar exits only after all clients disconnect or a 30 s timeout elapses.

Installer Updates in v3.5.1

The hermes-memory-installer script (the recommended way to deploy the sidecar binary) now includes:

• Checksum verification: The installer downloads SHA256SUMS from the same release directory and verifies the binary signature before placing it. If the checksum fails, the installer exits with a non‑zero code and does not modify any existing installation.

• Idempotent re‑runs: Running the installer over an existing installation no longer restarts the sidecar unless the binary hash changed. This makes it safe to keep hermes-memory-installer in CI/CD pipelines.

• Version pinning: Pass -p 3.5.1 to lock the installer to a specific patch level; without it, the installer fetches the latest stable (currently 3.5.1). Combined with the checksums, you get reproducible deployments.

Upgrade / Installation Example

# Download the installer, verify, and install the sidecar into /opt/memory-sidecar
curl -sL https://hermes-releases.example.com/hermes-memory-installer.sh -o installer.sh
chmod +x installer.sh
sudo ./installer.sh -p 3.5.1 -d /opt/memory-sidecar

# The installer automatically:
#   - Verifies checksum
#   - Stops the old service (if any)
#   - Replaces the binary
#   - Preserves existing configuration
#   - Restarts the service

Enter fullscreen mode Exit fullscreen mode

After upgrading, verify the sidecar is running the correct version:

curl -s http://localhost:8700/version | jq .
# { "version": "3.5.1", "commit": "a7ef90b", "build_date": "2025-04-01T08:00:00Z" }

Enter fullscreen mode Exit fullscreen mode

Configuration Changes to Review

The default configuration file (memory-sidecar.yml) remains backward compatible, but you may want to add:

server:
  health_timeout: 5s          # previously hardcoded to 3s
  shutdown_grace_period: 30s  # new, matches what installer uses

store:
  retry:
    max_attempts: 3           # default, was 1
    base_backoff_ms: 200      # was 0 (no backoff)

Enter fullscreen mode Exit fullscreen mode

No manual changes are required; existing configs work as before. The new values only activate if you explicitly set them.

Why Upgrade Now

If you run Memory Sidecar in a staging or production environment, this release eliminates several classes of intermittent failures we logged from the community over the past months – particularly connection leaks under traffic spikes and unhandled store driver errors during network blips. The installer improvements also remove the risk of a partially updated binary due to corrupted downloads.

The v3.5.x branch will continue receiving critical fixes. Next up is support for client‑side session caching (v3.6 planning). For now, update your installer invocation and enjoy a quieter operations dashboard.