ExcaliBrain

Ghost nodes represent links to files that do not yet exist. They allow you to visualize your intended knowledge structure before you create the actual files.

Key Characteristics

• Identification: They appear as "Virtual" nodes in the graph.
• Styling: By default, they are styled with a semi-transparent red background and a hatched (hachure) fill.
• Lifecycle: A ghost node is automatically replaced by a real file when that file is created. If the last reference to a ghost node is deleted, the node is removed from the index.

Configuration

• Visibility: You can toggle the visibility of these nodes in the settings via settings.showVirtualNodes.

To maintain performance within Obsidian, ExcaliBrain employs several optimization techniques:

• Lazy evaluation: Dataview (DV) fields are only parsed when a page is actually viewed (tracked via the dvIndexReady flag).
• Neighbor filtering: Filters are applied during the retrieval phase rather than at the storage phase to keep the index lightweight.
• Link deduplication: Uses map-based storage to prevent duplicate links.
• Case-sensitivity handling: Uses lowercase map lookups to ensure cross-platform consistency.
• Debounced rendering: Rapid successive changes are coalesced into a single render cycle to prevent UI lag.

ExcaliBrain indexes all HTTP(S) links within your vault to create a hierarchical view of web references.

How it works

1. Extraction: The URLParser scans markdown files using regex to find links like [label](https://example.com) or direct URLs.
2. Node Creation:
   • Each unique URL becomes a Page node.
   • Each unique URL origin (protocol + domain) becomes an origin node.
   • URLs are linked as children of their respective origins, enabling hierarchical browsing of web references.
3. Syncing: The parser automatically updates the index when files are created, modified, or deleted via vault event listeners.

ExcaliBrain unifies different types of connections into a single Relation structure. This allows you to query and filter the graph using a consistent interface regardless of how the connection was formed. The plugin reconciles the following:

• File hierarchy: Based on folder structures.
• Tag hierarchy: Based on the tag-tree.
• Explicit ontology: Defined via Dataview fields.
• Inferred links: Standard Obsidian links.
• HTTP links: Parsed via URLParser and treated as inferred links.

ExcaliBrain is built as a visualization layer on top of Obsidian's metadata cache and the Dataview plugin. The architecture is divided into three tiers:

1. Index Tier (Pages class): Maintains a centralized graph of Page objects representing all indexable content.
2. Relationship Tier (Page class): Manages neighbor relationships and applies transformation logic to determine roles (parent, child, friend, etc.).
3. Visualization Tier (Scene, Node, Link classes): Renders the graph using the Excalidraw API with customizable styling.

Core Dependencies:

• Obsidian API: File system, metadata cache, and workspace management.
• DataView Plugin: Parses YAML/inline frontmatter for explicit relationship definitions.
• Excalidraw Plugin: The rendering engine for shape management and API integration.

Nodes can be styled based on their tags. The plugin identifies a primaryTag (defined by settings.primaryTagField, defaulting to "Note type") to determine the base style.

• Primary Tag: Determines the main style from settings.tagNodeStyles.
• Additional Tags: If settings.displayAllStylePrefixes is enabled, prefixes from other tags are appended to the primary tag's prefix.

This allows you to visually distinguish different types of notes (e.g., Projects vs. Tasks) using specific colors or icons automatically.

ExcaliBrain distinguishes 5 types of relationships between notes. These are derived using specific logic:

Relationship Types

• Children
• Parents
• Friends
• Other Friends (lateral relationships on the right side)
• Siblings

Derivation Logic

1. Explicitly defined: Relationships specified via Dataview fields (e.g., Author:: [[Isaac Asimov]]).
2. Inferred (Links):
   • Forward-link: Inferred as a child.
   • Backlink: Inferred as a parent.
   • Mutual links: If files link to each other, they are friends.
   • Children of parents: These are considered siblings.

ExcaliBrain uses a centralized spatial logic to represent a 'Thought' (the currently focused note) in a structured map. Relationships are mapped to specific cardinal directions to provide spatial orientation:

• Parents (North): Broader categories or origins of the central idea.
• Children (South): Sub-topics, examples, or instances derived from the center.
• Friends (West/Left): Lateral connections representing similar or supporting ideas.
• Next/Competing (East/Right): Sequential steps or ideas that challenge/supercharge the concept.
• Siblings (Periphery): Other children of the current node's parents.

ExcaliBrain converts an Obsidian vault into a graph using three data sources:

1. Inferred Relationships: Automatically derived from standard Obsidian links.
   • Forward link: Inferred as a child.
   • Backlink: Inferred as a parent.
   • Mutual links: Inferred as friends.
2. Explicit Relationships (Ontology): Defined via Dataview fields (e.g., author::, inspired_by::, supports::). This allows you to create a formal 'link ontology' where specific metadata fields dictate exactly where a node appears on the graph.
3. Virtual Nodes: 'Ghost' nodes representing unresolved links (links to files that do not yet exist), allowing you to visualize the future structure of your vault.