Which AI agents and tools are supported?

Anything that speaks the Model Context Protocol (MCP) — Claude Desktop, Claude Code, Cursor, Cline, Windsurf, plus generic MCP clients like Zed, Goose, and Codex CLI. The plugin's Agents panel is a one-click installer for the popular ones; for others, copy the MCP server URL and API key into your tool's config.

What does HangarX cost?

Local mode is free forever — you only pay your own LLM and embedding provider. Cloud mode has a free tier covering single-vault personal use, with paid plans priced on monthly active credits (a credit is roughly one LLM-backed extraction or query).

Does HangarX work with multiple Obsidian vaults?

Yes. Each vault is a separate workspace in HangarX, with its own knowledge graph and API key. Agents can read across workspaces if you grant them multi-workspace scope on the key.

HangarX for ObsidianHangarX

Obsidian Community Plugin

Stop re-introducing yourself to your AI.

Your Obsidian vault becomes shared memory for Claude, Cursor, and every MCP-compatible agent on your machine.

Install in Obsidian Get started in 60 seconds

Built for Obsidian

Works withClaude Desktop · Claude Code · Cursor · Cline · Windsurf

See it in action

Five core surfaces, one plugin. Switch between them to see what your vault feels like once it's connected.

Chat over your knowledge graph with citations

Hybrid retrieval — BM25 + vector + multi-hop graph expansion — returns answers grounded in your notes. Click a citation to jump to the source. Suggested starters get you out of the blank-page state.

Why this exists

You've already written everything. Your standups, your design docs, your half-finished thoughts. The problem isn't capturing knowledge — it's making it usable by the agents you work with every day.

Claude Desktop forgot what you decided last week.

HangarX remembers.

Cursor doesn't know your team's conventions.

HangarX answers from your notes.

You repeat yourself across every new chat.

HangarX is the source of truth all of them read.

It's not another chat UI bolted onto Obsidian. It's the connective tissue that makes your existing AI tools dramatically more useful.

Quick start — 60 seconds (Cloud)

Cloud mode is the fastest way to try HangarX. Sign-in is OAuth — no key copy-paste.

1
Install the plugin from Obsidian's Community Plugins → search “HangarX”.
2
Open Settings → HangarX → Connection → Mode: ☁️ Cloud (HangarX hosted).
3
Click Sign in with HangarX. Your browser opens, you approve, and the plugin auto-fills your API key + workspace.
4
Run HangarX: Sync from the command palette (⌘P) — or wait for the next startup sync.

That's it. Your vault is now searchable, your agents can read it, and you can ask questions from inside Obsidian.

First sync uploads everything. Subsequent syncs only push files that changed. The .cortex/, .obsidian/, and your templates are excluded by default.

Quick start — Local Docker (private)

Run everything on your machine — your notes never leave the laptop.

1
Install the plugin and switch Mode to 🏠 Local (Docker).
2
Open LLM provider keys and paste at least one key — Gemini, OpenAI, Anthropic, Moonshot, HuggingFace, OpenRouter, or xAI. Or skip the keys and run Ollama locally for fully offline.
3
Click Save Compose to vault — writes docker-compose.cortex.yml next to your notes with your keys baked in (encrypted at rest).

Open a terminal in your vault folder and run:

docker compose -f docker-compose.cortex.yml up -d

5
Switch back to Obsidian — the connection pill turns green when the stack is up. Run HangarX: Sync from the command palette (⌘P) to push your vault.

Bring your own keys (BYOK)

Add or rotate keys anytime in LLM provider keys. The plugin pushes the change to the running container's encrypted runtime config — no Compose re-save, no docker compose up. Switch the active chat model per-request from the LLM (runtime) panel.

Fully offline

Run Ollama locally and pick it as the chat provider. For embeddings, switch the Embedding provider to Ollama and run ollama pull nomic-embed-text — the entire stack then makes zero cloud API calls.

