HangarX

HangarX for Obsidian

Stop re-introducing yourself to your AI.

HangarX turns your Obsidian vault into shared memory that every AI agent on your machine can query. Instead of re-explaining your projects to Claude, then to Cursor, then to Claude Code, your notes become a queryable knowledge graph — with entities, relationships, and citations — exposed through the Model Context Protocol (MCP). Agents can ask questions grounded in your vault, surface related notes, and write new findings back to the graph.

Run it hosted (sign in with HangarX, zero setup) or fully local (Docker + BYOK for OpenAI, Anthropic, Google, Mistral, Cohere, Groq, Together AI, or Ollama). The plugin ships with: a chat panel that cites the vault notes behind every answer, one-modal two-way sync between vault and graph, live entity highlighting on Obsidian's native graph view, inline wikilink suggestions powered by graph matching, and one-click MCP setup for Claude Desktop, Cursor, Cline, Windsurf, and Claude Code.

📖 Full docs · 🌐 Dashboard · 🐛 Issues

---

Why

You've already written everything: standups, design docs, half-finished thoughts. The bottleneck isn't capturing knowledge — it's making it usable by the agents you use 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 one source of truth they all read.

Who it's for

• Note-takers who want a smarter Q&A surface than the built-in search.
• Agent power users running 2+ AI tools that should share context.
• Teams with a single vault of decisions, runbooks, and architectural notes.
• Privacy-first users who want everything to stay on their laptop (Local mode = no cloud, no data leaves your machine).

---

What it does

---

Install

Community plugins (recommended).

1. Settings → Community plugins → Browse
2. Search "HangarX" → Install → Enable
3. The first-run onboarding modal walks you through Cloud / Local setup.

BRAT (beta builds). Install BRAT, then Add beta plugin → paste https://github.com/3-Elements-Design/hangarx-obsidian.

Manual. Grab main.js, manifest.json, styles.css from the latest release and drop them in <your-vault>/.obsidian/plugins/hangarx-obsidian/. Reload Obsidian, enable in Community Plugins.

---

Quick start

Cloud — 60 seconds

Best for trying HangarX out. Sign-in is OAuth, no key copy-paste.

1. Settings → HangarX → Connection → Mode: Cloud (hosted)
2. Sign in with HangarX → approve in browser → API key + workspace auto-fill
3. Command palette (⌘P / Ctrl-P) → Sync
4. Open the Ask your vault chat in the right sidebar and ask anything

Local — fully private

Everything runs in Docker on your machine. Notes never leave the laptop.

1. Settings → HangarX → Connection → Mode: Local (docker)
2. Add at least one LLM key in LLM provider keys (Gemini, OpenAI, Anthropic, Kimi, HuggingFace, OpenRouter, xAI, or Ollama for fully offline)
3. Click Save to vault — writes docker-compose.cortex.yml next to your notes with your keys baked in
4. In a terminal: docker compose -f docker-compose.cortex.yml up -d
5. Run Sync from the command palette

Requires Docker Desktop. Images are pulled from Docker Hub (hangarx/cortex-api) — no source code or Node.js needed.

Hand step 4 to Claude Code (or any LLM agent)

After step 3, instead of opening a terminal yourself, paste this prompt into Claude Code, Cursor, Cline, or any agentic coding assistant. It handles Docker checks, startup, health-polling, and troubleshooting.

