omind

OMI/Obsidian memory tooling for Claude Code: reproduce the integration on any machine, plus a local web app to view, edit, and add memory entries.

Mirrored on both GitHub and Codeberg. Issues filed on either are welcome; commits are pushed to both.

---

The omind serve web UI viewing a memory note in the Midnight theme — one of five built-in themes.

What it does

OMI ("Open Mind Interface") is a folder of Markdown notes that an AI agent reads and writes as long-term memory. omind does two things with it:

• omind setup — idempotently provisions the obsidian-mcp server for the Claude Code CLI, pointed at an OMI folder inside an Obsidian vault. After this, Claude Code can persist memory across sessions through the MCP tools.
• omind serve — a small local web app (FastAPI + Tailwind) to view, edit, and add memory entries in that same folder, without opening Obsidian. Ships with five themes and a switchable UI in six languages (English, Spanish, French, Arabic, Russian, Chinese), including right-to-left layout for Arabic.
• omind doctor — diagnose the wiring in one shot: Node/npm/Claude CLI on PATH, the MCP server registered at user scope (in the leak-free direct-node form) and pointed at the right folder, the stdin-EOF guard in place, and the OMI folder + Obsidian config readable.

The web UI works fully offline (fonts, styles, and the Markdown renderer are vendored — no CDN). It shows backlinks for the open note, refreshes the list live as other tools write the folder, guards against clobbering external edits, and has keyboard shortcuts (/ search, n new, j/k to move, Ctrl/Cmd+S to save, Esc to cancel).

Everything runs locally. No accounts, no cloud, no cost.

Install

One-step bootstrap (checks/installs dependencies, installs omind, verifies):

# clone, then:
scripts/bootstrap.sh                       # or: --remote codeberg, --vault PATH

It auto-installs uv (user-local, no root — and it bootstraps Python ≥3.10 for you), checks for node/npm/claude with install guidance if any are missing, then runs omind setup + omind doctor. Note: omind has no Docker dependency — only Node.js and the Claude Code CLI.

Manual — an isolated CLI install straight from the git remote:

# via uv (recommended — also provides a compatible Python if the system one is <3.10)
uv tool install git+https://github.com/CryptoJones/omind.git

# or via pipx
pipx install git+https://github.com/CryptoJones/omind.git

Either puts the omind command on your PATH in its own virtualenv. Codeberg works too — swap in git+https://codeberg.org/CryptoJones/omind.git.

For development, install editable from a clone (see CONTRIBUTING.md):

git clone https://github.com/CryptoJones/omind.git
cd omind
pip install -e ".[dev]"

Quick start

Provision the Claude Code MCP wiring (idempotent; safe to re-run):

omind setup --vault "$HOME/Documents/Obsidian Vault"

Prefer to wire things in yourself? Print the same steps as copy-paste shell commands and JSON, personalized to your paths — nothing is changed for you:

omind quickstart --vault "$HOME/Documents/Obsidian Vault"

It covers all four pieces (memory folder scaffold, MCP server install + stdin-EOF guard, user-scope registration, auto-memory hooks), each independently applicable. The annotated walkthrough lives in docs/manual-setup.md.

Run the web UI over the same memory folder:

omind serve --vault "$HOME/Documents/Obsidian Vault"
# open http://127.0.0.1:8765

Preview what setup would do without changing anything:

omind setup --vault "$HOME/Documents/Obsidian Vault" --dry-run

Check that everything is wired up correctly:

omind doctor --vault "$HOME/Documents/Obsidian Vault"

Back up or migrate the whole memory dataset:

# export — json (default; portable & diffable) or targz (full-fidelity snapshot)
omind export --vault "$HOME/Documents/Obsidian Vault" --out omi-export.json
omind export --vault "$HOME/Documents/Obsidian Vault" --format targz --out omi.tar.gz

# import — format auto-detected by extension
omind import omi-export.json --vault "$HOME/Documents/Obsidian Vault"

Import adds new notes and leaves identical ones untouched; a note whose content differs is kept as-is on disk and reported, unless you pass --force. Imports never delete.

See CHANGELOG.md for release notes.

License

Apache 2.0. See LICENSE.

Proudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/