Troubleshooting

Start with the checks below. Keep your memory folder in place while you diagnose a problem.

Check the local setup

npx memindex doctor
npx memindex status

Doctor checks the installed files, Bun, uv, the local service, and your note writer. It reports the address it checked. Use that address instead of assuming a fixed port.

Two rows describe the note writer and its tools:

• Note writer is a required check. It fails when the writer you chose cannot work: no Claude login or key, an expired login, a Claude command that will not start, a service with no key or model, a missing Codex command, a name MemIndex does not know, or a writer that keeps failing. In that case the row shows the last error. If your chosen service is not ready, the row also says whether Claude would take over and whether Claude can work. Doctor never sends a request to a model to find this out.
• Worker dependencies lists Bun, uv, the code-reading tool, whether the data folder can be written to, and anything the running service says is missing. Each gap is printed as PROBLEM:.

Doctor also warns when the running service and the command you ran are different versions. Restart the service after an update.

Read each row. “All required checks passed” does not prove that the background service is running. The Worker daemon check does not affect that final result.

The background service is stopped

npx memindex start

If the service responds but needs a restart:

npx memindex restart
npx memindex doctor

Restart your agent after installing or changing its integration. See its setup page.

Installed files or tools are missing

If doctor recommends repair:

npx memindex repair
npx memindex doctor

Repair can reinstall dependencies and supporting tools. On Windows, check the Git Bash row. Bun is needed to run MemIndex; uv supports local search by meaning.

Reading memory is refused

Reading memory needs the install secret. If you see a 401 answer, a notice that says MemIndex will not show your notes to a page that did not come from it, or a message that reading memory needs the install secret, check these:

1. Open the viewer with the link MemIndex prints when a session starts. A bare localhost address will not show notes.
2. If a program was running before you upgraded, restart it, or run npx memindex update. Older versions did not send the secret.
3. If you wrote a script, send the X-Memindex-Secret header with the contents of the worker-secret file in your data folder. Privacy shows how.

The viewer cannot save changes

Open the private View memory link printed by the installer in the tab you want to use. Opening the service address from doctor lets you browse, but does not authorize settings changes or deletion. Keep the private link out of anything you share.

No new notes appear

1. Check that your agent supports automatic capture. Some connections only search existing memory.
2. Start a fresh session in the intended project after restarting the agent.
3. Check that the project is not excluded and the whole turn is not marked private.
4. Run npx memindex doctor and read the Note writer row. It names what is wrong and how to fix it.
5. Check the account or API key for the service that writes your notes. If your Claude login keeps expiring, run claude setup-token and put the token in ~/.memindex/.env as CLAUDE_CODE_OAUTH_TOKEN.
6. Check its usage limit. A signed-in plan and an API account can have different limits.
7. Check that note writing is on. If the status line says “notes paused”, MEMINDEX_OBSERVER_ENABLED is set to false. See Settings.

Note-writing happens in the background. A working agent does not prove that notes have finished saving. Check the viewer for the expected project and session.

Notes stop on a gateway or an OpenRouter model

If you write notes through OpenRouter or another OpenAI-compatible service, MemIndex turns reasoning off by default so a thinking model cannot spend the whole reply and leave no note. If a reply is cut off at the size limit, MemIndex asks once more. If the service rejects the reasoning setting, MemIndex asks again without it. If the model refuses a request, the status panel says the model refused and that restarting will not help. Choose a different model in Settings.

Search misses something

Check the project and any filters first. Try a word you remember from the work. Look at recent notes in the viewer to see whether the work was captured.

Doctor can report failures in the local search service. If it says the search index is being rebuilt, results by meaning may be incomplete while that finishes. The saved database is separate from that index.

A server connection fails

Check the server's address and whether your key is still valid. The agent needs a project setting as well as an address and key. If it still fails, write to [email protected].

Search-only connections use /v1/mcp. A refused request may mean the key lacks permission or belongs to a different project. A server-side limit can also pause writes.

Some capture failures fall back to the local service. That does not prove the memory reached the server. Check the expected server project before relying on it from another machine.

Pi and DeepSeek Harness use the local setup. See hosting and plans for server limits.

Ask for help

Send the command that failed, the exact error, your operating system, and the agent you use to [email protected].

Remove keys, private connection links, personal file paths, and work content from any output you share. Do not send your memory database or an export as a routine diagnostic.