org-brain

org-brain implements a variant of concept mapping in Emacs, using org-mode. It is heavily inspired by a piece of software called The Brain (but currently with a more limited feature set), you can view an introduction to that program here.

You can think of org-brain as a combination of a wiki and a mind map, where each wiki page / mind-map node is an org-mode file which resides in your org-brain-path (a directory containing all your org-brain files). These files are called entries. Entries can link to other entries, and you can then view the network of links as a mind map, using M-x org-brain-visualize.

PINNED:  Index


               / Python              Game development / Game design
               / Programming books           |
   Programming / Emacs                       |
         |                                   |
         *-----------------*-----------------*
                           |
                           V
                    Game programming

Game Maker  Unity

-----------------------------------------------

- https://en.wikipedia.org/wiki/Game_programming

/* Gamasutra Articles
   - Passing Through Ghosts in Pac-Man
   - In-House Engine Development: Technical Tips

/* Brainchildren

Above is a visualization of the game programming entry (as can be seen in the middle). Above the entry title we can see that the entry has two parents (other entries which link to game programming): programming and game development. You can also see the siblings and which parent they come from: python, programming books, emacs, and game design. Below the entry title we can see the children of the entry: Game Maker and Unity. At the very top you’ll find pinned entries (entries which will be shown independent of the visualized entry).

At the bottom the entry’s table of contents (headlines in the buffer) is shown: Gamasutra Articles and Brainchildren. You can also see the resources of the entry: the two Gamasutra articles and the Wikipedia link. Resources can be org-mode links in the entry file, or org attachments.

The parents, children, siblings, headlines and resources are all links; they can be pressed to visualize other entries, visit resources etc.

Setup and requirements

The easiest way is to get org-brain from MELPA. If you do not want to do that, clone the repository or download org-brain.el and add it to your load-path. The example below is using use-package and that you’re using MELPA, but you could use (require 'org-brain) or add a :load-path to use-package instead.

(use-package org-brain :ensure t
  :init
  (setq org-brain-path "directory/path/where-i-want-org-brain")
  ;; For Evil users
  (eval-after-load 'evil
    (evil-set-initial-state 'org-brain-visualize-mode 'emacs))
  :config
  ;; Save/load org-brain caches to/from disk
  (org-brain-activate-cache-saving))

1. org-brain requires Emacs 25, org-mode 9. These need to be part of your Emacs.
2. Configure org-brain-path (defaults to /brain in your org-directory) to a directory where you want to put your org-brain files (which could be the location where you already keep your org files if you wish to transform your existing org files into org-brain files). You can set this with the example config presented above or through the customize interface,
3. If you are an evil user, you’ll want to add (evil-set-initial-state 'org-brain-visualize-mode 'emacs) to your org-brain configuration (see example above).
4. org-brain uses caches in order to speed up loading of entries. If you want to save these caches between Emacs sessions (saving time when you restart Emacs) put (org-brain-activate-cache-saving) in your init (included in example above).
5. If not using org-brain-activate-cache-saving you might want to eagerly build some of the caches (rather than wait to have them built automatically in a lazy way), you may use org-brain-build-caches either interactively or programatically, perhaps during Emacs startup time (while you get your coffee). You’ll be adding about 15 seconds to Emacs startup time in exchange for the same savings of save on your initial use of org-brain.

Usage

Primarily you should interact with the M-x org-brain-visualize interface in order to benefit from automatic caching and thus dramatic speed gains (~30x faster).

Once in the org-brain-visualize interface/mode, via M-x org-brain-visualize, you can type:

1. “o” to open the current entry in your org-brain for editing.
2. “c” to create a child for the current entry. You may enter several children at once separated by org-brain-batch-separator, “;” by default, to simultaneously create more than one. For instance pressing c and then guitar; mandolin;banjo would add guitar, mandolin and banjo as children. Currently it isn’t possible to use completion when batch entering children/parents, so it is best used for adding non-existing entries.

<<<<<<< HEAD

=======

>>>>>>> upstream/master If you add children to a file with org-brain-visualize, the links to the child entries will be added under the first headline in the file with the brainchildren tag. If this headline doesn’t exist, a headline named Brainchildren will be created and will be given the tag. If you want another default name for these headlines, you can customize org-brain-children-headline-default-name. <<<<<<< HEAD

1. “p” to create a parent for the current entry. You may enter several parents at once separated by org-brain-batch-separator, “;” by default, to simultaneously create more than one.
2. “P” to pin the current entry (if it is already pinned, then org-brain will respect that)
3. “r” to rename the current entry This will only change the filename and entry name, not the #+TITLE of the entry.
4. “t” to add or change the title of the current entry This will create a new title, prompting you for the value. If a title, #+TITLE: some-title, already exists then it will replace it with the new title you’ve provide.

=======

1. “C” to remove a child (link) for the current entry. This does not delete the file pointed to by the child (link). You may enter several children at once separated by org-brain-batch-separator, “;” by default, to simultaneously remove more than one.
2. “p” to create a parent for the current entry. You may enter several parents at once separated by org-brain-batch-separator, “;” by default, to simultaneously create more than one.
3. “P” to remove a parent for the current entry. You may enter several parents at once separated by org-brain-batch-separator, “;” by default, to simultaneously remove more than one.
4. “n” to pin the current entry (if it is already pinned, then org-brain will respect that)
5. “N” to remove a pin from the current entry
6. “r” to rename the current entry This will only change the filename and entry name, not the #+TITLE of the entry.
7. “t” to add or change the title of the current entry This will create a new title, prompting you for the value. If a title, #+TITLE: some-title, already exists then it will be replaced with the new title you’ve provide.
8. “T” to remove a title of the current entry altogether.

>>>>>>> upstream/master

Here is the the full list of keybindings:

j / TAB	Goto next link
k / S-TAB	Goto previous link

<<<<<<< HEAD

c	Add child
p	Add parent
P	Add pin
t	Add or change title

=======

c	Add child(ren)
C	Remove child(ren)
p	Add parent(s)
P	Remove parent(s)
n	Add pin
N	Remove pin
t	Add or change title
T	Remove title

>>>>>>> upstream/master

l	Add resource link
C-y	Paste resource link
a	Add resource attachment
o	Open and edit the visualized entry
f	Find/visit another entry to visualize
r	Rename this, or another, entry

In order to link to other entries, use an org-mode link with brain: type, its easiest to use C-c C-l brain: TAB or =M-x <<<<<<< HEAD org-brain-insert-link=.

M-x org-brain-agenda can be used to run org-agenda on your org-brain files.

======= org-brain-insert-link=.

M-x org-brain-agenda can be used to run org-agenda on your org-brain files. >>>>>>> upstream/master

If you add resources via org-brain-visualize they will be entered inserted under the current heading in the visualize buffer (link resource will be added as list items at the top of the heading in the entry file). If you’re not under a heading in the visualize buffer, the resources will be added to Brainchildren, as in the case with adding new children.

Editing Brainchildren manually is off the golden path. If you edit Brainchildren manually, i.e., outside the org-brain-visualize interface, then the caches will be inconsistent with actual state on disk. To remedy this situation, you may use M-x org-brain-invalidate-all-caches after making such edits. Subsequently the caches will be rebuilt and speed of the org-brain-visualize interface/mode will become very fast again after an initial cache miss (which will cause the caches to be built). org-brain-files cache is built all at once on first cache miss <<<<<<< HEAD while org-brain-children-cache, org-brain-parents-cache, and org-brain-pins-cache are necessarily built node by node. Subsequent returns to ======= while org-brain-children-cache, org-brain-parents-cache, and org-brain-pins-cache are necessarily built node by node. Subsequent returns to >>>>>>> upstream/master said cached nodes will be approximately 30x faster.

Other useful packages

There’s some missing functionality in org-brain, which could be useful, especially regarding finding text, etc.. However, there are many other packages for which might be useful alternatives. Below are some suggestions (feel free to create an issue or send a pull request if you have more examples).

deft

An Emacs mode for quickly browsing, filtering, and editing directories of plain text notes, inspired by Notational Velocity.

You can add the function below to your init-file.

(defun org-brain-deft ()
  "Use `deft' for files in `org-brain-path'."
  (interactive)
  (let ((deft-directory org-brain-path)
        (deft-recursive t)
        (deft-extensions '("org")))
    (deft)))

helm-org-rifle

It searches both headings and contents of entries in Org buffers, and it displays entries that match all search terms, whether the terms appear in the heading, the contents, or both.

You can add the function below to your init-file.

(defun helm-org-rifle-brain ()
  "Rifle files in `org-brain-path'."
  (interactive)
  (helm-org-rifle-directories (list org-brain-path)))

org-board

org-board is a bookmarking and web archival system for Emacs Org mode, building on ideas from Pinboard. It archives your bookmarks so that you can access them even when you’re not online, or when the site hosting them goes down.

emacs-freex

Emacs freex is a Pymacs/SQLite/Elisp system that implements a transcluding wiki. Emacs-freex is not compatible at this time with org-mode. Despite this, emacs-freex is an impressive system for maintaining a wiki. Further, because the data is stored both in files on disk and in an SQLite database, it opens the possibility for implementing something like org-brain’s visualize interface (ala TheBrain’s “plex”) by talking with SQLite, via Pymacs, to return the relationships between nodes. This would consistute a lot of work to implement but would be very impressive. If someone was to also add LaTeX rendering inside emacs-freex nuggets also, those two additional features would make emacs-freex more compelling. As it is, practically speaking, you may think of org-brain as implementing many of the features of emacs-freex, but with all of org-mode’s goodness included.