Installation

Installing Semantic Synchrony

Semantic Synchrony comes in two parts. The "front end" is the application the user interacts with, and the "back end" is the application that takes care of the data.

The easiest way to use smsn is to use the smsn-emacs-too Docker image.
The next easiest way to try smsn is by using the online graph. This way you don't have to run the server, and you don't need Docker. You'll just install Emacs, then install smsn-mode for Emacs, then use the shared graph hosted at fortytwo.net. To install this way, skip to Step 7 (Install Emacs) on this page.
The next easiest way: First, run SmSn in a Docker container. Then skip on this page to Step 6.1 (Test Gremlin Server), and work your way down.
The hard way: Install SmSn natively. To do that, read the rest of this page.

There is no disadvantage to running in a Docker container versus running natively.

The code examples assume a Unix-like environment (including Linux and Mac OS). If you use Windows, the first and second installation methods should work fine, but they are untested; let us know how it goes!

Step 1: get Semantic Synchrony

Ah, the easy part:

git clone https://github.com/synchrony/smsn.git
cd smsn

To build SmSn, you will need a Java compiler (version 1.8+) and Gradle (version 8.x). To build the entire project:

gradle :smsn-server:shadowJar

The result of a successful build is the file smsn-server/build/libs/smsn-server-*-all.jar, where * is the current SmSn version.

Step 2: install Gremlin Server

Download Gremlin Server 3.6.4, unzip it, and move it to the location from which you would like to run it.

Step 3: install the Neo4j plugin

For Neo4j support, cd into Gremlin Server's directory and execute:

bin/gremlin-server.sh install org.apache.tinkerpop neo4j-gremlin 3.6.4

If you encounter any issues during this process, be sure to read the TinkerPop documentation on Grape configuration for Gremlin.

Also note Groovy 4.x is expected. If your environment contains an older version of Groovy, it may be necessary to upgrade first (e.g. brew update; brew upgrade groovy on macOS) and/or delete your ~/.groovy directory.

Step 4: install the SmSn plugin

For SmSn support, you must create a smsn directory under gremlin-server/ext and copy the SmSn Server standalone JAR into it:

mkdir -p ext/smsn/plugin
cp $SMSN_DIR/smsn-server/build/libs/smsn-server-*-all.jar ext/smsn/plugin

...where SMSN_DIR is the SmSn source directory. This assumes that you have already built SmSn as in Step #1.

Step 5: configure Gremlin Server for use with SmSn

Now we need to tell Gremlin Server about your graph and how you want to access it. There will be one configuration file for the graph, and another for the plugin.

Modify the file neo4j-example.properties and put it in Gremlin Server's conf directory, replacing the value of gremlin.neo4j.directory with the file system location of your graph. If this directory does not already exist, it will be created.

Next, modify the file smsn-example.properties and put it in Gremlin Server's conf directory, replacing the value of net.fortytwo.smsn.activityLog; this is a flat file to which a stream of view and edit operations will be recorded. Configuration properties for other SmSn features can also be set here.

Finally, modify the file gremlin-server-smsn-example.yaml and put it in Gremlin Server's conf directory, replacing the graphs/graph and scriptEngines/smsn/scripts values with the names of the two files created above, if different.

Step 6: start Gremlin Server

Assuming you have placed gremlin-server-smsn-example.yaml in Gremlin Server's conf directory, you can start the server (while giving it some extra heap space) with:

export JAVA_OPTIONS="-Xmx500M"
bin/gremlin-server.sh conf/gremlin-server-smsn-example.yaml

It is best to start Gremlin Server, which should now be running and serving the graph you have configured, in a screen session or as a background process. You should see some output like this:

[INFO] GremlinServer -
         \,,,/
         (o o)
-----oOOo-(3)-oOOo-----
[INFO] GremlinServer - Configuring Gremlin Server from conf/gremlin-server-smsn.yaml
[...]
[INFO] GraphManager - Graph [graph] was successfully configured via [conf/neo4j-joesgraph.properties].
[INFO] ServerGremlinExecutor - Initialized Gremlin thread pool.  Threads in pool named with pattern gremlin-*
[...]
[INFO] ServerGremlinExecutor - A GraphTraversalSource is now bound to [g] with graphtraversalsource[neo4jgraph[Community [/tmp/neo4j]], standard]
[...]
[INFO] GremlinServer$1 - Channel started at port 8182.

Step 6.1: test Gremlin Server

If using HTTP, you can test that Gremlin Server is running with:

host=localhost
port=8182
curl http://$host:$port/gremlin

If using WebSocket (note that this will soon become the default), use:

host=localhost
port=8182
curl -i -N -vv -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Host: $host" -H "Origin: http://$host" -k "http://$host:$port/gremlin"

Step 7: install Emacs

Emacs 23 or higher is required for use with Semantic Synchrony. Download and install the appropriate distribution for your environment.

Step 8: install SmSn-mode for Emacs

SmSn-mode is the Emacs major mode which acts as a user interface to your graph of notes and properties, stored in Neo4j and made accessible by Gremlin Server and the SmSn script engine. It can be found in its own GitHub repository here and downloaded with

git clone https://github.com/synchrony/smsn-mode.git

One way to add SmSn-mode and its dependencies to your Emacs environment is to create a directory under ~/.emacs.d, and within this, create a symbolic link to SmSn-mode:

mkdir ~/.emacs.d/elisp
ln -s WHERE/IT/IS/smsn-mode/lisp ~/.emacs.d/elisp/smsn-mode-lisp

(Rather than WHERE/IT/IS, substitute the path to the smsn-mode folder you created when you ran git clone.)

Now all you need is to add a few lines to your ~/.emacs initialization file. You can copy and modify the contents of the example .el file here or follow along below.

To add the library directory to the Emacs load-path and load SmSn-mode:

(let ((default-directory "~/.emacs.d/elisp/"))
      (normal-top-level-add-subdirs-to-load-path))
(require 'smsn-mode)

To use the shared graph at fortytwo.net

This way you don't have to have smsn (the back end server) installed at all. Just add the following line to your .emacs file:

(defvar smsn-server-host "fortytwo.net")

Optional tweaks | Troubleshooting

If Gremlin Server is not accessible at the default 127.0.0.1:8182, or does not use the default HTTP protocol, override the smsn-server-host, smsn-server-port, and/or smsn-server-protocol variables:

(defvar smsn-server-protocol "websocket")  ;; use "http" or "websocket"
(defvar smsn-server-host "example.org")
(defvar smsn-server-port 8182)

If you plan to keep your knowledge base in sync with a GraphML file, add a default location for the file:

(defvar smsn-default-graphml-file "/data/my-graph.xml")

Additional file-related variables -- for export only -- include smsn-default-vertices-file (for all notes in a tab-separated format), smsn-default-edges-file (for an adjacency list of parent-child relationships), and others for advanced or experimental features.

Step 9: nirvana

Provided that Gremlin Server is running, you should be able to use SmSn-mode key bindings, all of which begin with C-c, to interact with your knowledge graph as soon as you start Emacs and type:

M-x smsn

To start, you can either create a root atom with C-c n or import an existing graph from GraphML with C-c C-r g.

This brief howto explains everything you will need to know to use Semantic Synchrony. It assumes no prior familiarity with Emacs, knowledge graphs, or any other technology. (For a brief list of critical commands, or the complete list, see the smsn-mode wiki.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly