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, and you can view an
introduction to that program here. They also provide a blog with great ideas of
how you can think when organizing your Brain.
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, or a headline with an ID property in one of those files. These
are called entries. Entries can be linked together, and you can then
view the network of links as a mind map, using
PINNED: Index +-Python Game development-+-Game design +-Programming books | Programming-+-Emacs | | | +-----------------+-----------------+ | V Game programming <-> Computer games Game Maker Unity --- Resources --------------------------------- - https://en.wikipedia.org/wiki/Game_programming - Passing Through Ghosts in Pac-Man - In-House Engine Development: Technical Tips --- Text -------------------------------------- Game programming is the art of programming computer games...
When visualizing an entry, you will see the entry’s relationship to other
entries. There are four different types of relationships in
- Entries above the visualized entry. If the visualized entry is a
headline, then the parent headline in the
org-modefile will be one of the parents. In the case of top level headlines, the file itself will be considered a parent. Additional parents can be added manually. In the example above, Programming and Game development are parents of the visualized Game programming entry.
- Entries below the visualized entry. This will by default be subheadings of the visualized entry (or level one headlines, if the visualized entry is a file). You can add other children, residing elsewhere, manually. In the example above, Game Maker and Unity are the children of Game programming.
- These appear to the right of the parent entries. Siblings are the other children of the visualized entry’s parents.
- These appear to the right of the visualized entry. Friends provide a way of adding a hierarchy independent two-way relationship between two entries. Friends must be added manually. In the example above, Computer games and Game programming are friends.
Here’s an article describing how you can use the different relationships (The
Brain’s jump thoughts are the equivalent of friends in
Apart from the visualized entry’s relationships,
org-brain-visualize also show
pinned entries, which are shown independently of the visualized entry; Index
is a pinned entry in the example above.
org-brain-visualize also show a list
of the entry’s resources (links and attachments), and the text in the entry. The
example above have three resources, and a short text. The resources and text is
There’s also the option to visualize the entry as a tree, or similar to a mind map, where you can zoom in order to show grandparents and grandchildren.
The relationship entries, pinned entries and resources are all links; they can be pressed/clicked 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 this git repository or download
org-brain.el and add it to your
load-path. The example below is using use-package and assumer that you’re using
MELPA, but you could use
(require 'org-brain) or add a
(use-package org-brain :ensure t :init (setq org-brain-path "directory/path/where-i-want-org-brain") ;; For Evil users (with-eval-after-load 'evil (evil-set-initial-state 'org-brain-visualize-mode 'emacs)) :config (setq org-id-track-globally t) (setq org-id-locations-file "~/.emacs.d/.org-id-locations") (push '("b" "Brain" plain (function org-brain-goto-end) "* %i%?" :empty-lines 1) org-capture-templates) (setq org-brain-visualize-default-choices 'all) (setq org-brain-title-max-length 12))
org-brainrequires Emacs 25 and org-mode 9. These need to be part of your Emacs.
org-directory) to a directory where you want to put your
org-brainfiles (which could be the location where you already keep your org files if you wish to transform your existing org files into
org-brainfiles). You can set this with the example config presented above or through
M-x customize-group RET org-brain.
- If you’re an evil user, you’ll want to add
(evil-set-initial-state 'org-brain-visualize-mode 'emacs)to your
org-idin order to speed things up. Because of this, the variable
t(which it already is by default). You may want to modify
- You might want to add information at the end of an entry, without visiting the file. A way to do this is to use a capture template, such as the one presented above.
- If you have a lot of entries, it might take some time to gather information
about all entries when using
org-brain-visualize. You could change the value of
org-brain-visualize-default-choices(which is =’all= by default) to only include files, or even just files in the direct root of
- If you feel that
org-brain-visualizeis too cluttered, you may want to set
- If you have very long entry names,
org-brain-visualizemay take a lot of horizontal space. You can cap the shown length of entry titles, by setting
Headline and file entries
There are two types of entries in
org-brain: headline entries and file
entries. For the most part these are used the same way, and the main difference
between them is how their content is stored inside your
All .org-files inside the
org-brain-path are considered as file entries (the
content typically being the text before the first headline in the file) and all
headlines with an ID property inside these files are considered as headline
If you have a headline entry, which you want to convert to a file entry, use
M-x org-brain-headline-to-file. Unfortunately there is currently no function
to convert a file entry into a headline entry.
If you find that
org-brain is missing entries, or list entries which doesn’t
exist, try using
M-x org-brain-update-id-locations, which syncs the
org-brain entries with the
org-id caching system.
The primary usage of
org-brain is through
M-x org-brain-visualize (which you
might want to bind to a key). From there you can browse entries, add/remove
relationships, open entries for editing etc. The following keybindings are
|m||Toggle between normal and mind-map visualization.|
|j or TAB||Goto next link|
|k or S-TAB||Goto previous link|
|b||Like the back button in a web browser.|
|h or *||Add a new child headline to entry|
|c||Add an existing entry, or a new file, as a child|
|C||Remove one the entry’s child relations|
|p||Add an existing entry, or a new file, as a parent|
|P||Remove one of the entry’s parent relations|
|f||Add an existing entry, or a new file, as a friend|
|F||Remove one of the entry’s friend relations|
|n||Toggle if the entry is pinned or not|
|t||Change the title of the entry.|
|T||Change the tags of the entry.|
|d||Choose an entry to delete.|
|l||Add a new resource link in entry|
|r||Shortcut to choose and open a resource from the entry.|
|C-y||Add a new resource link from clipboard|
|A||Archive the entry (headline entries only)|
|o||Open current entry for editing|
|O||Choose and edit one of your |
|v||Choose and visualize a different entry|
|w||Visualize one of your entries at random.|
|W||Visualize at random, in a set interval. |
You can also use
org-store-link inside of
org-brain-visualize in order to
store a link to the currently visualized
When using the mind map visualization (toggle by pressing
m), you can use the
following keybindings in order to show or hide successive levels of hierarchy relative to the current entry.
|+||Show one more level of entries to the right (children of children, etc.)|
|-||Hide rightmost level of descendant entries|
|z||Show one more level of entries to the left (parents of parents, etc.)|
|Z||Hide leftmost level of ancestor entries|
You can edit
org-brain entries directly from
org-mode. You can use the
org-mode outline structure to define parent/children relationships,
but keep in mind that only entries with an
ID property will be considered as
M-x org-id-get-create to create an
property to the current
org-mode headline. Another alternative is to use
org-brain-refile which will create the ids for you.
Most of the commands available in
org-brain-visualize can also be used in
org-mode directly, in which case they will operate on the “entry at point”. In
other words you can use
M-x org-brain-add-child directly from
order to add a child to the
org-brain entry at point. You may also want to use
org-brain-goto-<relationsship> to navigate between entries.
You may want to create a link to an
org-brain entry in an
org-mode file (not
org-brain file itself).
org-brain provides several link types
for this purpose. You can use
org-insert-link (bound to
C-c C-l in
org-mode by default) to insert one of these links. They all have in common
that they, when clicked, will open the
org-brain entry for editing. When
inserting a link like this,
org-brain will run completion upon all your
- The default kind of link. Just let’s you visit another
org-brainentry when clicked.
- When inserted using
org-insert-linkthis will make the linked entry a child to the current
org-brainentry, upon completion. Keep in mind that this doesn’t work if you type the link manually; only by completion through
brain-child:but makes the linked entry a parent of the current entry.
brain-child:but adds the linked entry as a friend.
The names of the relationship inserting links (
brain-friend) can be customized with the variables
org-brain-friend-link-name. This customization should be done before loading
org-brain. If you’re using
use-package, put the customization in the
If you try to add a child/parent/friend to an entry which doesn’t exist, that
entry will be created. The name of a new entry can be written like this:
headline will be created as a level one headline in
When adding children, parents, or friends, multiple entries can be added at once
by separating their titles with
org-brain-entry-separator (which is
default). For instance
M-x org-brain-add-parent RET music;artists would add
artists as parents.
Another available command is
M-x org-brain-agenda, which can be used to run
org-agenda on your
Slashes in file entry titles
When giving a file entry a title, the title can not contain slashes (
Renaming files in
Headline entries use
org-id to identify themselves, so the headlines can be
manually renamed without worries. File entries, on the other hand, uses the
filename as the identifier. This will cause problems if you try to manually
rename files inside of
In order to rename a file, use
org-archive has a problem in
org-brain: relationships are maintained, even
though the entry should really be removed from the brain. Because of this,
org-brain-archive instead. This command removes relationships to
the entry in the brain, before archiving it. The command also inserts handy
links to the archived entry’s relationships.
You might have a headline which you do not really want as an entry in
org-brain. The most basic way to exclude such a headline is simply to not add
ID property to it. However,
org-brain also provide two tags, which you
can use to tag the headline:
- This tag excludes the headline, and its subheadings, from your
org-brainentries. You can change the tag name by modifying
- This tag does not exclude the headline, but it excludes the
subheadings. You can change the tag name by modifying
org-brain-exclude-children-tag. Works on file entries.
The following tags modifies the kind of information that is shown when an entry is visualized:
- Do not show the entry’s text in
org-brain-visualize. You can change the tag name by modifying
- Do not show the entry’s resources in
org-brain-visualize. You can change the tag name by modifying
- By default local child entries aren’t shown as text. By
setting this tag the entry get the entire subtree as text. You can change
the tag name by modifying
org-brain-show-children-tag. Works on file entries.
You may add a description to an entry, which should be a short summary of what the entry is about. The description will be shown in
org-brain-visualize as mouse tooltips for links, and also by
eldoc-mode if point is at a link. Add a description by using a
#+BEGIN_description block. Here’s an example:
* org-brain.el :PROPERTIES: :ID: 7cf9563e-24e7-4823-8742-64b7fcc5cafb :END: #+BEGIN_description Package for concept mapping using org-mode. #+END_description ...
At the moment there’s no way to add/remove/change descriptions directly from the
org-brain-visualize interface, sorry!
Having multiple brains
You can have multiple brains simply by having more than one brain folder. In this way, each folder becomes a separate brain. You can switch between these using
org-brain creates and uses several headline properties in the
These properties are also mirrored as file keywords at the top of file entries,
These properties/keywords are not meant to be manipulated directly! If you
want to remove these properties, use the corresponding command instead
org-brain-remove-child or similar).
You might also see that
org-brain inserts a
RESOURCES drawer. It is okay to
modify this drawer manually.
org-brain is slow!
If you feel that
org-brain is slow while indexing your entries (for instance when running
M-x org-brain-visualize) you can customize
org-brain-file-entries-use-title, and set it to
nil. This will display file names when indexing, instead of the file entry’s title, which is faster.
Backwards compability breaking changes in 0.4
This is only relevant if you’ve been using org-brain before version 0.4
As of version 0.4 (June 2017)
org-brain has been rewritten, in order to
increase performance and add more options. Because of this, older setups are
considered obsolete. Prior to 0.4 only files were considered entries, but now
also headlines with an
ID property are included as entries. Prior to 0.4
org-brain was using the
brain: link and
#+BRAIN_PINNED: file keyword to
connect files, which was slow due to the need of searching all files for links.
In version 0.4
org-brain uses a combination of headline properties, file
org-id, and a data file (
No data in old configurations should be lost, but you’ll have to update the
connections between entries. This can be done by using
org-brain-create-relationships-from-links, but please backup your
It is still possible to add children to an entry by using the
brain-child: link, but
only if the link is inserted with
org-insert-link (bound to
C-c C-l in
org-mode by default). Linking to specific headlines in a file, via
brain:filename::*Headline is deprecated and will no longer work, instead you
can convert the headline to an entry and link directly to that.
Other useful packages
There’s some missing functionality in
org-brain, which you may find useful.
However there are other packages which might improve your
experience. Below are some suggestions (feel free to create an issue or send a
pull request if you have more examples), all of them should be available on
A simple command that takes a URL from the clipboard and inserts an org-mode link with a title of a page found by the URL into the current buffer.
Here’s a command which uses
org-cliplink to add a link from the clipboard as an
org-brain resource. It guesses the description from the URL title. Here I’ve bound it to
(defun org-brain-cliplink-resource () "Add a URL from the clipboard as an org-brain resource. Suggest the URL title as a description for resource." (interactive) (let ((url (org-cliplink-clipboard-content))) (org-brain-add-resource url (org-cliplink-retrieve-title-synchronously url) t))) (define-key org-brain-visualize-mode-map (kbd "L") #'org-brain-cliplink-resource)
link-hint.el is inspired by the link hinting functionality in vim-like browsers and browser plugins such as pentadactyl. It provides commands for using avy to open or copy “links.”
link-hint you could bind
link-hint-open-link to a key, and
use it in
org-brain-visualize-mode. If you only want to use
org-brain-visualize-mode, you could add the following to your init-file:
(define-key org-brain-visualize-mode-map (kbd "C-l") #'link-hint-open-link)
Converts simple ASCII art line drawings in the region of the current buffer to Unicode.
ascii-art-to-unicode is useful if you want
org-brain-visualize-mode to look
a bit nicer. After installing, add the following to your init-file:
(defface aa2u-face '((t . nil)) "Face for aa2u box drawing characters") (advice-add #'aa2u-1c :filter-return (lambda (str) (propertize str 'face 'aa2u-face))) (defun aa2u-org-brain-buffer () (let ((inhibit-read-only t)) (make-local-variable 'face-remapping-alist) (add-to-list 'face-remapping-alist '(aa2u-face . org-brain-wires)) (ignore-errors (aa2u (point-min) (point-max))))) (with-eval-after-load 'org-brain (add-hook 'org-brain-after-visualize-hook #'aa2u-org-brain-buffer))
A utility package to collect various Icon Fonts and propertize them within Emacs.
all-the-icons you could decorate the resources in
org-brain, by using
org-brain-after-resource-button-functions. Here’s a small example:
(defun org-brain-insert-resource-icon (link) "Insert an icon, based on content of org-mode LINK." (insert (format "%s " (cond ((string-prefix-p "http" link) (cond ((string-match "wikipedia\\.org" link) (all-the-icons-faicon "wikipedia-w")) ((string-match "github\\.com" link) (all-the-icons-octicon "mark-github")) ((string-match "vimeo\\.com" link) (all-the-icons-faicon "vimeo")) ((string-match "youtube\\.com" link) (all-the-icons-faicon "youtube")) (t (all-the-icons-faicon "globe")))) ((string-prefix-p "brain:" link) (all-the-icons-fileicon "brain")) (t (all-the-icons-icon-for-file link)))))) (add-hook 'org-brain-after-resource-button-functions #'org-brain-insert-resource-icon)
An Emacs mode for quickly browsing, filtering, and editing directories of plain text notes, inspired by Notational Velocity.
deft, 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)))
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.
helm-org-rifle, you can add the function below to your
(defun helm-org-rifle-brain () "Rifle files in `org-brain-path'." (interactive) (helm-org-rifle-directories (list org-brain-path)))
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.
The Emacs Wiki has an article about wiki modes in Emacs.
Org-wiki is a org-mode extension that provides tools to manage and build personal wiki or desktop wiki where each wiki page is a org-mode file.
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
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
org-mode’s goodness included.