MemOS

https://memos-docs.openmem.net
Admin
MemOS is a platform that empowers AI applications with long-term memory capabilities, offering cloud...
Tokens:177,056
Snippets:2,012
Trust Score:4.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Run Local Preview

Source: https://memos-docs.openmem.net/open_source/contribution/writing_docs

Commands to install dependencies and start the local development server from the project root.

```bash
## Make sure to install the dependencies:
pnpm install
```

```bash
pnpm dev
```

--------------------------------

### Install Dependencies

Source: https://memos-docs.openmem.net/llms-full.txt

Run this command from the project root to install required dependencies before starting the development server.

```bash
## Make sure to install the dependencies:
pnpm install
```

--------------------------------

### Full End-to-End Memory Example

Source: https://memos-docs.openmem.net/open_source/modules/memories/tree_textual_memory

A complete workflow demonstrating setup, memory extraction, searching, and persistence.

```python
from memos.configs.embedder import EmbedderConfigFactory
from memos.configs.memory import TreeTextMemoryConfig
from memos.configs.mem_reader import SimpleStructMemReaderConfig
from memos.embedders.factory import EmbedderFactory
from memos.mem_reader.simple_struct import SimpleStructMemReader
from memos.memories.textual.tree import TreeTextMemory

# Setup Embedder
embedder_config = EmbedderConfigFactory.model_validate({
    "backend": "ollama",
    "config": {"model_name_or_path": "nomic-embed-text:latest"}
})
embedder = EmbedderFactory.from_config(embedder_config)

# Create TreeTextMemory
tree_config = TreeTextMemoryConfig.from_json_file("examples/data/config/tree_config.json")
my_tree_textual_memory = TreeTextMemory(tree_config)
my_tree_textual_memory.delete_all()

# Setup Reader
reader_config = SimpleStructMemReaderConfig.from_json_file(
    "examples/data/config/simple_struct_reader_config.json"
)
reader = SimpleStructMemReader(reader_config)

# Extract from conversation
scene_data = [[
    {
        "role": "user",
        "content": "Tell me about your childhood."
    },
    {
        "role": "assistant",
        "content": "I loved playing in the garden with my dog."
    },
]]
memory = reader.get_memory(scene_data, type="chat", info={"user_id": "1234", "session_id": "2222"})
for m_list in memory:
    my_tree_textual_memory.add(m_list)

# Search
results = my_tree_textual_memory.search(
    "Talk about the user's childhood story?",
    top_k=10
)
for i, r in enumerate(results):
    print(f"{i}'th result: {r.memory}")

# [Optional] Add from documents
doc_paths = ["./text1.txt", "./text2.txt"]
doc_memory = reader.get_memory(
  doc_paths, "doc", info={
      "user_id": "your_user_id",
      "session_id": "your_session_id",
  }
)
for m_list in doc_memory:
    my_tree_textual_memory.add(m_list)

# [Optional] Dump & Drop
my_tree_textual_memory.dump("tmp/my_tree_textual_memory")
my_tree_textual_memory.drop()
```

--------------------------------

### Start Docker Containers

Source: https://memos-docs.openmem.net/llms-full.txt

Launch the service using Docker Compose. Use the build flag for the initial setup.

```bash
# Build required for first run
docker compose up --build
# Not required for subsequent runs
docker compose up
```

--------------------------------

### Supported Agent Targets

Source: https://memos-docs.openmem.net/memos_cloud/getting_started/agent_usage

Examples of initialization commands for various supported agent frameworks and their respective skill installation paths.

```bash
memos init --agent cursor    # ~/.cursor/skills/memos/
memos init --agent codex     # ~/.codex/skills/memos/
memos init --agent claude    # ~/.claude/skills/memos/
memos init --agent openclaw  # ~/.openclaw/skills/memos/
memos init --agent hermes    # ~/.hermes/skills/memos/
```

--------------------------------

### Memory Tool Call Examples

Source: https://memos-docs.openmem.net/openclaw/examples/hermes_usage

Demonstrates how agents invoke memory tools to retrieve deployment configurations and skill guides.

```text
Agent call:
  memory_search("Nginx deployment config")
  → Returns relevant Skills, Trace snippets, and environment knowledge

Agent call:
  skill_get("nginx-proxy")
  → Returns executable steps, applicability, and caveats
```

--------------------------------

### Download MemOS Examples

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Downloads example code, data, and configuration files.

```bash
memos download_examples
```

--------------------------------

### Configure MemOS CLI

Source: https://memos-docs.openmem.net/memos_cloud/getting_started/agent_usage

Use this prompt to guide an agent through installing the MemOS CLI and initializing the configuration for a specific agent.

```text
Help me set up the MemOS CLI development environment. Follow these steps:
1. Install the MemOS CLI globally
npm i -g @memtensor/memos-cloud-cli
2. Initialize the CLI configuration
memos init --api-key YOUR_API_KEY --agent <your agent>
For step 2, pass the --agent parameter matching the Agent the user is using.
If the value of --api-key is already a real Key starting with mpg-, run it directly;
if it is still a placeholder, first guide the user to open
https://memos-dashboard.openmem.net/ to get an API Key and replace it.
```

--------------------------------

### Install MemOS via Pip

Source: https://memos-docs.openmem.net/llms-full.txt

Install the core package and verify the installation.

```bash
pip install -U "MemoryOS[all]"
```

```bash
python -c "import memos; print(memos.__version__)"
```

--------------------------------

### Configure OpenClaw Plugin

