# Neural Composer
**Graph-based AI chat for your Obsidian vault.**
[](https://github.com/oscampo/obsidian-neural-composer/releases/latest)
[](LICENSE)
[](https://obsidian.md/plugins?id=neural-composer)
---
## TL;DR
Chat with your vault using a **Knowledge Graph**, not just keyword search. Neural Composer runs a local [LightRAG](https://github.com/HKUDS/LightRAG) server, builds a graph of your notes, and lets you ask questions that trace connections across your entire vault.
- ๐ **Finds relationships**, not just matching words
- โก **Manages the LightRAG server** for you โ no terminal juggling
- ๐ **100% local** when used with Ollama โ your data never leaves your machine
**Requirements:** Python 3.10+ ยท `pip install "lightrag-hku[api]"` ยท Obsidian 1.7.2+
---
## Features
| | |
|---|---|
| **โก Automated Server** | Starts and stops the LightRAG Python process automatically. No terminal needed. |
| **๐ง Graph + Vector Search** | Combines entity-relationship traversal with semantic vector search for deep, contextual answers. |
| **๐ Vault Sync** | Set a watched folder โ notes are re-indexed on save. Status dots in the file explorer show each note's graph state: ๐ข processed ยท ๐ก processing ยท ๐ด failed ยท ๐ต removed. |
| **๐ Knowledge Graph View** | Explore your graph visually in 2D or 3D. Overview mode renders all nodes; Explore mode does a BFS walk from any entity. |
| **๐ Remote Server** | Connect to a LightRAG instance on a NAS, VPS, or Docker container. |
| **๐ค MCP Tools** | Expose your graph to any MCP-compatible client (Claude Desktop, etc.). |
| **๐ Source Transparency** | Every answer includes citations `[1]` linked to the exact notes and text chunks that were used. |
| **๐ Local & Private** | Use Ollama for a fully offline setup, or any hosted provider you prefer. |
Complete list of supported file formats
`md` `txt` `docx` `pdf` `pptx` `xlsx` `rtf` `odt` `epub` `html` `htm` `xml` `json` `yaml` `yml` `csv` `tex` `log` `conf` `ini` `properties` `sql` `bat` `sh` `c` `cpp` `py` `java` `js` `ts` `swift` `go` `rb` `php` `css` `scss` `less`
---
## Why Graph RAG?
Standard vector search finds *similar text*. Graph RAG finds *connected ideas*.
| | Standard Vector Search | Neural Composer (Graph RAG) |
|:---|:---|:---|
| **How it works** | Finds chunks that match your query semantically | Traverses relationships between entities in your notes |
| **Best for** | "What is X?" | "How does X influence Y across my research?" |
| **Context quality** | Often fragmented | Holistic โ sees the whole picture |
| **Multi-hop reasoning** | โ | โ |
---
## Getting Started
> ๐ Full documentation on the [Wiki](https://github.com/oscampo/obsidian-neural-composer/wiki)
### 1. Install the LightRAG backend
```bash
# Recommended: use a virtual environment
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "lightrag-hku[api]"
```
Then find the path to the installed executable (you'll need it in Step 3):
```bash
which lightrag-server # macOS / Linux
where.exe lightrag-server # Windows
```
### 2. Install the Plugin
Search for **"Neural Composer"** in **Settings โ Community Plugins โ Browse** and enable it.
### 3. Connect & Configure
Open **Settings โ Neural Composer**. The panel has a sidebar with seven tabs:
1. **Providers** โ add your API keys (OpenAI, Anthropic, Gemini, Groq, Ollama, etc.)
2. **Models** โ select your chat, apply, and embedding models
3. **Graph & Vault** โ set the `lightrag-server` path, choose a data directory, and optionally configure a **Watched Folder** for auto-sync
4. Toggle **Auto-start** on, then click **Restart Server**
A green dot in the status bar confirms the server is running. Right-click any folder in your vault to ingest notes and start chatting.
---
๐ ๏ธ Use Cases
- **Researchers** โ synthesize arguments across hundreds of papers, surface consensus and contradictions that keyword search misses.
- **Writers & Game Masters** โ track relationships between characters and lore; keep your world internally consistent without digging through folders.
- **Journalers** โ connect entries from months ago to today, spotting patterns that aren't visible day-to-day.
- **Project Managers** โ visualize dependencies between project notes that otherwise look like separate tasks.
๐งฉ Advanced Options
| Feature | Where to configure |
|:---|:---|
| **Watched Folder** | Settings โ Graph & Vault โ Watched folder |
| **Remote Server** | Settings โ Graph & Vault โ Use remote server |
| **Custom Ontology** | Settings โ Graph & Vault โ Ontology section โ teach the graph domain-specific entity types (e.g. "Experiment", "Theorem") |
| **Reranking** | Settings โ Graph & Vault โ Reranking โ Jina AI, Cohere, or a custom local endpoint |
| **MCP Servers** | Settings โ Tools (MCP) |
| **Graph Visualization** | Settings โ Graph & Vault โ Graph rendering engine โ 2D (fast) or 3D (immersive) |
| **Performance Tuning** | Settings โ Advanced โ chunk size, overlap, async workers |
| **Custom `.env` overrides** | Settings โ Advanced โ raw `.env` editor with full LightRAG configuration access |
๐ Privacy & Security
Neural Composer is designed with privacy as a core principle.
### What leaves your machine
| Destination | When | Why |
|:---|:---|:---|
| **Your AI provider** (OpenAI, Anthropic, Gemini, Groq, etc.) | Every chat message or ingestion | To generate responses and embeddings. Only notes you explicitly ingest or attach are sent. |
| **Your local LightRAG server** (`localhost`) | Every query and ingestion | The plugin talks to a Python process on your own machine. No data leaves. |
| **Your remote LightRAG server** | Only if you configure a remote URL | Off by default. Opt-in only. |
**Using Ollama + local LightRAG = zero data leaves your machine.**
### What never happens
- The plugin does **not** send telemetry, analytics, or crash reports.
- The plugin does **not** contact `github.com` or any external domain at runtime. Links in the UI are navigation-only โ never fetched programmatically.
- API keys are stored **only** in Obsidian's own `data.json` in your local vault.
### System-level access disclosures
Why the Obsidian scanner flags certain capabilities
| Capability | Reason |
|:---|:---|
| **`fs` (filesystem)** | Writes the LightRAG `.env` config file to your chosen work directory, which may be outside the vault. |
| **`child_process` (shell)** | Starts and stops the local LightRAG Python server. The command is always the exact path you configure โ no user input is interpolated into shell arguments. |
| **Vault enumeration** | Lists file paths for ingestion and the search index. File content is only read when you explicitly ingest a file. |
| **Clipboard** | Inherited from the Lexical rich-text editor in the chat input. Standard paste operations only. |
| **`atob`/`btoa` (Base64)** | Used by bundled deps: `@modelcontextprotocol/sdk` decodes JWT tokens for MCP OAuth; `sigma`/`three-forcegraph` encode WebGL shader data. No sensitive data is encoded this way. |
| **`new Function`** | Used by two bundled libraries: `ngraph.forcelayout` (3D physics) and `ajv` (JSON schema validation via MCP SDK). Neither executes user-provided code. |
๐ Changelog
### v1.3.1 โ 2026-05-25
- Fix: removed all `!important` CSS declarations โ replaced with higher-specificity selectors to comply with the Obsidian plugin linter.
### v1.3.0 โ 2026-05-24
- **Settings UI redesign** โ new sidebar navigation with 7 tabs: Providers, Models, Chat, Graph & Vault, Tools (MCP), Advanced, Help.
- **Document status tracking** โ colored dots in the file explorer for each note (๐ข processed, ๐ก processing, ๐ด failed, ๐ต removed). Watched folder shows an aggregate status dot.
- **LightRAG version detection** โ the server version is displayed as a badge in Settings โ Graph & Vault.
- **Watched folder sync** โ notes are automatically re-indexed on save with a 5-second debounce.
- **"Remove from graph" action** โ right-click context menu lets you remove individual notes from the graph without deleting the file.
- **Tooltip improvements** โ status bar tooltip correctly distinguishes local vs. remote server offline state.
### v1.2.3 โ 2026-05-22
- Fix: correct LightRAG provider config for OpenRouter and Ollama (LLM\_BINDING\_HOST was missing, causing 401 errors).
- Fix: expose active embedding model selector in settings UI.
- Add: "Reprocess failed documents" button in Graph & Vault settings.
- Fix: stop server now correctly kills orphaned processes on macOS/Linux via port lookup.
### v1.2.1 โ 2026-05-20
- **Knowledge Graph Visualization** โ 2D and 3D interactive graph view inside Obsidian.
- Overview mode (all nodes) and Explore mode (BFS from a selected entity).
- Real relevance scores for cited references (citation-frequency formula).
- Improved "Context used" panel โ shows scores, snippets, and click-to-open for `.md` files.
- Fix: single-click on isolated nodes now auto-explores and shows full entity details.
### v1.2.0 โ 2026-05-17
- Initial public release on the Obsidian Community Plugin marketplace.
- Local LightRAG server management (auto-start, restart, stop).
- Right-click folder ingestion with multi-format support.
- Chat with graph RAG, hybrid query modes, Jina/Cohere reranking.
- Custom ontology (entity types) and `.env` editor.
---
Built on the shoulders of giants:
- Forked from **[Smart Composer](https://github.com/glowingjade/obsidian-smart-composer)** by glowingjade
- Powered by **[LightRAG](https://github.com/HKUDS/LightRAG)**
- Developed by **Oscar Campo** & **Cora** (AI)