Uru

Ask your Obsidian vault anything — and get answers from what you actually wrote, completely offline.

Uru makes your Obsidian vault searchable by meaning and lets you search or chat with everything you've written — with citations back to the exact notes. Everything runs on your own machine via llama.cpp; nothing is uploaded.

It's powered by Khora, a local-first search-and-connections library. Obsidian can't run Python, so Uru ships a tiny local backend that drives Khora for you — you never have to touch it.

What you can do

• Search. Ask a question and get the most relevant passages from across your vault — semantic, not keyword. Each result links back to its note.
• Chat with your vault. A RAG chat panel that answers from your notes and cites them by [1], [2]. Scope it to the whole vault or just the current note.
• Index automatically. New and edited notes are picked up as you write; deletes and renames are handled too. No manual re-sync.
• Stay private. No account, no API keys, no network calls after the one-time model download. Your notes never leave your computer — and Uru never alters them.

Get started

Requirements: Obsidian on desktop — macOS (Apple Silicon only, macOS 13.3 or newer), Windows, or Linux. Uru runs a local backend, so mobile isn't supported; Intel Macs aren't supported because Uru's vector database no longer ships Intel-Mac builds, and macOS 13.3+ is needed because Uru's local AI engine relies on math routines Apple added in that release. No Python, no GPU, no manual model setup — Uru downloads everything it needs on first run.

1. Install. In Obsidian: Settings → Community plugins → Browse, search for Uru (or open its directory page), install, and enable.
2. Run setup. A dialog opens — click Install & start. The first run downloads ~3 GB and sets up a few components. This is one-time; later launches are fast.
3. Use it. When the status bar reads Uru ✓, run the command "Uru: Index vault", then "Uru: Search in your vault" or open the chat (💬 ribbon icon).

Installing without the community directory, or with an AI assistant's help? See Install manually near the bottom.

Privacy

This is the whole point of Uru: everything happens on your own computer. All the AI runs on local models through llama.cpp, and everything is stored in an on-disk database on your machine. No account, no API keys, and — after the one-time model download — no network calls. Your notes are never copied or uploaded.

Network use

Uru touches the network in exactly one situation: the first-run setup download (and again only when a plugin update pins newer components). Every download is pinned to an exact version or revision, so the plugin can never silently fetch anything newer than what its release was tested with:

After that, everything — indexing, search, chat — talks only to Uru's own sidecar on 127.0.0.1. No telemetry, no analytics, no update pings.

The backend (the Python environment, models, llama.cpp binary, and the index/database) lives outside your vault, in per-user app-data, so it survives plugin updates and is never touched by Obsidian Sync:

A small vaults.json at the root of that folder tracks which vaults are using the shared backend, so cleanup never deletes another vault's data out from under it.

Permissions

Because Uru runs a real local AI service rather than calling a cloud API, it uses a few desktop capabilities that most plugins don't. Obsidian's automated review flags these categories for every plugin that uses them, so here is exactly what Uru does with each:

• Direct filesystem access — used only outside your vault, for the app-data folders in the table above: installing the Python environment, models, and llama.cpp binary; storing the per-vault index database and its state file; and maintaining vaults.json. (On Linux it also reads /sys/class/drm to detect your GPU vendor.) Uru never reads or writes your notes through the filesystem — notes are read through Obsidian's vault API, and the only vault-adjacent touch is resolving the plugin's own folder path at startup.
• Shell execution — Uru starts and supervises its local backend. Every call runs a fixed binary with a fixed argument list (never a shell command built from text, so nothing can be injected): the version-pinned uv to build the Python environment, the resulting python to run the sidecar, llama-server --list-devices to probe for a usable GPU, a PowerShell WMI query on Windows for GPU detection, and ps/pgrep/taskkill to verify and stop the sidecar process safely.
• Vault enumeration — Uru is a search index; listing your Markdown files is how it knows what to index. The list is filtered by your ignore patterns, and file paths go only to the local sidecar on 127.0.0.1.
• Clipboard — write-only, and only when you click a Copy diagnostics button (in Settings or the setup dialog). Uru never reads your clipboard.

Uninstalling Uru? It's a two-step process, because Obsidian's plugin remover only deletes the plugin's own folder inside your vault — it can't reach outside it:

