agentmemory doctor: it diagnoses config and feature flags interactively and can apply fixes (--all for CI, --dry-run to preview). agentmemory status shows health, memory count, and flags.
Port map
One
--port flag relocates the whole quartet. --instance K is a shortcut for port 3111 + K*100, for side-by-side daemons.
Starting a second instance on an occupied port is refused: it would corrupt the running daemon’s REST routing. Use the running instance, pick a different --instance, or agentmemory stop first.
Common failures
Stop refuses a foreign engine
Stop refuses a foreign engine
agentmemory only adopts an iii-engine it can verify as the pinned version (0.11.2). If another engine version owns the engine port, startup stops with an error instead of adopting it, because the worker would hang in a WebSocket reconnect loop. The fix is two steps:
agentmemory stop --force, then start normally; the pinned engine downloads into ~/.agentmemory/bin.Plain stop only signals the engine this CLI started, found via its pidfile. stop --force bypasses the Docker-heuristic guard and signals whatever the pidfile and lsof report on the REST port; use it when the engine was started natively but the state file is missing.Hybrid search stops returning known records
Hybrid search stops returning known records
The persisted BM25 or vector index is stale or dimensionally wrong (for example after switching embedding providers). Set
AGENTMEMORY_DROP_STALE_INDEX=true and restart: the index drops and rebuilds from KV. Imports index themselves inline; when import-time indexing fails it is logged and the restart rebuild recovers. POST /agentmemory/graph/snapshot-rebuild rebuilds the graph snapshot separately.iii-engine did not become ready within 15s
iii-engine did not become ready within 15s
Startup waits 15 seconds for the engine; this message means the boot failed underneath. Re-run with
--verbose to see engine stderr. If the native binary cannot run on your platform, use Docker: AGENTMEMORY_USE_DOCKER=1 or docker pull iiidev/iii:0.11.2.MCP shim cannot reach the daemon
MCP shim cannot reach the daemon
The
mcp command probes livez before proxying (timeout AGENTMEMORY_PROBE_TIMEOUT_MS, default 2000 ms). Sandboxed MCP clients that cannot reach localhost can set AGENTMEMORY_FORCE_PROXY=1 to skip the probe and trust AGENTMEMORY_URL, or STANDALONE_MCP=1 to run fully in-process against a local store. AGENTMEMORY_DEBUG=1 traces the shim’s decisions to stderr.Hooks stopped firing after an agentmemory upgrade
Hooks stopped firing after an agentmemory upgrade
User-scope hook installs (Claude Code, Codex, Droid, Antigravity CLI) reference absolute paths under the bundled
plugin/ directory, and those paths embed the package version. Re-run agentmemory connect <agent> --with-hooks after every upgrade to refresh them.Circuit breaker open: LLM features silently degrade
Circuit breaker open: LLM features silently degrade
Every LLM provider sits behind a circuit breaker: 3 failures within a 60-second window opens it, LLM calls (compression, summarize, graph extraction) are skipped for 30 seconds, then one probe call decides whether it closes again.
GET /health reports the live state under circuitBreaker (closed, open, or half-open, with failure counts and timestamps). An open breaker means the provider itself is failing — check the key, model name, and endpoint with agentmemory doctor rather than restarting; the breaker recovers on its own once calls succeed. While it’s open, keyless paths (synthetic compression, BM25 and local-embedding search) keep working.Metrics
The worker records named OpenTelemetry counters and histograms (observations.total, search.total, search.latency_ms, compression.success/failure, embedding.latency_ms, circuit_breaker.open, and more) through the iii-engine’s meter, so they flow to wherever the engine’s OTel exporter points. Without an exporter they cost nothing (no-op). GET /health also returns per-function call counts and latencies under functionMetrics, which the viewer renders — the quickest way to see what your agents are actually calling.
Agent-specific failure modes (Codex Desktop silent hooks, OpenClaw slot claims, Antigravity path rules) live on each integration page.