Repository files navigation

The OpenCog AtomSpace is an in-RAM knowledge representation (KR)database with an associated query engine and graph-re-writing system.It is a kind of in-RAM generalized hypergraph (metagraph) database.Metagraphs offer more efficient, more flexible and more powerful waysof representing graphs:a metagraph store is literally just-plainbetter than a graph store.On top of this, the Atomspace provides a large variety of advancedfeatures not available anywhere else.

The AtomSpace is a platform for building Artificial General Intelligence(AGI) systems. It provides the central knowledge representation componentfor OpenCog. As such, it is a fairly mature component, on which a lot ofother systems are built, and which depend on it for stable, correctoperation in a day-to-day production environment.

There are several dozen modules built on top of the AtomSpace. Notableones include:

• Store AtomSpaces to disk
• Network-distributed AtomSpace storage
• Network shell to AtomSpaces, including a WebSocket API
• Sparse Vector/Matrix embeddings/access to graphs
• Sensori-motor research
• Language learning

It is now commonplace to represent data as graphs; there are more graphdatabases than you can shake a stick at. What makes the AtomSpacedifferent? A dozen features that no other graph DB does, or has evendreamed of doing.

But, first: five things everyone else does:

• Performgraphical database queries,returning results that satisfy a provided search pattern.
• Arbitrarily complex patterns with an arbitrary number of variableregions can be specified, by unifying multiple clauses.
• Modify searches with conditionals, such as "greater than", and withuser callbacks into scheme, python or Haskell.
• Performgraph rewriting: use search results to create new graphs.
• Trigger execution of user callbacks... or of executable graphs (asexplained below).

A key difference: the AtomSpace is a metagraph store, not a graph store.Metagraphs can efficiently represent graphs, but not the other way around.This is carefully explainedhere,which also gives a precise definition of what a metagraph is, and how itis related to a graph. As a side-effect, metagraphs open up manypossibilities not available to ordinary graph databases. These arelisted below. Things are things that no one else does:

• Search queries are graphs.(The API to thepattern engineis a graph.) That is, every query, every search is also a graph. Thatmeans one can store a collection of searches in the database, andaccess them later. This allows a graph rule engine to be built up.
• Inverted searches.(DualLink.)Normally, a search is like "asking a question" and "getting ananswer". For the inverted search, one "has an answer" and is lookingfor all "questions" for which its a solution. This is patternrecognition, as opposed to pattern search. All chatbots do this asa matter of course, to handle chat dialog. No chatbot can hostarbitrary graph data, or search it. The AtomSpace can. This is becausequeries are also graphs, and not just data.
• Both"meet" and "join"searches are possible: One can perform a "fill in the blanks" search(a meet, withMeetLink)and one can perform a "what contains this?" search (a join, withJoinLink.)
• Graphs are executable. Graph vertex types include "plus", "times","greater than" and many other programming constructs. The resultinggraphs encode"abstract syntax trees"and the resulting language is calledAtomese.It resembles theintermediate representationcommonly found in compilers, except that, here, its explicitly exposedto the user as a storable, queriable, manipulable, executable graph.
• Graphs are typed(TypeNode andtype constructors.)Graph elements have types, and there are half a dozen typeconstructors, including types for graphs that are functions. Thisresembles programming systems that have type constructors, such asCaML or Haskell.
• Graph nodes carry vectorsValues are mutable vectors ofdata. Each graph element (vertex or edge, node or link) can hostan arbitrary collection of Values. This is, each graph element isalso a key-value database.
• Graphs specify flowsValues can be static or dynamic. For the dynamic case, a givengraph can be thought of as "pipes" or "plumbing"; the Values can"flow" along that graph. For example, theFormulaStream allowsnumeric vector operations ("formulas") to be defined. Accessinga FormulaStream provides the vector valueat that instant.
• Unordered sets(UnorderedLink.)A graph vertex can be an unordered set (Think of a list of edges, butthey are not in any fixed order.) When searching for a matchingpattern, one must considerall permutations of the set. This iseasy, if the search has only one unordered set. This is hard, ifthey are nested and inter-linked: it becomes a constraint-satisfactionproblem. The AtomSpace pattern engine handles all of these casescorrectly.
• Alternative sub-patterns(ChoiceLink.)A search query can include a menu of sub-patterns to be matched. Suchsets of alternatives can be nested and composed arbitrarily. (i.e.they can contain variables,etc.)
• Globby matching(GlobNode.)One can match zero, one or more subgraphs with globs This is similarto the idea of globbing in a regex. Thus, a variable need not begrounded by only one subgraph: a variable can be grounded by anindeterminate range of subgraphs.
• Quotations (QuoteLink.)Executable graphs can be quoted. This is similar to quotations infunctional programming languages. In this case, it allows queriesto search for other queries, without triggering the query that wassearched for. Handy for rule-engines that use rules to find otherrules.
• Negation as failure(AbsentLink.)Reject matches to subgraphs having particular sub-patterns in them.That is, find all graphs of some shape, except those having theseother sub-shapes.
• For-all predicate(AlwaysLink.)Require that all matches contain a particular subgraph or satisfy aparticular predicate. For example: find all baskets that have onlyred balls in them. This requires not only finding the baskets, makingsure they have balls in them, but also testing each and every ball ina basket to make sure they areall of the same color.
• Frames (ChangeSets)Store a sequence of graph rewrites, changes of values as a singlechangeset. The database itself is a collection of such changesets or"Frames". Very roughly, a changeset resembles a git commit, but forthe graph database. The word "Frame" is mean to invoke the idea of astackframe, or a Kripke frame: the graph state, at this moment. Bystoring frames, it is possible to revert to earlier graph state. It ispossible to compare different branches and to explore differentrewrite histories starting from the same base graph. Differentbranches may be merged, forming a set-union of thier contents. Thisis useful for inference and learning algos, which explore long chainsof large, complex graph rewrites.