Source: https://memos-docs.openmem.net/memos_cloud/getting_started/agent_usage

Use this prompt to guide an agent through installing and configuring the MemOS plugin for OpenClaw.

```text
Help me set up the MemOS OpenClaw plugin. Follow these steps:

1. Verify the API Key
   Check the value of MEMOS_API_KEY in the commands of step 2:
   - If it is already a real API Key starting with mpg-, go straight to step 2
   - If it is still a placeholder, guide the user to open
     https://memos-dashboard.openmem.net/quickstart/ to get an API Key,
     then replace the placeholder in the commands with the real Key

2. Configure the API Key environment variable
   Detect the current operating system first, then write it accordingly:

   macOS / Linux:
     mkdir -p ~/.openclaw
     echo 'MEMOS_API_KEY=YOUR_API_KEY' >> ~/.openclaw/.env

   Windows PowerShell:
     [System.Environment]::SetEnvironmentVariable("MEMOS_API_KEY", "YOUR_API_KEY", "User")

3. Install and enable the plugin
   openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest
   openclaw gateway restart

4. Verify the installation
   Read ~/.openclaw/openclaw.json (%USERPROFILE%\.openclaw\openclaw.json on Windows),
   and confirm that under plugins.entries, memos-cloud-openclaw-plugin has enabled set to true
```

--------------------------------

### Start Required Services

Source: https://memos-docs.openmem.net/open_source/best_practice/common_errors_solutions

Use Docker and Ollama to initialize the necessary backend services.

```bash
# Start required services as needed
docker run -p 6333:6333 qdrant/qdrant
ollama serve
```

--------------------------------

### Start MemOS Server

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Launch the API server using uvicorn.

```bash
# project root directory
uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8000 --workers 1
```

--------------------------------

### Get Knowledge Base File Response Example

Source: https://memos-docs.openmem.net/api_docs/knowledge/get_kb_doc

Example JSON response structure for a successful file retrieval request.

```json
{
  "data": {
    "file_detail_list": [
      {
        "type": "document",
        "status": "running"
      }
    ]
  }
}
```

--------------------------------

### Install Huggingface Hub

Source: https://memos-docs.openmem.net/open_source/best_practice/network_workarounds

Install the required library to interact with Huggingface services.

```bash
pip install -U huggingface_hub
```

--------------------------------

### Install MemOS via pip

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Installs the core package with all optional components.

```bash
pip install -U "MemoryOS[all]"
```

--------------------------------

### Install or Upgrade the Plugin

Source: https://memos-docs.openmem.net/openclaw/local_plugin

Use this command to install or upgrade the plugin on macOS or Linux systems. The script automatically detects installed agents and handles dependencies.

```bash
curl -fsSL https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.sh | bash
```

--------------------------------

### Start Server with Docker Compose

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Commands to start the container. Use the build flag for the initial run.

```bash

# Build required for first run
docker compose up --build
# Not required for subsequent runs
docker compose up
```

--------------------------------

### Start Local Development Server

Source: https://memos-docs.openmem.net/llms-full.txt

Execute this command to launch the local web server for previewing documentation changes.

```bash
pnpm dev
```

--------------------------------

### Start MemOS Server

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Navigate to the project root and launch the server using the provided Makefile command.

```bash
cd MemOS
make serve
```

--------------------------------

### Install dependencies via Makefile

Source: https://memos-docs.openmem.net/llms-full.txt

Runs the project installation script using make.

```bash
make install  
```

--------------------------------

### Build and Start Service

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Use Docker Compose to start the required services within the docker directory.

```bash
# In the docker directory
docker compose up neo4j
```

--------------------------------

### Install and Verify Poetry

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Install the Poetry dependency manager and verify the installation.

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

```bash
poetry --version
```

--------------------------------

### Install CLI and Initialize Plugin

Source: https://memos-docs.openmem.net/openclaw/guide

Installs the global CLI tool and initializes a project with the OpenClaw plugin enabled.

```bash
npm install -g @memtensor/memos-cloud-cli
memos init --agent openclaw --memos-plugin
```

--------------------------------

### Install ModelScope

Source: https://memos-docs.openmem.net/open_source/best_practice/network_workarounds

Install the ModelScope framework dependencies.

```bash
pip install modelscope[framework]
```

--------------------------------

### Configure Dockerfile

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Example Dockerfile configuration using the simplified package.

```dockerfile
# The current example uses a simplified package url
FROM registry.cn-shanghai.aliyuncs.com/memtensor/memos-base: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"]
```

--------------------------------

### Execute Shared Database Example

Source: https://memos-docs.openmem.net/open_source/modules/memories/neo4j_graph_db

Run the provided example function to test the shared database configuration.

```python
examples/basic_modules/neo4j_example.example_complex_shared_db(db_name="shared-traval-group-complex-new")
```

--------------------------------

### Install and Initialize OpenClaw

Source: https://memos-docs.openmem.net/openclaw/guide

Installs the latest OpenClaw package globally and initializes the configuration.

```bash
# Install the newest version
npm install -g openclaw@latest

# Initialize and configure startup
openclaw onboard
```

--------------------------------

### Install Project Dependencies

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Install all project dependencies and development tools using the provided Makefile.

```bash
make install
```

--------------------------------

### Start Server API

Source: https://memos-docs.openmem.net/open_source/best_practice/mcp_for_cozespace_and_tools

Launch the backend Server API to enable memory management capabilities.

```bash
cd /path/to/MemOS
python src/memos/api/server_api.py --port 8001
```