Requires Docker Desktop. No source code, no Node.js, no compile step — images are pulled from Docker Hub.

Connect your AI agents

The Agents section in settings shows every supported harness as a one-click row. HangarX merges its MCP server entry into the client's config file non-destructively — your other MCP servers are preserved.

Claude DesktopClaude CodeCursorClineWindsurfZed

Goose

Claude Desktop

Anthropic's desktop chat app

Claude Code

Anthropic's CLI coding agent

Cursor

AI-first code editor

Cline

VS Code autonomous coding extension

Windsurf

Codeium's agentic IDE

Other MCP-compatible app

Zed, Goose, Codex CLI, or any custom client via JSON snippet

Tools agents get after connecting

50+ tools across the categories below. Most agents only use 5–10 in practice — the Q&A, graph exploration, and memory sections cover almost every common workload.

Q&A and unified retrieval

cortex_unified_ask	Natural-language Q&A grounded in your vault, with citations
cortex_chat	Multi-turn agentic chat with the full tool loop
cortex_get_context	Hybrid retrieval bundle (entities + chunks + memories) for one query
cortex_unified_search	One-shot search across entities, documents, and memories
cortex_advanced_search	Hybrid search with date / tag / entity-type filters

Knowledge-graph exploration

cortex_search_entities	Find entities by name + optional type filter
cortex_list_entities	Paginated entity listing with type filters
cortex_get_entity	Fetch one entity's full record
cortex_get_neighbors	Expand 1–3 hops out from an entity
cortex_find_paths	Shortest path between two entities — multi-hop reasoning
cortex_explain_entity	Properties + neighbors + sources for one entity in a single call
cortex_get_provenance	Source documents an entity was extracted from — the citation tool
cortex_query_graph	Run a custom Cypher query (read-only) against the graph
cortex_get_schema	Introspect the live graph schema
cortex_get_communities	Auto-detected entity clusters / topics
cortex_predict_links	ML-suggested missing edges between entities
cortex_point_in_time	Temporal queries — graph state as of a given timestamp

Document retrieval

cortex_search_documents	Semantic search across your notes
cortex_summarize_document	LLM summary of a single document

Memory (cross-session)

cortex_remember	Save a fact / preference / decision to persistent memory
cortex_recall	Retrieve memories relevant to a query
cortex_relate	Find memories semantically related to an entity or topic
cortex_feedback	Record agent feedback (helpful / not helpful) for future ranking

Graph health and ops

cortex_graph_stats	Totals + per-type breakdowns of entities and relationships
cortex_find_duplicates	Find likely duplicate entities by embedding similarity
cortex_diff_graph	Compare graph state between two timestamps
cortex_export_graph	Export the graph to JSON / GraphML / Cypher
cortex_file_persistence_status	Check sync state of files between vault and graph

Ingestion and writes

cortex_ingest	Add a single text chunk + metadata to the graph
cortex_bulk_ingest	Batch ingest — efficient for large documents
cortex_create_document / cortex_delete_document	Document-level lifecycle
cortex_create_entity / cortex_update_entity / cortex_delete_entity	Entity-level lifecycle
cortex_create_relationship	Add a typed edge between two entities
cortex_merge_entities	Merge a source entity into a target
cortex_tag_entity	Lightweight metadata write

Web access

cortex_web_search	Search the public web
cortex_web_scrape	Fetch and extract content from a URL

Workflows, custom tools, and live streams

cortex_list_workflows / cortex_run_workflow	Discover and trigger durable workflows
cortex_create_workflow / cortex_update_workflow / cortex_delete_workflow	Workflow lifecycle
cortex_list_custom_tools / cortex_run_custom_tool	User-defined API tools
cortex_subscribe / cortex_subscribe_poll	Subscribe to graph mutations
cortex_event_log_subscribe / cortex_event_log_poll / cortex_event_log_unsubscribe	Event-log subscription lifecycle
cortex_generate_image	Generate an image from a prompt
cortex_query_analytics	Run pre-computed KPI / analytics queries

