The KB API provides basic functionality for manipulating CycL-based Java objects. The API extracts the main Predicate Logic constructs in the Cyc KB as Java classes. A set of factory classes allow finding and creating terms and assertions. These can be used to build sentences, to create new assertions or to build queries.


The KB API has two main object hierarchies:
  • The term hierarchy and its sub-classes are used to create various Predicate Logic constructs. The main classes under KbTerm are KbCollection, KbIndividual, Relation and Context.
  • The assertion hierarchy is used to create Facts (Ground Atomic Formulas) and Rules. To help create and manipulate assertion sentences, the API provides the Sentence class.
Diagram of the KB API class hierarchy
Diagram of the KB API class hierarchy

A corresponding set of factory classes allow KB API objects to be constructed via calls to static findOrCreate() and get() methods, which create and cache java-side objects that correspond to objects in the KB. For example:
KbCollection actorsInMovies = KbCollectionFactory.findOrCreate("ActorInMovies");
Because of caching, it is possible for a KbObject to point to an object that no longer exists in the Cyc KB. The validity (or staleness) of a KB Object can be checked by the KbObject#isValid() method.

The Session API provides thread local variables to set bookkeeping (which time-stamps and tracks authorship for assertions and term creations) and transcription (which records every KB operation), as well as default context for queries and assertions. These can be found via com.cyc.session.CycSession#getOptions(). Note that SessionOptions.setCyclistName("<the cyclist>") should be set for bookkeeping information to be asserted.

The exception hierarchy of the KB API provides useful information about the cause of failure of an operation. All instances of CycConnectionException (which indicate Cyc Server unavailability) are chained under KbRuntimeException. Most instances of CycApiException and CycApiServerSideException are chained under KbServerSideExceptions. Because the KB API uses cached objects, it throws a StaleKbObjectException when an object refers to a deleted KB concept.

Below are snippets of code that show how to perform some of the most basic operations using the KB API. More detailed examples can be found on the Sample Code page.

Configure (per session/thread)

Here we are defining options programmatically, but future versions of the Session API will allow them to be defined via configuration properties.
SessionOptions options = CycSessionManager.getCurrentSession().getOptions();
            ContextFactory.getDefaultContext(ContextFactory.UV_MT, ContextFactory.INFERENCE_PSC));

Create a KB Term

KbCollection actorsInMovies = KbCollectionFactory.findOrCreate("ActorInMovies");
Context peopleDataMt = ContextFactory.get("PeopleDataMt");
KbIndividual nicholson = 
  KbIndividualFactory.findOrCreate("JackNicholson", actorsInMovies, peopleDataMt);

Create an Assertion

BinaryPredicate movieActors = BinaryPredicateFactory.findOrCreate("movieActors");
KbIndividual kingOfMarvinGardens = 
Context massMediaMt = ContextFactory.get("MassMediaDataMt");
Sentence aSent = KbFactory.getSentence(movieActors, kingOfMarvinGardens, Nicholson);
Fact nicholsonInMarvinGardens = 
  FactFactory.findOrCreate(aSent, massMediaMt);

Clearing the cache

If your program dynamically creates and reuses the same term name, it is strongly recommended to clear the KB API object cache.