### Quick Start Installation and Configuration

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/contribution/writing_docs.md

This snippet demonstrates a quick start guide for installing MemOS, creating a minimal configuration, and setting up a user.

```mdc
::steps{level="4"}

#### Install MemOS

```bash
pip install MemoryOS
```

#### Create a Minimal Config

For this Quick Start, we'll use the built-in GeneralTextMemory.

```python
from memos.configs.mem_os import MOSConfig

# init MOSConfig
mos_config = MOSConfig.from_json_file("examples/data/config/simple_memos_config.json")
```

#### Create a User & Register a MemCube

```python
import uuid
from memos.mem_os.main import MOS

mos = MOS(mos_config)

# Generate a unique user ID
user_id = str(uuid.uuid4())

# Create the user
mos.create_user(user_id=user_id)
```

::
```

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

### Download MemOS Examples

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/installation.md

Download example code, data, and configurations to help you get started with MemOS.

```bash
memos download_examples
```

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

### Dual OpenClaw Instance Setup Example

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/HUB-SHARING-GUIDE.md

Demonstrates how to start two OpenClaw instances with distinct configurations for personal and work use, ensuring port and state isolation.

```bash
# Instance 1 (Personal): gateway on 18789, viewer on 18799, hub on 18800
OPENCLAW_CONFIG_PATH=~/oc-personal/openclaw.json openclaw gateway start

# Instance 2 (Work): gateway on 19001, viewer on 19011, hub on 19012
OPENCLAW_CONFIG_PATH=~/oc-work/openclaw.json openclaw gateway start
```

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

### Install Dependencies

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/contribution/writing_docs.md

Run this command to install project dependencies before starting the local preview.

```bash
pnpm install
```

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

### Install and Run Openwork

Source: https://github.com/memtensor/memos/blob/main/apps/openwork-memos-integration/README.md

Install dependencies and start the development server for the desktop application.

```bash
pnpm install
pnpm dev
```

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

### Start MCP Server using Example Script

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/mos/memos_mcp.md

Run the MCP server using the example script, specifying HTTP transport and a port. Navigate to the examples directory first.

```bash
# Navigate to the examples directory
cd examples/mem_mcp

# Run the server
python simple_fastmcp_serve.py --transport http --port 8000
```

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

### Install Memos Local Plugin (Windows)

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/website/index.html

Installs the plugin and starts the viewer on Windows systems using PowerShell.

```powershell
$ irm https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.ps1 | iex
```

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

### Verify Plugin Initialization Logs

Source: https://github.com/memtensor/memos/blob/main/src/memos/plugins/README.md

Example startup logs indicating a plugin has been discovered and initialized. Check these logs after starting the API server.

```text
INFO: Plugin discovered: dream v0.1.0 (priority=10)
INFO: Plugin initialized: dream
```

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

### Quick Start Workflow Commands

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/skill/browserwing-admin/SKILL.md

A sequence of commands and API calls to get started with BrowserWing, including installation, starting the service, adding LLM configurations, and executing scripts.

```bash
# Start BrowserWing
./browserwing --port 8080
```

```bash
# AI Exploration
POST /ai-explore/start with a task description
```

```bash
# Manual Creation
POST /scripts with actions array
```

```bash
# Web UI
Open http://<host>:8080 in browser to use the visual editor
```

```bash
# Execute scripts
POST /scripts/<id>/play
```

```bash
# View results
GET /scripts/play/result
```

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

### Run MemOS Example Script

Source: https://github.com/memtensor/memos/blob/main/examples/README.md

Execute a MemOS example script. Ensure project dependencies are installed and run from the repository root for correct path resolution.

```bash
python examples/mem_cube/load_cube.py
```

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

### Self-Host MemOS Installation

Source: https://github.com/memtensor/memos/blob/main/README.md

Steps to clone the repository, install dependencies, configure environment variables, and start the MemOS service for self-hosting.

```bash
git clone https://github.com/MemTensor/MemOS.git
cd MemOS

pip install -r ./docker/requirements.txt

cp docker/.env.example MemOS/.env

# Start service
# See docs for full setup
```

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

### Install Memos Local Plugin (macOS/Linux)

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/website/index.html