Inside Obsidian

You don't have to use external agents. The plugin ships with:

Ask your vault (⌘P)

Multi-hop chat over your knowledge graph with citations back to source notes. Suggested starters get you out of the blank-page state.

Show on graph

Push chat answers into Obsidian's built-in Graph view. Cited entities stay highlighted, everything else dims. Toggle the pin to auto-highlight every future answer.

Two-way sync modal

Push, pull, two-way, diff, force re-ingest — all in one modal. Mid-flight cancellation drains in-flight server workers cleanly.

Inline link suggestions

Ghost-text [[wikilink]] autocompletes driven by entity matches in your graph. Tab to accept, Esc to dismiss.

Knowledge graph stats

Totals + per-type breakdowns for entities and relationships. Surfaced both in Obsidian and to external agents via the cortex_stats MCP tool.

Switch LLMs on the fly

Pick Gemini, Claude, GPT-4o, Kimi K2.5, Llama, Qwen, or Ollama per request — no container restart. BYOK keys live encrypted on the server and update the runtime config immediately.

Privacy & what gets synced

Cloud mode

Notes are sent to the HangarX hosted API for entity extraction and embedding. They're stored in your scoped workspace and never used to train models. Revoke access anytime from your API keys settings.

Local mode

Nothing leaves your machine. The Docker stack runs FalkorDB (graph), Postgres + pgvector (embeddings), and the Cortex API. You bring an LLM key — or run Ollama for fully offline.

What's excluded by default

.cortex/, .obsidian/, and templates/. Configure include/exclude lists in What to sync.

Attachments

Images, PDFs, and other binaries referenced by your notes are ingested by default. Toggle off in Sync attachments.

Commands

Command	Description
HangarX: Ask your vault	Open the Q&A chat
HangarX: Sync	Open the multi-purpose sync modal
HangarX: Sync current note	Push only the active file
HangarX: Diff vault vs knowledge graph	Open the 4-bucket diff view
HangarX: Pull graph entities into vault	Materialize entities as markdown
HangarX: Force re-ingest entire vault	Re-sync everything (use after a server reset)
HangarX: Connect agents (Claude, Cursor)…	Jump to the Agents settings panel
HangarX: Knowledge graph stats	Show entity / relationship totals + breakdowns
HangarX: Ingest URL into knowledge graph	Scrape a URL and add it to the graph
HangarX: Show onboarding	Reopen the first-run walkthrough

Docs

A deep tour of how the plugin works, every setting, and what each piece does. If you just want to ship, the quick start is enough.

How it works

HangarX turns your vault into a queryable knowledge graph + vector index, then exposes it over MCP (Model Context Protocol) so any compliant agent can read and write to it. Nothing magical — just three layers wired together:

1. Sync. The plugin watches your vault, hashes each note, and pushes only what changed to the Cortex API (cloud) or your local Docker stack.
2. Extract. Each note is chunked, embedded, and run through entity / relationship extraction (people, projects, decisions, claims). Results land in FalkorDB (graph) and Postgres with pgvector (semantic index).
3. Serve. An MCP server (cortex-mcp) wraps the API and exposes a small set of tools. Agents you connect call those tools to ask questions, recall facts, or trace ideas back to source notes.

Reads are sub-100ms after the index warms up. Writes from agents (cortex_remember) are stored as new entities with provenance so you can see which agent claimed what, when.

Installation

Three ways to install, in order of how most people do it.

Community Plugins (recommended)

1. Open Obsidian → Settings → Community plugins.
2. Turn off Restricted mode if needed.
3. Browse → search HangarX.
4. Install → Enable.

From release URI

