Docs

Troubleshooting

Health checks, missing sessions, word-only search, missing tools in ChatGPT or Claude, and other common questions.

Start with a health check

agent-memory health
agent-memory cloud health --base-url https://agent-memory.jp
agent-memory ingest progress
agent-memory cloud sources --base-url https://agent-memory.jp --limit 1

Expect local health to be ok, cloud health to be authenticated and available, error_count in the ingest progress to be 0, and the latest source to have verified_at.

A session didn't show up

Check that the SessionEnd hook is on: agent-memory hooks status.
Codex asks you to trust new hooks. Approve it in Codex.
Wait for the periodic sweep, or start an import from the app.
Look for files set aside after repeated failures with agent-memory ingest deferred, and add --reset to retry them.

Search only matches words

On your device, the model may not be downloaded yet. Run agent-memory model prepare or use Settings.
Over Remote MCP, semantic search needs your own provider key. query_embedding_not_configured means none is set, and word search is the expected behavior.

ChatGPT or Claude shows only read tools

Disconnect the connector and connect again; refreshing the tool list doesn't authorize again. See When new permissions are added.

Cloud commands fail in local mode

Local mode blocks outbound traffic, so cloud commands and cloud capture are refused. Change the storage mode in the app first.

Nothing listens on a local port

That is expected. The app doesn't run a local HTTP server; agents use the CLI and MCP stdio.

Still stuck?

Email contact@arcm.co.jp with what you ran and what you saw.