--------------------------------

### Verify MemOS Installation

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Checks if the package is correctly installed by printing the version.

```bash
python -c "import memos; print(memos.__version__)"
```

--------------------------------

### Start Service with Docker Compose

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Command to build and start the service using docker-compose.

```bash
# Enter docker directory
docker compose up
```

--------------------------------

### Install Local Plugin

Source: https://memos-docs.openmem.net/openclaw/plugin_compare

Executes the automated installation script for local plugin deployment.

```bash
# Install the plugin
curl -fsSL https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.sh | bash
```

--------------------------------

### Start FastAPI Server

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Launch the product API server using Uvicorn with reload enabled.

```bash
uvicorn memos.api.product_api:app --host 0.0.0.0 --port 8000 --reload
```

--------------------------------

### Initialize and Install Skill

Source: https://memos-docs.openmem.net/memos_cloud/getting_started/agent_usage

Commands to initialize the MemOS environment and install the memory skill for a specific agent.

```bash
memos init --agent cursor
memos init --api-key YOUR_API_KEY --agent cursor
```

--------------------------------

### Install Poetry

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Install the Poetry dependency manager via curl.

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

--------------------------------

### Install Ollama CLI

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Installs the Ollama CLI for integration with MemOS.

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

--------------------------------

### Install Dependencies and Configure Path

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Install Python requirements and set the PYTHONPATH to the source directory.

```bash
# Execute the installation command
pip install -e .
pip install --no-cache-dir -r ./docker/requirements.txt
# Configure PYTHONPATH to the absolute directory of the current project file src
export PYTHONPATH=/******/MemOS/src
```

--------------------------------

### Example .env Configuration

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Required and optional environment variables for MemOS server operation.

```text
# ========== Required Configuration ==========
CHAT_MODEL_LIST='[
  {
    "name": "default",
    "backend": "openai",
    "config": {
      "model": "gpt-4o-mini",
      "api_key": "YOUR_API_KEY"
    }
  }
]'

# ========== Optional Configuration ==========
MEMOS_LOG_LEVEL=INFO
```

--------------------------------

### Instance Field Examples

Source: https://memos-docs.openmem.net/memos_cloud/features/filters

Examples of filtering by instance-specific fields.

```json
{"agent_id":"memos_agent"}
```

```json
{"app_id":"app_123"}
```

```json
{"related_id": ["memos_user_1", "memos_user_2"]}
```

--------------------------------

### Complete End-to-End Workflow

Source: https://memos-docs.openmem.net/open_source/modules/memories/preference_textual_memory

A full example integrating configuration, extraction, search, and persistence.

```python
from memos.configs.memory import PreferenceTextMemoryConfig
from memos.memories.textual.preference import PreferenceTextMemory

# Create PreferenceTextMemory
config = PreferenceTextMemoryConfig.from_json_file("examples/data/config/preference_config.json")

preference_memory = PreferenceTextMemory(config)
preference_memory.delete_all()

scene_data = [[
    {"role": "user", "content": "Tell me about your childhood."},
    {"role": "assistant", "content": "I loved playing in the garden with my dog."}
]]

# Extract preference memories from original dialogues and add to Milvus database
memories = preference_memory.get_memory(scene_data, type="chat", info={"user_id": "1234"})
preference_memory.add(memories)

# Search memory
results = preference_memory.search("Tell me more about the user", top_k=2)

# Persist preference memories
preference_memory.dump("tmp/pref_memories")
```

--------------------------------

### Start MemOS Server

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Launches the API server using python-dotenv to load the .env configuration.

```bash
python -m dotenv run -- \
  uvicorn memos.api.server_api:app \
  --host 0.0.0.0 \
  --port 8000
```

--------------------------------

### Configure Dockerfile

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Example Dockerfile configuration using the slim package for ARM architecture.

```dockerfile
# 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"]
```

--------------------------------

### Install and Enable OpenClaw Plugin

Source: https://memos-docs.openmem.net/memos_cloud/getting_started/agent_usage

Commands to install the plugin and the JSON structure to enable it in the configuration file.

```bash
openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest
openclaw gateway restart
```

```json
{
  "plugins": {
    "entries": {
      "memos-cloud-openclaw-plugin": { "enabled": true }
    }
  }
}
```

--------------------------------

### Install MemOS Python SDK

Source: https://memos-docs.openmem.net/memos_cloud/getting_started/quick_start

Install the required Python package for manual integration.

```bash
pip install MemoryOS -U
```

--------------------------------

### Time Field Examples

Source: https://memos-docs.openmem.net/memos_cloud/features/filters

Examples of filtering by creation and update timestamps.

```json
{"create_time": {"gte": "2025-12-10"}}
```

```json
{"update_time": {"lte": "2025-12-10"}}
```

--------------------------------

### Install MemOS library

Source: https://memos-docs.openmem.net/open_source/contribution/writing_docs

Install the MemOS package via pip.

```bash
pip install MemoryOS
```

--------------------------------

### Install MemOS CLI

Source: https://memos-docs.openmem.net/llms.txt

Install the command-line interface for MemOS via pip.

```bash
pip install memos-cli
```

--------------------------------

### Install Plugin via NPM

Source: https://memos-docs.openmem.net/openclaw/guide

Installs the MemOS cloud plugin and restarts the gateway.

```bash
openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest
openclaw gateway restart
```

--------------------------------

### Execute Neo4j Community Example