Click the install button anywhere on this page (or copy obsidian://show-plugin?id=hangarx-obsidian) and Obsidian opens the install dialog directly.

Manual / BRAT

Grab main.js, manifest.json, and styles.css from the latest GitHub release into .obsidian/plugins/hangarx-obsidian/, then enable.

Configuration reference

Everything is in Settings → HangarX. Defaults are sensible; the fields you actually touch are below.

Setting	What it does
Mode	Cloud (HangarX hosted) or Local (Docker). Cloud is OAuth-managed; Local is BYO infrastructure.
API URL	Auto-set per mode — https://cortex.hangarx.ai for Cloud, http://localhost:3400 for Local. Editable as an advanced override only (custom self-hosted endpoint).
API key	Auto-filled when you sign in via OAuth (Cloud). Generate or revoke from the dashboard. Click Test to verify.
Workspace	The graph namespace your vault writes to. One vault → one workspace by convention.
LLM provider keys (BYOK)	Local mode. Paste any combination of Gemini, OpenAI, Anthropic, Moonshot (Kimi), HuggingFace, OpenRouter, or xAI keys. Stored encrypted on the cortex-api and pushed to the running container immediately — no docker rebuild.
LLM (runtime)	Per-request chat provider + model. Pick Gemini, Claude, GPT-4o, Kimi K2.5, Llama 3.3, Qwen, or Ollama and click Apply — takes effect on the very next chat answer with no container restart.
Embedding provider	Local mode. Gemini (default) or Ollama (fully offline — run `ollama pull nomic-embed-text` first). Switching providers requires a re-ingest because vector dimensions differ.
What to sync	Include / exclude globs. Defaults exclude .obsidian/, .cortex/, and templates/.
Sync attachments	Pull in PDFs, images, and other binaries referenced by your notes. On by default; toggle off in low-bandwidth setups.
Sync on startup	Run a sync automatically when Obsidian opens. Off by default — trigger manually via the Sync modal or the command palette.
Auto-highlight on graph	When on, every chat answer auto-pushes its cited entities into Obsidian's Graph view filter (non-matching nodes dim, cited ones stay highlighted). Off by default; toggle from the pin button on any answer or here in settings.
Agents panel	One-click installer that merges HangarX into Claude Desktop / Claude Code / Cursor / Cline / Windsurf MCP configs without overwriting existing entries.

Core features in depth

Vault sync

Change-detection by content hash, not modified time. Edits to .cortex/, .obsidian/, and templates are skipped. Deletes are propagated, so removing a note also removes its entities (configurable).

First sync uploads everything; subsequent syncs are diff-based and finish in seconds for typical vaults.

Ask your vault (⌘P)

GraphRAG chat that runs hybrid retrieval (BM25 + vector + graph expansion via PageRank) and cites the source notes inline. Click a citation to jump straight to the note.

Multi-hop questions like “What did we decide about pricing in the Q3 review, and who pushed back?” traverse relationships rather than just matching keywords.

Show on graph

Each chat answer can push its cited entities into Obsidian's built-in Graph view filter. Non-matching nodes dim, cited ones stay highlighted. Toggle the pin to make every future answer auto-highlight without clicking again.

Two-way sync modal

One UI for Push, Pull, Two-way, Diff (4-bucket reconciliation: vault-only · drifted · graph-only · in-sync), and Force re-ingest. Mid-flight cancellation propagates to in-flight server workers via a job ID and drains cleanly within ~30 seconds.

Inline link suggestions

Ghost-text wikilink autocomplete driven by entity matches in your graph. As you type, HangarX detects when you're referencing a known entity and suggests a [[wikilink]]. Tab accepts,Esc dismisses.

Knowledge graph stats

Totals and per-type breakdowns for entities, relationships, and documents. Surfaced both in Obsidian's stats panel and to external agents via the cortex_stats MCP tool, so a connected Claude or Cursor session can answer “how big is my graph?” in one call.

Switch LLMs on the fly

Pick Gemini, Claude, GPT-4o, Kimi K2.5, Llama 3.3, Qwen, or Ollama per request — no container restart. BYOK keys live encrypted in Postgres on the server and update the runtime config immediately when you save them in settings.

MCP tools for agents

Once an agent is connected, it gets the nine tools listed in Agents — including cortex_stats for graph totals and cortex_paths for multi-hop reasoning. Writes (cortex_remember) record provenance so you can audit what each agent claimed.

Cloud / Local toggle

Per-mode connection state. Switching from Cloud to Local doesn't migrate data — re-ingest in the new mode to rebuild the graph there. Both modes can coexist; the active one is whichever is selected.

Provenance & contradictions

Every claim is tagged with the note it came from. The cortex_contradictions tool surfaces cases where two notes assert conflicting facts about the same entity — handy when reconciling old decisions.

Architecture (local mode)

When you run the local Docker stack, three containers come up. You don't have to think about them, but here's the shape:

cortex-api

Node service on port 3400. Handles ingest, extraction, retrieval, and the MCP endpoint.

falkordb

Cypher-compatible graph database for entities and relationships. Built on Redis, so it also serves as the in-stack cache for query results and working memory — no separate Redis container needed.

postgres + pgvector

Stores chunks, embeddings, episodes, and provenance. Used for hybrid search.

Resources

Source on GitHub — issues, releases, and the full plugin code.
HangarX dashboard — manage workspaces, API keys, and billing.
Full HangarX docs — Cortex API reference, GraphRAG internals, and SDKs.
Model Context Protocol — the open spec the plugin speaks to agents.

FAQ

Is my vault data sent to the cloud?

Only if you choose Cloud mode. In Local mode, your notes, embeddings, and the entire knowledge graph stay on your machine — Docker runs Postgres + the API locally and nothing leaves the network. Cloud mode uploads chunks and embeddings to HangarX so agents can reach them from anywhere; we never train on your data and you can delete a workspace at any time.

Which agents and tools are supported?

Anything that speaks MCP — Claude Desktop, Claude Code, Cursor, Cline, Windsurf, plus generic MCP clients. The plugin's Agents panel is a one-click installer for the popular ones; for others, copy the MCP server URL and API key into your tool's config.

What does Cloud mode cost?

Free tier covers single-vault personal use. Paid plans price on monthly active credits (a credit ≈ one LLM-backed extraction or query). See pricing for current tiers. Local mode is free forever — you only pay your own LLM/embedding provider.

Which LLM and embedding providers can I use?

Cloud mode is fully managed. Local mode supports eight chat providers: Google Gemini, OpenAI, Anthropic Claude, xAI Grok, Moonshot (Kimi K2.5), HuggingFace Inference (auto-routes Kimi K2.5, Llama 3.3 70B, Qwen 2.5 72B), OpenRouter (200+ models behind one key), and Ollama (fully local). For embeddings, pick Gemini (default) or Ollama. You can mix providers — for example, run chat on Kimi via HuggingFace and embeddings on local Ollama. All keys are managed in the LLM provider keys panel, encrypted at rest, and pushed to the running container automatically — no .env editing required.

Can I switch chat models without restarting Docker?

Yes. The LLM (runtime) panel in settings lets you pick a provider and model per-request. Click Apply and the very next chat answer uses the new combination — no docker compose up, no --force-recreate. The runtime config is encrypted in Postgres and the model router consults it on every request, so the change is effectively instant.

How is HangarX different from Smart Connections / Obsidian Copilot?

Three things. (1) MCP bridge — every external agent you use (Claude Desktop, Cursor, Cline, Windsurf, Claude Code) reads from the same vault graph through nine purpose-built tools, not just the in-Obsidian chat. (2) Knowledge graph, not just embeddings — entities, relationships, and claims are extracted into a queryable FalkorDB graph alongside the vector index, so multi-hop questions like “what did we decide about pricing in Q3, and who pushed back?” actually traverse relationships. (3) Cloud or Local with BYOK — Local mode runs entirely on your laptop in Docker; you bring your own LLM keys and switch chat models per request without restarting anything.

Can I switch between Local and Cloud later?

Yes. The plugin keeps separate connections per mode, so you can flip between them in settings. Data does not migrate automatically — re-ingesting in the new mode rebuilds the graph there.

"This API key was rejected (401)" in Cloud mode.

Generate a fresh key in the dashboard and click Test on the API Key field. If you signed in via OAuth, click Sign out then Sign in with HangarX again.

Local stack: "Cannot reach http://localhost:3400".

Make sure Docker Desktop is running and docker compose ps shows the cortex-api container as healthy. Check docker compose logs cortex-api for startup errors. The most common cause is a missing LLM key — open Settings → HangarX → LLM provider keys, paste at least one key, then click Save Compose to vault and run docker compose -f docker-compose.cortex.yml up -d --force-recreate so the container picks them up.

My HuggingFace requests are returning 403 (HTML response).

The HF edge layer denied your token at the routing tier. Two common causes: (1) the token doesn't have Inference-Providers enabled — visit huggingface.co/settings/inference-providers and turn it on for your token; (2) the model needs paid credits — Kimi K2.5 via Novita, Llama 3.3 via Fireworks, etc., bill per request. Either add credits, or pick a model on HF's free serverless tier (e.g. Qwen 2.5 72B, Mistral Small 24B) in the LLM (runtime) panel.

"LLM provider API key expired" in chat.

Open Settings → HangarX → LLM provider keys, paste a fresh key in the relevant section, and click Save. The runtime config picks up the new key on the very next chat request — no container restart, no Compose YAML re-save. The chat error card now surfaces this state directly so you don't have to read docker logs cortex-api to find it.

Auto-highlight on graph isn't dimming nodes.

Two checks. (1) Has your vault been synced at least once? Dimming requires the cited entities to exist as files in the graph; otherwise nothing matches the filter. Run HangarX: Sync first. (2) Was the graph view corrupted by an older plugin version? If so the plugin auto-detaches the leaf and recreates it on the next click — just reload Obsidian once. The toggle itself is the pin button on any chat answer; settings have a persistent Auto-highlight chat answers on graph toggle too.

What is cortex_stats and why is it new?

It's an MCP tool that returns totals + per-type breakdowns for the whole knowledge graph in one call. Before cortex_stats, agents like Claude Desktop had no way to answer “how big is my graph?” — the existing tools all required a query string and returned ranked matches, not totals. Now an agent can call cortex_stats and get { totalEntities, totalRelationships, entityTypes, relationshipTypes } directly. Ships in plugin v0.0.5+; reconnect your agents to pick it up.

Local stack: embedding dimension mismatch.

You changed embedding providers and the existing chunks were embedded with a different model. Run HangarX: Force re-ingest entire vault after recreating the container, or wipe the local Postgres volume.

Agent shows "Connected" but doesn't see HangarX tools.

Restart the agent fully — Claude Desktop, Cursor, and Windsurf cache MCP servers and only re-read the config on launch. For Claude Code, start a new session.

Sync is slow on first run. Is something wrong?

No — initial syncs are O(notes × LLM latency) because each note is parsed and entity-extracted. Cloud mode uses our infrastructure; local mode is bound by your LLM provider's throughput. Switch the embedding provider to Ollama for faster, free local embeddings. Subsequent syncs only touch changed files.

Does it work with multiple vaults?

Yes. Each vault is a separate workspace in HangarX, with its own graph and API key. Agents can read across workspaces if you grant them multi-workspace scope on the key.

Is HangarX open source?

Yes — the plugin and the local Cortex API stack are open source on GitHub. Cloud mode runs the same core with managed infrastructure on top.

Ready to start?

Install the plugin, sign in, and your vault becomes shared memory across every AI tool you already use.

Install in Obsidian Open dashboard