Newcomers often struggle with the AtomSpace, because they bringpreconceived notions of what they think it should be, and its not that.So, a few things it is not.

• It's not JSON. So JSON is a perfectly good way of representingstructured data. JSON records data askey:value pairs, arrangedhierarchically, with braces, or as lists, with square brackets.The AtomSpace is similar, except that there are no keys! TheAtomSpace still organizes data hierarchically, and provides lists,but all entries are anonymous, nameless. Why? There are performance(CPU and RAM usage) and other design benefits in not using explicitnamed keys in the data structure. You can still have named values;it is just that they are not required. There are several differentways of importing JSON data into the AtomSpace. If your mental modelof "data" is JSON, then you will be confused by the AtomSpace.

• It's not SQL. It's also not noSQL. Databases from 50 years agoorganized structured data into tables, where thekey is the labelof a column, and differentvalues sit in different rows. This ismore efficient than JSON, when you have many rows: you don't have tostore the same key over and over again, for each row. Of course,tabular data is impractical if you have zillions of tables, each withonly one or two rows. That's one reason why JSON was invented.The AtomSpace was designed to storeunstructured data. You canstill store structured data in it; there are several different waysof importing tabular data into the AtomSpace. If your mental modelof "data" is structured data, then you will be confused by the AtomSpace.

• It's not a vertex+edge store. (Almost?) all graph databasesdecompose graphs into lists of vertexes and edges. This is just fine,if you don't use complex algorithms. The problem with this storageformat is locality: graph traversal becomes a game of repeatedlylooking up a specific vertex and then, a specific edge, each locatedin a large table of vertexes and edges. This is non-local; itrequires large indexes on those tables (requires a lot of RAM),and the lookups are CPU consuming. Graph traversal can be abottleneck. The AtomSpaceavoids much of this overhead by using(hyper-/meta-)graphs.This enables more effective and simplertraversal algorithms, which in turn allows more sophisticatedsearch features to be implemented. If your mental model ofgraph data is lists of vertexes and edges, then you will be confusedby the AtomSpace.

What is it, then? Most simply, the AtomSpace stores immutable,globally unique,typeds-expressions. The typescan be thought of as being like object-oriented classes, and many (notall) Atom types do have a corresponding C++ class. Each s-expression iscalled "an Atom". Each Atom is globally unique: there is only one copy,ever, of any given s-expression (Atom). It's almost just that simple,with only one little twist: a (mutable) key-value database is attachedto each Atom. Now, "ordinary" graph databases do this too: every vertexor edge can have "attributes" on it. The AtomSpace allows theseattributes to be dynamic: to change in time or to "flow". The flowitself is described by a graph; thus, graphs can be thought of as"plumbing"; whereas the Values are like the "fluid" in these pipes.This is much like the distinction between "software" and "data":software describes algos, data is what moves through them. In theAtomSpace, the algos are explicit graphs. The Values are the data.

