README file from
GithubSimple Graph Builder
This plugin builds a lightweight knowledge graph from users' Obsidian notes using LLM-powered entity extraction with a simple yet expressive ontology model to provide knowledge extraction, exploration, and RAG search. Since Obsidian provides wonderful links between notes, implementing ontology model would meet users' (especially researchers') needs.

What's new in 0.10.2
- Add a required concept directly. Type a search term in Required concept or choose a graph path suggestion, then press Add AND condition or Enter. The PubMed and OpenAlex previews update immediately.
- See how terms combine. Groups show their search terms with AND between them. Use Add alternative (OR) within a group. If a term is already selected as an alternative, the required concept field identifies the group to edit.
- Open a restored tab from the graph. Find more literature… applies the current graph origin even when Obsidian restores the literature search tab.
See the 0.10.2 release notes and the full changelog.
Find more literature from your graph
- Search from a concept or path. Choose Find more literature… in the graph inspector. Keep the route, relationship directions and supporting source notes visible while developing the next search.
- Editable searches for PubMed and OpenAlex. Review each source's query, dates and result limits, then press Search to submit the queries.
- Results and abstracts inside Obsidian. Inspect source metadata, identifiers and reliable matches to articles already in your vault. Open an article landing page in your external browser for access and downloading.
- Built into Simple Graph Builder. This needs no model API key, agent session, med-lit-mcp or separate backend. Searching creates no notes and makes no graph changes.
For the full workflow, see Literature search.
Why a lightweight ontology?
Traditional knowledge graphs often require complex schemas with dozens of entity and relationship types, making them difficult to maintain and query. Simple Graph Builder uses 10 fixed entity types (PERSON, ORGANIZATION, CONCEPT, PROJECT, TOOL, EVENT, PLACE, DOCUMENT, METHOD, TOPIC), free-form relationship verbs ("develops", "uses", "causes", "cites"), and a detail on each relationship for nuance without schema explosion. See the data model.
Features
- Entity extraction: Extract entities and relationships from your notes with an LLM, at a depth you choose. Every request carries a JSON schema and every reply is validated against it, so malformed entities are reported and dropped rather than polluting the graph
- Hybrid entity resolution (opt-in): A multi-stage pipeline of fast lookups, embedding similarity and LLM verification merges "AI", "artificial intelligence" and "인공지능" into one entity (inspired by KGGen [3])
- Notes in the graph: Each analyzed note becomes a node linked to the entities it mentions and the notes it wikilinks
- Interactive graph view: Search the graph in place, inspect and walk its relationships, focus on a neighborhood, find paths, and adjust appearance, forces and clusters live. Fast on graphs of thousands of nodes
- Advanced search: Notes and entities ranked by text match plus graph proximity (Personalized PageRank, as in HippoRAG [6]), with an explanation for every result and no API calls
- Find more literature: Develop editable PubMed/OpenAlex searches from explored concepts and paths, inspect citations and abstracts in Obsidian, and open articles externally
- Agent access (MCP): Let Claude Code, Claude Desktop or Codex search your vault and knowledge graph through a local, token-protected MCP server, and optionally build the graph with their own model instead of an API key
- med-lit import: Bring a med-lit-mcp literature review (articles, wiki pages and its knowledge graph) into your vault, merged into your graph and kept up to date by re-importing
- Vault write-back (opt-in): Mirror the graph into your vault as real Obsidian links, so it also appears in Obsidian's graph view, backlinks and properties
- Multiple LLM providers: Claude, OpenAI, Gemini, DeepSeek, and local servers (Ollama, or anything OpenAI-compatible such as llama.cpp, LM Studio and vLLM), with reasoning-effort control
- Analysis exclusions: Skip files and folders by path or glob, optionally honoring Obsidian's own exclusion list
- Korean language support: Syllable-pair matching in both entity resolution and search, so particles ("머신러닝은") and spacing variations still match, with names normalized to Unicode NFC so composed and decomposed Hangul resolve to one entity
- Note neighborhood panel: The current note's entities and their connections, in a sidebar
Installation
From Obsidian Community Plugins
- Open Settings → Community plugins
- Search for "Simple Graph Builder"
- Click Install, then Enable
Using BRAT (Recommended for Beta)
- Install BRAT from Community Plugins
- Open command palette → "BRAT: Add a beta plugin"
- Enter:
junhewk/simple-graph-builder - Enable the plugin in Settings → Community plugins
Manual Installation
- Download
main.js,styles.css, andmanifest.jsonfrom the latest release - Create folder:
VaultFolder/.obsidian/plugins/simple-graph-builder/ - Copy the downloaded files into the folder
- Reload Obsidian and enable the plugin
Quick start
- Choose a provider and enter its API key in Settings → Simple Graph Builder (or point it at a local server, or let a connected agent do the analysis)
- Open a note and run Analyze current note, or Analyze entire vault from settings
- Run Open graph view, and type in its search box to find your way in
With an already prepared graph, start at step 3. For example, open
Find more literature… from Uncertainty sampling, enter Abstract screening
in Required concept, and press Enter. Review both query previews and press
Search.
Commands
| Command | Description |
|---|---|
Analyze current note |
Extract entities from the active note |
Search graph and notes |
Advanced search over notes and entities (no API calls) |
Open graph view |
Show the knowledge graph |
Find more literature… |
Search PubMed/OpenAlex from the active graph selection; also available in the inspector and path view |
Open note neighborhood panel |
Show the current note's connections in the sidebar |
Remove current note from graph |
Remove the active note from the graph |
Rebuild note layer |
Recreate note nodes and their links from existing data (no API calls) |
Write graph links into notes |
Apply the graph to your vault as Obsidian links (no API calls) |
Remove graph links from notes |
Take the link property back out of every note |
Import or update med-lit project |
Import a med-lit-mcp review into the vault, or update one imported before (no API calls) |
Clear all graph data |
Reset the entire graph |
The ribbon icon offers Analyze current note and Open graph view. The status bar shows node counts by type.
Documentation
| Guide | Covers |
|---|---|
| Graph View | Searching, inspecting and arranging the graph; display, forces, clusters and layout |
| Search | The search command, and how results are ranked |
| Literature Search | Graph origins, editable PubMed/OpenAlex queries, results, abstracts and external article links |
| Settings | Providers, analysis, exclusions, entity resolution, vault write-back |
| Agent Access (MCP) | Connecting Claude Code, Claude Desktop or Codex, the tools they get, and what they can see |
| Importing med-lit Projects | Importing, updating and removing literature reviews |
| Data Model | Entity types, relationships, entity resolution, and where data is stored |
| Changelog | What changed in each release, and what upgrading does |
| Development | Building, testing and releasing |
Supported models
Note analysis requires a model that can return structured output. Models that cannot are refused with a message rather than silently producing a lower-quality graph, and the settings panel flags them as you select them.
| Provider | Models |
|---|---|
| Claude | claude-sonnet-5, claude-haiku-4-5 |
| OpenAI | gpt-6-luna, gpt-5.4-mini |
| Gemini | gemini-3.6-flash, gemini-3.5-flash-lite |
| DeepSeek | deepseek-flash |
| Local | any model your server exposes — Ollama, or an OpenAI-compatible server such as llama.cpp's llama-server, LM Studio or vLLM |
Any other model can be typed into the Custom… field, for example deepseek-v4-pro.
DeepSeek offers JSON mode rather than schema-enforced output, so the plugin puts the schema in the prompt and still validates every reply against it. At the default Minimal reasoning effort, DeepSeek's thinking is switched off. At higher levels it stays on, and the output budget is raised to 32k tokens, because DeepSeek counts thinking against it.
API costs
Local graph/note search, graph exploration and agent access make no provider API calls. Find more literature makes explicit PubMed/OpenAlex retrieval requests, under their current usage allowances; optional literature keys are configured separately. Note analysis calls the configured model API. When an agent analyzes notes for you, it uses its own model, billed however that agent is.
- Claude, OpenAI, Gemini, DeepSeek: Each note analysis costs your provider's pricing
- Local servers: Free (runs on your machine)
If entity resolution is on, embeddings add a little:
- OpenAI: ~$0.02 per 1M tokens for
text-embedding-3-small - Gemini: Free tier available for
gemini-embedding-001 - Local: Free (models like
nomic-embed-text)
Privacy
- Your notes are sent to the configured LLM provider for entity extraction. Use a local server for fully local processing
- Analyze entire vault enumerates markdown file paths only when you start it. It reads eligible notes on your computer to count the new and changed ones, and sends nothing until you confirm those numbers
- Analyzing the current note and auto-analysis read only the individual note being processed
- Literature search sends only submitted queries, filters and configured contact/authentication details to the selected sources. Routes, source passages, vault paths and the local research question stay in Obsidian. Citation results are cached temporarily in memory
- No data is stored externally; all graph data stays in your vault (where)
- Importing a med-lit project reads its folder on your computer and copies its pages into the vault. It makes no API calls, unless you choose embedding-based matching
- Agent Access (off by default) serves your notes to AI agents you connect. They see notes, not your API keys or settings, and never your excluded notes. What an agent does with what it reads (for example, sending it to its own model provider) is governed by that agent. Agents can change the graph only if you turn on Let agents add to the graph, and never your notes' text
If you version-control your vault
Obsidian stores plugin settings — including extraction and embedding API keys — in
.obsidian/plugins/simple-graph-builder/data.json, together with the graph
itself. If your vault is a git repository, add this to your .gitignore:
.obsidian/plugins/simple-graph-builder/data.json
Pushing that file to a public repository publishes your keys in plaintext, and deleting it later does not help — git keeps the history. If it has already been pushed, revoke the key at your provider's console and issue a new one.
Literature keys use Obsidian secret storage where available and session memory
on older versions. They are not written to data.json or included in a copied
prepared vault.
Technical background
This plugin's entity resolution approach is inspired by recent advances in knowledge graph construction:
- LightRAG [1] demonstrated lightweight graph-based RAG but lacks entity resolution
- Microsoft GraphRAG [2] provides comprehensive extraction but at high cost ($50-100+ per corpus)
- KGGen [3] introduced the insight that entity resolution is critical for quality knowledge graphs
Simple Graph Builder combines the simplicity of LightRAG with KGGen's hybrid resolution approach, adapted for Obsidian's local-first architecture. Search follows HippoRAG [6] in ranking by Personalized PageRank over the graph.
References
[1] Guo, Z., et al. (2024). "LightRAG: Simple and Fast Retrieval-Augmented Generation." https://github.com/HKUDS/LightRAG
[2] Edge, D., et al. (2024). "From Local to Global: A Graph RAG Approach to Query-Focused Summarization." arXiv:2404.16130. https://github.com/microsoft/graphrag
[3] Shu, Y., et al. (2025). "KGGen: Extracting Knowledge Graphs from Plain Text with Language Models." NeurIPS 2025. arXiv:2502.09956. https://github.com/stair-lab/kggen
[4] Neo4j, Inc. (2024). "Neo4j GraphRAG Package for Python." https://neo4j.com/docs/neo4j-graphrag-python/current/
[5] Veen, A. (2024). "pgvector: Open-source vector similarity search for Postgres." https://github.com/pgvector/pgvector
[6] Gutiérrez, B. J., et al. (2024). "HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models." NeurIPS 2024. arXiv:2405.14831. https://github.com/OSU-NLP-Group/HippoRAG
Support
License
MIT License - see LICENSE for details.