Getting Started

From OpenCog
Jump to: navigation, search

This page is designed to give you a quick fire introduction to OpenCog and the concepts involved, and put you in a position to start contributing to the project. If you need additional assistance, feel free to ask for help.

Hands On With OpenCog

This tutorial will walk you through the steps to build and start using OpenCog.

You may also read below. This is older material but likely still up-to-date.

Get and build OpenCog

Obviously the first step is to get yourself a copy of the software. Instructions for obtaining source code, getting the correct dependencies, and building the software are available at BuildingOpenCog.

OpenCog basics

In OpenCog there's an AtomSpace filled with with Atoms. There are two main types of atoms, nodes and links, and atoms can have further sub-types, such as being directed or undirected links and representing specific types of relationships and entities. These types are not fixed and can be added to OpenCog through the ClassServer.

Links can point to numerous atoms at once (i.e. not just 2) including other links. Together, the nodes and links within the AtomSpace can be thought of as a generalized Hypergraph.

All atoms have a TruthValue associated with them.


Atoms have several properties:

  • name - the name of the atom.
  • incoming set - all the links that point to an atom.
  • outgoing set - all the atoms that an atom connects to.
  • arity - the number of atoms in the outgoing set of an atom.
  • type - the type of the atom.


Nodes are unique based on their name and type. Nodes can be created with a null name, but OpenCog will randomly apply a unique identifier to it.

Nodes have no outgoing set, and thus arity 0.


Links have at least one item in their outgoing set and thus their arity is >= 1. They are unique based on their type and outgoing set. Once added to the AtomSpace, a links outgoing set cannot be changed (the link has to be deleted and recreated if for some reason you need to change it, but this is rare). A link has no name.

Truth values


TruthValue 0.8, 0.9 the_earth_is_flat
TruthValue 0.1, 0.9 the_earth_is_flat (context ConceptNode Joel)

Interacting with the AtomSpace

All atoms referred to by Handles.

  • TLB - converts handles into pointers to atoms and check validity of a handle.
  • AtomSpace - API for interface to the hypergraph, getHandleSet methods, getType.
  • AtomTable - an implementation of atom storage, several indexes to ensure fast lookup by type and importance. Shouldn't need to be accessed directly.


So, having all these atoms floating around the AtomSpace is all very nice... but without having something acting on them, then not a lot will happen. That's where MindAgents come in...

Attention allocation

All atoms have an AttentionValue which indicates how much attention OpenCog should pay to it. The AttentionValue is based on the pass utility of atoms in relation to one another and is composed of:

  • Short term importance (STI): combination of whether to keep atoms in memory, and guides the use of atoms by various reasoning processes/MindAgents while spreading.
  • Long term importance (LTI): influences whether the atom is forgotten.
  • Very long term importance (VLTI): boolean value of whether the atom can be permanently forgotten or not.

There is also a quantity called stimulus, which is a temporary credit of work or usefulness that MindAgents confer to atoms. At the end of the MindAgent's execution cycle, it can reward the atoms it used relative to to how much STI and LTI is available.

There are a number of MindAgents that specifically control the diffusion and update of importance in OpenCog, there are discussed in more detail on the Attention Allocation page.

Interacting with OpenCog

See the guide on the OpenCog shell.

Scheme shell

The scheme shell provides an easy-to-use interpreter for creating and manipulating atoms. Below is an example of using scheme to create assorted atoms. Be sure to run the shell script in the opencog/scm directory to initialize scheme shell!

(ConceptNode "dog")
(ConceptNode "dog" (stv 0.8 0.9))
(ConceptNode "mammal" (stv 0.8 0.9))

(ConceptNode "cat" (stv 0.8 0.9))
(ConceptNode "lion" (stv 0.8 0.9))

(define x (ConceptNode "dog"))
(define y (ConceptNode "mammal"))
(define l (InheritanceLink x y (stv 0.8 0.9)))
(define x (ConceptNode "cat"))
(define y (ConceptNode "mammal"))
(define l (InheritanceLink x y (stv 0.8 0.9)))
(define y (ConceptNode "lion"))
(define l (InheritanceLink y x (stv 0.8 0.9)))

(cog-outgoing-set l)
(cog-incoming-set x)

Natural Language Processing

Currently, OpenCog has an experimental natural language processing pipeline. It doesn't "do much", although it is currently in production use to perform certain various corpus linguistics projects. See the NLP page for details.