Spherical Knowledge Graph for Obsidian

English | 简体中文

Spherical Knowledge Graph turns the links already present in an Obsidian vault into an auto-updating, interactive knowledge instrument.

It is intentionally local-first and read-only: the plugin scans notes and metadata, but never edits note content.

What it does

• Builds either one rotatable pseudo-3D sphere or a multi-planet knowledge system from every Markdown note in the vault.
• Watches note create, modify, rename, delete, and metadata-resolution events.
• Groups planets by folder, graph community, custom rules, or manual assignment.
• Colors nodes by folder, tag, property, or ordered custom rules, with editable group colors.
• Encodes link direction, relation type, and repeated-reference strength.
• Shows link context when an edge is hovered or clicked.
• Finds a shortest knowledge path by selecting one node and Shift-clicking another.
• Creates a deterministic learning route from a search topic and suggests starting points from the current vault instead of fixed examples.
• Provides Chinese, English, and automatic interface-language selection.
• Audits orphan notes, weak notes, stale hubs, cross-category bridges, and unresolved concepts.
• Opens any result in the original Obsidian note.

Release notes

1.1.0 · Adaptive vaults and multi-planet organization

• Replaces fixed learning-path examples with recommendations derived from folders, tags, properties, hubs, and planets in the current vault.
• Adds optional multi-planet layouts with folder, graph-community, custom-rule, and manual grouping.
• Adds configurable node coloring by folder, tag, note property, filename, path, or ordered custom rules.
• Adds complete Chinese and English interface modes with automatic language detection and a safe fallback for older Obsidian versions.
• Adds planet focus plus keyboard exploration: focus the canvas, move with WASD or arrow keys, and press Home to return to the overview.
• Explains the current planet count and grouping source in settings, with controls for the maximum count and minimum relationship-cluster size.
• Adds optional visual follow: selecting a node smoothly focuses it and its direct neighbors while the detail panel renders a bounded Markdown preview.
• Migrates existing 1.0.1 settings, preserves single-sphere behavior by default, batches large-vault reads, and prevents stale refresh tasks from replacing newer graph results.

1.0.1 · Review compliance and release provenance

• Removes the redundant product name from the manifest description.
• Adds GitHub artifact attestations for main.js and styles.css.
• Removes clip-path and !important so the stylesheet passes stricter compatibility and lint checks.
• Explains why the plugin enumerates Markdown files across the current vault.

0.1.1 · Obsidian-integrated interface

• Keeps the graph canvas dominant and moves Explore, Learn, and Inspect into a floating right-side context panel.
• Uses Obsidian theme variables for the toolbar, controls, borders, radii, and backgrounds.
• Reduces product-style decoration and adopts a settings panel closer to Obsidian's native graph view.

0.1.2 · Collapsible context panel

• Collapse the Explore, Learn, or Inspect panel with its × button.
• Restore it from the compact toolbar button; choosing a work mode also reopens its content.

0.1.3 · Layout controls and authorship

• Sets the author to IronMind&Codex.
• Adds independent Link attraction and Node repulsion controls, both defaulting to 1.

0.1.4 · Dispersed layout and compact labels

• Initial node positions use an even spherical distribution. A top-level folder contributes only a slight positional bias, so notes from one folder no longer begin as a tight block.
• Link attraction acts only along real vault links and pulls connected notes closer.
• Node repulsion is calculated independently across every node pair, whether or not the two notes are linked.
• Long labels stay as tidy single-line ellipses by default. Hovering or keyboard-focusing a result, chip, or relation control reveals its full text; native hover titles are included as a fallback.

1.0.0 · Community-ready source release

• Changes the official plugin ID and installation folder to spherical-knowledge-graph.
• Adds reproducible source builds, release validation, GitHub CI, and tag-driven GitHub Releases.
• Documents local-only data access, privacy behavior, development, and official release assets.
• Keeps the tested 3D graph, learning routes, inspections, playback, force layout, and compact Obsidian-native interface from the 0.1.x previews.

0.1.6 · Clear selection and tidy hub cards

• Clicking empty canvas space now clears the selected node, restores every dimmed node and edge, removes path highlights, and closes the contextual detail panel.
• Explore-mode hub cards now stay inside the panel at every width: title and metrics are cleanly truncated by default and expand within the card on hover or keyboard focus.

0.1.5 · Playback, overflow fixes, and guided learning