Source: https://memos-docs.openmem.net/open_source/modules/memories/neo4j_graph_db

Run the example function specifically for the Neo4j Community Edition configuration.

```python
examples/basic_modules/neo4j_example.example_complex_shared_db(db_name="paper", community=True)
```

--------------------------------

### Install MemOS and PolarDB dependencies

Source: https://memos-docs.openmem.net/open_source/modules/memories/polardb_graph_db

Install the required PostgreSQL driver and the MemOS package.

```bash
# Install psycopg2 driver (choose one)
pip install psycopg2-binary  # Recommended: pre-compiled version
# or
pip install psycopg2          # Requires PostgreSQL development libraries

# Install MemOS
pip install MemoryOS -U
```

--------------------------------

### Start and Verify Docker

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Commands to initialize the Docker service and verify running containers or images.

```bash
 # 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
```

--------------------------------

### Manage Docker Containers and Start Server

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Load required Docker images and start the Uvicorn server, including PYTHONPATH configuration if needed.

```bash
docker load -i neo4j.5.26.4.tar
docker load -i qdrant.v1.15.3.tar
docker images
docker ps -a

uvicorn memos.api.server_api:app --host 0.0.0.0 --port 8000 --workers 1

export PYTHONPATH=/you-file-absolute-path/MemOS/src
```

--------------------------------

### Configure Dockerfile

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Example Dockerfile configuration using the lite package for ARM architecture.

```dockerfile
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"]
```

--------------------------------

### Install Python Dependencies

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Install project requirements using pip with a specified mirror source.

```bash
pip install --no-cache-dir -r ./docker/requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```

--------------------------------

### Install MemOS CLI

Source: https://memos-docs.openmem.net/memos_cloud/getting_started/agent_usage

Global installation of the MemOS CLI package via npm.

```bash
npm install -g @memtensor/memos-cloud-cli
```

--------------------------------

### Example Workflow for Local Plugin Retrieval

Source: https://memos-docs.openmem.net/llms-full.txt

Illustrates how memory search prioritizes local agent stores and how the optional hub enables shared skill retrieval.

```text
OpenClaw:
  memory_search("deploy config")
  → prioritizes OpenClaw's local Skill / Trace / World Model store

Hermes:
  memory_search("deploy config")
  → prioritizes Hermes' local Skill / Trace / World Model store

With Hub enabled:
  OpenClaw / Hermes can pull team-shared Skills
  private Traces remain local to each machine and runtime home by default
```

--------------------------------

### Install Cloud Plugin

Source: https://memos-docs.openmem.net/openclaw/plugin_compare

Installs the latest version of the MemOS Cloud plugin using the OpenClaw CLI.

```bash
openclaw plugins install @memtensor/memos-cloud-openclaw-plugin@latest
```

--------------------------------

### Start Docker Service

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Commands to initiate the Docker daemon and verify its status.

```bash
 # If Docker is not installed, please install the corresponding version. The download link is as follows:
 https://www.docker.com/

 #After installation, Docker can be started through the client or through the command line
 #Command line start
 sudo systemctl start docker

# Check docker status
docker ps
# Check docker images (optional)
docker images

```

--------------------------------

### Get Memory Response Example

Source: https://memos-docs.openmem.net/api_docs/core/get_memory_by_id

Example JSON response structure returned by the get_memory_by_id operation.

```json
{
  "code": 0,
  "data": {
    "memory_view": "detail_factual",
    "status": "activated"
  },
  "message": "ok"
}
```

--------------------------------

### Install Optional MemOS Dependencies

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Commands for installing specific feature sets like tree memory, readers, or schedulers.

```bash
pip install MemoryOS[tree-mem]
pip install MemoryOS[tree-mem,mem-reader]
pip install MemoryOS[mem-scheduler]
pip install MemoryOS[tree-mem,mem-reader,mem-scheduler]
```

--------------------------------

### Install Dependency Modules

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Install required Python packages from requirements.txt. An alternative command for Aliyun mirrors is provided as a comment.

```bash

pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt
# Install dependencies using Aliyun source
# pip install --upgrade pip && pip install --no-cache-dir -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```

--------------------------------

### Define Minimal Environment Configuration

Source: https://memos-docs.openmem.net/openclaw/guide

Example content for an .env file to store the API token.

```env
MEMOS_API_KEY=YOUR_TOKEN
```

--------------------------------

### Create a knowledge base with memos kb create

Source: https://memos-docs.openmem.net/mcp_agent/cli/guide

Initializes a new knowledge base with a name and optional description.

```bash
memos kb create --name "Product FAQ" --description "Common product questions" --format json
```

--------------------------------

### Create and Activate Conda Environment

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Recommended to isolate dependencies for the MemOS installation.

```bash
conda create -n memos python=3.11
conda activate memos
```

--------------------------------

### Complete End-to-End Memory Workflow

Source: https://memos-docs.openmem.net/open_source/modules/memories/naive_textual_memory

A comprehensive example covering initialization, extraction, searching, updating, persistence, and deletion.