You're helping me bring up the HangarX local stack for the Obsidian plugin
(https://community.obsidian.md/plugins/hangarx). Be terse — one update
per phase, no narration.

1. Find docker-compose.cortex.yml at the root of my Obsidian vault. Ask
   me for my vault path if you can't infer it. If the file doesn't
   exist, stop and tell me to open Obsidian → Settings → HangarX →
   Local mode → click "Save to vault" in step 2, then re-run this prompt.

2. Verify Docker is ready: `docker --version` and `docker ps` both
   succeed. If Docker Desktop isn't installed, point me to
   https://www.docker.com/products/docker-desktop/ and stop. If it's
   installed but not running, launch it (`open -a Docker` on macOS) and
   wait until `docker ps` succeeds before continuing.

3. cd to my vault and run:
   docker compose -f docker-compose.cortex.yml up -d
   First run pulls hangarx/cortex-api, falkordb/falkordb, and
   pgvector/pgvector:pg16 — expect a few minutes.

4. Poll `curl -sf http://127.0.0.1:3400/health` every 3 seconds for up
   to 90 seconds. If it doesn't come up, show me the last 30 lines of
   `docker compose -f docker-compose.cortex.yml logs cortex-api`.

5. Once healthy, tell me to open Obsidian's command palette and run
   "HangarX: Sync". The plugin's settings page will flip from the
   three-step wizard to "✓ Local stack running" on its next probe
   (Retry button on the connection status pill if it doesn't refresh).

If anything fails:
- Port 3400 in use → `lsof -i :3400` to see who's using it. Either
  stop that process or change CORTEX_PORT in the compose file and
  re-run with `up -d --force-recreate`.
- cortex-api exits immediately → check the logs. Most common: missing
  LLM provider key (re-save the YAML from Obsidian with a key
  configured) or Postgres healthcheck failing on first boot
  (`docker compose down -v` and retry).

Don't generate the docker-compose file yourself — the plugin owns it
(encryption keys + provider keys are baked in by Obsidian so re-saves
stay in sync). If the file is missing or broken, hand control back to
the plugin's "Save to vault" button.

The same prompt is available as a "Copy LLM setup prompt" button next to the docker command in step 3 of the plugin's local setup wizard.

---

How it works

┌──────────────┐       ┌──────────────┐       ┌──────────────────┐
│  Your vault  │  ──►  │  Cortex API  │  ──►  │ Knowledge graph  │
│  (markdown)  │       │  (entity     │       │  FalkorDB +      │
│              │       │  extraction) │       │  pgvector        │
└──────────────┘       └──────────────┘       └──────────────────┘
                              ▲                        ▲
                              │                        │
                       ┌──────┴────────┐       ┌───────┴────────┐
                       │ Obsidian      │       │ External agents│
                       │ chat panel    │       │ (Claude, Cursor│
                       │ + graph view  │       │  Cline, etc.)  │
                       └───────────────┘       └────────────────┘

1. Sync parses your notes, extracts entities (people, projects, concepts) + relationships, and stores them as a graph alongside vector embeddings.
2. Ask runs multi-hop retrieval (graph traversal + semantic search + reranking) over that graph and an LLM composes the answer with citations.
3. MCP bridge exposes the same retrieval tools to external agents over a local protocol — they query your vault the same way the in-Obsidian chat does.

---

Connect external agents

Settings → Agents shows every supported harness:

Click Connect and HangarX merges its MCP server entry into the agent's config (non-destructively — your other MCP servers stay). Restart the agent and it gets the tools below.

The same tool set is available to the in-Obsidian chat agent and to every MCP-compatible client. Tool names match what you'll see in your AI tool's debug panel.

Q&A and unified retrieval

Knowledge-graph exploration

Document retrieval

Memory (cross-session)

Graph health and ops

Ingestion and writes

Web access

Workflows and automation

Live event streams

Generative

50+ tools total. Most agents will only use 5–10 of them — the Q&A, exploration, and memory sections cover almost every common workload. The rest are there when you need them.

---

In-Obsidian features

Ask your vault

Right-sidebar chat. Multi-hop retrieval with citations. Click an entity chip to open the source note; click a citation to jump to the exact paragraph.

• Suggested starters — Catch me up · Trace connections · Surface decisions · Find blind spots
• Auto-highlight on graph — toggle the pin on any answer to make every future answer auto-push its cited entities into the Graph view filter
• Save as note — drop the answer into Cortex Chats/
• Conversation history — sessions persist across restarts

Sync modal

Sync (in the command palette) — one place, five actions:

Push runs are cancellable mid-flight; cancellation propagates to in-flight server workers.

Inline link suggestions

Type and HangarX shows ghost-text [[wikilink]] autocompletes from your graph. Tab to accept, Esc to dismiss.

---

Supported LLM providers

Pick any in Settings → HangarX → LLM provider keys (BYOK) or in the per-request LLM (runtime) panel. Switch on the fly — no container restart.

• 🟦 Google Gemini — fast, cheap default
• 🟩 OpenAI — GPT-5.x, o-series
• 🟧 Anthropic Claude — Sonnet 4.x, Opus 4.x
• ⬛ xAI Grok
• 🟨 Moonshot Kimi K2.5 — direct
• 🟪 HuggingFace Inference — auto-routes Kimi K2.5, Llama 3.3 70B, Qwen 2.5 72B
• 🌐 OpenRouter — 200+ models behind one key
• 💻 Ollama — fully local (gemma3, llama3.3, qwen2.5, mistral, phi4, …)

---

Privacy

Excluded by default: .cortex/, templates/, plus your vault's config folder (whatever Vault#configDir resolves to — usually .obsidian/). Configurable in What to sync. Attachments: images, PDFs, and other binaries are ingested by default. Toggle off in Sync attachments.

Background network activity: while the Ask your vault panel or Knowledge graph stats modal is open, the plugin polls the configured API's /health endpoint every 30 seconds to keep the connection-status pill accurate. The poll sends no vault data — just a bare GET — and stops when the panel/modal closes. Vault syncs are change-driven (triggered by edits/saves), not on a periodic timer.

---

Commands

All commands appear in the palette under the HangarX plugin namespace.

---

Troubleshooting

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

The chat error card surfaces this directly. Open Settings → HangarX → LLM provider keys, paste a fresh key in the relevant section. Runtime config updates immediately — no container restart.

Visit huggingface.co/settings/inference-providers and confirm your token has provider access. Paid models (Kimi K2.5 via Novita, Llama 3.3 via Fireworks) need credits — switch to a free serverless model in the runtime panel if not.

Make sure Docker Desktop is running and docker compose ps shows cortex-api as healthy. Check docker compose logs cortex-api for startup errors. The most common cause is a missing LLM key — re-save the Compose YAML from settings (it bakes in whichever BYOK keys you've configured) and docker compose up -d --force-recreate.

You changed embedding providers and existing chunks were embedded with a different model. Run Force re-ingest entire vault from the command palette, or wipe the local Postgres volume.

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.

Make sure you've synced your vault at least once — dimming requires the cited entities to exist as files. If the graph view was previously corrupted by an older plugin version, the plugin auto-detaches and recreates the leaf — reload Obsidian once.

Initial syncs are bound by LLM latency (O(notes × LLM round-trip)). Cloud uses our infrastructure; local is bound by your provider. Switch the embedding provider to Ollama for free, fast local embeddings.

---

Architecture

For the deep-dive on how entity extraction, multi-hop retrieval, claim graphs, and the MCP bridge actually work, see docs/HOW_IT_WORKS.md.

Contributing

Issues and PRs welcome at github.com/3-Elements-Design/hangarx-obsidian.

License

MIT — see LICENSE.