• Renames the displayed project and plugin to Spherical Knowledge Graph. The preview builds still used the temporary neural-sphere ID; version 1.0.0 completes the migration to spherical-knowledge-graph.
• Rebuild playback now uses stable controls: the left button pauses/resumes or restarts playback, and the progress slider can be clicked, dragged, or adjusted from the keyboard.
• Prevents long summaries, filenames, headings, health-check text, and recommended-path labels from escaping the Explore, Learn, or Inspect panel.
• Learn search now checks title, aliases, tags, folder/path, summary, full note content, and matching graph neighbors. Chinese long phrases also receive partial two-character matching.
• Every adjacent learning step is connected by a real vault link; the step label displays the inferred relationship used to reach it.
• Learn mode generates several recommendations from strong folders, repeated tags, and graph hubs, so a user can start without inventing a query.

How node distance works

The layout is deterministic and graph-based, not a direct text-embedding or semantic-similarity calculation:

1. Notes start from an approximately even Fibonacci-sphere distribution, with a small stable path-based rotation.
2. In single-sphere mode, folder category adds only a weak directional bias. The selected color strategy determines node color.
3. Link attraction pulls directly linked notes toward their neighbors. The Link attraction slider controls this force.
4. Node repulsion acts across all node pairs and prevents crowding independently of links. The Node repulsion slider controls this force.
5. Every iteration projects nodes back onto its assigned sphere, preserving the selected single- or multi-planet form.

Higher attraction creates tighter linked clusters. Higher repulsion spreads crowded regions. A practical starting range for both controls is 0.7–1.3.

Install

Copy this folder to:

<your-vault>/.obsidian/plugins/spherical-knowledge-graph

Then enable Spherical Knowledge Graph in Obsidian > Settings > Community plugins. Use the ribbon icon or the command Open Spherical Knowledge Graph.

No npm install, build step, network request, API key, or external service is required.

Interaction

• Drag: rotate the sphere.
• Mouse wheel: zoom.
• W/S move through depth, A/D strafe, and the arrow keys pan vertically or horizontally; press Home to reset the overview.
• Hover a node: preview its note summary.
• Click a node: inspect its metrics, bounded Markdown preview, and neighbors; optional visual follow also focuses that neighborhood.
• Shift-click another node: show the shortest path from the selected node.
• Hover or click a line: inspect direction, relation type, strength, and source context.
• Click or drag the build timeline: inspect the network construction at any point; use the left button to pause, resume, or restart.
• Search in Learn mode: match title, aliases, tags, path, summary, body, and linked context, then build a continuously linked reading route.
• Choose a recommended learning path: immediately build a route from strong categories, repeated tags, or graph hubs.
• Open graph settings: switch layouts, choose planet assignment, inspect the current count, and configure count limits, cluster size, keyboard exploration, or visual follow.
• In node details: assign a note to a custom planet when manual planets are configured.

Relationship inference

Links are classified from the nearby sentence around the source link:

• Supports: evidence, verification, causality.
• Contrasts: comparison, limitations, risks, disagreement.
• Extends: next steps, deeper or adjacent concepts.
• Example: practice, applications, cases.
• Reference: citations and further reading.
• Related: fallback when no stronger signal is present.

This is a transparent heuristic, not an AI claim. The original context is always shown so the classification can be reviewed.

Development

npm ci
npm run dev

Use npm run build for a production bundle and npm run check before publishing. The build output is the root main.js; it is ignored by Git and attached to GitHub Releases instead.

Official release files

Keep README.md, LICENSE, manifest.json, versions.json, source files, and build configuration in the GitHub repository. Attach these three runtime files individually to a GitHub Release whose tag exactly matches manifest.json:

• main.js
• manifest.json
• styles.css

Never distribute data.json; it contains per-vault user settings.

Privacy and data access

• Enumerates Markdown files across the current vault because a complete index is required to build the full graph, identify missing concepts, calculate learning routes, and run graph health checks.
• Reads each indexed Markdown note and its Obsidian metadata only through the Obsidian API and only for those user-requested local analyses.
• Stores plugin preferences in Obsidian's local plugin data file.
• Does not access files outside the vault.
• Does not use network requests, accounts, API keys, advertising, payments, or telemetry.
• Does not automatically create, modify, move, or delete notes.
• All graph analysis, relationship inference, learning routes, and health checks run locally inside Obsidian.

License

MIT. Anyone may use, modify, and redistribute the plugin under the included license.