Getting Started with MemoryX

MemoryX is based on the ArmarX framework and provides a memory layer for robots. It depends on ArmarXCore and ArmarXGui and further Components of VisionX use MemoryX to store and update retrieved data. All information is stored using MongoDB as a backend.

Starting the MongoDB daemon

Before running the mongodb for the first time you should adapt the port of your mongo db in the configuration file ~/.armarx/default.cfg to avoid conflicts with other users on the pc.

As a first step MongoDB needs to be started before MemoryX can be used. This is done via the following script:

armarx memory start

If an error occurs during the execution of this script follow the given advice and run

armarx memory repair
Using the armarx command without prefix assumes that either the ArmarX python scripts package is installed or ${ArmarXCore_DIR}/build/bin is in your $PATH variable.

Filling the database with prior knowledge

If MongoDB is started for the first time no databases will be available. To work with ARMAR-III, you therefore have to first import a memory snapshot with the kitchen and object models into the MongoDB. To do so, execute the following command:

${MemoryX_DIR}/build/bin/ ${ArmarX_DIR}/ArmarXDB/data/ArmarXDB/dbexport/memdb

At ${ArmarX_DIR}/ArmarXDB/data/ArmarXDB/dbexport/memdb the standard library is stored as JSON text files.

The export of a current database in the mongoDB is also easily possible: Use the following command to export the database memdb to the directory ${ArmarX_DIR}/ArmarXDB/data/ArmarXDB/dbexport/memdb.

${MemoryX_DIR}/build/bin/ memdb ${ArmarX_DIR}/ArmarXDB/data/ArmarXDB/dbexport/memdb

This directory and the current database collections are already checked in into git. To commit the database to git, just commit the contents of the directory ${ArmarX_DIR}/ArmarXDB/data/ArmarXDB/dbexport/memdb after export. Each database should be exported into a separate directory, because the importer reads alls files from the given directory.

Accessing MongoDB

The MongoDB Shell can be used for quick interactions with MongoDB. It can be started with the following script:


The following commands are helpful to check available databases and their collections:

show dbs                   # list all available databases
use <dbname>               # use <dbname> as a basis for all further queries
show collections           # list all available collections in the currently active database
db.<collection>.findOne()  # select one item from <collection> and display its JSON data

An easy-to-use GUI for accessing and querying MongoDB is RoboMongo.

With robomongo it is easy to depict and edit the current content of the database (see below).

The Robomongo tool

Available Collections

Altogether, the following three memory types are provided:

  • LongtermMemory -> Snapshots, KitchenScenes
  • WorkingMemory -> all current objects (which have for example been recognized)
  • CommonPlaces -> infers common location of certain object classes (Masterthesis of Alexey)

The information associated with these memory types are stored in different collections. After the snapshot has been loaded into MongoDB the following collections among others can be found in the memdb database:

  • Prior_KitchenKK
  • Prior_KitchenKK_Sim
  • Prior_MobileKitchen
  • Prior_Objects
  • Snapshot_KitchenKK_ObjectInstances
  • Snapshot_KitchenKK_Sim_ObjectInstances
  • Snapshot_MobileKitchen_ObjectInstances
  • snapshots

The collections prefixed with Prior_ contain prior knowledge data such as objects, kitchen visualisation information, links to *.iv files and so on.

An object in the Prior_Objects collection can be examined with the db.Prior_Objects.findOne() query. It reveals that an object in this collection contains the attributes for (stored in "attr"):

  • OpenInventor model files: "ivFile*"
  • textFiles containing textures
  • "ManipulationFile" which combines all attributes into a common visualisation

MemoryX other Scenarios


CommonStorage is a wrapper for MongoDB and can be used to store and retrieve arbitrary data. CommonStorageTest shows some testcases on how CommonStorage can be used.


CommonPlacesTest contains example code on how to use the CommonPlaces memory.