## 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](https://github.com/AlexW00/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](../../releases/latest) (see [CHANGELOG.md](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`](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`](src/mcp/McpServer.ts) for exactly what it does. Configure a client (e.g. OpenCode) with:

```json
"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](LICENSE). Includes original work by Alexander Weichart under the same license.