1. In Obsidian, go to Settings → Uru → Danger zone → "Uninstall Uru". This checks whether any other vault is still using the shared backend and only deletes what's safe — the models, Python environment, and this vault's index.
2. Then remove the plugin as usual from Settings → Community plugins.

If Uru is installed in more than one vault, "Uninstall Uru" stays disabled — deleting the shared backend would break the other vaults. To stop using Uru in just one vault, disable it there from Settings → Community plugins; the shared backend stays for the rest.

If you already removed the plugin without doing step 1, see Troubleshooting for how to clean up manually.

Hardware

Troubleshooting

• Stuck on "starting" / setup failed — the setup dialog (and Settings → Uru) has a Copy diagnostics button. Paste that when reporting an issue.
• Uru ✕ after it was working — an inference server may have crashed; Uru restarts it automatically and the badge returns to Uru ✓. If it stays red, grab diagnostics.
• Indexing is slow — very large vaults can take a while on CPU-only machines. Run "Uru: Stop indexing" any time; the next run resumes where it left off.
• Start over — to rebuild the index from scratch, use "Re-index everything" under Settings → Uru → Indexing. If the local backend itself is misbehaving, "Repair Uru" (Settings → Uru → Status) re-runs setup without touching your index.
• I already removed the plugin and now have leftover files — Uru couldn't run any cleanup code, since the plugin is gone. Manually delete the per-OS folder from the Privacy table (e.g. ~/Library/Application Support/uru on macOS). This is only safe if you're not using Uru in any other vault — if you are, open uru/vaults.json to see which uru/vaults/<id> subfolder belongs to which vault (by name/path), delete only the ones you no longer need, and leave uru/runtime alone.

Changelog

See CHANGELOG.md for the full release history.

How it works (for the curious)

Obsidian plugin (TypeScript)
  → spawns + Bearer-auth HTTP →  uru_sidecar (Python, FastAPI)
                                   ├─ Khora  (sqlite_lance: SQLite + LanceDB)
                                   └─ proxy → 2× llama.cpp servers (chat + embed)

Khora is a pure-Python library, so the plugin drives it through a small local sidecar. The sidecar runs two single-model llama-server processes — a chat model (used for RAG answers) and an embedding model — behind a one-URL, OpenAI-compatible proxy, then points Khora at them. It supervises those processes and restarts either one if it dies, and idle-shuts-down when you're not using Uru.

Default models (~3 GB total):

• Chat: Qwen2.5-3B-Instruct (Q4_K_M GGUF) — see The chat model
• Embeddings: bge-m3 (Q8_0 GGUF, 1024-dim, 8192-token context — the dimension fixes the vector dimension, so changing it requires a full re-index) — see The embedding model

The chat model

Uru answers your questions with Qwen2.5-3B-Instruct, from Alibaba's Qwen team, downloaded as a quantized GGUF from Hugging Face. It's the model behind the chat panel: given the passages Uru retrieves from your vault, it writes the answer and the [1], [2] citations back to your notes.

Why this one:

• Small enough to run locally. At 3B parameters it fits in a few GB of RAM and runs on a laptop CPU (and much faster on Apple Silicon / a supported GPU) — no cloud, no API key.
• Strong instruction-following for its size. Qwen2.5-3B holds up well at grounded, "answer only from these passages" RAG prompting, which is exactly what Uru asks of it.
• Q4_K_M quantization trades a sliver of quality for roughly half the memory and faster generation — the sweet spot for a resident local model.

The model runs entirely on your machine through llama.cpp; nothing you type or retrieve leaves your computer.

The embedding model

Search and retrieval are powered by bge-m3, from BAAI (Beijing Academy of Artificial Intelligence), also a quantized GGUF (Q8_0) from Hugging Face. Every note you index is turned into a numeric vector by this model; a search embeds your query the same way and finds the passages whose vectors are closest — that's what makes search semantic rather than keyword.

Why this one:

• Built for retrieval. bge-m3 is a dedicated embedding model with strong retrieval quality, so "find what I mean" works even when your wording doesn't match the note's.
• Multilingual — it embeds many languages into the same space, so a vault isn't limited to English.
• Long context (8192 tokens) lets it embed sizable passages without chopping them into tiny fragments.
• 1024 dimensions at Q8_0 keeps vectors compact while preserving quality. This dimension is fixed: it defines the shape of every stored vector, so switching embedding models later requires a full re-index.

