Installation

This guide helps you install SmartMemory as a package and choose where memory runs.

Lite or Service

• Lite (the default): everything runs on your machine. SQLite graph plus usearch vectors, no Docker, no external services, no account.
• Service: connect to the managed SmartMemory backend instead of running storage locally. Run smartmemory setup --mode remote and paste an API key from app.smartmemory.ai. Nothing to install or operate, and there is a free tier to start on.

You choose Lite or Service at smartmemory setup time, not at install time, and you can switch later by re-running setup.

Requirements

• Python 3.8 or higher
• pip or a dedicated conda environment
• No Docker or database service for normal Lite or Service use

Install the Package

Always install SmartMemory into a fresh, isolated environment, a virtualenv or a dedicated conda env, never into a shared or system environment.

# venv (recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install smartmemory

# or a dedicated conda env
conda create -n smartmemory python=3.11
conda activate smartmemory
pip install smartmemory

Do not install into the Anaconda base environment. Its pre-pinned packages can conflict with SmartMemory's dependency tree and force pip's resolver to backtrack to an old wrapper release instead of the current one. A clean venv avoids this. If you ever suspect a backtracked install, run smartmemory doctor to check that the installed core meets the minimum version.

Choose Lite

Lite is the default local mode. It uses local SQLite storage and embedded vectors with zero infrastructure.

smartmemory setup

Then accept the local Lite defaults.

Choose Service

Service mode connects the SDK and tools to the managed SmartMemory backend.

smartmemory setup --mode remote

Paste an API key from app.smartmemory.ai when prompted. There is a free tier, and there is no database or server to run locally.

For non-interactive setup:

smartmemory setup --mode remote --api-key sk_...

Verify Installation

Verify the package and selected mode with a simple test:

from smartmemory import SmartMemory

memory = SmartMemory()

item_id = memory.add("Hello, SmartMemory!")
results = memory.search("Hello")

print(f"Stored {item_id}")
print(f"Found {len(results)} memories")

Optional LLM Keys

SmartMemory can store and search explicit memories without an LLM key. Set a provider key when you want LLM-backed extraction or classification.

export OPENAI_API_KEY="your-openai-api-key"

Install from Source

Use a source install only when contributing to SmartMemory itself:

git clone https://github.com/regression-io/smart-memory.git
cd smart-memory
python -m venv .venv
source .venv/bin/activate
pip install -e .

Troubleshooting

Command Not Found

If smartmemory is not available after install, confirm that your virtual environment is active:

which python
which smartmemory
python -m pip show smartmemory

Service Authentication Error

For Service mode, confirm that setup stored the right API key or export it explicitly:

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

Lite Storage Path Error

Lite writes local data under the configured data directory. If startup fails, check that the directory exists and is writable.

OpenAI API Key Error

# Verify API key is set
echo $OPENAI_API_KEY

# Test API key
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
     https://api.openai.com/v1/models

Next Steps

• Quick Start Guide - Build your first application
• Configuration Guide - Detailed configuration options
• Basic Usage - Learn the core APIs