```python
from memos.configs.memory import MemoryConfigFactory
from memos.memories.factory import MemoryFactory

# ========================================
# 1. Initialization
# ========================================
config = MemoryConfigFactory(
    backend="naive_text",
    config={
        "extractor_llm": {
            "backend": "openai",
            "config": {
                "model_name_or_path": "gpt-4o-mini",
                "api_key": "your-api-key",
            },
        },
    },
)
memory = MemoryFactory.from_config(config)

# ========================================
# 2. Extract and Add Memories
# ========================================
memories = memory.extract([
    {"role": "user", "content": "I love tomatoes."},
    {"role": "assistant", "content": "Great! Tomatoes are delicious."},
])
memory.add(memories)
print(f"✓ Added {len(memories)} memories")

# ========================================
# 3. Search Memories
# ========================================
results = memory.search("tomatoes", top_k=2)
print(f"\n🔍 Found {len(results)} relevant memories:")
for i, item in enumerate(results, 1):
    print(f"  {i}. {item.memory}")

# ========================================
# 4. Get All Memories
# ========================================
all_memories = memory.get_all()
print(f"\n📊 Total {len(all_memories)} memories")

# ========================================
# 5. Update Memory
# ========================================
if memories:
    memory_id = memories[0].id
    memory.update(
        memory_id, 
        {
            "memory": "User loves tomatoes.",
            "metadata": {"type": "opinion", "confidence": 95.0}
        }
    )
    print(f"\n✓ Updated memory: {memory_id}")

# ========================================
# 6. Persist to Storage
# ========================================
memory.dump("tmp/mem")
print("\n💾 Memories saved to tmp/mem/textual_memory.json")

# ========================================
# 7. Load Memories
# ========================================
memory.load("tmp/mem")
print("✓ Memories loaded from file")

# ========================================
# 8. Delete Memories
# ========================================
if memories:
    memory.delete([memories[0].id])
    print(f"\n🗑️ Deleted 1 memory")

# Delete all memories
# memory.delete_all()
```

--------------------------------

### Install dependencies via CLI

Source: https://memos-docs.openmem.net/llms-full.txt

Installs project dependencies using pip with a specific mirror source.

```bash
# pip install --upgrade pip && pip install --no-cache-dir -r ./docker/requirements.txt
# Install dependencies using Aliyun source
pip install --no-cache-dir -r ./docker/requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```

--------------------------------

### Create Configuration File

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Initialize the .env file in the project root directory.

```bash
cd MemOS
touch .env
```

--------------------------------

### Configure Bailian Environment Variables

Source: https://memos-docs.openmem.net/open_source/getting_started/rest_api_server

Example configuration for the .env file specifically using the Bailian platform.

```bash
# You can apply through the Bailian platform
# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api
# After successful application, obtain API_KEY and BASE-URL. The example configuration is as follows

# OpenAI API Key (Using the API_KEY of Bailian)
OPENAI_API_KEY=you_bailian_api_key
# OpenAI API Base URL
OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
# Default model name
MOS_CHAT_MODEL=qwen3-max

# Memory Reader LLM model
MEMRADER_MODEL=qwen3-max
# Memory Reader API Key (Using the API_KEY of Bailian)
MEMRADER_API_KEY=you_bailian_api_key
# Memory Reader API Base URL
MEMRADER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1

# Embedder The model name can refer to the following link
# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api/?type=model&url=2846066
MOS_EMBEDDER_MODEL=text-embedding-v4
# set default embedding backend default: ollama | universal_api
MOS_EMBEDDER_BACKEND=universal_api
# Embedder API Base URL
MOS_EMBEDDER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
# Embedder API Key (Using the API_KEY of Bailian)
MOS_EMBEDDER_API_KEY=you_bailian_api_key
# Embedding vector dimension
EMBEDDING_DIMENSION=1024
# Reranker backend (http_bge | etc.)
MOS_RERANKER_BACKEND=cosine_local

# Neo4j Connection URI
# Optional values: neo4j-community | neo4j | nebular | polardb
NEO4J_BACKEND=neo4j-community
# required when backend=neo4j*
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=12345678
NEO4J_DB_NAME=neo4j
MOS_NEO4J_SHARED_DB=false

# Whether to use Redis scheduler
DEFAULT_USE_REDIS_QUEUE=false

# Enable chat api
ENABLE_CHAT_API=true

CHAT_MODEL_LIST=[{"backend": "qwen", "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key": "you_bailian_api_key", "model_name_or_path": "qwen3-max-preview", "extra_body": {"enable_thinking": true} ,"support_models": ["qwen3-max-preview"]}]
```

--------------------------------

### GeneralTextMemory Usage Recommendation

Source: https://memos-docs.openmem.net/llms-full.txt

Recommended starting point for memory implementation before scaling to more complex graph or KV-cache structures.

```text
GeneralTextMemory
```

--------------------------------

### Retrieve Memory ID for Deletion

Source: https://memos-docs.openmem.net/memos_cloud/mem_operations/delete_memory

Example JSON response from a search or get memory call, containing the 'id' field required for deletion.

```json
{
  "memory_detail_list": [
    {
      "id": "e2a7c194-7062-4fa5-a6c0-bbe554d05d60",
      "memory_key": "User ice cream preference",
      "memory_value": "[user opinion] The user likes ice cream.",
      "memory_type": "WorkingMemory",
      "memory_time": null,
      "conversation_id": "0610",
      "status": "activated",
      "confidence": 0,
      "tags": [
        "food",
        "preference",
        "ice cream"
      ],
      "update_time": 1761315278665,
      "relativity": 0.7524414
    }
  ]
}
```

--------------------------------

### Configure .env File

Source: https://memos-docs.openmem.net/open_source/getting_started/installation

Example configurations for the .env file, including API keys, model settings, and database connections.