Installs the plugin and starts the viewer on macOS and Linux systems using a curl command.

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

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

### Install and Help for Local Plugin

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/website/docs/troubleshooting.html

Run the installation script for the local plugin and display its help message.

```bash
cd apps/memos-local-plugin
bash install.sh

bash install.sh --help
```

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

### Run MCP Client Example

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/mos/memos_mcp.md

Execute the sample client script to interact with a running MCP server. Ensure the server is started with HTTP transport on the specified port.

```bash
# Ensure the MCP server is running on HTTP transport
cd examples/mem_mcp
python simple_fastmcp_serve.py --transport http --port 8000

# In another terminal, run the client
cd examples/mem_mcp
python simple_fastmcp_client.py
```

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

### One-Line MemOS Setup

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/mos/memos_neo.md

Initialize an auto-configured MemOS instance with `MOS.simple()`. This is the quickest way to start building memory-enhanced applications.

```python
from memos.mem_os.main import MOS

# Auto-configured instance
memory = MOS.simple()
```

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

### Load Docker Images and Start Server

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/rest_api_server.md

Loads necessary Docker images (Neo4j, Qdrant) and starts the FastAPI server. Includes commands to verify installation and running status. Sets PYTHONPATH if module not found.

```bash
# Packages that might need manual installation currently. Need to find resources for these two packages
# neo4j.5.26.4.tar   qdrant.v1.15.3.tar
docker load -i neo4j.5.26.4.tar
docker load -i qdrant.v1.15.3.tar
# Check if installed successfully
docker images
# Check if running
docker ps -a


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

# If ModuleNotFoundError: No module named 'memos' appears during startup, it is due to path matching problem, please execute
export PYTHONPATH=/you-file-absolute-path/MemOS/src
```

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

### Start Docker Service

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/rest_api_server.md

Commands to start and check the Docker service. Ensure Docker is installed before running these commands.

```bash
sudo systemctl start docker

docker ps
docker images
```

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

### Skill Get Tool Example

Source: https://github.com/memtensor/memos/blob/main/docs/en/openclaw/examples/hermes_usage.md

Demonstrates calling the skill_get tool to retrieve details about a specific skill.

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

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

### Install Memos Local Plugin from Source (Development)

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/README.md

Clones the repository, installs dependencies, builds the plugin, and installs it locally for development purposes.

```bash
git clone https://github.com/MemTensor/MemOS.git
cd MemOS/apps/memos-local-openclaw
npm install && npm run build
openclaw plugins install .
```

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

### Example Docker Deployment for Hermes Agent

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/README.md

A complete Dockerfile example for deploying the memos-local-plugin with the Hermes Agent, including installation, configuration, and daemon startup.

```dockerfile
FROM nousresearch/hermes-agent:latest

# Install memos-local-plugin
RUN bash -c "$(curl -fsSL https://raw.githubusercontent.com/MemTensor/MemOS/main/apps/memos-local-plugin/install.sh)"

# Set the config location
ENV MEMOS_HOME=/opt/data/.hermes/memos-plugin

# Start daemon in background, then run Hermes
CMD node /opt/data/.hermes/plugins/memos-local-plugin/bridge.cts --agent=hermes --daemon && hermes chat
```

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

### Install OpenClaw

Source: https://github.com/memtensor/memos/blob/main/docs/en/openclaw/guide.md

Installs the latest version of OpenClaw and initializes its configuration.

```bash
npm install -g openclaw@latest
openclaw onboard
```

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

### Chat API Quick Start with MemOSClient

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/open_source_api/chat/chat.md

Demonstrates how to initiate a chat request using the MemOSClient, specifying user ID, query, readable and writable cube IDs, and retrieval mode. This example enables automatic memory write-back.

```python
from memos.api.client import MemOSClient

client = MemOSClient(api_key="...", base_url="...")

# Initiate a chat request
res = client.chat(
    user_id="dev_user_01",
    query="Based on my previous preferences, recommend an R language data cleaning workflow",
    readable_cube_ids=["private_cube_01", "public_kb_r_lang"], # Read: personal preferences + public knowledge base
    writable_cube_ids=["private_cube_01"],                      # Write: persist to personal space
    add_message_on_answer=True,                                 # Enable automatic memory write-back
    mode="fine"                                                 # Use fine-grained retrieval mode
)

if res:
    print(f"AI Response: {res.data}")
```

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

