Skip to content

Latest commit

 

History

History
371 lines (253 loc) · 8.42 KB

SETUP.md

File metadata and controls

371 lines (253 loc) · 8.42 KB

Complete Setup Guide

Home > Docs > Installation > Setup

This guide provides comprehensive instructions for installing and setting up EverMemOS.

Table of Contents

System Requirements

Minimum Requirements

  • Python: 3.10 or higher
  • uv: Package manager (will be installed during setup)
  • Docker: 20.10+
  • Docker Compose: 2.0+
  • RAM: At least 4GB available (for Elasticsearch and Milvus)
  • Disk Space: At least 10GB free

Recommended Requirements

  • RAM: 8GB or more
  • CPU: 4 cores or more
  • Disk Space: 20GB or more (especially for large datasets)

Operating Systems

EverMemOS has been tested on:

  • macOS (Intel and Apple Silicon)
  • Linux (Ubuntu 20.04+, Debian, etc.)
  • Windows (via WSL2)

Installation Methods

EverMemOS can be installed in two ways:

  1. Docker Installation (Recommended) - Use Docker Compose for all dependency services
  2. Manual Installation - Install and configure each service manually

This guide covers the Docker installation method. For manual installation, see Advanced Installation.

Docker Installation (Recommended)

Step 1: Clone the Repository

git clone https://github.com/EverMind-AI/EverMemOS.git
cd EverMemOS

Step 2: Start Docker Services

Start all dependency services (MongoDB, Elasticsearch, Milvus, Redis) with one command:

docker-compose up -d

This will start:

  • MongoDB on port 27017
  • Elasticsearch on port 19200
  • Milvus on port 19530
  • Redis on port 6379

See Docker Setup Guide for detailed service configuration.

Step 3: Verify Docker Services

Check that all services are running:

docker-compose ps

You should see all services in the "Up" state.

Step 4: Install uv Package Manager

If you don't have uv installed:

curl -LsSf https://astral.sh/uv/install.sh | sh

After installation, restart your terminal or run:

source $HOME/.cargo/env

Verify installation:

uv --version

Step 5: Install Project Dependencies

uv sync

This will:

  • Create a virtual environment
  • Install all required Python packages
  • Set up the project for development

Environment Configuration

Step 1: Copy Environment Template

cp env.template .env

Step 2: Configure API Keys

Edit the .env file and fill in the required configurations:

# Open .env in your preferred editor
nano .env
# or
vim .env
# or
code .env

Required Configuration

LLM API Key (for memory extraction)

Choose one of the following:

# Option 1: OpenAI
LLM_API_KEY=sk-your-openai-key-here
LLM_API_BASE=https://api.openai.com/v1

# Option 2: OpenRouter
OPENROUTER_API_KEY=sk-or-v1-your-openrouter-key
OPENROUTER_API_BASE=https://openrouter.ai/api/v1

# Option 3: Other OpenAI-compatible API
LLM_API_KEY=your-api-key
LLM_API_BASE=https://your-api-endpoint.com/v1

Vectorize API Key (for embedding and reranking)

# DeepInfra (recommended)
VECTORIZE_API_KEY=your-deepinfra-key
VECTORIZE_API_BASE=https://api.deepinfra.com/v1/openai

# Or configure embedding and rerank separately
EMBEDDING_API_KEY=your-embedding-key
EMBEDDING_API_BASE=https://your-embedding-endpoint.com
RERANK_API_KEY=your-rerank-key
RERANK_API_BASE=https://your-rerank-endpoint.com

Optional Configuration

# Model selection
LLM_MODEL=gpt-4  # or gpt-3.5-turbo, etc.
EMBEDDING_MODEL=BAAI/bge-large-en-v1.5
RERANK_MODEL=BAAI/bge-reranker-large

# Service endpoints (default values shown)
MONGODB_URI=mongodb://admin:memsys123@localhost:27017
ELASTICSEARCH_URL=http://localhost:19200
MILVUS_HOST=localhost
MILVUS_PORT=19530
REDIS_URL=redis://localhost:6379

For complete configuration options, see the Configuration Guide.

Starting the Server

Start the API Server

uv run python src/run.py --port 1995

The server will start on http://localhost:1995 by default.

You should see output similar to:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:1995 (Press CTRL+C to quit)

Custom Port

The default port is 1995. To use a different port:

uv run python src/run.py --port 9000

Verification

Test the API

Open a new terminal and test the API:

curl http://localhost:1995/health

You should receive a response indicating the service is healthy.

Run Simple Demo

Test the complete workflow with the simple demo:

# In a new terminal (keep the server running)
uv run python src/bootstrap.py demo/simple_demo.py

This will:

  1. Store sample conversation messages
  2. Wait for indexing
  3. Search for relevant memories
  4. Display results

If this works, your installation is successful!

Troubleshooting

Docker Services Not Starting

Problem: docker-compose up -d fails or services don't start

Solutions:

  • Check Docker is running: docker info
  • Check port conflicts: lsof -i :27017,19200,19530,6379
  • View logs: docker-compose logs -f
  • Restart services: docker-compose restart

Insufficient Memory

Problem: Elasticsearch or Milvus crashes due to OOM

Solutions:

  • Increase Docker memory limit (Docker Desktop > Preferences > Resources)
  • Reduce heap size in docker-compose.yml
  • Close other memory-intensive applications

Python Dependencies Fail

Problem: uv sync fails with errors

Solutions:

  • Update uv: curl -LsSf https://astral.sh/uv/install.sh | sh
  • Clear cache: uv cache clean
  • Try with verbose output: uv sync -v

API Server Won't Start

Problem: Server fails to start or crashes

Solutions:

  • Check .env file is configured correctly
  • Verify all Docker services are running: docker-compose ps
  • Check logs for specific errors
  • Ensure port 1995 is not in use: lsof -i :1995

Connection Errors

Problem: Can't connect to MongoDB/Elasticsearch/Milvus

Solutions:

  • Verify services are running: docker-compose ps
  • Check connection strings in .env
  • Use host ports (27017, 19200, 19530) not container ports
  • Test connections individually: 
    # MongoDB
mongosh mongodb://admin:memsys123@localhost:27017

# Elasticsearch
curl http://localhost:19200

# Redis
redis-cli -h localhost -p 6379 ping

For more troubleshooting help, see:

Manual Installation (Advanced)

If you prefer not to use Docker, you can install each service manually:

Required Services

  1. MongoDB 7.0+

  2. Elasticsearch 8.x

  3. Milvus 2.4+

  4. Redis 7.x

    • Install via package manager or from redis.io
    • Configure port 6379

After installing services manually, update connection strings in .env accordingly.

Next Steps

Now that EverMemOS is installed, you can:

  1. Try the Demos - Interactive examples showing memory extraction and chat
  2. Learn the API - Integrate EverMemOS into your application
  3. Explore Usage Examples - Common usage patterns
  4. Run Evaluations - Test on benchmark datasets

See Also