> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Ports, stop, auth, indexes, and the engine

Start with `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

| Port  | What                 | Derivation                    |
| ----- | -------------------- | ----------------------------- |
| 3111  | REST API             | `--port N` or `III_REST_PORT` |
| 3112  | Streams API          | N+1                           |
| 3113  | Viewer               | N+2                           |
| 49134 | iii-engine WebSocket | N+46023                       |

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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="401 or unauthorized with a secret set">
    With `AGENTMEMORY_SECRET` set, every REST and viewer request needs `Authorization: Bearer <secret>`; requests without it fail auth. Token comparison is timing-safe. The viewer proxies the REST API with the secret attached, so opening it in a browser keeps working. Without a secret, endpoints are open on loopback only.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## 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](/docs/connectors).