| title | Install MemOS: Docker, pip, or from source |
|---|---|
| description | Install MemOS using Docker for production, pip for quick local use, or from source for development. Covers environment setup, LLM providers, and server startup. |
MemOS runs as a local server that exposes a REST API your agents call at runtime. You can install it three ways: Docker (recommended for production), pip (fastest for local experimentation), or from source (best for development and contribution). All three methods result in the same running API server.
Docker is the recommended path for production deployments. It handles service dependencies — including the vector database and graph database — automatically via `docker compose`.<Steps>
<Step title="Clone the repository">
```bash
git clone https://github.com/MemTensor/MemOS.git
cd MemOS
```
</Step>
<Step title="Create your .env file">
The MemOS server reads all configuration from environment variables. Create a `.env` file in the project root:
```bash
touch .env
```
<Warning>
The `.env` file must be placed in the MemOS project root directory, not inside the `docker/` subdirectory.
</Warning>
Populate it with your model and infrastructure credentials. Here is a minimal working configuration:
```bash
# LLM configuration (required)
OPENAI_API_KEY=sk-your-key-here
OPENAI_API_BASE=https://api.openai.com/v1
MOS_CHAT_MODEL=gpt-4o-mini
# Embedder configuration (required)
MOS_EMBEDDER_MODEL=text-embedding-v4
MOS_EMBEDDER_BACKEND=universal_api
MOS_EMBEDDER_API_BASE=https://api.openai.com/v1
MOS_EMBEDDER_API_KEY=sk-your-key-here
EMBEDDING_DIMENSION=1024
MOS_RERANKER_BACKEND=cosine_local
# Neo4j for tree memory (required if using graph memory)
NEO4J_BACKEND=neo4j-community
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=12345678
NEO4J_DB_NAME=neo4j
# Redis scheduler (optional, set true to enable async scheduling)
DEFAULT_USE_REDIS_QUEUE=false
# Chat API
ENABLE_CHAT_API=true
CHAT_MODEL_LIST=[{"backend": "openai", "api_base": "https://api.openai.com/v1", "api_key": "sk-your-key-here", "model_name_or_path": "gpt-4o-mini", "support_models": ["gpt-4o-mini"]}]
```
<Note>
MemOS supports multiple LLM providers. Set `MOS_CHAT_MODEL_PROVIDER` to switch backends: `openai`, `qwen`, `deepseek`, `minimax`, `ollama`, `huggingface`, or `vllm`. See the [LLM providers guide](/integrations/llm-providers) for provider-specific configuration.
</Note>
</Step>
<Step title="Build and start the service">
Navigate to the `docker/` directory and start the service with Docker Compose:
```bash
cd docker
docker compose up
```
Docker Compose starts the MemOS server and all required dependencies. The first run downloads base images, which may take a few minutes.
Once running, the API is available at [http://localhost:8000](http://localhost:8000). Open [http://localhost:8000/docs](http://localhost:8000/docs) to verify the server is up and explore the interactive API documentation.
</Step>
</Steps>
#### Docker image options
MemOS provides two image variants for both x86 and ARM architectures:
| Variant | Image | Best for |
| --- | --- | --- |
| Lite (x86) | `registry.cn-shanghai.aliyuncs.com/memtensor/memos-base:v1.0` | Fast local deployment, smaller image size |
| Lite (ARM) | `registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0` | Apple Silicon and ARM servers |
| Full (x86) | `registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base:v1.0.0` | All features, no manual dependency setup |
| Full (ARM) | `registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base-arm:v1.0.0` | Full features on ARM |
The lite image omits large GPU-related dependencies for a faster download. The full image includes all MemOS dependencies pre-built.
<Steps>
<Step title="Create a virtual environment (recommended)">
To avoid dependency conflicts, create a dedicated Python environment. Python 3.10 or later is required.
```bash
conda create -n memos python=3.11
conda activate memos
```
You can also use `venv` if you prefer:
```bash
python -m venv .venv
source .venv/bin/activate
```
</Step>
<Step title="Install MemOS from PyPI">
Install with all optional components:
```bash
pip install -U "MemoryOS[all]"
```
Verify the installation:
```bash
python -c "import memos; print(memos.__version__)"
```
#### Optional dependency groups
If you want a lighter install, you can select only the features you need:
| Feature | Install command |
| --- | --- |
| Tree memory (Neo4j graph) | `pip install "MemoryOS[tree-mem]"` |
| Memory Reader (doc/URL ingestion) | `pip install "MemoryOS[mem-reader]"` |
| Memory Scheduler (Redis async) | `pip install "MemoryOS[mem-scheduler]"` |
| Preference memory (Milvus) | `pip install "MemoryOS[pref-mem]"` |
| Multiple extras together | `pip install "MemoryOS[tree-mem,mem-reader]"` |
</Step>
<Step title="Create your .env file">
MemOS does not automatically load `.env` files — you pass them explicitly at startup. Create the file in your working directory:
```bash
touch .env
```
Minimal configuration:
```bash
CHAT_MODEL_LIST='[
{
"name": "default",
"backend": "openai",
"config": {
"model": "gpt-4o-mini",
"api_key": "YOUR_API_KEY"
}
}
]'
# Optional
MEMOS_LOG_LEVEL=INFO
```
</Step>
<Step title="Start the server">
Use `python-dotenv` to load your `.env` file and start the server:
```bash
python -m dotenv run -- \
uvicorn memos.api.server_api:app \
--host 0.0.0.0 \
--port 8000
```
After a successful startup you will see:
```text
INFO: Uvicorn running on http://0.0.0.0:8000
INFO: Application startup complete.
```
The API is now available at [http://localhost:8000](http://localhost:8000).
</Step>
<Step title="Download example files (optional)">
To get example code, data, and configuration files:
```bash
memos download_examples
```
</Step>
</Steps>
#### Additional backends
**Ollama** — to use local models via Ollama, install the Ollama CLI first:
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
**Neo4j** — if you plan to use graph-based tree memory, install [Neo4j Desktop](https://neo4j.com/download/) and set `NEO4J_BACKEND=neo4j` in your `.env` file.
<Steps>
<Step title="Clone the repository">
```bash
git clone https://github.com/MemTensor/MemOS.git
cd MemOS
```
</Step>
<Step title="Install in editable mode">
```bash
pip install -e .
pip install --no-cache-dir -r ./docker/requirements.txt
```
Set `PYTHONPATH` to point to the `src/` directory so Python can find the `memos` package:
```bash
export PYTHONPATH=/path/to/MemOS/src
```
Replace `/path/to/MemOS` with the absolute path to your cloned repository.
</Step>
<Step title="Create your .env file">
Create a `.env` file in the project root. Refer to the Docker tab above for the full list of environment variables and a working configuration example.
<Warning>
The `.env` file must be placed in the MemOS project root directory.
</Warning>
For tree memory (graph-based), set `NEO4J_BACKEND=neo4j` and ensure Neo4j Desktop is running before you start the server.
</Step>
<Step title="Start the server">
From the project root, start the server with uvicorn:
```bash
uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8000 --workers 1
```
The API is available at [http://localhost:8000](http://localhost:8000). Open [http://localhost:8000/docs](http://localhost:8000/docs) to confirm the server is running.
</Step>
</Steps>
MemOS works with any of the following LLM backends. Set the provider using the backend field in CHAT_MODEL_LIST inside your .env file.
| Provider | Backend value |
|---|---|
| OpenAI | openai |
| Azure OpenAI | azure |
| Qwen (DashScope / Bailian) | qwen |
| DeepSeek | deepseek |
| MiniMax | minimax |
| Ollama (local) | ollama |
| HuggingFace Transformers | huggingface |
| vLLM | vllm |
Once your server is running at http://localhost:8000, follow the Quickstart to add and search your first memory.