### Dockerfile Configuration Example

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/contribution/setting_up.md

Example Dockerfile for building a MemOS service image. This example uses a slim package for ARM architecture and configures environment variables for Hugging Face endpoints and Python path.

```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 Hugging Face Hub

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/best_practice/network_workarounds.md

Install the huggingface_hub library to manage Hugging Face models and datasets.

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

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

### Example Neo4j Configuration

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/best_practice/mcp_for_cozespace_and_tools.md

Refer to this JSON file for an example of how to configure Neo4j connection details.

```json
{
    "neo4j_uri": "bolt://localhost:7687",
    "neo4j_user": "neo4j",
    "neo4j_password": "password"
}
```

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

### Install ModelScope

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/best_practice/network_workarounds.md

Install the ModelScope library with framework support to download models and datasets.

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

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

### Start MemOS Server

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/installation.md

Start the MemOS server API using uvicorn from the project root directory.

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

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

### Start Local Documentation Preview

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/contribution/writing_docs.md

Execute this command from the project root to start a local web server for previewing documentation. The server is typically accessible at http://127.0.0.1:3000.

```bash
pnpm dev
```

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

### Manual Dependency Installation

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/docs/troubleshooting.html

Run these commands if the plugin installation hangs during dependency compilation, particularly for `better-sqlite3`.

```bash
cd ~/.openclaw/extensions/memos-local-openclaw-plugin
npm install --omit=dev
npm rebuild better-sqlite3
```

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

### Install MemOS Local Plugin

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/website/docs/troubleshooting.html

Installs the MemOS Local Plugin using a script from GitHub. It's recommended to run this command to get the latest version and ensure proper setup.

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

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

### Start OpenClaw Gateway

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/README.md

Commands to stop, install, and start the OpenClaw gateway. Ensure the LaunchAgent is installed on macOS.

```bash
openclaw gateway stop    # if already running
openclaw gateway install # ensure LaunchAgent is installed (macOS)
openclaw gateway start
```

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

### Start Development Server

Source: https://github.com/memtensor/memos/blob/main/apps/openwork-memos-integration/docs/plans/2026-01-17-safe-file-deletion-impl.md

Launch the development server to manually test the implemented features. This allows for interactive verification of UI changes and functionality.

```bash
pnpm dev
```

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

### Install Memos Project

Source: https://github.com/memtensor/memos/blob/main/AGENTS.md

Installs the Memos project dependencies and development tools. This command is a shortcut for a more detailed poetry installation and hook setup.

```bash
make install
```

```bash
poetry install --extras all --with dev --with test
```

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

### Start Docker Service

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/installation.md

Commands to start the Docker service and check its status. Ensure Docker is installed before proceeding.

```bash
# Command line start
sudo systemctl start docker

# After installation, check docker status
docker ps

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

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

### Capture Post-installation Logs

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/docs/troubleshooting.html

Navigate to the plugin directory and run the post-installation script, capturing its output to a debug log.

```bash
cd ~/.openclaw/extensions/memos-local-openclaw-plugin
node scripts/postinstall.cjs 2>&1 | tee /tmp/postinstall-debug.log
```

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

### Start Server API

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/best_practice/mcp_for_cozespace_and_tools.md

Initiate the Server API from the MemOS directory. The API defaults to port 8001 and exposes `/product/*` endpoints.

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

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

### Complete MOS Initialization and Usage

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/mos/users_configurations.md

Demonstrates loading configuration, initializing the MOS system, registering a user and memory cube, and performing a chat operation.

```python
from memos.configs.mem_os import MOSConfig
from memos.mem_os.main import MOS

# Load configuration
mos_config = MOSConfig.from_json_file("examples/data/config/simple_memos_config.json")

# Initialize MOS
mos = MOS(mos_config)

# Create user and register cube
user_id = "user_123"
mos.create_user(user_id=user_id)
mos.register_mem_cube("path/to/mem_cube", user_id=user_id)

# Use MOS
response = mos.chat("Hello, how are you?", user_id=user_id)
```

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

### Start Docker Service

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/contribution/setting_up.md

