Silver-Brain

Notice

I have been using it for a year or so and have been re-thinking of this software for some time. I would like to re-design it and make it more useful for general purpose (and surely for myself).

1.4.4 is the last stable version of existing functionality.

Next release will be a re-implementation of whole software, versioned starting from 2.0.0.

Overview

Prologue

Back to the time when I was preparing the final examinations as a bachelor student. I wrote down all the concepts to a big white paper in a structured way in order to review what I have learned. I draw lines between concepts and labeled the relationship. For each concept, I wrote some text describing it (usually the paper was too small for large trunk of text).

After Emacs and its decent Org Mode became best partner for my electronic life, I always wanted a software that helps me record everything in a structured way, like described above.

I found org-brain. I used it for some time, but there were some drawbacks that made me stop using it:

• Issue #127 is a very important reason. Not being able to use rich-text in it really made me sad. (This issue has been fixed now.)
• Although it is doable via org-brain-rename-file, but the inconsistency between file name and concept name made me uncomfortable, really.
• I was concerned about the performance of plain text when the number of concepts grow too large.

Introduction

Silver Brain is a Brain like software and is directly inspired by org-brain. It helps you build your very own personal knowledge center.

It has the following features:

• Edit concepts using Emacs Org Mode (or probably other major modes in future).
• Maintain the relationship between concepts, including paternity and friendship.

The following technical decisions were made:

• Concepts are stored in a single SQLite file. Easy to maintain and synchronize.
• Separation between back-end and front-end. This makes it possible to develop another UI. The directory web-ui/ contains a proof-of-concept demonstration.
• Back-end code was written in Common Lisp (a bless or a curse).

Screenshots

Change Log

Please refer to CHANGELOG.org.

Usage

Installation

External Dependencies

Make sure SQLite 3 is installed on your system.

Add silver-brain System to ASDF Path

It is essential for the following installation process. And it is a good idea if you would like to load silver-brain using ASDF during manual installation.

• When using Roswell, you may simply create a symbolic link of silver-brain

directory in ~/.roswell/local-projects/ directory.

• Otherwise, you need to add the path of Silver Brain to asdf:*central-registry*.

Using Installation Script

An installation script is provided for the sake of quick installation. Before running it, you need to put Silver Brain project under a directory that your local ASDF can find, i.e. (ql:quickload :silver-brain) does work.

cd /path/to/silver-brain/
./install.sh

It mainly does the following things:

1. Build back-end server using Roswell.
2. Install the generated binary to ~/.roswell/bin/ directory.
3. Copy Emacs Lisp files to ~/.silver-brain/ directory.

You may need to add ~/.roswell/bin/ to your PATH in order to use silver-brain anywhere.

Installing Manually

Installing Back-End Server

Roswell Way

It is highly recommended to use Roswell to build and install Lisp systems for its simplicity.

cd /path/to/silver-brain/backend/
ros build silver-brain.ros

Legacy Way

It is a little bit complicated not to use Roswell. You may load Silver Brain into an image and dump it.

See The Common Lisp Cookbook for more details.

Installing Emacs UI Code

Copy the emacs/ directory to somewhere Emacs can find.

Configuration

The server uses 5000 as the port. Currently this cannot be changed unless modifying the source code.

For Emacs UI to work, the following snippet needs to be added into the Emacs configuration file:

(add-to-list 'load-path "~/.silver-brain/emacs/")
(use-package silver-brain
  :init
  ;; The port of back-end server. Does NOT affect server side.
  (setq silver-brain-server-port 5000)

  :bind
  ("C-c b" . silver-brain))

Manual

Concepts

The core concept of Silver Brain is concept. A concept a node in your knowledge network. It contains title, content etc.

Concepts are connected via relations. A concept can be either parent, child or friend of another one. You may think of parent/child as a single directional link, while friend is a bi-directional link.

Practically, parent/child can be used to connect concepts with logical precedence, e.g. Editor and Emacs. And friend can be used to connect concepts with slightly weak relations, e.g. Emacs and Vim, hopefully ;-)

Software

The back-end server accepts -h or --help argument. Please refer to the help.

For Emacs side, the command silver-brain is the entry point of the software.

The following is a list of commands defined for silver-brain-mode:

Command	Binding	Description
silver-brain-refresh	g	Refresh current concept
silver-brain-new-concept	n	Create a new concept
silver-brain-rename	r	Rename current concept
silver-brain-save	s	Save changes of current concept
silver-brain	o	Open a new concept
silver-brain-new-window	O	Open a new concept in new window
silver-brain-delete	d	Delete current concept
silver-brain-add-parent	p	Add a parent of current concept
silver-brain-add-child	c	Add a child of current concept
silver-brain-add-friend	f	Add a friend of current concept
silver-brain-remove-relation	R	Remove a relational concept
silver-brain-kill-concept	q	Kill the concept window
silver-brain-kill-all-concepts	Q	Kill all the concept windows

Implementation

Silver Brain was designed as a traditional Web application that back-end and front-end code communicates via HTTP requests. The concepts and relations are stored in a local SQLite file.

The web-ui directory contains browser UI code written using Vuetify.

Known Issues

The Software Needs to Be Restarted If DB file is Changed Externally

If you use a synchronization software, such as Syncthing, you may need to restart the software after the DB file got synchronized.

This is because the database needs to be re-connected while the current version of Silver Brain cannot handle it well.

The Newly Updated Content is Not Shown

If you run silver-brain-refresh after some modification and says yes to save the new contents, you may notice that the content buffer reverts to the original state.

The solution is simply refreshing the buffer again.

This is because when silver-brain-save is triggered, the modifications are not transferred to the server, thus the first silver-brain-refresh command will receive the old content.

Silver Brain Fails to Start After Quicklisp Update

Because Mito and Clack quickload its dependencies at run-time dynamically, the dependency packages cannot be built into the image. So after upgrading Quicklisp dist, you need to re-build the Roswell binary.