Installation

📚 Repository: smartmemory-ai/smart-memory
🐛 Issues: Report bugs or request features

Note, skip this guide for now, it's not public yet.

This guide will help you install SmartMemory and its dependencies in your development environment.

🚀 Quick Start with Docker (Recommended)

The fastest way to get SmartMemory running is with Docker, which handles all backend services automatically.

Prerequisites

Docker and Docker Compose installed
Python 3.8+ for the SmartMemory package

1. Clone and Setup (Not public yet, sorry)

# Clone the repository
git clone https://github.com/regression-io/smart-memory.git
# Install SmartMemory package
pip install -e .

2. Start Backend Services

# Start required services (Redis/FalkorDB)
docker-compose up -d

# Verify services are running
docker-compose ps

3. Verify Installation

from smartmemory import SmartMemory

# Initialize with default Docker configuration
memory = SmartMemory()

# Test basic functionality
memory.add("Hello, SmartMemory!")
results = memory.search("Hello")
print(f"Found {len(results)} memories")

✅ You're ready to go! Skip to the Quick Start Guide to begin using SmartMemory.

Manual Installation

Requirements

Python 3.8 or higher
pip or conda package manager
Optional: Docker (for graph database backends)

Basic Installation

Using pip

# Clone the repository
git clone https://github.com/regression-io/smart-memory.git
cd smart-memory

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Using conda

# Clone the repository
git clone https://github.com/regression-io/smart-memory.git
cd smart-memory

# Create conda environment
conda create -n smartmemory python=3.9
conda activate smartmemory

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Use an isolated environment

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 (e.g. an old pyopenssl/cryptography) can conflict with SmartMemory's dependency tree and force pip's resolver to backtrack — silently walking back to an ancient, broken wrapper release instead of the current one. A clean venv avoids this entirely. If you ever suspect a backtracked install, run smartmemory doctor to check that the installed core meets the minimum version.

Dependencies

SmartMemory requires the following core dependencies:

# Core dependencies
pydantic>=2.0.0
numpy>=1.21.0
sentence-transformers>=2.2.0
spacy>=3.4.0
openai>=1.0.0

# Graph database backends
falkordb>=1.0.0  # Recommended (default)
# SQLite (lite mode) uses the Python stdlib — no extra dependency required

# Vector storage
# Vectors are stored natively inside FalkorDB (HNSW) — no separate vector DB required.
# Optional embedded backend:
usearch>=2.0.0  # Optional (zero-infra / lite mode)

# Background processing
asyncio
concurrent.futures

# Development tools
pytest>=7.0.0
black>=22.0.0

Backend Setup

SmartMemory supports multiple backend configurations. Choose the one that best fits your needs.

Option 1: FalkorDB Backend (Recommended)

FalkorDB provides high-performance graph operations with Redis compatibility.

Using Docker (Recommended)

# Start FalkorDB with Docker
docker run -p 6379:6379 falkordb/falkordb:latest

# Or use docker-compose
docker-compose -f docker-compose.services.yml up falkordb

The bare docker run above uses FalkorDB's default RDB-only persistence (snapshot every 100 changes / 5 minutes). For production deployments, enable AOF (Append-Only File) so worst-case data loss on a crash is ~1 second instead of ~5 minutes:

docker run -d \
  --name falkordb \
  -p 6379:6379 \
  -v falkordb_data:/var/lib/falkordb/data \
  -e REDIS_ARGS="--appendonly yes --appendfsync everysec" \
  falkordb/falkordb:latest

Notes:

REDIS_ARGS env var, not command: flags. The FalkorDB image entrypoint at /var/lib/falkordb/bin/run.sh constructs the redis-server invocation from REDIS_ARGS; flags passed via command: are ignored.
Volume mount path is /var/lib/falkordb/data (env: FALKORDB_DATA_PATH). The legacy /data path used by older FalkorDB image versions is no longer the data path — mounting there persists nothing in current images.
For automatic restart of a hung-but-running container (FalkorDB's signal handler can dump state and survive in a non-responsive state), pair AOF with the willfarrell/autoheal sidecar pattern.

Manual Installation

# Install Redis with FalkorDB module
# Follow instructions at: https://docs.falkordb.com/

Option 2: SQLite Backend (Lite Mode)

For local development and zero-infrastructure use, SmartMemory Lite ships a SQLite graph backend that needs no Docker or external services — it stores the graph in a single file via the Python stdlib. Select it by setting graph_db.backend_class to SQLiteBackend in config.json (see the Configuration section below), or programmatically with the lite memory factory:

from smartmemory.tools.factory import create_lite_memory

memory = create_lite_memory("./data")  # writes ./data/memory.db

Configuration

Create a configuration file to customize SmartMemory behavior:

config.json

{
  "graph": {
    "backend": "FalkorDBBackend",
    "host": "localhost",
    "port": 6379,
    "graph_name": "smartmemory"
  },
  "vector": {
    "backend": "falkordb",
    "host": "localhost",
    "port": 9010,
    "dimension": 768,
    "metric": "cosine",
    "hnsw_m": 16,
    "hnsw_ef_construction": 200,
    "hnsw_ef_runtime": 64
  },
  "llm": {
    "provider": "openai",
    "model": "gpt-4",
    "api_key": "${OPENAI_API_KEY}"
  },
  "extraction": {
    "spacy_model": "en_core_web_sm"
  },
  "background_processing": {
    "enabled": true,
    "max_workers": 3
  }
}

Environment Variables

Set up required environment variables:

# OpenAI API key for LLM operations
export OPENAI_API_KEY="your-openai-api-key"

# Optional: Custom config path
export SMARTMEMORY_CONFIG_PATH="/path/to/your/config.json"

Verification

Verify your installation with a simple test:

from smartmemory import SmartMemory

# Initialize SmartMemory
memory = SmartMemory()

# Test basic functionality
memory.add("Test memory item")
results = memory.search("test")

print(f"Installation successful! Found {len(results)} results.")

Troubleshooting

Common Issues

1. spaCy Model Not Found

# Download the English language models
python -m spacy download en_core_web_sm

2. FalkorDB Connection Error

# Check if FalkorDB is running
docker ps | grep falkordb

# Check connection
redis-cli -p 6379 ping

3. Vector Index Not Created

Vectors are stored natively inside FalkorDB via an HNSW index — there is no separate vector service. If similarity search returns no results, confirm the embedding model loaded and that FalkorDB supports vector indexes:

# Confirm FalkorDB is reachable (vectors live in the same instance as the graph)
redis-cli -p 9010 ping

4. 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

Performance Optimization

For production deployments:

Use persistent storage for graph and vector databases
Enable background processing for better performance
Configure appropriate worker counts based on your hardware
Use GPU acceleration for sentence transformers if available

# Example production configuration
memory = SmartMemory(config_path="production_config.json")

Next Steps

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

Installation

🚀 Quick Start with Docker (Recommended)

Prerequisites

1. Clone and Setup (Not public yet, sorry)

2. Start Backend Services

3. Verify Installation

Manual Installation

Requirements

Basic Installation

Using pip

Using conda

Use an isolated environment

Dependencies

Backend Setup

Option 1: FalkorDB Backend (Recommended)

Using Docker (Recommended)

Production Durability

Manual Installation

Option 2: SQLite Backend (Lite Mode)

Configuration

config.json

Environment Variables

Verification

Troubleshooting

Common Issues

1. spaCy Model Not Found

2. FalkorDB Connection Error

3. Vector Index Not Created

4. OpenAI API Key Error

Performance Optimization

Next Steps

On this page