Samind 3D Graph

Samind 3D Graph

Mostly done by Claude!

⚠️ Disclaimer: I built this for my own use at work, on top of a POC I already had lying around. It's not a polished, general-purpose release — expect rough edges, and use it at your own judgment.

A 3D force-directed graph view for Obsidian, with AI-driven topic clustering and gap-insight analysis layered on top.

Forked from Obsidian 3D Graph by Alexander Weichart, extended with:

• AI cluster visualization — notes are colored and sized by an AI-generated topic clustering, with dashed boundary boxes and labels drawn around each cluster
• Cluster physics — a tunable spatial force pulls notes in the same cluster together and pushes different clusters apart, with live sliders for target radius, force strength, and inter-cluster separation
• Explode interaction — double-click a cluster to spread it apart and frame the camera on it
• Gap insights — surfaces AI-found structural gaps between clusters (e.g. two topics that should probably reference each other but don't), with a "show in graph" button that highlights and frames the relevant clusters
• Cluster legend — a collapsible panel listing each cluster's color, note count, and share of the vault
• MCP server (optional, off by default) — lets an MCP-compatible AI tool (e.g. OpenCode) query the graph and drive highlights/snippet cards while talking to you

Installation

To install manually:

1. Download main.js, manifest.json, and styles.css from the latest release (see CHANGELOG.md for what's changed)
2. Copy them into <vault>/.obsidian/plugins/samind-graph/
3. Reload Obsidian and enable "Samind 3D Graph" under Community Plugins

Usage

Open the graph via the ribbon icon, the command palette ("Open Global 3D Graph" / "Open Local 3D Graph"), or a note's file menu. The settings panel (gear icon, top-right of the graph) has sections for filters, groups, display, and cluster physics — and, once an analysis.json exists, a cluster legend and gap-insight list. Double-click a cluster's box or title to explode it apart; right-click a note to pin it and its neighbors.

How clustering works

This plugin does not call out to any AI backend itself. Instead, it reads a local, vendor-neutral file at <vault>/.samind-3d-graph/analysis.json containing cluster assignments, colors, importances, and gap insights. That file can be generated by any AI assistant. Without this file, the graph falls back to plain, unclustered rendering — the graph view shows a "Set up" prompt in this case.

Setting up AI clustering

1. Open this vault's folder with an AI assistant that can read and write files — Claude Code, Claude Desktop with filesystem access, or similar.
2. Point it at skills/samind-graph-analysis/SKILL.md and ask it to follow those instructions against this vault — either by installing the file as a proper Claude Skill, or just pasting its contents into the conversation and asking Claude to follow them.
3. Once it reports .samind-3d-graph/analysis.json has been written, run the "Reload AI Graph Analysis" command (or reopen the graph) to see the clusters.

Re-run the same skill any time your vault changes enough that the clustering feels stale.

MCP server (optional)

Off by default. Enabling it (Settings panel → MCP Server) starts a local server at http://127.0.0.1:27184/mcp that lets an MCP-compatible AI tool query the graph's structure and drive highlights/snippet cards. It only accepts connections from this machine and only exposes read access to your vault plus the same highlight actions available in the UI — see src/mcp/McpServer.ts for exactly what it does. Configure a client (e.g. OpenCode) with:

"mcp": { "samind-graph": { "type": "remote", "url": "http://127.0.0.1:27184/mcp" } }

Privacy

This plugin reads no files outside your vault and makes no network requests - it never connects out to anywhere, local or remote. The one exception is the optional MCP server above: when you turn it on, the plugin listens on 127.0.0.1 for incoming local connections (it doesn't request anything itself), and is off by default.

License

MIT — see LICENSE. Includes original work by Alexander Weichart under the same license.