The AtomSpace borrows ideas and concepts from many different systems,including ideas from JSON, SQL and graph stores. The goal of theAtomSpace is to be general: to allow you to work with whatever styleof data you want: structured or unstructured. As graphs, as tables,as objects. As lambda expressions, as abstract syntax trees, asprolog-like logical statements. A place to store relational dataobeying some relational algebra. As a place to store ontologies ormereologies or taxonomies. A place for syntactic (BNF-style)productions or constraints or RDF/OWL-style schemas.In a mix of declarative, procedural and functional styles.The AtomSpace is meant to allow general knowledge representation,in any format.

The "special extra twist" of immutable graphs decorated with mutablevalues resembles a corresponding idea in logic: the split betweenlogical statements, and the truth values (valuations) attached to them.This is useful not only for logic, but also for specifying dataprocessing pipelines: the graph specifies the pipeline; the values arewhat flow through that pipeline. The graph is the "code"; the valuesare the data that the code acts on.

All this means that the AtomSpace is different and unusual.It might be a bit outside of the comfort zone for most programmers.It doesn't have API's that are instantly recognizable to users ofthese other systems. There is a challenging learning curve involved.We're sorry about that: if you have ideas for better API's thatwould allow the AtomSpace to look more conventional, and be lessintimidating to most programmers, then contact us!

As it turns out, knowledge representation is hard, and so the AtomSpacehas been (and continues to be) a platform for active scientific researchon knowledge representation, knowledge discovery and knowledgemanipulation. If you are comfortable with extremely complexmathematical theory, and just also happen to be extremely comfortablewriting code, you are invited -- encouraged -- to join the project.

A short list of some related concepts:

• Carnegie Mellon Binary Analysis Platforrm (BAP)allows binary programs (viruses, etc.) to be disassembled and analyzed.The disassembled program is stored as a graph in a database. The graphcan be analyzed, investigated, and even executed, to see what it does.Thus, similar to the AtomSpace, but very highly specialized for binaries,and nothing else.

• Modelica is a modellinglanguage for describing complex systems. Intended for describingmechanical, electrical, electronic, hydraulic, thermal, control,electric power and process-oriented systems. The descriptions arestatic, object-oriented, file-based, and meant to be written byhumans. That is, the models are atomated, but not the creation andmanagement of them. Not suitable for general graph structures.

• The concept of graph programming.

The AtomSpace is not an "app". Rather, it is a knowledge-base platform.It is probably easiest to think of it as kind-of-like an operatingsystem kernel: you don't need to know how it works to use it. Youprobably don't need to tinker with it. It just works, and it's therewhen you need it.

End-users and application developers will want to use one of the existing"app" subsystems, or write their own. Most of the existing AtomSpace "apps"are focused on various aspects of "Artificial General Intelligence". Thisincludes (unsupervised) natural-language learning, machine-learning,reasoning and induction, chatbots, robot control, perceptual subsystems(vision processing, sound input), genomic and proteomic data analysis,deep-learning neural-net interfaces. These can be found in other githubrepos, including:

• Unsupervised natural language learning(learn repo)
• JSON, Python, Scheme network interfaces(cogserver repo)

Zombie projects: these are half-dead; no one is currently working on them,but they should still work and still provide useful capabilities.

• Genomic, proteomic data analysis(agi-bio repo) and variousMOZI.AI repos.
• Port of the MOSES machine learning to Atomese(as-moses repo)
• Unified Rule Engine (ure repo)
• OpenAI Gym and Minecraft agents(rocca repo)

Dead projects: these are no longer maintained. They used to work, but havebeen abandoned for various theoretical and political reasons:

• Natural language chat, robot control(the opencog repo)
• ROS bridge to robots, vision subsystem, chat(ghost-bridge repo)
• Opencog on a Raspberry Pi(tinycog repo)
• Probabilistic Logic Networks (pln repo)

