Local mode
Run SmartMemory entirely on your own machine, offline, with no account. What stays on the machine, how to set it up, and how to move to a SmartMemory account later.
Local mode keeps your memories on your own computer. There is no account, no server to run and no Docker. Search works offline once setup has downloaded its models. This page covers how to turn it on, what stays on the machine, and what changes if you later move to an account.
If you want the same memory shared across several agents and machines, use a SmartMemory account instead.
Set it up
Install the package into a fresh environment (see Installation), then run setup in local mode:
sm setup --mode localsm and smartmemory are the same command. Setup asks a few questions and downloads the language and embedding models it needs. To accept the default answer to every question, add --yes:
sm setup --mode local --yesIf a run is interrupted, sm setup --restart starts over instead of resuming. To check the result at any time, run sm doctor.
For the LLM provider and embedding choices that setup offers, see Installation. Choose none at the LLM provider prompt and keep the local embedding provider to run with no API key at all.
What stays on the machine
Everything SmartMemory stores in local mode lives in one data directory, ~/.smartmemory by default. You can pick another path during setup.
| Stays on your machine | Notes |
|---|---|
| Your memories and the graph built from them | A SQLite database in the data directory |
| The search index | Local vector files in the data directory |
| Your configuration | No account or API key is created or needed |
| Local usage records | Written to a file in the data directory, never sent anywhere |
Search and storage do not need the network. Three things can still reach the internet, and each one is optional or switchable:
- An LLM provider, if you choose one. If you pick a hosted provider such as Groq for extraction, the text being extracted is sent to that provider. Choose
noneto avoid this. - The first-run model download. Setup fetches the language and embedding models once. After that they are cached locally.
- Update checks and crash reports. The CLI checks PyPI for a newer version at most once a day. Set
SMARTMEMORY_NO_UPDATE_CHECK=1to turn that off. Anonymous crash and support reports can be turned off withSMARTMEMORY_CRASH_REPORTS=0.
Limits of local mode
Local mode is one person on one machine. Memories are not shared with other machines or agents. The extraction quality without an LLM is lower than with one, because only pattern-based and spaCy extraction run. The developer-facing details, including which pipeline stages change, are in Lite Mode.
Move to an account later
You can switch at any time by running setup in service mode:
sm setup --mode remotePaste an API key from the SmartMemory dashboard when prompted. See Installation for the non-interactive form.
What this does and does not do:
- It points the CLI and your tools at the hosted service. New memories go to your account.
- It does not upload the memories you already have. They stay in your local data directory, untouched.
- While you are in service mode, the local-only commands
sm exportandsm importare unavailable. If you want a portable copy of your local memories, runsm export <folder>before you switch. It writes an OKF bundle, a folder of Markdown pages you can keep.
To go back, run sm setup --mode local again.
Remove local data
sm uninstall removes the hooks, configuration and, by default, the data directory itself, which is the only copy of your local memories. To remove everything except your memories, run:
sm uninstall --keep-dataBefore an uninstall without --keep-data, make an sm export bundle or a copy of ~/.smartmemory.