MCP Server for MemOS API

A Model Context Protocol (MCP) implementation for the MemOS API service. This package provides a command-line interface to interact with MemOS API using MCP standards.

MCP Configuration

To use this package In MCP Client, use the following configuration: （You may need to install Node.js first）

{
  "mcpServers": {
    "memos-api-mcp": {
      "command": "npx",
      "args": ["-y", "github:shijieweb/memos-mcp-custom-trae#main"],
      "env": {
        "MEMOS_API_KEY": "your-api-key",
        "MEMOS_USER_ID": "your-user-id",
        "MEMOS_CHANNEL": "MODELSCOPE_REMOTE",
        "MEMOS_AGENT_ID": "your-agent-id"
      }
    }
  }
}

Configuration Explanation

• command: Uses npx to run the package

• args: Arguments passed to npx to run the package

• env: Environment variables

  • MEMOS_API_KEY: Your Memos API key for authentication (Get your API Key in Dashboard[https://memos-dashboard.openmem.net/cn/apikeys/])

  • MEMOS_USER_ID: Stable per-human identifier. MUST be deterministic and non-PII, and MUST remain the same for the same person across devices/sessions. NEVER reuse across different people. DO NOT use random values, device IDs, or model/chat session IDs. Recommended: SHA-256(lowercase(trim(email))) or your SSO subject/employee ID.

  • MEMOS_CHANNEL: The platform where this MCP is running. Default: MODELSCOPE_REMOTE.

  • MEMOS_AGENT_ID: (Optional) Agent ID to tag every memory write with. Used for tracking which Agent generated each memory on the cloud platform. If set, all add_message calls automatically include this agent_id. If not set, agent_id is omitted from writes.

Available MCP Tools

This package provides the following MCP tools:

1. add_message

   • Adds a new message to a conversation. Automatically called after every answer.

   • Parameters:

     • conversation_first_message: First user message in the thread (used to generate conversation_id).

     • agent_id: (Optional) Agent ID to associate this memory with. If MEMOS_AGENT_ID env var is set, this is auto-injected.

     • messages: Array of messages containing role and content information.

       • role: Role of the message sender (user or assistant).

       • content: Message content.

       • chat_time: (Optional) Message timestamp.

2. search_memory

   • Searches for memories in a conversation.

   • Parameters:

     • query: Text content to search within the memories. The token limit for a single query is 4k.

     • filter: (Optional) Filter conditions, used to precisely limit the memory scope before retrieval.

     • knowledgebase_ids: (Optional) Array specifying the knowledge bases to search.

       • DO NOT USE THIS unless the user explicitly mentions "knowledge base" or "KB".

       • 1. If the user explicitly asks to search ALL knowledge bases -> pass ["all"].

       • 2. If the user specifies particular KB IDs -> pass those IDs.

       • 3. If the user DOES NOT mention knowledge bases -> OMIT this parameter (do not send it).

     • include_preference: (Optional) Enable preference memory recall. Default: true.

     • preference_limit_number: (Optional) Max preference memories to return. Default: 9, max 25.

     • include_tool_memory: (Optional) Enable tool memory recall. Default: false.

     • tool_memory_limit_number: (Optional) Max tool memories to return. Default: 6, max 25.

     • include_skill: (Optional) Enable Skill recall. Default: false.

     • skill_limit_number: (Optional) Max Skills to return. Default: 6, max 25.

     • relativity: (Optional) Relevance threshold (0-1) for recalled memories. A value of 0 disables relevance filtering.

     • conversation_first_message: First user message in the thread (used to generate conversation_id).

     • memory_limit_number: Maximum number of memories that can be recalled. Default: 9, max 25.

3. add_feedback

   • Submit user feedback to the MemOS system.

   • Note: Feedback is applied asynchronously — add_feedback returns immediately (often with a task_id), and the effect may take a short time to appear.

   • Parameters:

     • user_id: The user identifier associated with the feedback.

     • conversation_id: Unique identifier of the conversation associated with the feedback.

     • feedback_content: The specific content of the feedback.

     • agent_id: (Optional) Agent ID associated with the feedback.

     • app_id: (Optional) App ID associated with the feedback.

     • feedback_time: (Optional) Feedback time string (default: current UTC time).

     • allow_public: (Optional) Whether to allow public access (default: false).

     • allow_knowledgebase_ids: (Optional) List of knowledge base IDs allowed to be written to.

4. get_user_profile

   • Get the user's full memory profile (facts, preferences, and tool trajectories).

   • Parameters:

     • include_preference: (Optional) Whether to include preference memories.

     • include_tool_memory: (Optional) Whether to include tool trajectory memories.

     • current: (Optional) Page number.

     • size: (Optional) Number of entries per page.

5. create_knowledge_base

   • Create a named knowledge base container.

   • Parameters:

     • knowledgebase_name: Name of the knowledge base.

     • knowledgebase_description: (Optional) Description of the knowledge base.

6. remove_knowledge_base

   • Remove a knowledge base association.

   • Parameters:

     • knowledgebase_id: Target knowledge base ID.

7. add_kb_document

   • Upload document(s) to a specified knowledge base.

   • Parameters:

     • knowledgebase_id: Target knowledge base ID.

     • file: Document list.

       • content: Local absolute path, public URL, or Base64 Data URI.

       • file_name: (Optional) File name.

       • mime_type: (Optional) MIME type. Required when content is a local file path.

8. get_kb_documents

   • Get document metadata in batches by file IDs.

   • Parameters:

     • file_ids: List of document IDs.

9. delete_kb_documents

   • Delete specified documents from the knowledge base by file IDs.

   • Parameters:

     • file_ids: List of document IDs.

All tools use the same configuration and require the MEMOS_API_KEY environment variable.

Related MCP server: yantrikdb-mcp

Features

• MCP-compliant API interface

• Command-line tool for easy interaction

• Built with TypeScript for type safety

• Express.js server implementation

• Zod schema validation

Prerequisites

• Node.js >= 18

• npm or pnpm (recommended)

Installation

You can install the package globally using npm:

npm install -g @memtensor/memos-api-mcp

Or using pnpm:

pnpm add -g @memtensor/memos-api-mcp

Usage

After installation, you can run the CLI tool using:

npx @memtensor/memos-api-mcp

Or if installed globally:

memos-api-mcp

Development

1. Clone the repository:

git clone <repository-url>
cd memos-api-mcp

2. Install dependencies:

pnpm install

3. Start development server:

pnpm dev

4. Build the project:

pnpm build

Available Scripts

• pnpm build - Build the project

• pnpm dev - Start development server using tsx

• pnpm start - Run the built version

• pnpm inspect - Inspect the MCP implementation using @modelcontextprotocol/inspector

Project Structure

memos-mcp/
├── src/           # Source code
├── build/         # Compiled JavaScript files
├── package.json   # Project configuration
└── tsconfig.json  # TypeScript configuration

Dependencies

• @modelcontextprotocol/sdk: ^1.0.0

• express: ^4.19.2

• zod: ^3.23.8

• ts-md5: ^2.0.0

Version

Current version: 1.1.0