MemoryOS Documentation

MemoryOS is a memory operating system designed for personalized AI agents. It enables coherent, personalized, and context-aware interactions by managing memory through a hierarchical storage architecture.

Core modules include:

• Storage: Hierarchical layers for different memory durations.
• Updating: Logic for processing and promoting information between layers.
• Retrieval: Mechanisms to fetch relevant context.
• Generation: Using retrieved memory to inform LLM responses.

Key features include a plug-and-play architecture for storage engines and retrieval algorithms, support for various LLMs (OpenAI, Deepseek, Qwen, etc.), and an MCP (Model Context Protocol) server for easy integration into agent workflows.

MemoryOS operates using a hierarchical memory management system. The project structure reveals the core functional components:

• memoryos.py: The main orchestrator class.
• short_term.py: Manages recent interactions.
• mid_term.py: Consolidates short-term interactions into mid-term memory.
• long_term.py: Manages long-term persona memory, including user profiles and knowledge.
• retriever.py: Handles information retrieval across all memory layers.
• updater.py: Processes updates and promotes information between layers (e.g., from short-term to mid-term).
• prompts.py: Contains the LLM prompts used for summarization and analysis.

To reproduce the evaluation results, navigate to the eval directory and run the parsing and evaluation scripts. Ensure you have configured the necessary API keys in the code before running.

cd eval
# Configure API keys in the code first
python3 main_loco_parse.py
python3 evalution_loco.py

To use the ChromaDB implementation of MemoryOS, install the required dependencies and run the provided test script.

Note: If you switch embedding models, you must use a different data_storage_path to avoid data corruption or incompatibility.

cd memoryos-chromadb
pip install -r requirements.txt

To install the MemoryOS package from PyPI, use the following command. Note that the package name is memoryos-pro.

pip install memoryos-pro -i https://pypi.org/simple

You can deploy MemoryOS using Docker for quick setup or production.

Option 1: Pull Official Image

docker pull ghcr.io/bai-lab/memoryos:latest
docker run -it --gpus=all ghcr.io/bai-lab/memoryos /bin/bash

Option 2: Build from Source

git clone https://github.com/BAI-LAB/MemoryOS.git
cd MemoryOS
docker build -t memoryos .
docker run -it --gpus=all memoryos /bin/bash

Prerequisites

• Python >= 3.10
• Recommended environment setup:

  conda create -n MemoryOS python=3.10
  conda activate MemoryOS

Installation

Via PyPi

pip install memoryos-pro -i https://pypi.org/simple

Via GitHub (Latest)

git clone https://github.com/BAI-LAB/MemoryOS.git
cd MemoryOS/memoryos-pypi
pip install -r requirements.txt

The playground provides a web interface to interact with the memory system.

1. Launch the app:

   cd MemoryOS/memoryos-playground/memdemo/
   python3 app.py

2. Configure: In the browser, enter your User ID, OpenAI API Key, Model, and API Base URL.
3. Data Location: Memories are stored in MemoryOS-main/memoryos-playground/memdemo/data.

To install the latest version directly from the GitHub repository, clone the repo and install the requirements from the memoryos-pypi directory.

git clone https://github.com/BAI-LAB/MemoryOS.git
cd MemoryOS/memoryos-pypi
pip install -r requirements.txt

MemoryOS-MCP allows you to inject long-term memory into AI agent clients (like Claude Desktop or Cline) via the Model Context Protocol.

1. Install Dependencies

cd memoryos-mcp
pip install -r requirements.txt

2. Configure config.json

Create a config.json file with the following structure:

{
  "user_id": "用户ID",
  "openai_api_key": "OpenAI API 密钥",
  "openai_base_url": "https://api.openai.com/v1",
  "data_storage_path": "./memoryos_data",
  "assistant_id": "助手ID",
  "llm_model": "gpt-4o-mini",
  "embedding_model_name": "BAAI/bge-m3"
}

3. Start the Server

python server_new.py --config config.json

4. Client Configuration (e.g., Cline)

When configuring your client, ensure the command points to the correct Python interpreter in your virtual environment.

"command": "/path/to/your/venv/bin/python"

MemoryOS can be run as a Model Context Protocol (MCP) server.

1. Install dependencies:

   cd memoryos-mcp
   pip install -r requirements.txt

2. Configure config.json: Ensure you provide user_id, openai_api_key, openai_base_url, data_storage_path, assistant_id, llm_model, and embedding_model_name.
3. Start the server:

   python server_new.py --config config.json

4. Client Integration (e.g., Cline): Copy the mcp.json file to your client and ensure the command path points to the correct Python interpreter of your virtual environment.