Skip to content

Troubleshooting

Terminal window
agent-mem doctor

Every check prints ✓, ! with the next step, or ✗. Most problems below show up there first. For any error in a command, AGENT_MEM_DEBUG=1 agent-mem <command> prints the full traceback.

The panel never appears and agent-mem status shows no sessions

Cause: the hooks are not registered, not trusted, or point at a missing binary.

  1. agent-mem doctor lists, per agent, whether hooks are registered, whether they match this release, and the command they run. Check that the path exists.
  2. Codex: start codex, run /hooks, trust the agent-mem hooks.
  3. Claude Code: /hooks shows what is registered. Plugin and setup --write both on? Keep one.
  4. Copilot: use agent-mem setup copilot --write; plugin-defined preToolUse hooks do not fire.
  5. Rewrite them: agent-mem setup <agent> --write.
One project is never recorded

Check, in this order: agent-mem status (paused?), excluded_projects in config.json, a .agent-mem.json with "capture": false in the repository root, and whether the folder is inside ~/.claude, ~/.codex, ~/.copilot or ~/.config/opencode (never recorded). AGENT_MEM_DISABLE=1 in the agent’s environment turns everything off.

Executable not found in $PATH: “agent-mem” or command not found in every hook

Cause: the hooks call a command that is gone or not on the agent’s PATH. Typical after uv tool uninstall without agent-mem uninstall all, or with the Claude Code plugin but no installed command.

Fix: install the command (uv tool install "agent-mem[semantic,observer] @ git+https://github.com/Abuarchiv/agent-mem") and run agent-mem setup all --write, which writes absolute paths. To remove agent-mem instead, see Uninstall.

agent-mem cannot save events: they wait in the spool. Run agent-mem doctor.

Cause: events could not reach the database for more than 30 seconds: a lock held by another process, a pending migration, or a damaged database.

Fix: agent-mem index replays the spool (and migrates if needed). agent-mem status shows “Not saved yet: N events”. If it stays, agent-mem doctor names the database problem.

agent-mem cannot save events (…). This session is not being recorded.

Cause: neither the database nor the spool can be written. Usually a full disk or a data folder without write permission.

Fix: free disk space; agent-mem doctor checks space and permissions (doctor --fix makes the folder private and writable by you).

agent-mem cannot use its database (…). What happens now is kept and saved later.

Cause: the database failed (damaged, schema newer than this release, unexpected error). Events go to the spool.

Fix: agent-mem doctor. A damaged database: agent-mem index moves it aside as memory.db.corrupt-<time> and starts a new one. A newer schema: agent-mem upgrade.

status says “could not be read: N files”

Hook payloads that were not valid JSON, lacked a session id or a required field, or exceeded limits.stdin_bytes are noted in quarantine/ instead of being stored. logs/hook.log names the reason. A few after an agent update can mean the agent changed its payload; report it. Notes are deleted after 30 days.

Requests stay “waiting for facts”

agent-mem observe --status shows the queue. Then:

Panel or status saysDo
Facts: off, codex is not installedinstall the agent’s CLI, then agent-mem observe --reprocess-raw
Facts: paused, claude is not logged inlog in once in that CLI; requests wait and are retried within the hour
Facts: paused until 14:20, the usage limit of claude is reachedwait; requests are processed after the pause
nothing, but requests waitagent-mem observe runs a pass now and prints what happened
No facts for N request(s) (last error: …)agent-mem observe --status, then agent-mem observe --retry-failed

The daily limit (observe.daily_limit, 300 calls) holds requests until midnight UTC.

Writing facts is failing: … at session start

The observer’s last run ended with an error. The message names it; logs/observe.log has the run. agent-mem observe runs it in the foreground. “facts unavailable, turns kept raw” means mem0 could not be built (an extra or the embedder is missing): agent-mem upgrade --extras semantic observer.

OpenCode requests never get facts

They go to opencode run with the free opencode/big-pickle model. Check that opencode is on PATH for the observer and that agent-mem doctor does not name it as failing or paused; observe.opencode_model picks another model. Without OpenCode installed a request is saved word for word.

The agent gets no context for a prompt

Only confident matches are injected. Check what exists with agent-mem search "<key words>". A hit below score 0.35, or covering less than half of the words, is left out on purpose. Lower retrieval.inject_min_score or retrieval.min_term_coverage for more (and noisier) context.

Search by meaning: unavailable
CauseFix
the [semantic] extra is missingagent-mem upgrade --extras semantic
the model is not downloadedagent-mem models install
macOS on Intelno fastembed wheels there; word search and the graph still work
the model failed to loadagent-mem doctor names the error; delete models/ and run agent-mem models install
topic links: en_core_web_sm missing

Facts work without topic links. Set observe.entity_model to the language of your facts (de_core_news_sm, en_core_web_sm, …) and run agent-mem models install.

The briefing is too long or too short

budgets.session_start (800) sets it. Claude Code receives at most 2,400 tokens per block regardless; Codex 7,800. See Session briefing.

Cannot start the viewer on 127.0.0.1:37778: …

Another program uses the port. Set "viewer": {"port": <free port>} in config.json. If another agent-mem viewer already answers there, agent-mem serve says so instead and exits 0.

The page says “agent-mem was updated”

The viewer noticed new code after an upgrade and restarts; the page reloads in 3 seconds. If it stays, run agent-mem view, which starts it.

The page says “agent-mem cannot read its memory”

The database could not be opened (locked for long, damaged, being migrated). The page retries every 10 seconds. Run agent-mem doctor.

”Forbidden: Open http://localhost:37778/ instead”

The viewer answers only to localhost:<port> and 127.0.0.1:<port>. Another host name pointing at your machine is refused (protection against DNS rebinding).

MessageCauseFix
agent-mem: the database is busy (database is locked)…another agent-mem process holds a long writetry again shortly
agent-mem: the database is damaged (…)integrity check failedagent-mem index keeps it as memory.db.corrupt-<time> and starts a new one
agent-mem: database schema N is newer than supported M…a newer release wrote the databaseagent-mem upgrade
agent-mem: missing module X…an extra is not installedagent-mem upgrade --extras semantic observer
agent-mem: <file> cannot be read as JSON (…). Nothing was changed…setup found an agent config it cannot parsefix the file (a trailing comma, a comment), run setup again
Refusing to delete … without --yes.purge in a scriptadd --yes
<dir> is not a project root; it lies in project …purge --project with a folder inside a projectpass the project’s root
No recorded project at <dir>.--project names a folder agent-mem never sawcheck the path
duration must look like 30m, 2h or 1dpause --foruse a number with m, h or d
This copy was not installed with uv tool…upgrade on a pipx or pip installupgrade the way you installed, then agent-mem doctor --fix
Upgrade failed; uv names the cause above.uv could not installread uv’s message above it
agent-mem: memory is busy or unavailable (…); try again, or ask the user to run `agent-mem doctor`.
agent-mem: the memory database is damaged (…); ask the user to run `agent-mem doctor`.
M7 belongs to another project; the user can delete it with `agent-mem purge --id M7`.
Stored M9; M3 was not superseded (not an agent memory of this project).