[@agentmemory/mcp] livez probe ${url}/agentmemory/livez fail

Error message

[@agentmemory/mcp] livez probe ${url}/agentmemory/livez failed in ${timeout}ms: ${err instanceof Error ? err.message : String(err)}; falling back to local InMemoryKV (set AGENTMEMORY_FORCE_PROXY=1 to skip the probe, or raise AGENTMEMORY_PROBE_TIMEOUT_MS)

What it means

When the MCP layer starts, probe() issues a livez HTTP probe against the configured AGENTMEMORY_URL (/agentmemory/livez) to decide whether to proxy to the daemon. On a thrown error (connection refused, DNS failure, abort on timeout) it writes this diagnostic to stderr and returns false, causing the MCP server to fall back to a local InMemoryKV instead of the persistent daemon. It is a warning log, not an exception that propagates.

Source

Thrown at src/mcp/rest-proxy.ts:104

 * dropped before the next call.
 */
export function setLivezProbe(fn?: LivezProbe): void {
  livezProbe = fn ?? defaultLivezProbe;
}

async function probe(url: string): Promise<boolean> {
  const timeout = probeTimeoutMs();
  try {
    const res = await livezProbe(url, timeout, authHeader());
    if (!res.ok) {
      process.stderr.write(
        `[@agentmemory/mcp] livez probe ${url}/agentmemory/livez -> ${res.status ?? "?"} ${res.statusText ?? ""}; falling back to local InMemoryKV (set AGENTMEMORY_FORCE_PROXY=1 to skip the probe)\n`,
      );
    }
    return res.ok;
  } catch (err) {
    process.stderr.write(
      `[@agentmemory/mcp] livez probe ${url}/agentmemory/livez failed in ${timeout}ms: ${err instanceof Error ? err.message : String(err)}; falling back to local InMemoryKV (set AGENTMEMORY_FORCE_PROXY=1 to skip the probe, or raise AGENTMEMORY_PROBE_TIMEOUT_MS)\n`,
    );
    return false;
  }
}

export function invalidateHandle(): void {
  cached = null;
  cachedAt = 0;
}

export async function resolveHandle(): Promise<Handle> {
  const now = Date.now();
  if (cached) {
    if (cached.mode === "local" && now - cachedAt >= LOCAL_MODE_TTL_MS) {
      cached = null;
      cachedAt = 0;
    } else {
      return cached;

View on GitHub (pinned to e04ba88819)

Solutions

Start the agentmemory daemon and verify the URL responds: curl ${AGENTMEMORY_URL}/agentmemory/livez.
Correct AGENTMEMORY_URL (scheme, host, port) to match the running daemon.
Raise AGENTMEMORY_PROBE_TIMEOUT_MS (e.g. 5000) if the daemon is slow to start.
Set AGENTMEMORY_FORCE_PROXY=1 to skip the probe and always proxy if you know the daemon will be there.

Example fix

// before: probe times out against wrong port
// AGENTMEMORY_URL=http://127.0.0.1:3113
// after
export AGENTMEMORY_URL=http://127.0.0.1:3111
export AGENTMEMORY_PROBE_TIMEOUT_MS=5000

Defensive patterns

Strategy: retry

Validate before calling

const url = process.env.AGENTMEMORY_URL ?? "http://127.0.0.1:3111";
try {
  const r = await fetch(`${url}/agentmemory/livez`, { signal: AbortSignal.timeout(5000) });
  if (!r.ok) throw new Error(`livez ${r.status}`);
} catch (e) { console.error("daemon not reachable; start it or fix AGENTMEMORY_URL"); }

Try / catch

let up = false;
for (let i = 0; i < 5 && !up; i++) {
  up = await probe();
  if (!up) await new Promise(r => setTimeout(r, 500));
}
if (!up) console.error("falling back to InMemoryKV; data will not persist");

Prevention

Start the daemon before launching the MCP server (supervisor/entrypoint ordering).
Pin AGENTMEMORY_URL explicitly and verify with curl /agentmemory/livez.
Raise AGENTMEMORY_PROBE_TIMEOUT_MS in cold-start environments.
Set AGENTMEMORY_FORCE_PROXY=1 when the daemon is guaranteed but slow to boot.

When it happens

Trigger: The fetch to ${url}/agentmemory/livez throws: daemon not running, AGENTMEMORY_URL points to the wrong host/port, a timeout exceeds AGENTMEMORY_PROBE_TIMEOUT_MS, or a transient network error.

Common situations: Developer forgot to start the agentmemory daemon before launching the MCP server; AGENTMEMORY_URL misconfigured (wrong port, https vs http); slow daemon startup exceeding the probe timeout in CI or cold containers.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/c13f142d13d03148. Report an issue: GitHub.