If you are impatient, a good way to learn the AtomSpace is to run theexample demos.Start with these. Then move on tothepattern-matcher examples.

Documentation is on the OpenCog wiki. Good places to start are here:

• AtomSpace
• Atom types
• Pattern matching

TheOpenCog Brainwave blog provides readingmaterial for what this is all about, and why.

Atomese is a collection of structural primitives meant to describestructural relationships as they are witnessed in "reality". Thisincludes descriptions of physical nature, biological nature,psychological, social, cultural, political and economic, and, of course,mathematical and technological. So, software and programming.

The idea of representing "everything" is as old as Aristotle. Set theoryis an early mathematical framework. This is followed by combinators andlambda calulus, by means of which "anything sayable can be said". Modernmath offers Category Theory and Topos Theory, along with Proof Theoryand Model Theory as ways of talking about "anything". The goals ofmathematicians, however, are not the same as the moreentrepreneurial-minded, and the latter have created the trillion dollarcomputer industry, with only token acknowledgement of the mathematicalfoundations. The computer industry gives us relational databases,knowledge representation, upper ontologies, and now LLM's, transformersand weights as mechanisms by which "anything" can be represented.

Atomese is an ongoing attempt to roll all of this up into one, and to doso in a way that makes general intelligence algorithmically accessible.Until now, all attempts to extract structure from the universe arecomplex systems hand-crafted by human engineers. These might befinancial credit-worthiness rating systems, or astronomicalstellar-redshift analysis tools. The software for these systems arewritten by humans, applying conventional software developmentmethodologies, using conventional programming languages, designed tomake it easy for the human software engineer to perform their task.

What if, instead, we ask: what would it take to make it easy foralgorithmic systems to automatically explore and extract structure? Tocreate world-models that can be stored in short-term or long-termmemory, to process and transform sensory information, to drive motorsand perform actions in the real world? That is, rather than having asmall army of humans hand-crafting custom robots for others to use, toinstead provide a recursive infrastructure to allow, umm, err, robots tocraft themselves? This is the driving vision of Atomese.

Atomese originally arose as an attempt by Ben Goertzel and company tocombine symbolic AI methods with probability theory, resulting in thedefinition of PLN, Probabilistic Logic Networks, articulated in severalbooks devoted to the topic. In this articulation, the primitives ofknowledge representation theory are mashed up with mathematical logic toprovide Nodes and Links, which are general enough to represent almostany kind of relational structure. The base object then becomes acollection of graphs, or, more properly, hypergraphs. To be able toprocess, digest, reason and manipulate these, these are placed in a(hyper-)graph database, the AtomSpace.

To layer on probability theory onto what is otherwise a purely symbolicrepresentation of nature, the SimpleTruthValue is introduced. This is apair of floating-point numbers, representing the probability, and theconfidence of any given symbolic factual assertion. The goal is tosupport logical reasoning systems of any type, not only conventionalBayesian inference, but any collection of rule systems and axioms, asmight be encountered in mathematical proof theory. This would include,for example, any of the rich varieties of modal logic, but also fuzzylogic, the so-called "non-axiomatic reasoning systems" andstatistical-mechanical systems like Markov logic.

The word-phrase TruthValue, and more generally Value, has its roots inmathematical logic, where any given assertion in first-order logic (orhigher-order logic) can be assigned a "valuation", indicating it'sbinary truth/falsehood. Probability theory forces a replacement of crisp0/1 by a floating-point number. Probabilistic logic (along with neuralnets) famously has issues with converging rapidly enough to a givensolution. For this reason, an extra float is introduced, the"confidence". This helps, but is still not enough to capture the conceptof an ensemble, e.g. a "Bell curve", a Gaussian, or more generally anykind of probability distribution: a "histogram" or more simply "a vectorof numbers". This leads to the idea of a FloatValue, and then rapidly toa Value in general, which is a vector of anything at all, representingtruths in any ensemble, hypothetical modal universe, a set of Bayesianpriors, as the case may be. Of course, vectors of floats are thebread-n-butter of neural nets.

