Troubleshooting

The most common problems you'll hit, with the fix. SmartMemory runs in one of two modes, chosen at smartmemory setup time (see Installation):

Lite: storage and search run on your machine with a local SQLite graph and local vectors.
Service: the SDK and tools connect to the managed SmartMemory API with an API key.

Start with the checks that apply to both, then jump to your mode.

First checks

`smartmemory: command not found`

Cause: The virtual environment you installed into isn't active.

Fix: Activate it and confirm the package is installed:

which python
which smartmemory
python -m pip show smartmemory

Something is broken and you don't know where to start

Run the built-in diagnostic:

sm doctor

It checks your Python version (SmartMemory needs 3.11 or newer), checks that the installed smartmemory-core is recent enough for the smartmemory package, and flags a configured SOCKS proxy that is missing its transport library.

Then check what mode you are in and whether the local daemon is healthy:

sm status

Lite mode

`SmartMemory daemon is not running.`

Cause: The local daemon that serves the viewer and the local API isn't running.

Fix: Start it, or restart it if sm status says it should be running but is not responding:

smartmemory start
sm restart

`sm status` reports `degraded`

Cause: The daemon is up but could not open your saved memories. The status output prints the reason.

Fix: Run sm doctor and follow its output. Also check that the configured data directory exists and is writable.

The cloud dashboard shows 0 memories

Cause: This is expected in Lite mode. Lite memories are stored on your machine in a local SQLite graph. They are not in your cloud account, so the dashboard at smartmemory.ai does not see them.

Fix: None needed. To use the managed service instead, re-run smartmemory setup --mode remote with an API key.

The first add or search is slow

Cause: The first call loads the local embedding and reranker models (and downloads them the first time).

Fix: Preload them once after install:

sm warm

No entities extracted

Cause: No LLM provider is active, so ingestion falls back to local pattern-based extraction. sm status shows the selected LLM provider and flags a provider that is configured without an API key, in which case extraction is disabled.

Fix: Re-run sm setup, choose local storage, and pick a provider. Groq is the recommended hosted provider and uses GROQ_API_KEY. Local runtimes such as Ollama and LM Studio need no key. Explicit memory storage and search work without an LLM. See Lite mode for how the LLM is detected.

Search results got worse after changing the embedding model

Cause: Stored vectors were created with the previous embedding model.

Fix: If the new model produces vectors of the same dimension as the old one, re-embed every memory with the current model. The daemon must be running:

sm admin reindex

This re-embeds into the existing vector index. If the new model uses a different vector dimension, those memories are skipped and the index needs to be rebuilt at the new dimension. There is no CLI command for that rebuild, so contact SmartMemory support before switching to a model with a different dimension.

`ValueError: 'working' is not a valid MemoryType`

Cause: Code or data still references the legacy memory_type="working".

Fix: Rename it to pending. See Migration & upgrade.

Service mode

`No API key found`

Cause: Service mode is configured but no API key was found in the environment or the OS keychain. On headless machines (Docker, SSH, CI) the keychain is often unavailable, so a key entered at setup is not saved.

Fix: Create a key in the SmartMemory dashboard (Dashboard, then Settings, then API Keys) and either re-run setup or export it:

smartmemory setup --mode remote --api-key sk_...
# or
export SMARTMEMORY_API_KEY="sm_live_..."

`SmartMemory API unreachable at ...`

Cause: The client could not connect to the API URL.

Fix: Check your network connection and that SMARTMEMORY_API_URL, if you set it, points at the managed API:

export SMARTMEMORY_API_URL="https://api.smartmemory.ai"