Command to start the Docker service using systemctl. Ensure Docker is installed before running this command.

```bash
# Start docker via command line
sudo systemctl start docker
```

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

### Install Poetry

Source: https://github.com/memtensor/memos/blob/main/CONTRIBUTING.md

Installs Poetry, a dependency management tool for Python projects. Run this command to get Poetry on your system.

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

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

### Initialize Environment and Register Custom Logic

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/mem_scheduler.md

Sets up the environment by adding the project root to sys.path and configuring necessary environment variables. It then imports core components and registers custom handlers for query and memory update tasks.

```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}")

        # Initiate chat request
        chat_req = ChatPlaygroundRequest(
            user_id=user_id,
            query=query,
            readable_cube_ids=[mem_cube_id],
            writable_cube_ids=[mem_cube_id],
        )

        # Get streaming response
        response = chat_stream_playground(chat_req)

```

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

### Start FastAPI Server with Uvicorn (Product API)

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/rest_api_server.md

Starts the FastAPI server using uvicorn, specifically for the product API. This command should be run from the project's root directory.

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

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

### Start a Browser Instance

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/skill/browserwing-admin/SKILL.md

Initiate a specific browser instance using its ID.

```bash
curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/start'
```

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

### Start OpenClaw Gateway

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/README.md

Stops any existing OpenClaw gateway and then starts it with the newly installed plugin. This ensures the gateway is running with the latest configuration.

```bash
openclaw gateway stop    # stop existing
openclaw gateway start   # start with new plugin
```

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

### Basic MemOS Usage Example

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/mos/memos_neo.md

Demonstrates how to initialize MemOS, add memories, and query the system using the `chat` method. Ensure environment variables are set correctly.

```python
#!/usr/bin/env python3
import os
from memos.mem_os.main import MOS

# Set environment variables
os.environ["OPENAI_API_KEY"] = "sk-your-api-key"
os.environ["MOS_TEXT_MEM_TYPE"] = "general_text"

# Create memory system
memory = MOS.simple()

# Add memories
memory.add("My favorite color is blue")
memory.add("I work as a software engineer")
memory.add("I live in San Francisco")

# Chat with memory context
response = memory.chat("What is user favorite color?")
print(response)  # "favorite color is blue!"

response = memory.chat("Tell me about user job and location")
print(response)  # Uses stored memories to respond
```

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

### MemOS Onboarding and Setup Wording

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/site/public/SKILL.md

Use this plain product language when presenting onboarding or setup instructions for MemOS. Emphasize local and private data storage, and mention backup and search configuration options.

```text
MemOS stores all your memories locally on this machine.
No data is sent to the cloud. No API keys are needed to get started.

Every conversation is automatically captured, organized into tasks,
and distilled into reusable skills — all happening locally.

The Memory Viewer at http://127.0.0.1:18799 lets you browse, search,
and manage everything your agent has learned.

For better search quality, you can optionally configure an embedding provider
like OpenAI, Gemini, or any OpenAI-compatible API. But the local offline
model works well enough to start.

Backup is simple: just copy ~/.openclaw/memos-local/memos.db
This single file contains all your memories, tasks, and skills.
```

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

### Full Code Example: TreeTextualMemory Operations

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/memories/tree_textual_memory.md

An end-to-end example demonstrating setup, memory extraction from chat and documents, searching, and persistence operations for TreeTextualMemory.

```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()
```

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

### Complete PreferenceTextMemory Workflow Example

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/modules/memories/preference_textual_memory.md

An end-to-end example demonstrating the complete workflow: configuration, initialization, memory extraction, addition, search, and persistence of preference memories.

```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")
```

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

### Check if Bundled Skill is Installed

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/site/public/SKILL.md

Verifies the presence of the 'memos-memory-guide' skill by checking common installation paths. A missing skill may require re-installation or setup.

```javascript
node -e "
const fs = require('fs');
const path = require('path');
const home = require('os').homedir();
const p1 = path.join(home, '.openclaw', 'workspace', 'skills', 'memos-memory-guide', 'SKILL.md');
const p2 = path.join(home, '.openclaw', 'skills', 'memos-memory-guide', 'SKILL.md');
if (fs.existsSync(p1)) { console.log('SKILL_OK'); }
else if (fs.existsSync(p2)) { console.log('SKILL_OK (alt path)'); }
else { console.log('SKILL_MISSING'); }
"
```

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

