Add Message

This API allows you to add one or more messages to a specific conversation. As illustrated in the examples bellow, you can add messages in real time during a user-assistant interaction, import historical messages in bulk, or enrich the conversation with user preferences and behavior data. All added messages are transformed into memories by MemOS, enabling their retrieval in future conversations to support chat history management, user behavior tracking, and personalized interactions.

POST

add

message

import os
import requests
import json

# Replace with your API Key
os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

data = {
    "user_id": "memos_user_123",
    "conversation_id": "0610",
    "messages": [
      {"role": "user", "content": "I’ve planned to travel to Guangzhou this summer. What chain hotels are available for accommodation?"},
      {"role": "assistant", "content": "You can consider options like 7 Days Inn, All Seasons, Hilton, etc."},
      {"role": "user", "content": "I’ll choose 7 Days Inn."},
      {"role": "assistant", "content": "Alright, feel free to ask me if you have any other questions."}
    ]
  }
headers = {
  "Content-Type": "application/json",
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}"
}
url = f"{os.environ['MEMOS_BASE_URL']}/add/message"

res = requests.post(url=url, headers=headers, data=json.dumps(data))

print(f"result: {res.json()}")

# Please ensure that MemOS has been installed (pip install MemoryOS -U)
from memos.api.client import MemOSClient

# Initialize MemOS client with API Key to start sending requests
client = MemOSClient(api_key="YOUR_API_KEY")

messages = [
  {"role": "user", "content": "I’ve planned to travel to Guangzhou this summer. What chain hotels are available for accommodation?"},
  {"role": "assistant", "content": "You can consider options like 7 Days Inn, All Seasons, Hilton, etc."},
  {"role": "user", "content": "I’ll choose 7 Days Inn."},
  {"role": "assistant", "content": "Alright, feel free to ask me if you have any other questions."}
]
user_id = "memos_user_123"
conversation_id = "0610"

res = client.add_message(messages=messages, user_id=user_id, conversation_id=conversation_id)

print(f"result: {res}")

curl --request POST \
  --url https://memos.memtensor.cn/api/openmem/v1/add/message \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "memos_user_123",
    "conversation_id": "0610",
    "messages": [
      {"role": "user", "content": "I’ve planned to travel to Guangzhou this summer. What chain hotels are available for accommodation?"},
      {"role": "assistant", "content": "You can consider options like 7 Days Inn, All Seasons, Hilton, etc."},
      {"role": "user", "content": "I’ll choose 7 Days Inn."},
      {"role": "assistant", "content": "Alright, feel free to ask me if you have any other questions."}
    ]
  }'

{
  "code": 0,
  "data": {
    "success": true
  },
  "message": "ok"
}

Authorizations

Authorization

string

header

required

Token API_key, available in API Console > API Keys

Body

application/json

user_id

string

required

Unique identifier of the user associated with the message.

conversation_id

string

required

Unique identifier of the conversation.

messages

MessageInput·object[]

required

Array of message objects representing the memory content. Each object contains:

Show child attributes

Response

application/json

Successful Response

code

number

required

API status code. See Error Code for details

Example: 0

data

object

Object representing the result of adding the message.

Show child attributes

message

string

required

API response message, e.g., "Message added successfully".

Example: "ok"

Examples

Real-Time Conversation Sync

Use the API to append messages in real time whenever the user receives a model response. This ensures conversations between the user and the assistant are always in sync with MemOS. MemOS continuously updates the user’s memory in the backend as new messages are added.

import os
import json
import requests

# Set your API key and base URL
os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

headers = {
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}",
  "Content-Type": "application/json"
}
BASE_URL = os.environ['MEMOS_BASE_URL']

def add_message(user_id, conversation_id, role, content):
    data = {
        "user_id": user_id,
        "conversation_id": conversation_id,
        "messages": [{"role": role, "content": content}]
    }
    
    res = requests.post(f"{BASE_URL}/add/message", headers=headers, data=json.dumps(data))
    result = res.json()
  
    if result.get('code') == 0: 
      print(f"✅ Message added successfully")
    else:
      print(f"❌ Failed to add message: {result.get('message')}")

# === Example ===

# User sends a message
add_message("memos_user_123", "memos_conversation_123", "user","""I ran 5 kilometers this morning and my knees feel a bit sore.""")

# Assistant replies
add_message("memos_assistant_123", "memos_conversation_123", "assistant","""You ran 5 kilometers this morning and your knees feel sore. That means your joints and muscles are still adjusting to the intensity. Tomorrow, try keeping the distance to around 3 kilometers and focus on proper warm-up and cool-down. This will help you stay consistent while giving your knees time to recover.""")

Importing Historical Conversations

If your application already has existing chat logs, you can bulk import them into MemOS. This allows the assistant to access past context immediately and deliver more personalized, consistent responses.

🍬 Tip: The chat_time field accepts both structured timestamps and plain Chinese text. MemOS uses this field to improve memory retrieval accuracy.

import os
import json
import requests

# Set your API key and base URL
os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

headers = {
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}",
  "Content-Type": "application/json"
}
BASE_URL = os.environ['MEMOS_BASE_URL']

# Example: historical conversation data
history_messages = [
    # Day 1 - User and assistant conversation
    {"role": "user", "content": "I like spicy food.", "chat_time": "2025-09-12 08:00:00"},
    {"role": "assistant", "content": "Got it — I’ll remember that you like spicy food.", "chat_time": "2025-09-12 08:01:00"},

    # A few days later - New conversation
    {"role": "user", "content": "But I don’t really like heavy or oily dishes, like hotpot or spicy beef soup.", "chat_time": "2025-09-25 12:00:00"},
    {"role": "assistant", "content": "So you prefer light but spicy dishes. I can recommend some that might suit your taste!", "chat_time": "2025-09-25 12:01:00"}
]