Parallel universes, such as the hypothetical worlds of modal logic,thermodynamic canonical ensembles, the infinite collection of Bayesianpriors, or, god forbid, quantum-mechanical decompositions, are oftenimagined to live "in parallel" or to somehow co-exist temporally. Inphysical reality, though, the changing network of relationships andlikelihoods is time-varying, and usually accessible only through sensorydevices, rather than through pure reason. This motivates the recastingof Values as streams that flow data. This relegates the AtomSpace tobeing a form of memory, a repository for world-models, while flowingstreams encapsulate the process of, well, "processing information". Thisfits well with present-day software theory, which includes descriptionsof generators, futures and promises as software primitive constructs forcreating sensory agentic systems. The backends of large commercialwebsites use futures and promises as extremely low-level programmingconstructs to implement millisecond reaction times when customers clickon their favorite TikTok influencer. The point of having streams inAtomese is not to be hopelessly abstract, but to capture an idea that isalready widespread in the design and development of agentic softwaresystems.

This brings Atomese to it's present-day state: an infrastructure forsymbolic AI, together with a (hyper-)graph database, offering dynamicsensori-motor processing primitives. The hope is that this is anappropriate toolset for agentic systems that can reify, transform andtransmute their own content. It remains a research platform to figureout how this is possible, or, perhaps being more honest, if this ispossible.

One of the primary conceptual distinctions in Atomese is between"Atoms" and "Values". The distinction is made for both usability andperformance. Atoms are:

• Used to represent graphs, networks, and long-term stable graphical relations.
• Indexed (by the AtomSpace), which enables the rapid search and traversal of graphs.
• Globally unique, and thus unambiguous anchor points for data.
• Immutable: can only be created and destroyed, and are effectively static and unchanging.
• Large, bulky, heavy-weight (because indexes are necessarily bulky).

By contrast, Values, and valuations in general, are:

• A way of holding on to rapidly-changing data, including streaming data.
• Hold "truth values" and "probabilities", which change over time as newevidence is accumulated.
• Provide a per-Atom key-value store (a mini noSQL database per-Atom).
• Are not indexed, and are accessible only by direct reference.
• Small, fast, fleeting (no indexes!)

Thus, for example, a piece of knowledge, or some proposition would bestored as an Atom. As new evidence accumulates, the truth value of theproposition is adjusted. Other fleeting changes, or general free-formannotations can be stored as Values. Essentially, the AtomSpace lookslike a database-of-databases; each atom is a key-value database; theatoms are related to one-another as a graph. The graph is searchable,editable; it holds rules and relations and ontologies and axioms.Values are the data that stream and flow through this network, likewater through pipes. Atoms define the pipes, the connectivity. Valuesflow and change. See the blog entryvalue flows aswell asAtom andValue.

The primary documentation for the atomspace and Atomese is here:

• https://wiki.opencog.org/w/AtomSpace
• https://wiki.opencog.org/w/Atomese
• https://wiki.opencog.org/w/Atom
• https://wiki.opencog.org/w/Value

The main project site is athttps://opencog.org

Most users should almost surely focus their attention on one of thehigh-level systems built on top of the AtomSpace. The rest of thissection is aimed at anyone who wants to workinside of the AtomSpace.

Most users/developers should think of the AtomSpace as being kind-of-likean operating system kernel, or the guts of a database: its complex, andyou don't need to know how the innards work to use the system. Theseinnards are best left to committed systems programmers and researchscientists; there is no easy way for junior programmers to participate,at least, not without a lot of hard work and study. Its incrediblyexciting, though, if you know what you're doing.

The AtomSpace is a relatively mature system, and thus fairly complex.Because other users depend on it, it is not very "hackable"; it needsto stay relatively stable. Despite this, it is simultaneously aresearch platform for discovering the proper way of adequatelyrepresenting knowledge in a way that is useful for general intelligence.It turns out that knowledge representation is not easy. This projectis a -good- excellent place to explore it, if you're interested in thatsort of thing.

Experience in any of the following areas will make things easier foryou; in fact, if you are good at any of these ... we want you. Bad.