### Start Server API

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/best_practice/mcp_for_cozespace_and_tools.md

Navigate to the MemOS directory and start the Server API on port 8001. Verify it's running by checking the API documentation page.

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

```bash
curl http://localhost:8001/docs
```

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

### Example Hub Configuration

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/HUB-SHARING-GUIDE.md

Example configuration for setting up a team server (hub) with a team name and token. The port is auto-derived unless explicitly set.

```jsonc
{
  "plugins": {
    "entries": {
      "memos-local-openclaw-plugin": {
        "enabled": true,
        "config": {
          "sharing": {
            "enabled": true,
            "role": "hub",
            "hub": {
              "teamName": "My Team",
              "teamToken": "${MEMOS_TEAM_TOKEN}" 
              // port is auto-derived from gateway port; set explicitly only if needed
            }
          }
        }
      }
    }
  }
}
```

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

### Get a Specific Prompt

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/skill/browserwing-admin/SKILL.md

Fetch the content of a particular system prompt using its ID. Examples include `system-extractor`, `system-formfiller`, and `system-aiagent`.

```bash
curl -X GET 'http://localhost:8080/api/v1/prompts/<prompt-id>'
```

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

### Initialize Session Manager and Create Session/Episode

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/session/README.md

Demonstrates the initialization of the session manager with repository adapters and an intent classifier. It then shows how to open a new session and start a new episode with an initial user message.

```typescript
import { createSessionManager, createIntentClassifier,
         adaptSessionsRepo, adaptEpisodesRepo } from "@memos/core";

const intent = createIntentClassifier({ llm, timeoutMs: 5000 });
const sm = createSessionManager({
  sessionsRepo: adaptSessionsRepo(sqliteSessions),
  episodesRepo: adaptEpisodesRepo(sqliteEpisodes),
  intentClassifier: intent,
  idleCutoffMs: 24 * 60 * 60 * 1000,
});

const session = sm.openSession({ agent: "openclaw", meta: { hostPid: 1234 } });
const episode = await sm.startEpisode({ sessionId: session.id, userMessage: "fix the flaky test" });

sm.addTurn(episode.id, { role: "assistant", content: "Sure. Reading the log…" });
sm.addTurn(episode.id, { role: "tool", content: "<log output>", meta: { tool: "read_file" } });
sm.addTurn(episode.id, { role: "assistant", content: "Done. Patched `mutex_lock`." });

sm.finalizeEpisode(episode.id); // rTask scored later (Phase 7)
```

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

### Out-of-process Bridge Command

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/adapters/README.md

Example command to start the Node.js bridge process for an out-of-process adapter. It specifies the agent type for the bridge to handle.

```bash
node --experimental-strip-types bridge.cts --agent=hermes
```

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

### Build and Start Service with Docker Compose

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/contribution/setting_up.md

Build and start the specified service (neo4j in this case) using Docker Compose. This command should be executed from within the 'docker' directory.

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

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

### Configure Poetry PATH Environment Variable

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/rest_api_server.md

Guides through adding Poetry's bin directory to the system's PATH environment variable for zsh or bash shells. Includes steps to verify the installation.

```bash
# To start using, you need to find Poetry's bin directory in "PATH" (/Users/jinyunyuan/.local/bin) environment variable
# Modern macOS systems default Shell is zsh. You can confirm via following command
# 1. Determine which Shell you are using

echo $SHELL
# If output is /bin/zsh or /usr/bin/env zsh, then you are zsh.
# (If your system version is older, might still be using bash, output will be /bin/bash)
# 2. Open corresponding Shell config file
# If using zsh (vast majority of cases):
# Use nano editor (recommended for beginners)
nano ~/.zshrc

# Or use vim editor
# vim ~/.zshrc
# If using bash:
nano ~/.bash_profile
# Or
nano ~/.bashrc

# 3. Add PATH environment variable

# At the very end of opened file, start a new line, paste installation prompt command:
export PATH="/you-path/.local/bin:$PATH"

# 4. Save and exit editor

# If using nano:
# Press Ctrl + O to write (save), press Enter to confirm filename.
# Then press Ctrl + X to exit editor.

# If using vim:
# Press i to enter insert mode, paste code, then press ESC key to exit insert mode.
# Input :wq, then press Enter to save and exit.

# 5. Make configuration take effect immediately
# Newly modified config file won't automatically take effect in currently open terminal window, you need to run one of the following commands to reload it:

# For zsh:
source ~/.zshrc

# For bash:
source ~/.bash_profile

# 6. Verify if installation is successful
# Now, you can execute test command in prompt to check if everything is ready:
poetry --version
# Success will show version number Poetry (version 2.2.0)
```

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