def add_message(user_id, conversation_id, messages):
    data = {
        "user_id": user_id,
        "conversation_id": conversation_id,
        "messages": messages
    }
    res = requests.post(f"{BASE_URL}/add/message", headers=headers, data=json.dumps(data))
    result = res.json()
  
    if result.get('code') == 0:
        print("✅ Message added successfully")
    else:
        print(f"❌ Failed to add message: {result.get('message')}")

# === Example ===

# Import historical conversation
add_message("memos_user_345", "memos_conversation_345", history_messages)

Storing User Preferences and Behaviors

In addition to conversation data, you can import user preferences and behavioral information—such as interest surveys collected during onboarding—into MemOS as part of the user’s memory.

🍬 Tip: The content field must be a string. Both single-line and multi-line text are supported and will be correctly parsed by the system.

import os
import json
import requests

# Set your API key and base URL
os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

headers = {
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}",
  "Content-Type": "application/json"
}
BASE_URL = os.environ['MEMOS_BASE_URL']

# Example: user profile and interest data
user_profile_info = [
    {
        "role": "user",
        "content": """
Favorite movie genres: Sci-fi, Action, Comedy
Favorite TV genres: Mystery, Historical dramas
Favorite book genres: Popular science, Technology, Personal growth
Preferred learning formats: Articles, Videos, Podcasts
Exercise habits: Running, Fitness
Dietary preferences: Spicy food, Healthy eating
Travel interests: Nature, Urban culture, Adventure
Preferred conversation style: Humorous, Warm, Casual
Types of support I want from AI: Suggestions, Information lookup, Inspiration
Topics I’m most interested in: Artificial intelligence, Future tech, Film reviews
I’d like AI to help me with: Daily study planning, Movie and book recommendations, Emotional companionship
        """
    }
]

def add_message(user_id, conversation_id, messages):
    data = {
        "user_id": user_id,
        "conversation_id": conversation_id,
        "messages": messages
    }
  
    res = requests.post(f"{BASE_URL}/add/message", headers=headers, data=json.dumps(data))
    result = res.json()
  
    if result.get('code') == 0:
        print("✅ Message added successfully")
    else:
        print(f"❌ Failed to add message: {result.get('message')}")

# === Usage Example ===

# Import user interest and preference data
add_message("memos_user_567", "memos_conversation_id_567", user_profile_info)

Get Message

This API retrieves the historical conversation records between a user and the assistant for a specified session, with the option to limit the number of results. As shown in the examples bellow, you can use the returned recent messages as references for the model when generating responses, maintaining dialogue coherence and contextual understanding. It can also be used to restore chat context when a user refreshes or reopens the app, ensuring a seamless user experience and supporting personalized interactions.

import os
import requests
import json

# Replace with your API Key
os.environ["MEMOS_API_KEY"] = "YOUR_API_KEY"
os.environ["MEMOS_BASE_URL"] = "https://memos.memtensor.cn/api/openmem/v1"

data = {
    "user_id": "memos_user_123",
    "conversation_id": "0610",
    "messages": [
      {"role": "user", "content": "I’ve planned to travel to Guangzhou this summer. What chain hotels are available for accommodation?"},
      {"role": "assistant", "content": "You can consider options like 7 Days Inn, All Seasons, Hilton, etc."},
      {"role": "user", "content": "I’ll choose 7 Days Inn."},
      {"role": "assistant", "content": "Alright, feel free to ask me if you have any other questions."}
    ]
  }
headers = {
  "Content-Type": "application/json",
  "Authorization": f"Token {os.environ['MEMOS_API_KEY']}"
}
url = f"{os.environ['MEMOS_BASE_URL']}/add/message"

res = requests.post(url=url, headers=headers, data=json.dumps(data))

print(f"result: {res.json()}")

# Please ensure that MemOS has been installed (pip install MemoryOS -U)
from memos.api.client import MemOSClient

# Initialize MemOS client with API Key to start sending requests
client = MemOSClient(api_key="YOUR_API_KEY")

messages = [
  {"role": "user", "content": "I’ve planned to travel to Guangzhou this summer. What chain hotels are available for accommodation?"},
  {"role": "assistant", "content": "You can consider options like 7 Days Inn, All Seasons, Hilton, etc."},
  {"role": "user", "content": "I’ll choose 7 Days Inn."},
  {"role": "assistant", "content": "Alright, feel free to ask me if you have any other questions."}
]
user_id = "memos_user_123"
conversation_id = "0610"

res = client.add_message(messages=messages, user_id=user_id, conversation_id=conversation_id)

print(f"result: {res}")

curl --request POST \
  --url https://memos.memtensor.cn/api/openmem/v1/add/message \
  --header 'Authorization: Token YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "user_id": "memos_user_123",
    "conversation_id": "0610",
    "messages": [
      {"role": "user", "content": "I’ve planned to travel to Guangzhou this summer. What chain hotels are available for accommodation?"},
      {"role": "assistant", "content": "You can consider options like 7 Days Inn, All Seasons, Hilton, etc."},
      {"role": "user", "content": "I’ll choose 7 Days Inn."},
      {"role": "assistant", "content": "Alright, feel free to ask me if you have any other questions."}
    ]
  }'

{
  "code": 0,
  "data": {
    "success": true
  },
  "message": "ok"
}