• Database internals; query optimization.
• Logic programming; Prolog.
• SAT-solving; Answer Set programming; Satisfiability Modulo Theories.
• Programming language design & implementation.
• Rule engines; reasoning; inference; parsing.
• Theorem-proving systems; Type theory.
• Compiler internals; code generation; code optimization; bytecode; VM's.
• Operating systems; distributed database internals.
• GPU processing pipelines, lighting-shading pipelines, CUDA, OpenCL.
• Dataflow in GPU's for neural networks.

Basically, Atomese is a mash-up of ideas taken from all of the abovefields. It's kind-of trying to do and be all of these, all at once,and to find the right balance between all of them. Again: the goal isknowledge representation for general intelligence. Building somethingthat the AGI developers can use.

We've gotten quite far; we've got a good, clean code-base, more-or-less,and we're ready to kick it to the next level. The above gives a hint ofthe directions that are now open and ready to be explored.

If you don't have at least some fair grounding in one of the above,you'll be lost, and find it hard to contribute. If you do know somethingabout any of these topics, then please dive into the open bug list. Fixingbugs is the #1 best way of learning the internals of any system.

Looking ahead, some key major projects.

One of the development goals for the 2021-2023 time frameis to gain experience with distributed data processing. Currently,one can build simple distributed networks of AtomSpaces, by usingtheStorageNode tospecify a remote AtomSpace. However, it is up to you as to whatkinds of data these AtomSpace exchange with one-another. Only twosimple pre-configured communications styles have been created: theread-thru and the write-thru proxies for the cogserver. These passincoming data and results on to the next nodes in the network.

Because the AtomSpace can hold many different representatioinalstyles, it is relatively easy to import data into the AtomSpace.The low-brow way to do this is to write a script file that importsthe data. This is fine, but leads to data management issues: who'sgot the master copy?

The goal of data bridges is to create new Atoms that allow liveaccess into other online systems. For example, if an SQL databaseholds a table of(name, address, phone-number), it should bepossible to map this into the AtomSpace, such that updates notonly alter the SQL table, live and on line, but also such thata query performed on the AtomSpace side translates into a query onthe SQL database side. This is not hard to do, but no one's done ityet.

Similarly, a live online bridge between the AtomSpace and populargraph databases should also be possible. It's not clear if thisshould use theStorageNodeAPI mentioned above, or if it needs something else.

The new Value system seems to provide a very nice way of workingwith fast-moving high-frequency data. It seems suitable for holdingon to live-video feeds and audio streams and piping them throughvarious data-processing configurations. It looks to be a decentAPI for declaring the structure and topology of neural nets (e.g.TensorFlow). However, it is more-or-less unused for these tasks.Apparently, there is still some missing infrastructure, as well assome important design decisions to be made. Developers have not begunto explore the depth and breadth of this subsystem, to exert pressureon it. Ratcheting up the tension by exploring new and better ways ofusing and working with Values will be an important goal for the2021-2024 time-frame. See thevalue flows blogentry.

A particularly important first step would be to build interfacesbetween values and an audio DSP framework. This would allow AtomSpacestructures to control audio processing, thus enabling (for example)sound recognition (do I hear clapping? Cheers? Boos?) without havingto hard-code a "cheer recognizer". This opens the door to using machinelearning to learn how to detect different kinds of audio events.

There is no particular need to limit oneself to audio: other kindsof data is possible (e.g. exploring the syntactic, hierarchicalpart-whole structure in images) but audio is perhaps easier!?

Many important types of real-world data, include parses of naturallanguage and biochemical processes resemble the abstract mathematicalconcept of "sheaves", in the sense of sheaf theory. One reason thatthings like deep learning and neural nets work well is because somekinds of sheaves look like tensor algebras; thus one has things likeWord2Vec and SkipGram models. One reason why neural nets stillstumble on natural language processing is because natural languageonly kind-of-ish, partly looks like a tensor algebra. But naturallanguage looks a whole lot more like a sheaf (because things likepre-group grammars and categorial grammars "naturally" look likesheaves.) Thus, it seems promising to take the theory and all thebasic concepts of deep learning and neural nets, rip out the explicittensor-algebra in those theories, and replace them by sheaves. Acrude sketch is here.

Some primitive, basic infrastructure has been built. Huge remainingwork items are using neural nets to perform the tensor-like factorizationof sheaves, and to redesign the rule engine to use sheaf-type theoremproving techniques.

