Installation

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

Lite or Service

• Lite (the default): storage and search run on your machine with a SQLite graph and local usearch vectors. No Docker, database service or account is needed for local use. Optional LLM extraction through a hosted provider such as Groq calls that provider's service.
• Service: connect to the managed SmartMemory backend instead of running storage locally. Run smartmemory setup --mode remote and paste an API key from the SmartMemory dashboard (Dashboard, then Settings, then API Keys). See pricing for current plans and access options.

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.11 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 -U smartmemory

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

Check your active conda environment. Run conda info --envs. The * marks the active environment. If base is active, create and activate a dedicated environment using the commands above. If your dedicated environment is already active, continue with setup.

Choose Lite

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

smartmemory setup

Choose local storage. Groq is the recommended hosted LLM provider and the default at the LLM provider prompt. For local use without an LLM key, choose none at that prompt and keep the local embedding provider.

Choose Service

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

smartmemory setup --mode remote

Paste an API key from the SmartMemory dashboard when prompted. Keys live under Dashboard, then Settings, then API Keys. See pricing for current plans and API access options. There is no database or server to run locally.

For non-interactive setup:

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

Verify Installation

After local setup has downloaded the spaCy and embedding models, verify Lite storage and search with this no-key Python example. It reads setup's configured data directory and spaCy model, while keeping embeddings local and LLM extraction disabled. The Lite context selects SQLite and closes it when the example finishes.

from smartmemory.pipeline.config import PipelineConfig
from smartmemory.tools.factory import lite_context
from smartmemory_app.config import load_config

config = load_config()
pipeline = PipelineConfig.lite(llm_enabled=False)
pipeline.extraction.entity_ruler.spacy_model = config.spacy_model

with lite_context(data_dir=config.data_dir, pipeline_profile=pipeline) as memory:
    item_id = memory.ingest("Hello, SmartMemory!")
    results = memory.search("Hello")
    print(f"Stored {item_id}")
    print(f"Found {len(results)} memories")

On a fresh local store, this prints the stored memory ID and Found 1 memories.

Optional LLM Keys

SmartMemory can store and search explicit memories without an LLM key. Choose a provider when you want LLM-backed extraction. Groq is the recommended hosted LLM provider. Re-run sm setup, choose local storage, and select groq. Setup prompts for GROQ_API_KEY and lets you skip the key.

The local setup menu offers these LLM providers:

Embedding selection is separate. Keep local for embeddings without a provider key. Setup also offers openai and ollama embeddings.

Install from Source

Use a source install only when contributing to SmartMemory itself:

git clone https://git.smartmemory.ai/smartmemory/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.

LLM Provider Key Error

Re-run sm setup and check the selected provider and its key prompt. For the recommended Groq provider, use GROQ_API_KEY. To continue without an LLM key, choose none and keep local embeddings. Explicit memory storage and search work without LLM extraction.

Next Steps

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