Like the chat model, it runs locally via llama.cpp — your notes are never uploaded.

git clone https://github.com/Arsenije/Uru.git
cd Uru
npm install
npm run install-plugin -- "<your-vault>"    # builds, then deploys into .obsidian/plugins/uru/

GOAL: Install the Uru Obsidian plugin into the user's vault.

INPUTS YOU NEED FROM THE USER:
  - VAULT  = absolute path to their Obsidian vault (the folder containing `.obsidian/`)

STEP 1 — get the plugin files. Pick ONE:

  Option A — prebuilt release (no Node toolchain needed; prefer this):
    With the GitHub CLI (one command, always the right assets):
      gh release download --repo Arsenije/Uru \
        --pattern 'main.js' --pattern 'manifest.json' --pattern 'styles.css' \
        --dir "<VAULT>/.obsidian/plugins/uru"
      # no tag = newest release. `gh release view --repo Arsenije/Uru` (no tag)
      # shows the latest; the literal word `latest` is NOT a valid tag argument.
    Without gh, download the main.js, manifest.json, and styles.css ASSETS from
    https://github.com/Arsenije/Uru/releases/latest by hand into
    `<VAULT>/.obsidian/plugins/uru/`.
    IMPORTANT: use the individual assets, NOT GitHub's "Source code (zip)" — the
    source archive has no built main.js, so the plugin will fail to load.
    NOTE: the assets are small (~150 KB total) — expected, NOT a broken/partial
    download. The Python sidecar is embedded in main.js; its dependencies and
    the models install on first run.

  Option B — build from source (requires Node.js 18+):
    git clone https://github.com/Arsenije/Uru.git
    cd Uru
    npm install
    npm run install-plugin -- "<VAULT>"   # builds AND copies the plugin files
                                          # into .obsidian/plugins/uru/

STEP 2 — VERIFY staging (headless; this is as far as you can verify — everything
  after this is GUI-only and only the user can confirm it):
  Run the SAME checker for either install path — it prints "OK: Uru <version> staged ...":
    Option B (source clone):     node scripts/verify-staging.mjs "<VAULT>"
    Option A (release assets), or either without a local copy: curl -fsSL \
      https://raw.githubusercontent.com/Arsenije/Uru/main/scripts/verify-staging.mjs \
      | node - "<VAULT>"
  The checker confirms main.js (with the embedded sidecar), manifest.json, and
  styles.css are present and non-empty. Do NOT hand off until it prints "OK:".

STEP 3 — HAND OFF TO THE USER (you cannot click Obsidian's UI):
  Tell them: "Open Obsidian → Settings → Community plugins → enable 'Uru'.
  A setup dialog appears — click 'Install & start'. The first run downloads
  ~3 GB; wait for it."

STEP 4 — tell them the success signal:
  The Obsidian status bar shows `Uru ✓`. If it shows `Uru ✕`, the setup
  dialog (and Settings → Uru) has a "Copy diagnostics" button — ask for that text.

STEP 5 — tell them how to use it:
  Run the command "Uru: Index vault", then "Uru: Search in your vault" or the 💬 chat icon.

DO NOT:
  - Try to install on Obsidian mobile (desktop only).
  - Place files outside `<VAULT>/.obsidian/plugins/uru/`.
  - Install Python, llama.cpp, or models by hand — Uru bootstraps them itself.

npm install
npm run dev          # watch-build main.js
npm run build        # production build + typecheck

cd sidecar
PYTHONPATH=. .venv/bin/python scripts/smoke_sidecar.py

Uru/
├── main.ts              # plugin entry — lifecycle, commands, status
├── src/
│   ├── bootstrap/uv.ts  # uv-based Python/Khora bootstrap + model download
│   ├── sidecar/         # process manager + typed HTTP client
│   ├── indexing/        # full + incremental vault indexing (hash-gated)
│   ├── views/           # search + chat panels
│   └── settings.ts      # settings tab
└── sidecar/             # Python sidecar (FastAPI + llama.cpp supervisor)
    └── uru_sidecar/

License

MIT