```bash

# OpenAI API Key (Required configuration)
OPENAI_API_KEY=sk-xxx
# OpenAI API Base URL 
OPENAI_API_BASE=http://xxx:3000/v1
# Default model name
MOS_CHAT_MODEL=qwen3-max

# Memory Reader LLM Model
MEMRADER_MODEL=qwen3-max
# Memory Reader API Key 
MEMRADER_API_KEY=sk-xxx
# Memory Reader API Base URL
MEMRADER_API_BASE=http://xxx:3000/v1

# Embedder Model Name
MOS_EMBEDDER_MODEL=text-embedding-v4
# Configure embedding backend: ollama | universal_api
MOS_EMBEDDER_BACKEND=universal_api
# Embedder API Base URL 
MOS_EMBEDDER_API_BASE=http://xxx:8081/v1
# Embedder API Key
MOS_EMBEDDER_API_KEY=xxx
# Embedding Vector Dimension
EMBEDDING_DIMENSION=1024
# Reranker Backend (http_bge | etc.)
MOS_RERANKER_BACKEND=cosine_local

# Neo4j Connection URI
# Options: neo4j-community | neo4j | nebular | polardb
NEO4J_BACKEND=neo4j-community
# Required when backend=neo4j*
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=12345678
NEO4J_DB_NAME=neo4j
MOS_NEO4J_SHARED_DB=false

# Whether to use redis scheduler
DEFAULT_USE_REDIS_QUEUE=false

# Enable Chat API
ENABLE_CHAT_API=true
# Chat model list, can be applied through Bailian. Models are customizable.
CHAT_MODEL_LIST=[{"backend": "qwen", "api_base": "https://xxx/v1", "api_key": "sk-xxx", "model_name_or_path": "qwen3-max", "extra_body": {"enable_thinking": true} ,"support_models": ["qwen3-max"]}]
```

```bash
# Can be applied through Bailian platform
# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api
# After successful application, get API_KEY and BASE_URL, configuration example as follows

# OpenAI API Key (Use Bailian API_KEY)
OPENAI_API_KEY=you_bailian_api_key
# OpenAI API Base URL 
OPENAI_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
# Default model name
MOS_CHAT_MODEL=qwen3-max

# Memory Reader LLM Model
MEMRADER_MODEL=qwen3-max
# Memory Reader API Key (Use Bailian API_KEY)
MEMRADER_API_KEY=you_bailian_api_key
# Memory Reader API Base URL
MEMRADER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1

# Embedder model name can refer to the link below
# https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.2f2165b08fRk4l&tab=api#/api/?type=model&url=2846066
MOS_EMBEDDER_MODEL=text-embedding-v4
# Configure embedding backend: ollama | universal_api
MOS_EMBEDDER_BACKEND=universal_api
# Embedder API Base URL 
MOS_EMBEDDER_API_BASE=https://dashscope.aliyuncs.com/compatible-mode/v1
# Embedder API Key (Use Bailian API_KEY)
MOS_EMBEDDER_API_KEY=you_bailian_api_key
# Embedding Vector Dimension
EMBEDDING_DIMENSION=1024
# Reranker Backend (http_bge | etc.)
MOS_RERANKER_BACKEND=cosine_local

# Neo4j Connection URI
# Options: neo4j-community | neo4j | nebular | polardb
NEO4J_BACKEND=neo4j-community
# Required when backend=neo4j*
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=12345678
NEO4J_DB_NAME=neo4j
MOS_NEO4J_SHARED_DB=false

# Whether to use redis scheduler
DEFAULT_USE_REDIS_QUEUE=false

# Enable Chat API
ENABLE_CHAT_API=true

CHAT_MODEL_LIST=[{"backend": "qwen", "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key": "you_bailian_api_key", "model_name_or_path": "qwen3-max-preview", "extra_body": {"enable_thinking": true} ,"support_models": ["qwen3-max-preview"]}]
```

--------------------------------

### Initialize and Run MemScheduler Demo

Source: https://memos-docs.openmem.net/open_source/modules/mem_scheduler

Demonstrates environment setup, custom handler registration for query and memory update tasks, and the execution of a mock conversation flow.

