Tool Calling

Add tool calling information, integrating tool calling decisions, execution results, and usage trajectories into MemOS memory.

Note

You must first pass tool memory when calling addMessage (Click here for detailed API documentation)
Only then can you search for tool memory when calling searchMemory (Click here for detailed API documentation)

This article focuses on functional description. For detailed API fields and limits, please click the text links above.

1. When to Use

This message structure is suitable when your Agent needs to obtain external information through tools (function / tool), and you want these "tool calling contexts and results" to be understood, associated, and precipitated as retrievable memories by MemOS.

2. How it Works

Step 1: Add Tool Calling Information

assistant message: tool_calls describes the model's decision to call a tool and its parameters.

tool message: Carries the actual tool execution result and precisely associates with the corresponding tool_calls via tool_call_id.

Step 2: MemOS Processes Tool-Related Memory

Tool Schema: MemOS supports structured management and dynamic updates of tool information, unifying the description of different tools. This enables the model to efficiently retrieve, understand, and discover tools without hardcoding tool details in prompts.
Tool Trajectory Memory: MemOS extracts and stores key trajectories during tool usage, including "what tool was called in what context, what parameters were used, and what result was returned". These trajectories can be retrieved and reused in subsequent conversations, helping the model reproduce tool usage patterns more stably and reducing repetitive trial-and-error and calling errors.

3. Usage Example

For a complete list of API fields, formats, etc., please refer to the Add Message API Documentation to see how to add tool calling information.

Add Tool Calling Information

Session A: User asks How is the weather in Beijing in the conversation. The assistant calls the Weather Tool. The weather tool returns the result Beijing, Temperature 7°C, Cloudy.

import os
import requests
import json

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

# Message sequence with tool_call
tool_schema = [{
    "name": "get_weather",
    "description": "Get current weather information for a given location",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "City name, e.g. Beijing"
            }
        },
        "required": [
            "location"
        ]
    }
}]

data = {
    "user_id": "memos_user_123",
    "conversation_id": "demo-conv-id",
    "messages": [
        {
            "role": "system",
            "content": f"""You are an assistant that can call tools.
When a user's request can be fulfilled by a tool, you MUST call the appropriate tool.
<tool_schema>
{json.dumps(tool_schema, indent=2, ensure_ascii=False)}
</tool_schema>
"""
        },
        {"role": "user", "content": "What's the weather like in Beijing right now?"},
        {
            "role": "assistant",
            "tool_calls": [
                {
                    "id": "call_123",
                    "type": "function",
                    "function": {
                        "name": "get_weather",
                        "arguments": json.dumps({"location": "Beijing"}),
                    },
                }
            ],
        },
        {
            "role": "tool",
            "tool_call_id": "call_123",
            "content": [
                {
                    "type": "text",
                    "text": json.dumps(
                        {"location": "Beijing", "temperature": "7°C", "condition": "Cloudy"}
                    ),
                }
            ],
        },
    ],
}

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(json.dumps(res.json(), indent=2, ensure_ascii=False))

Retrieve Tool Memory

Session B: In a new session, the user asks What clothes are suitable for Beijing. MemOS can recall relevant tool memories from past Weather Tool Calls. The model can use tool memories in the future to improve the accuracy and effectiveness of tool usage.

import os
import requests
import json

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": "0928",
    "query": "What clothes are suitable for Beijing",
    "memory_limit_number": 10,
    "include_preference": True,
    "preference_limit_number": 10,
    "include_tool_memory":True,
    "tool_memory_limit_number":10,
}

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

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

print(json.dumps(res.json(), indent=2, ensure_ascii=False))

Output Result

"tool_memory_detail_list": [
   {
    "id": "7ec50fd8-19ec-42a2-a7c7-ce3cebdb70cf",
    "tool_type": "ToolSchemaMemory",
    "tool_value": {"name": "get_weather", "description": "Get current weather information for a given location", "parameters": {"type": "object", "properties": {"location": {"type": "string", "description": "City name, e.g. Beijing"}}, "required": ["location"]}},
    "create_time": 1766494806624,
    "conversation_id": "demo-conv-id",
    "status": "activated",
    "update_time": 1766494806625,
    "relativity": 0.44700349055540967
  },
  {
    "id": "56215e5d-6827-429d-a862-068ea5935e8e",
    "tool_type": "ToolTrajectoryMemory",
    "tool_value": "The user asked about the current weather in Beijing. The assistant attempted to call a weather retrieval tool named 'get_weather' with the argument specifying the location as Beijing. The tool successfully executed and returned the weather information indicating a temperature of 7°C and a cloudy condition. The assistant did not provide a final answer in this instance.",
    "tool_used_status": [
      {
        "used_tool": "get_weather",
        "error_type": "",
        "experience": "This tool is commonly used to retrieve weather information based on location parameters. It typically returns temperature and weather conditions in a structured format, allowing for straightforward interpretation.",
        "success_rate": 1.0
      }
    ],
    "create_time": 1765793446220,
    "conversation_id": "demo-conv-id",
    "status": "activated",
    "update_time": 1765793446221,
    "relativity": 5.027827501180582e-05
  }
]

Knowledge Base

Create a knowledge base associated with the project, and combine user memory with knowledge base to supplement knowledge when retrieving memories.