### Install/Upgrade Memos Local OpenCLAW (macOS/Linux)

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-openclaw/www/index.html

Use this command to automatically install all dependencies, build tools, and upgrade to the latest version on macOS and Linux systems. It's a single-line command for a quick setup.

```bash
$ curl -fsSL https://cdn.memtensor.com.cn/memos-local-openclaw/install.sh | bash
```

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

### Install Dependencies with Aliyun Source

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/rest_api_server.md

Installs project dependencies using pip, leveraging the Aliyun mirror for faster downloads. Ensure pip is up-to-date.

```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/
```

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

### Skill Formal Definition

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/core/skill/README.md

Defines the structure of a Skill, including its name, invocation guide, procedure, parameters, examples, reliability score (eta), trial counts, source policies, and status. The reliability score drives retrieval and lifecycle transitions, while status determines visibility.

```plaintext
Skill = (name, invocationGuide, procedure, parameters, examples,
         η, trialsAttempted, trialsPassed, sourcePolicyIds, status)
```

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

### Simple MCP Client Implementation

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/best_practice/mcp_for_cozespace_and_tools.md

An example Python script demonstrating how to connect to and interact with an MCP service.

```python
import requests
import json


def call_mcp_server(url, headers, payload):
    response = requests.post(url, headers=headers, data=payload)
    return json.loads(response.text)


if __name__ == "__main__":
    # Example usage:
    # url = "http://localhost:8001/product/add"
    # headers = {"Content-Type": "application/json"}
    # payload = json.dumps({"memory_content": "test", "mem_cube_id": "test_cube"})
    # result = call_mcp_server(url, headers, payload)
    # print(result)
    pass

```

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

### Verify MemOS Installation

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/installation.md

After installation, verify that MemOS has been installed correctly by checking its version.

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

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

### Install Local Plugin

Source: https://github.com/memtensor/memos/blob/main/docs/en/openclaw/plugin_compare.md

Installs the Memos local plugin using a curl script. This command handles both initial installation and upgrades, auto-detecting necessary agent installations.

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

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

### Dockerfile for Simplified Package

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/rest_api_server.md

Example Dockerfile using a simplified base image for faster local deployment. It sets up the working directory, environment variables, copies source code, exposes the port, and defines the command to run the server.

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

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

### Set Up Task Workspace

Source: https://github.com/memtensor/memos/blob/main/apps/memos-local-plugin/docs/SKILLFLOW_HERMES_EVAL.md

Prepares a clean workspace for each task by removing any existing content and copying the instruction file and environment configuration from the family directory.

```bash
TASK="fund-snapshot-canonical"
FAMILY_DIR="$PWD/.test_skillflow_official_family/SEC-13F-Financial-Analysis"
WORKSPACE="$RUN_DIR/workspaces/$TASK"
rm -rf "$WORKSPACE"
mkdir -p "$WORKSPACE"
cp "$FAMILY_DIR/$TASK/instruction.md" "$WORKSPACE/instruction.md"
cp -R "$FAMILY_DIR/$TASK/environment/." "$WORKSPACE/"
```

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

### Install Poetry Dependency Manager

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/contribution/setting_up.md

Install the Poetry dependency manager using the official installation script.

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

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

### Default .env Configuration Example

Source: https://github.com/memtensor/memos/blob/main/docs/en/open_source/getting_started/installation.md

Example .env file configuration for MemOS, including settings for OpenAI, Memory Reader, Embedder, Neo4j, and chat API. Ensure all required API keys and base URLs are correctly set.

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