org-exobrain (org-xob)

WIP: org-exobrain. A knowledge management system inspired by zettlekasten, wikis, and all that’s great about org-mode.

Screenshots

Coming soon…

Contents

• Installation
• Usage
• Changelog
• Credits
• Development
• License

Installation

MELPA not available for this release

If you installed from MELPA, you’re done. Just run one of the commands below.

Manual

Install these required packages:

• org-super-links
• org-ql
• helm
• Other I believe these are part of current emacs versions: org, org-element, org-id, cl, cl-lib

Then put this file in your load-path, and put this in your init file:

(require 'org-xob.el)

File Setup

You need to set org-xob-dir, default value is “~/xob”. xob only looks at files in this directory.

There are 4 file types used by xob:

• xob general knowledge base (KB) files. This is intended for long term material.
• xob agenda files which are added to org-agenda-files. All ‘activity’ based content goes in these files and the files are treated as normal org files.
• xob log files. These are similar to agenda files. All day node entries are added here in a date tree. When editing a xob node from a KB file, temporal based material (scheduling, clocking, etc) is sent instead to its corresponding entry in the day node. Only the current log file is added to org-agenda-files.
• xob archive files. Any material sent here is ignored by the xob system and not included in agenda files.

Files are recognized by property headings loocated in the top 1K of the file:

#+PROPERTY: xob t lets xob know to use this file #+PROPERTY: xob-current-file t Current files are those where new material is sent: #+PROPERTY: xob-log t identifies a xob log file #+PROPERTY: xob-agenda t identifies a xob agenda file #+PROPERTY: xob-archive t identifies a xob archive file

If no current file is found for either of the file types, then a new numbered file is created and set as current.

(Coming soon) Likewise, if a file gets too big (based on org-xob-max-KB-filesize), then a new file of that type is created. Default file size value is 2^19 or 524,288 bytes.

Org Setup

org-xob fully relies on org-id and UUID formatted IDs. Please make sure that:

org-id-link-to-org-use-id is set to either: t, create-if-interactive, or create-if-interactive-and-no-custom-id

org-id-method is set to uuid

(setq org-id-link-to-org-use-id t)
(setq org-id-method uuid)

Usage

The central idea is presentation management where xob buffers are not associated with files but are instead treated like windows; they are a place where material is displayed and possibly edited. As such, all content is copied from the original location and pasted into a xob buffer. For current release v0.5, to edit a xob node (note, entry) an indirect buffer is created and narrowed to that entry. Next release will likely also copy the content and then provide syncing capabilities.

This approach allows for great flexibility in interacting with your org files. Unlike zettlekasten approaches, there is no restriction on using a tree structure, you are free to have org headings in a node, vice-versa, and even nest nodes.

Contextual material from both backlinks and forlinks are presented in a dedicated context buffer under ‘source’ headings. ie all backlinks go under the node backlinks heading, and similarly for the forlinks. You can alter what is displayed, simply the headings, their first paragraph, top section, subheadings, or the full content of that node.

Future release will allow for associated material from other sources, such as org-ql searches, or internet content.

New [2025-08-07]: multi-repo support. If you need to partition your knowledge base into distinct repositories you can now add them to the list in org-xob-known-dirs. For now there is no way to combine, each are treated distinctly.

Commands

All commands will start org-xob if it has not started already. General commands are applicable anywhere, Edit buffer commands are relevant in the edit buffer, and Context buffer commands are relevant in that buffer.

Opening a current or new node via org-xob-get-node will open it in an edit buffer. All contextual material is sent to the context buffer. The edit buffer is a clone that is narrowed to the node entry. The context buffer is not read-only so that the headlines can be re-ordered to preference. Any additional content you enter will be ignored, except demoting source headings will screw up insertion of sub-tree content (will be fixed soon).

If the xob system is running, a timer will open a new log day entry at 12:00am. Opening any node for editing will add an entry to the log. (Coming soon): clocking, scheduling, and other org temporal material will apply to the log entry of a node, not the node itself. This applies to knowledge base nodes, not to nodes that are in designated agenda files.

General Commands
org-xob-get-node	Open or create node for editing
org-xob-insert-link	Insert a xob link (to a node) at point
org-xob-open-day	Go to the current day log entry
org-xob-todo-at-point	Create a todo item, insert xob link to here
org-xob-remove-node	Remove entry from system, but do not delete contents
Node Conversion
org-xob-heading-to-node	Convert regular org entry to a xob node
org-xob-log-done	Convert a todo entry into a log entry
org-xob-add-node-labels	Add labels in property drawer (not links)
org-xob-change-node-type	Change node type in property drawer
System Management
org-xob-start	Required: Start the xob system
org-xob-stop	Stopping saves state and cleans up
org-xob-rebuild	Go through all xob files and rebuild xob data structures
org-xob-switch-repo	select a different xob KB
org-xob-add-repo	add new repository
org-xob-remove-repo	remove repository
Edit Buffer
org-xob-toggle-sideline	Toggle the sideline window on/off
org-xob-show-backlinks	Show node backlinks in context buffer
org-xob-show-forlinks	Show node forlinks in context buffer
org-xob-ql-search	(N/A) show ql search results in context buffer
org-xob-refresh-contexts	Refresh all the context sources in context buffer
Context Buffer
org-xob-clear-heading	Clear heading contents
org-xob-to-summary	Show first paragraph
org-xob-to-section	Show section before first subheading
org-xob-to-node-tree	Show only tree structure of source item
org-xob-to-full-node	Show the complete source item
org-xob-refresh-contexts	Refresh context item at point
Bulk Context Operations	(Apply to ALL context entries in buffer)
org-xob-bulk-to-summary	Show summary for all context entries
org-xob-bulk-to-section	Show section for all context entries
org-xob-bulk-to-node-tree	Show tree structure for all context entries
org-xob-bulk-to-full-node	Show full content for all context entries
org-xob-bulk-clear-all	Clear all context entries in the buffer
Region ↔ Node Conversion	(Convert between text regions and nodes)
org-xob-region-to-node	Convert selected text to new node, replace with link
org-xob-node-to-region	Convert node link back to inline text content

Note: Bulk operations work across ALL sources (backlinks, forlinks, etc.) in the context buffer. Use the org-xob hydra with C-s, C-S, C-t, C-T, C-c for quick access to bulk operations.

Region-to-node conversion allows you to:

1. Select text and convert it to a new node (r in hydra or org-xob-region-to-node)
2. Convert node links back to inline text (R in hydra or org-xob-node-to-region)

Tips

• You can customize settings in the org-xob group.
• Use org-xob-auto-display-links to automatically show backlinks and forlinks when opening nodes.
• Toggle auto-display behavior with M-x org-xob-toggle-auto-display-links.

Known Limitations

• **Node Removal**: The org-xob-remove-node function attempts to clean up both outgoing and incoming links when removing a node from the system. However, due to org-super-links internal behavior, some link cleanup operations may not complete successfully. In such cases, warning messages will be displayed, and users may need to manually remove any remaining links if desired. The core functionality (removing the node from the xob system and optionally deleting content) always works correctly.

Configuration

Auto-Display Links

org-xob can automatically display backlinks and forlinks when you open a node for editing:

;; Auto-display both backlinks and forlinks (default: t)
(setq org-xob-auto-display-links t)

;; Auto-display only backlinks
(setq org-xob-auto-display-links 'backlinks)

;; Auto-display only forlinks  
(setq org-xob-auto-display-links 'forlinks)

;; Disable auto-display
(setq org-xob-auto-display-links nil)

;; Toggle interactively
(define-key org-mode-map (kbd "C-c x a") 'org-xob-toggle-auto-display-links)

Auto Dual-Pane Layout

org-xob can automatically set up a dual-pane window layout when starting, with the main editing buffer on the left and context buffer on the right:

;; Enable auto dual-pane layout (default: t)
(setq org-xob-auto-dual-pane t)

;; Disable auto dual-pane layout
(setq org-xob-auto-dual-pane nil)

;; Toggle interactively
(define-key org-mode-map (kbd "C-c x p") 'org-xob-toggle-auto-dual-pane)

;; Manually set up dual-pane layout
(define-key org-mode-map (kbd "C-c x d") 'org-xob-setup-dual-pane)

Changelog

0.6 (WIP)

• Added auto-display links feature: automatically show backlinks and forlinks when opening nodes
• Added org-xob-auto-display-links customization variable
• Added org-xob-toggle-auto-display-links interactive command
• Added auto dual-pane layout feature: automatically set up split-window layout when starting
• Added org-xob-auto-dual-pane customization variable
• Added org-xob-toggle-auto-dual-pane and org-xob-setup-dual-pane interactive commands
• Added bulk context operations: apply display actions to ALL context entries at once
• Added org-xob-bulk-to-summary, org-xob-bulk-to-section, org-xob-bulk-to-node-tree, org-xob-bulk-to-full-node, and org-xob-bulk-clear-all commands
• Extended org-xob hydra with bulk operation keybindings (C-s, C-S, C-t, C-T, C-c)
• Added region ↔ node conversion feature: bidirectional conversion between text regions and nodes
• Added org-xob-region-to-node command to convert selected text to new node with link replacement
• Added org-xob-node-to-region command to convert node links back to inline text content
• Extended org-xob hydra with region conversion keybindings (r, R)

0.5

Initial release.

Credits

This package would not have been possible without the following packages:

• org, org-id, org-element
• org-super-links
• org-ql

Development

Bug reports, feature requests, suggestions — I’ll try to keep up, please be patient, thanks.

License

GPLv3