Clone or download

Roboy Dialog System

Documentation Status

What is this Project

Roboy says hi!

This repository contains a dialog system developed for the humanoid robot Roboy. One can find more information about this project through its documentation.

Installation Guide


  • Apache Maven
  • Java 8 (Oracle is preferred)
  • ruby (1.8.7 or 1.9 advised)
  • git
  • Neo4J
  • wget
  • make
  • zip
  • Working Internet Connection for downloading dependencies!

Make sure that you are using Java 1.8 both for java and javac ! You can check this by running

javac -version
java -version


  • Intellij IDEA
  • At least 8GB of RAM
  • At least 6GB of Disk Space
    • ~ 4GB for Maven Dependencies
    • ~ 500MB for Roboy_Dialog with all sub-modules and files generated via mvn clean install
    • Rest is a ballpark estimate for Neo4J, Redis, ROS and their dependencies
  • Ubuntu (or variation) 16.04 LTS or Mac OSX
    • Needed for ROS Kinetic
    • If you do not need ROS features, any version of Linux should do

Command Line Installation Instructions

Assumes you have already set up Neo4j.

# Install Maven, Java, Docker and other programs needed (installing openJDK because of simplicity)
sudo apt-get install maven openjdk-8-jdk git make wget zip ruby
# Download and Run Neo4J with Docker
sudo docker run --publish=7474:7474 --publish=7687:7687 --volume=$HOME/neo4j/data:/data --volume=$HOME/neo4j/logs:/logs neo4j:3.0
# Clone Dialog's Master Branch (replace master with devel for other branches)
git clone --recursive -b master
# Change Directory to your new clone
cd roboy_dialog
# Download Dependencies and Install
mvn clean install
# Use this to Start Dialog

Running Neo4J's Docker Image as Non-Root

See here for more information.

Installation without Neo4J Tests

If you do not require Neo4J, or otherwise wish to prevent Neo4J-dependent tests execute (ie. situations with no internet connection and only remote instance setup), you can have the Neo4J tests ignored, by simply appending -D neo4jtest=false to your maven command.

Example: mvn clean install -D neo4jtest=false, mvn test -D neo4jtest=false

This will disable roboy_memory's org.roboy.memory.util.Neo4jTest & dialog's roboy.memory.MemoryIntegrationTest, since both require an active Neo4J database instance.

IDE Installation Instructions

Clone the Dialog Manager repository either using your IDE's VCS Tools or using the command line. git clone --recursive

Attention: Make sure that the git sub-modules are initialized!

  1. Import Dialog System as a Maven project into the IDE
  2. Download the Maven Dependencies
  3. Execute roboy.dialog.ConversationManager as the main class.

Do not forget to start Neo4J!

Environment Variables

You need to set environment variables to tell roboy_dialog where Neo4j, ROS (optional) and Redis (optional) are located. In most cases, it will suffice just to set the Neo4J variables. Just add the export VARIABLE=value statements to your $HOME/.bashrc.

Since all of these dependencies are actually required by roboy_memory, you can find more detailed installation instructions in the memory docs.


The dialog system's memory module uses Neo4j, a graph database which stores relations between enttities observed by roboy (names, hobbies, locations etc.).Therefore, make sure to set the following environment variables to meaningful values:

export NEO4J_USERNAME=user
export NEO4J_PASSWORD=pass

If no remote development instance of Neo4j is available, just run Neo4j in a docker container. For more options and additional information, refer to docs/Usage in the memory module.

sudo docker run \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j/data:/data \
    --volume=$HOME/neo4j/logs:/logs \


Note: Running ROS is only necessary when running roboy_dialog within the Roboy architecture. Otherwise, you may also set ROS_ENABLED: false in

Dialog is tied into the Roboy architecture as a ROS node. Therefore, make sure to set the following environment variables to meaningful values:

export ROS_HOSTNAME=local-hostname
export ROS_MASTER_URI=http://rosmaster:11311

If no remote development instance of ROS master is available, just run roscore in a docker container.


Redis is a software used for facial feature-storage on a remote server. In most cases, you can simply ignore this, as the average project does not need this.

export REDIS_URI="***"
export REDIS_PASSWORD="***"

Running the Dialog System

Once the Neo4j (and ROS) dependencies are satisfied, run the dialog system via ...


If everything is running and configured correctly, you should be able to have a basic conversation like following

Roboy says hi!

Running NLU only

java -Xmx6g -d64 -cp \
    nlu/parser/target/roboy-parser-2.0.0-jar-with-dependencies.jar \

Using the Google Word2Vec Model in NLU

For a more complete but also much more memory-intensive Word Vector model, the NLU module has the ability to parse the GoogleNews word vector collection, which can be retrieved from here.

In order to use it, store and extract it under resources_nlu/word2vec. Then just set WORD2VEC_GOOGLE: true in

Configuration of roboy_dialog

One is able to customize the modules that are enabled, when dialog starts. One does this by altering the options in For more details, see the [detailed documentation page](

Logging Levels

One can configure the amount of logging one gets from memory, dialog and parser individually. It is recommended that...

User Type Dialog Parser Memory

If you wish to have more detailed information, please view the docs page.

Enabling External APIs

If you want to set external APIs, you will have to create an APIkeys.yml file containing all the keys. For more information, see the relevant documentation page


See the Troubleshooting Page