Setting Up Your Development Environment

Fork & Clone the Repository

Set up the repository on your local machine:

• Fork the repository on GitHub
• Clone your fork to your local machine:

  git clone https://github.com/YOUR-USERNAME/MemOS.git
  cd MemOS
  

• Add the upstream repository as a remote:

  git remote add upstream https://github.com/MemTensor/MemOS.git
  

Prepare Development Dependencies

Ensure the following are installed locally:

• Git
• Python 3.9+
• Make

Verify Python:

python3 --version

Install Poetry

MemOS uses Poetry for dependency management. We recommend using the official installer:

curl -sSL https://install.python-poetry.org | python3 -

Verify the installation:

poetry --version

If you see poetry: command not found, please add the Poetry executable directory to your PATH as prompted by the installer, then restart your terminal and verify again.

For more installation options, see the official installation guide.

Install Dependencies and Set Up Pre-commit Hooks

Install all project dependencies and development tools in the repository root:

make install

Tip:

• If you switch branches or dependencies change, you may need to re-run make install to keep the environment consistent.

Understanding Memory Modules and Dependency Selection

Before setting up the environment, we need to understand MemOS's memory module classification and their corresponding database dependencies. This will determine which components you need to install.

Memory Types

The MemOS memory system is mainly divided into two categories (identifiers for backend config are in parentheses):

• Textual Memory: Fact-based memory, you must choose one.
  • tree (tree_text): Tree memory (recommended), highest structure.
  • general (general_text): General memory, based on vector retrieval.
  • naive (naive_text): Naive memory, no special dependencies (for testing only).
• Preference Memory: User preferences, optional.
  • pref: Used for storing and retrieving user preferences.

Database Dependency Matrix

Different memory types require different database support:

About Tree Memory and Graph Database Selection

If you choose the most powerful tree memory (which is what most developers choose), you need to prepare a graph database. Currently, there are three options:

• Neo4j Desktop (Recommended for PC): Install directly on PC, comes with full GUI and features, easiest solution.
• PolarDB: Graph database service provided by Alibaba Cloud (paid).
• Neo4j Community: Open source and free, suitable for server or Linux environments.

Special Note:

• If you use Neo4j Desktop, it usually handles graph data independently.
• If you use Neo4j Community, it does not have native vector retrieval capabilities. Therefore, you need to pair it with an additional vector database (Qdrant) to supplement vector retrieval capabilities.

Configuration Scheme for This Tutorial

To help developers get started quickly, this tutorial will use the following configuration:

• Memory Type: tree (tree_text)
• Graph Database: Neo4j Community (requires you to download installer or use Docker)
• Vector Database: Qdrant (Local Mode)

Since Neo4j Community lacks vector capabilities, we will introduce Qdrant. To avoid running an extra Qdrant service (Docker), we will configure Qdrant to run in Local Embedded Mode (reading/writing local files directly), so you don't need to install an additional Qdrant server. If no external configuration is provided, the system will automatically create a local database.

Create Configuration File

For .env content, please refer to env config under docker installation for quick configuration. For detailed .env configuration, please see env configuration.

cd MemOS
touch .env

Configure Dockerfile

# Enter the docker directory
cd docker

Includes fast mode and full mode, distinguishing between slim packages (arm and x86) and full packages (arm and x86).

● Slim Package: Simplifies heavy dependencies like nvidia, making the image lightweight for faster local deployment.
  - url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-base:v1.0
  - url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0

● Full Package: Packages all MemOS dependencies into the image for full functionality. Can be built and started directly by configuring the Dockerfile.
  - url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base:v1.0.0
  - url: registry.cn-shanghai.aliyuncs.com/memtensor/memos-full-base-arm:v1.0.0

# Current example uses slim package url
FROM registry.cn-shanghai.aliyuncs.com/memtensor/memos-base-arm:v1.0

WORKDIR /app

ENV HF_ENDPOINT=https://hf-mirror.com

ENV PYTHONPATH=/app/src

COPY src/ ./src/

EXPOSE 8000

CMD ["uvicorn", "memos.api.server_api:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

Start Docker Client

 # If docker is not installed, please install the corresponding version from:
 https://www.docker.com/

 # After installation, start docker via client or command line
 # Start docker via command line
 sudo systemctl start docker

# After installation, check docker status
docker ps

# Check docker images (optional)
docker images

Build and Start Service

# In the docker directory
docker compose up neo4j

Open New Terminal to Start Server

cd MemOS
make serve