OperationsTroubleshooting

Troubleshooting

Recall returns 0 hits

Run curl http://localhost:3000/v1/health and check three fields.

If embeddings.indexed is 0, no embedder is configured. Set MNEMO_LLM_PROVIDER + MNEMO_LLM_API_KEY so new writes embed inline; once a provider is attached, recall starts using the vector index.

If lastRecallAt is very old, recall may be hitting a stale tier. The hot tier rebuilds from Postgres on the next boot — restart the server to warm it.

If factsLive is 0 you probably authenticated against the wrong workspace. The workspace is derived from the API key, so verify you’re using a key bound to the workspace you expect.

In Mode A (no embedder) the matcher is lexical. Make sure your query shares textual terms with the stored statement.

Embedded 0% in the Brain Inspector

This was a bug in v2.1: the /health route emitted snapshotAt while the hook read capturedAt. Hard-refresh the dashboard after upgrading.

If the percentage is genuinely 0, no embedding provider is configured. Set MNEMO_LLM_PROVIDER + MNEMO_LLM_API_KEY; new and updated facts then embed inline as they’re written.

401 missing_bearer_token

The Authorization header is absent or malformed. The format is Authorization: Bearer mns_live_xxx. The Bearer prefix is required.

403 workspace_mismatch

The bearer token doesn’t have access to the workspace the request targets. The workspace is derived from the API key, so mint a key bound to the right workspace with the create-api-key script:

docker compose exec server node scripts/create-api-key.cjs --workspace ws_xxx

409 conflict_detected

A write contradicts an existing fact. The response body lists the conflicting fact IDs and a verdict from the deterministic resolver.

You can trust the verdict (re-submit with forceSupersede: true), trust the existing fact (drop the new write), or defer (let the conflict sit in /v1/review).

429 rate_limited

You exceeded the per-key bucket. Honour the Retry-After header.

To raise the limit at the database:

UPDATE mnemo_api_keys SET recall_rpm = 6000 WHERE id = 'key_xxx';

Mnemosyne will not boot

Check the container logs first with docker compose logs mnemosyne.

Common boot failures:

  • DATABASE_URL is required — env not set.
  • connect ECONNREFUSED postgres:5432 — Postgres is not ready or the host is wrong. Wait for the healthcheck or fix the DSN.
  • relation "mnemo_fact" does not exist — migrations did not run. Run the migrate service (npx mnemo-migrate) and make sure it exits 0 before the server starts.
  • pgvector extension not installed — wrong Postgres image. Use pgvector/pgvector:pg17.

Need more help

Open a GitHub issue at https://github.com/lucasmailland/mnemosyne/issues. Include the request_id from any failed response and the output of /v1/health if you can.

UpgradeOverview