Endless Org Roam (EOR)

Federated org-roam: link to and search across multiple org-roam knowledge bases.

The Problem

org-roam slows down at scale. Around 1,000 nodes, completion, search, and DB sync become noticeably sluggish. You’re forced to choose: one large knowledge base (slow, comprehensive) or multiple small ones (fast, isolated).

EOR eliminates the trade-off. Keep focused, fast knowledge bases for different domains while maintaining full awareness of the broader knowledge space.

BEFORE                            AFTER (with EOR)

+--------------------+            +----------+  +----------+  +----------+
| One Big KB         |            | Personal |  | Work     |  | Project  |
| ~1000+ nodes       |            | 300 nodes|  | 400 nodes|  | 50 nodes |
| slow completion    |            +-----+----+  +----+-----+  +----+-----+
| slow search        |                  |            |             |
| slow DB sync       |            +-----+------------+-------------+
+--------------------+            |          EOR Federation          |
                                  | cross-link, search, shared view |
                                  +----------------------------------+

Use Cases

• Performance through decomposition – each instance stays small and fast; a 200-node project KB + 500-node personal KB respond instantly
• Knowledge base sharing – share a team KB across users; everyone registers it alongside their personal KB and sees the same team knowledge
• Project-aware main KB – your personal KB stays aware of project KBs without importing their contents; unregister when the project ends
• Read-only isolation – mount a reference KB without filesystem contamination risk; browse and link to it, but EOR won’t modify its files
• Non-destructive onboarding – existing KBs gain one file (eor-instance.org); no schema changes, no note modifications, existing id: links keep working

How It Works

EOR introduces a new eor: link type that resolves local-first, then searches registered instances. The package requires no modifications to org-roam – it extends org-roam purely via org-link-set-parameters and temporary let-bindings of org-roam-directory.

      +-------------------+
      |   EOR Registry    |
      +---------+---------+
                |
     +----------+----------+
     |          |          |
Instance A  Instance B  Instance C
(local)     (local)     (remote)

Features

• Instance Registry – register any existing org-roam directory for federation
• Federated Links – [[eor:node-uuid]] links that resolve across instances
• Cross-Instance Search – eor-node-find searches all instances at once
• Non-Destructive – existing KBs get one sentinel file; nothing else changes
• Circuit Breaker – graceful handling of unreachable instances with auto-recovery
• Collision Detection – warns when a node UUID exists in multiple instances
• Local-First – always checks the current instance before querying others

Installation

straight.el (Doom Emacs)

(package! endless-org-roam
  :recipe (:host github :repo "cuttlefisch/endless-org-roam"))

use-package + straight

(use-package endless-org-roam
  :straight (:host github :repo "cuttlefisch/endless-org-roam")
  :after org-roam
  :config
  (eor-mode 1))

Manual

Clone the repository and add it to your load-path:

(add-to-list 'load-path "/path/to/endless-org-roam")
(require 'endless-org-roam)
(eor-mode 1)

Quick Start

1. Enable EOR:

   (eor-mode 1)
       

2. Register your existing org-roam directory:

   M-x eor-register-instance

   This creates an eor-instance.org sentinel node in your org-roam directory and adds the instance to the federation registry.

3. Register a second org-roam directory:

   M-x eor-register-instance and point it at another directory.

4. Insert a cross-instance link:

   M-x eor-node-insert to search across all instances and insert an eor: link.

5. Follow the link – it resolves local-first, then checks other instances.

Link Format

[[eor:<node-uuid>][description]]                    ;; local-first
[[eor:<instance-uuid>/<node-uuid>][description]]    ;; targeted

• Local-first links search the current instance, then optionally other registered instances (controlled by eor-search-all-instances).
• Targeted links dispatch directly to a specific instance.

Configuration

Variable	Default	Description
eor-verbose	t	Log informational messages
eor-search-all-instances	nil	Search all instances for unqualified links
eor-transport-timeout	5	Timeout (seconds) for transport ops
eor-registry-file	~/.emacs.d/eor-registry.el	Path to the registry file
eor-sentinel-filename	eor-instance.org	Sentinel filename in registered dirs
eor-transport-circuit-threshold	3	Failures before circuit breaker opens
eor-transport-circuit-recovery-timeout	300	Seconds before open circuit retries
eor-include-remote-in-completion	nil	Include remote nodes in org-roam completion

FAQ

Will this break my existing org-roam setup?

No. EOR is purely additive. The only change to your org-roam directory is one new file (eor-instance.org). All existing id: links continue working.

What about performance with many instances?

Local-first resolution means the common case (local node found) is fast. Cross-instance queries are opt-in via eor-search-all-instances. The circuit breaker prevents repeated timeouts against unreachable instances, and automatically retries after eor-transport-circuit-recovery-timeout seconds.

Can multiple users share a knowledge base?

Yes. Each user registers the shared KB directory alongside their personal KB. Everyone gets cross-instance search and linking to the shared content.

Does it work over the network?

Phase 1 supports local filesystem paths (including TRAMP/sshfs mounts). HTTP transport for true remote instances is planned for Phase 3.

Roadmap

1. Phase 1 (current) – Local federation: registry, links, local transport
2. Phase 2 – Cross-instance search and completion integration
3. Phase 3 – HTTP transport, authentication, protocol handler
4. Phase 4 – Caching, backlinks, graph integration

Contributing

See CONTRIBUTING.org for development setup, coding standards, and PR workflow.

License

GPL-3.0-or-later. See LICENSE.