```python
import asyncio
import json
import os
import sys
import time
from pathlib import Path

# --- Environment Setup ---
# 1. Add project root to sys.path to ensure memos module can be imported
FILE_PATH = Path(__file__).absolute()
BASE_DIR = FILE_PATH.parent.parent.parent
sys.path.insert(0, str(BASE_DIR))

# 2. Set necessary environment variables (simulating .env configuration)
os.environ["ENABLE_CHAT_API"] = "true"
os.environ["MOS_ENABLE_SCHEDULER"] = "true"
# Choose between Redis or Local queue
os.environ["MOS_SCHEDULER_USE_REDIS_QUEUE"] = "false" 

# --- Import Components ---
# Note: Importing server_router triggers component initialization,
# ensure environment variables are set before this import
from memos.api.product_models import APIADDRequest, ChatPlaygroundRequest
from memos.api.routers.server_router import (
    add_handler,
    chat_stream_playground,
    mem_scheduler,  # mem_scheduler here is already an initialized singleton
)
from memos.log import get_logger
from memos.mem_scheduler.schemas.message_schemas import ScheduleMessageItem
from memos.mem_scheduler.schemas.task_schemas import (
    MEM_UPDATE_TASK_LABEL,
    QUERY_TASK_LABEL,
)

logger = get_logger(__name__)

# Global variable for demonstrating memory retrieval results
working_memories = []

# --- Custom Handlers ---

def custom_query_handler(messages: list[ScheduleMessageItem]):
    """
    Handle user query messages:
    1. Print query content
    2. Convert message to MEM_UPDATE task, triggering memory retrieval/update process
    """
    for msg in messages:
        print(f"\n[Scheduler 🟢] Received user query: {msg.content}")
        
        # Copy message and change label to MEM_UPDATE, a common "task chaining" pattern
        new_msg = msg.model_copy(update={"label": MEM_UPDATE_TASK_LABEL})
        
        # Submit new task back to scheduler
        mem_scheduler.submit_messages([new_msg])

def custom_mem_update_handler(messages: list[ScheduleMessageItem]):
    """
    Handle memory update tasks:
    1. Use retriever to find relevant memories
    2. Update global working memory list
    """
    global working_memories
    search_args = {}
    top_k = 2
    
    for msg in messages:
        print(f"[Scheduler 🔵] Retrieving memories for query...")
        # Call core retrieval functionality
        results = mem_scheduler.retriever.search(
            query=msg.content,
            user_id=msg.user_id,
            mem_cube_id=msg.mem_cube_id,
            mem_cube=mem_scheduler.current_mem_cube,
            top_k=top_k,
            method=mem_scheduler.search_method,
            search_args=search_args,
        )
        
        # Simulate working memory update
        working_memories.extend(results)
        working_memories = working_memories[-5:] # Keep the latest 5
        
        for mem in results:
            # Print retrieved memory fragments
            print(f"  ↳ [Memory Found]: {mem.memory[:50]}...")

# --- Mock Business Data ---

def get_mock_data():
    """Generate mock conversation data"""
    conversations = [
        {"role": "user", "content": "I just adopted a golden retriever puppy named Max."},
        {"role": "assistant", "content": "That's exciting! Max is a great name."},
        {"role": "user", "content": "He loves peanut butter treats but I am allergic to nuts."},
        {"role": "assistant", "content": "Noted. Peanut butter for Max, no nuts for you."},
    ]
    
    questions = [
        {"question": "What is my dog's name?", "category": "Pet"},
        {"question": "What am I allergic to?", "category": "Allergy"},
    ]
    return conversations, questions

# --- Main Flow ---

async def run_demo():
    print("==== MemScheduler Demo Start ====")
    conversations, questions = get_mock_data()

    user_id = "demo_user_001"
    mem_cube_id = "cube_demo_001"

    print(f"1. Initialize user memory library ({user_id})...")
    # Use API Handler to add initial memories (synchronous mode)
    add_req = APIADDRequest(
        user_id=user_id,
        writable_cube_ids=[mem_cube_id],
        messages=conversations,
        async_mode="sync", 
    )
    add_handler.handle_add_memories(add_req)
    print("   Memory addition completed.")

    print("\n2. Start conversation testing (triggering background scheduling tasks)...")
    for item in questions:
        query = item["question"]
        print(f"\n>> User: {query}")
```

--------------------------------

### Shopping Assistant MemOS Solution

Source: https://memos-docs.openmem.net/memos_cloud/features/knowledge_base

Example of the MemOS approach successfully recalling user history and constraints.

```python
# Retrieve relevant memories based on user input, perceive that the user's dog is a three-month-old Golden Retriever puppy, dislikes chicken, and needs a recommendation for puppy food that won't cause diarrhea. Retrieved memories:

1. The user has a three-month-old Golden Retriever weighing about 12 catties.
2. The user's dog does not eat chicken-flavored dog food.
3. The user previously purchased lamb puppy food.
4. Common reasons for dog food diarrhea: Can switch to hypoallergenic dog food.
5. Hypoallergenic puppy food recommendation: B (Chicken), C (Salmon).

# ✅ Shopping Assistant: You mentioned before that the dog is a 3-month-old Golden Retriever and cannot eat chicken flavor, so I have excluded all chicken-flavored puppy foods for you. You bought lamb + salmon puppy food before. If diarrhea occurs now, you can try the milder C (Salmon Puppy Hypoallergenic).
```

--------------------------------

### API response examples

Source: https://memos-docs.openmem.net/llms-full.txt

Expected JSON response structures for different extraction requests.

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "memory_detail_list": [
      {
        "memory_key": "User profile and job",
        "memory_value": "User Alex, 28, backend developer in Hangzhou, plays badminton.",
        "memory_type": "UserMemory",
        "tags": ["person", "job", "location", "hobby"]
      }
    ],
    "preference_detail_list": [
      {
        "preference": "Wants assistant replies to stay concise and not overly verbose.",
        "reasoning": "User explicitly asked to keep responses short and not too wordy.",
        "preference_type": "explicit_preference"
      }
    ]
  }
}
```

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "memory_detail_list": [
      {
        "memory_key": "Travel and stay",
        "memory_value": "User flies to Beijing next Wednesday on business and plans to stay at Ji Hotel in Chaoyang.",
        "memory_type": "LongTermMemory",
        "tags": ["travel", "trip", "hotel"]
      }
    ]
  }
}
```

```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "success": true,
    "preference_detail_list": [
      {
        "preference": "Prefers Markdown documents with syntax-highlighted code blocks.",
        "reasoning": "User clearly asked for Markdown and highlighted code blocks.",
        "preference_type": "explicit_preference"
      },
      {
        "preference": "Use fewer emoji.",
        "reasoning": "User directly asked to avoid too many emoji.",
        "preference_type": "explicit_preference"
      }
    ]
  }
}
```

--------------------------------

### Start MCP HTTP Service

