MemOS

MemOS (Sistema Operacional de Memória) é um sistema operacional de gerenciamento de memória projetado para aplicações de IA.

GitHub
7

Documentação

Servidor MCP para a API MemOS

Uma implementação do Model Context Protocol (MCP) para o serviço de API do MemOS. Este pacote fornece uma interface de linha de comando para interagir com a API MemOS usando os padrões MCP.

Configuração do MCP

Para usar este pacote no Cliente MCP, use a seguinte configuração: （Talvez seja necessário instalar o Node.js primeiro）

{
  "mcpServers": {
    "memos-api-mcp": {
      "command": "npx",
      "args": ["-y", "@memtensor/memos-api-mcp"],
      "env": {
        "MEMOS_API_KEY": "your-api-key",
        "MEMOS_USER_ID": "your-user-id",
        "MEMOS_CHANNEL": "the-site-where-you-are-seeing-this-document"
      }
    }
  }
}

Explicação da Configuração

  • command: Usa npx para executar o pacote
  • args: Argumentos passados para o npx para executar o pacote
  • env: Variáveis de ambiente
    • MEMOS_API_KEY: Sua chave de API do Memos para autenticação (Obtenha sua chave de API no Dashboard[https://memos-dashboard.openmem.net/cn/apikeys/])
    • MEMOS_USER_ID: Identificador estável por pessoa. DEVE ser determinístico e não conter PII, e DEVE permanecer o mesmo para a mesma pessoa em diferentes dispositivos/sessões. NUNCA reutilize entre pessoas diferentes. NÃO use valores aleatórios, IDs de dispositivo ou IDs de sessão de modelo/chat. Recomendado: SHA-256(lowercase(trim(email))) ou seu subject/ID de funcionário do SSO.
    • MEMOS_CHANNEL: O site onde você está vendo este documento. Valores candidatos: MODELSCOPE, MCPSO, MCPMARKETCN, MCPMARKETCOM, GLAMA, PULSEMCP, MCPSERVERS,LOBEHUB,MEMOS(significando o site oficial do MemOS), GITHUB(significando este arquivo README)

Ferramentas MCP Disponíveis

Este pacote fornece as seguintes ferramentas MCP:

  1. add_message

    • Adiciona uma nova mensagem a uma conversa
    • Parâmetros:
      • conversation_id: Identificador único da conversa associada ao feedback.
      • messages: Matriz de mensagens contendo informações de função e conteúdo.
        • role: Função do remetente da mensagem (user ou assistant).
        • content: Conteúdo da mensagem.
        • chat_time: (Opcional) Carimbo de data/hora da mensagem.

  2. search_memory

    • Busca memórias em uma conversa.
    • Parâmetros:
      • query: Conteúdo de texto para buscar nas memórias. O limite de tokens para uma única consulta é de 4k.
      • filter: (Opcional) Condições de filtro, usadas para limitar com precisão o escopo da memória antes da recuperação.
      • knowledgebase_ids: (Opcional) Matriz especificando as bases de conhecimento a serem pesquisadas.
        • NÃO USE ISSO a menos que o usuário mencione explicitamente "knowledge base" ou "KB".
          1. Se o usuário pedir explicitamente para pesquisar TODAS as bases de conhecimento -> passe ["all"].
          1. Se o usuário especificar IDs de KB específicos -> passe esses IDs.
          1. Se o usuário NÃO mencionar bases de conhecimento -> OMITA este parâmetro (não o envie).
      • include_preference: (Opcional) Ativar recuperação de memória de preferências. Padrão: true.
      • preference_limit_number: (Opcional) Máximo de memórias de preferência a retornar. Padrão: 9, máximo 25.
      • include_tool_memory: (Opcional) Ativar recuperação de memória de ferramentas. Padrão: false.
      • tool_memory_limit_number: (Opcional) Máximo de memórias de ferramentas a retornar. Padrão: 6, máximo 25.
      • include_skill: (Opcional) Ativar recuperação de Skills. Padrão: false.
      • skill_limit_number: (Opcional) Máximo de Skills a retornar. Padrão: 6, máximo 25.
      • relativity: (Opcional) Limiar de relevância (0-1) para memórias recuperadas. Um valor de 0 desativa a filtragem por relevância.
      • conversation_first_message: Primeira mensagem do usuário no tópico (usada para gerar conversation_id).
      • memory_limit_number: Número máximo de memórias que podem ser recuperadas. Padrão: 9, máximo 25.

  3. delete_memory

    • Exclui memórias específicas pelos seus IDs.
    • Parâmetros:
      • user_ids: Lista de IDs de usuários cujas memórias serão excluídas.
      • memory_ids: Lista de IDs de memórias a excluir.

  4. add_feedback

    • Envia feedback do usuário para o sistema MemOS.
    • Nota: O feedback é aplicado de forma assíncrona — add_feedback retorna imediatamente (frequentemente com um task_id), e o efeito pode levar um curto período para aparecer.
    • Parâmetros:
      • user_id: O identificador do usuário associado ao feedback.
      • conversation_id: Identificador único da conversa associada ao feedback.
      • feedback_content: O conteúdo específico do feedback.
      • agent_id: (Opcional) ID do agente associado ao feedback.
      • app_id: (Opcional) ID do aplicativo associado ao feedback.
      • feedback_time: (Opcional) String de horário do feedback (padrão: horário UTC atual).
      • allow_public: (Opcional) Se deve permitir acesso público (padrão: false).
      • allow_knowledgebase_ids: (Opcional) Lista de IDs de bases de conhecimento permitidos para escrita.

  5. get_user_profile

    • Obtém o perfil completo de memória do usuário (fatos, preferências e trajetórias de ferramentas).
    • Parâmetros:
      • include_preference: (Opcional) Se deve incluir memórias de preferências.
      • include_tool_memory: (Opcional) Se deve incluir memórias de trajetória de ferramentas.
      • current: (Opcional) Número da página.
      • size: (Opcional) Número de entradas por página.

  6. create_knowledge_base

    • Cria um contêiner de base de conhecimento nomeado.
    • Parâmetros:
      • knowledgebase_name: Nome da base de conhecimento.
      • knowledgebase_description: (Opcional) Descrição da base de conhecimento.

  7. remove_knowledge_base

    • Remove uma associação de base de conhecimento.
    • Parâmetros:
      • knowledgebase_id: ID da base de conhecimento de destino.

  8. add_kb_document

    • Envia documento(s) para uma base de conhecimento especificada.
    • Parâmetros:
      • knowledgebase_id: ID da base de conhecimento de destino.
      • file: Lista de documentos.
        • content: Caminho absoluto local, URL pública ou URI de dados Base64.
        • file_name: (Opcional) Nome do arquivo.
        • mime_type: (Opcional) Tipo MIME. Obrigatório quando content é um caminho de arquivo local.

  9. get_kb_documents

    • Obtém metadados de documentos em lotes por IDs de arquivo.
    • Parâmetros:
      • file_ids: Lista de IDs de documentos.

  10. delete_kb_documents

  • Exclui documentos especificados da base de conhecimento por IDs de arquivo.
  • Parâmetros:
    • file_ids: Lista de IDs de documentos.

Todas as ferramentas usam a mesma configuração e exigem a variável de ambiente MEMOS_API_KEY.

Recursos

  • Interface de API compatível com MCP
  • Ferramenta de linha de comando para interação fácil
  • Construído com TypeScript para segurança de tipos
  • Implementação de servidor Express.js
  • Validação de esquema Zod

Pré-requisitos

  • Node.js >= 18
  • npm ou pnpm (recomendado)

Instalação

Você pode instalar o pacote globalmente usando npm:

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

Ou usando pnpm:

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

Uso

Após a instalação, você pode executar a ferramenta CLI usando:

npx @memtensor/memos-api-mcp

Ou, se instalado globalmente:

memos-api-mcp

Desenvolvimento

  1. Clone o repositório:
git clone <repository-url>
cd memos-api-mcp
  1. Instale as dependências:
pnpm install
  1. Inicie o servidor de desenvolvimento:
pnpm dev
  1. Compile o projeto:
pnpm build

Scripts Disponíveis

  • pnpm build - Compila o projeto
  • pnpm dev - Inicia o servidor de desenvolvimento usando tsx
  • pnpm start - Executa a versão compilada
  • pnpm inspect - Inspeciona a implementação MCP usando @modelcontextprotocol/inspector

Estrutura do Projeto

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

Dependências

  • @modelcontextprotocol/sdk: ^1.0.0
  • express: ^4.19.2
  • zod: ^3.23.8
  • ts-md5: ^2.0.0

Versão

Versão atual: 1.1.0