Current work is split between two locations: the "sheaf" subdirectoryin this repo, and thegeneraterepo.

The Atomspace runs on more-or-less any flavor of GNU/Linux. It does notrun on any non-Linux operating systems (except maybe some of the BSD's).Sorry!

There are a small number of pre-requisites that must be installedbefore it can be built. Many users will find it easiest to use theinstall scripts provided in theocpkg repo.Some users may find some success with one of theopencog Docker containers.Developers interested in working on the AtomSpace must be able to buildit manually. If you can't do that, all hope is lost.

To build the OpenCog AtomSpace, the packages listed below are required.Essentially all Linux distributions will provide these packages.

• C++ utilities package.
• https://www.boost.org/ |apt install libboost-dev

• Build management tool; v3.0.2 or higher recommended.
• https://www.cmake.org/ |apt install cmake

• Common OpenCog C++ utilities.
• https://github.com/opencog/cogutil
• It uses exactly the same build procedure as this package. Be suretosudo make install at the end.

• Embedded scheme REPL; version 3.0 or newer required.
• https://www.gnu.org/software/guile/guile.html
• For Debian/Ubuntu,apt install guile-3.0-dev

• Unit test framework.
• Required for running unit tests. Breaking unit tests is verboten!
• https://cxxtest.com/ |apt install cxxtest

The following packages are optional. If they are not installed, someoptional parts of the AtomSpace will not be built. Thecmake command,during the build, will be more precise as to which parts will not be built.

• C bindings for Python. (Cython version 0.23 or newer)
• Recommended, as many users enjoy using python.
• https://cython.org |apt install cython

• Haskell bindings (experimental).
• Optional; almost no existing code makes use of Haskell.
• https://www.haskell.org/

• OCaml bindings (experimental).
• Optional; almost no existing code makes use of OCaml.
• https://www.ocaml.org/ |apt install ocaml ocaml-findlib

• Distributed, multi-client networked storage.
• Needed for "remembering" between shutdowns (and for distributed AtomSpace)
• Optional; The RocksDB backend is recommended. Use the cogserver to get adistributed atomspace.
• https://postgres.org |apt install postgresql postgresql-client libpq-dev

Be sure to install the pre-requisites first!Perform the following steps at the shell prompt:

    cd to project root dir    mkdir build    cd build    cmake ..    make -j4    sudo make install    make -j4 check

Libraries will be built into subdirectories within build, mirroringthe structure of the source directory root.

To build and run the unit tests, from the./build directory enter(after building opencog as above):

    make -j4 check

Most tests (just not the database tests) can be run in parallel:

    make -j4 check ARGS=-j4

The database testswill fail if run in parallel: they will step onone-another, since they all set and clear the same database tables.

Specific subsets of the unit tests can be run:

    make test_atomese    make test_atomspace    make test_guile    make test_join    make test_python    make test_query

After building, you MUST install the atomspace.

    sudo make install

Atomese -- that is -- all of the different Atom types, can be thoughtof as the primary API to the AtomSpace. Atoms can, of course, becreated and manipulated with Atomese; but, in practice, programmerswill work with either Scheme (guile), Python, C++, OCaml or Haskell.

The simplest, most complete and extensive interface to Atoms and theAtomspace is via scheme, and specifically, the GNU Guile schemeimplementation. An extensive set of examples can be found in the/examples/atomspace and the/examples/pattern-matcher directories.

Python is more familiar than scheme to most programmers, and it offersanother way of interfacing to the atomspace. Unfortunately, it is notas easy and simple to use as scheme; it also has various technical issues.Thus, it is significantly less-used than scheme in the OpenCog project.None-the-less, it remains vital for various applications. See the/examples/python directory for how to use pythonwith the AtomSpace.

• Porting to Android: multiple issues described incogroid/b-obstacles.See alsobug 2995.

• Bug: Crashes on Arm v7a:bug 2944.

• Seems that the AtomSpace is no longer alone in the hypergraph world!As of 2022, one can find a python library calledHyperNetX.Their documentation is even eerily similar to our own! Gee, how couldthat happen?

• Stop the presses! There's more! Extra! Extra! Read all about it!NetworkX is a python package for analyzingcomplex networks.