Source: https://memos-docs.openmem.net/open_source/best_practice/mcp_for_cozespace_and_tools

Launch the MCP service using HTTP transport on the specified port.

```bash
cd /path/to/MemOS
python examples/mem_mcp/simple_fastmcp_serve.py --transport http --port 8002
```

--------------------------------

### Metadata Field Examples

Source: https://memos-docs.openmem.net/memos_cloud/features/filters

Examples of filtering by business metadata fields.

```json
{"business_type":"shopping"}
```

```json
{"biz_id":"order_123456"}
```

```json
{"scene":"payment"}
```

```json
{"custom_status":"VIP3"}
```

--------------------------------

### Manage Docker Service

Source: https://memos-docs.openmem.net/llms-full.txt

Commands to start the Docker daemon and verify the status of containers and images.

```bash
 # If Docker is not installed, please install the corresponding version. Download address:
 https://www.docker.com/

#After installation, Docker can be started through the client or through the command line
#Command line start
sudo systemctl start docker

# After installation, check docker status
docker ps

# Check docker images (optional)
docker images
```

--------------------------------

### GET /api_docs/core/search_memory

Source: https://memos-docs.openmem.net/llms-full.txt

Retrieves a collection of memory-related details including skills, preferences, and profiles.

```APIDOC
## GET /api_docs/core/search_memory

### Description
Retrieves a comprehensive list of memory details, including skill_detail_list, memory_detail_list, preference_detail_list, profile_detail_list, event_detail_list, and tool_memory_detail_list.

### Endpoint
/api_docs/core/search_memory

### Response
#### Success Response (200)
- **code** (number) - Status code of the response.
- **data** (object) - Contains lists of various memory and skill details.

#### Response Example
{
  "code": 0,
  "data": {
    "memory_detail_list": [
      {
        "memory_type": "LongTermMemory",
        "status": "activated",
        "confidence": 0.95,
        "relativity": 0.87
      }
    ],
    "preference_detail_list": [
      {
        "preference_type": "explicit_preference",
        "status": "activated",
        "relativity": 0.87
      }
    ],
    "profile_detail_list": [
      {
        "memory_type": "ProfileMemory",
        "status": "activated"
      }
    ],
    "event_detail_list": [
      {
        "status": "activated"
      }
    ],
    "tool_memory_detail_list": [
      {
        "tool_type": "ToolTrajectoryMemory",
        "status": "activated"
      }
    ],
    "skill_detail_list": [
      {
        "status": "activated"
      }
    ]
  }
}
```

--------------------------------

### Tag Field Example

Source: https://memos-docs.openmem.net/memos_cloud/features/filters

Example of filtering by tags using the contains operator.

```json
{"tags": {"contains": "finance"}}
```

--------------------------------

### Extract memory and preferences via Python

Source: https://memos-docs.openmem.net/llms-full.txt

Use these examples to send dialogue data to the Memos API for extraction. Ensure MEMOS_API_KEY and MEMOS_BASE_URL are set in your environment.

```python
import os, json, requests

os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

data = {
    "messages": [
        {"role": "system", "content": "Extract key memories from the dialogue."},
        {"role": "user", "content": "I'm Alex, 28, backend dev in Hangzhou, I play badminton."},
        {"role": "assistant", "content": "Hi Alex!"},
        {"role": "user", "content": "Keep replies short, not too wordy."},
    ]
}
headers = {"Content-Type": "application/json", "Authorization": f"Token {os.environ['MEMOS_API_KEY']}"}
url = f"{os.environ['MEMOS_BASE_URL']}/extract/memory"
res = requests.post(url, headers=headers, data=json.dumps(data))
print(res.json())
```

```python
import os, json, requests

os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

data = {
    "messages": [{"role": "user", "content": "Flying to Beijing next Wed, staying at Ji Hotel Chaoyang."}],
    "extraction_types": ["memory"],
}
headers = {"Content-Type": "application/json", "Authorization": f"Token {os.environ['MEMOS_API_KEY']}"}
url = f"{os.environ['MEMOS_BASE_URL']}/extract/memory"
res = requests.post(url, headers=headers, data=json.dumps(data))
print(res.json())
```

```python
import os, json, requests

os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

data = {
    "messages": [
        {"role": "user", "content": "Use Markdown for docs, code blocks should have syntax highlighting."},
        {"role": "assistant", "content": "Got it."},
        {"role": "user", "content": "Also go easy on emoji."},
    ],
    "extraction_types": ["preference"],
}
headers = {"Content-Type": "application/json", "Authorization": f"Token {os.environ['MEMOS_API_KEY']}"}
url = f"{os.environ['MEMOS_BASE_URL']}/extract/memory"
res = requests.post(url, headers=headers, data=json.dumps(data))
print(res.json())
```

--------------------------------

### Preview Documentation via NPM

Source: https://memos-docs.openmem.net/open_source/contribution/writing_docs

Alternative command to preview changes locally using npm.

```bash
npm run dev
```

--------------------------------

### Request Body Example

Source: https://memos-docs.openmem.net/api_docs/core/bind_profile_template

Example payload for binding a profile template to a specific user.

```json
{
  "bind_list": [
    {
      "user_id": "memos_user_123",
      "profile_template_id": "tpl_user_001"
    }
  ]
}
```

--------------------------------

### Verify Python Installation

Source: https://memos-docs.openmem.net/open_source/contribution/setting_up

Check the installed version of Python to ensure it meets the 3.9+ requirement.

```bash
python3 --version
```
Tokens:
Raw