{"id":50792841,"url":"https://github.com/cryptojones/omind","last_synced_at":"2026-06-12T12:02:23.028Z","repository":{"id":363576509,"uuid":"1258427032","full_name":"CryptoJones/omind","owner":"CryptoJones","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-09T13:27:48.000Z","size":1193,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T14:16:24.224Z","etag":null,"topics":["claude-code","cli","fastapi","markdown","mcp","memory","obsidian","python"],"latest_commit_sha":null,"homepage":"https://github.com/CryptoJones/omind","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CryptoJones.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T15:10:03.000Z","updated_at":"2026-06-09T12:36:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CryptoJones/omind","commit_stats":null,"previous_names":["cryptojones/omind"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/CryptoJones/omind","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2Fomind","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2Fomind/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2Fomind/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2Fomind/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CryptoJones","download_url":"https://codeload.github.com/CryptoJones/omind/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CryptoJones%2Fomind/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34243053,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","cli","fastapi","markdown","mcp","memory","obsidian","python"],"created_at":"2026-06-12T12:01:45.597Z","updated_at":"2026-06-12T12:02:22.942Z","avatar_url":"https://github.com/CryptoJones.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# omind\n\nOMI/Obsidian memory tooling for AI agents: reproduce the integration on any machine, plus a local web app to view, edit, and add memory entries.\n\n[![Tests](https://github.com/CryptoJones/omind/actions/workflows/test.yml/badge.svg)](https://github.com/CryptoJones/omind/actions/workflows/test.yml)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?logo=apache)](LICENSE)\n[![Codeberg](https://img.shields.io/badge/Codeberg-CryptoJones%2Fomind-2185D0?logo=codeberg\u0026logoColor=white)](https://codeberg.org/CryptoJones/omind)\n[![GitHub](https://img.shields.io/badge/GitHub-CryptoJones%2Fomind-181717?logo=github\u0026logoColor=white)](https://github.com/CryptoJones/omind)\n[![Python](https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python\u0026logoColor=white)](https://www.python.org/)\n[![Version](https://img.shields.io/github/v/tag/CryptoJones/omind?label=version\u0026color=orange)](https://github.com/CryptoJones/omind/tags)\n\n\u003e Mirrored on both [GitHub](https://github.com/CryptoJones/omind) and\n\u003e [Codeberg](https://codeberg.org/CryptoJones/omind). Issues filed on\n\u003e either are welcome; commits are pushed to both.\n\n---\n\n![omind web UI — viewing a memory note in the Midnight theme](docs/screenshot.png)\n\n*The `omind serve` web UI viewing a memory note in the Midnight theme — one of five built-in themes.*\n\n## What it does\n\n**OMI** (\"Open Mind Interface\") is a folder of Markdown notes that an AI agent\nreads and writes as long-term memory. `omind` does two things with it:\n\n- **`omind setup`** — idempotently registers **omind's own node MCP server**\n  (`omind node`) with the Claude Code CLI, pointed at an OMI folder inside an\n  Obsidian vault, and initializes the folder as a **mesh node** (see below).\n  After this, Claude Code persists memory across sessions through the MCP\n  tools — and across machines through the mesh.\n- **`omind mesh`** — peer-to-peer replication: every machine runs a full local\n  node and nodes sync over git+ssh, with per-note Lamport versioning and a\n  field-level merge driver. No central server, full offline operation.\n  Deleting archives (restorable) instead of removing. See\n  [docs/mesh.md](docs/mesh.md) (design) and [docs/mesh-ops.md](docs/mesh-ops.md)\n  (operation).\n- **`omind serve`** — a small local web app (FastAPI + Tailwind) to **view, edit,\n  and add** memory entries in that same folder, without opening Obsidian. Ships\n  with five themes and a switchable UI in six languages (English, Spanish,\n  French, Arabic, Russian, Chinese), including right-to-left layout for Arabic.\n- **`omind doctor`** — diagnose the wiring in one shot: Claude CLI + git on\n  `PATH`, the `omi` MCP server registered at user scope with the right command,\n  the OMI folder readable, mesh health (node identity, merge driver, per-peer\n  ahead/behind, last-sync age, unresolved conflicts), backup health\n  (unconfigured / last-success age / failing), and whether the auto-memory\n  hooks have recorded any recent failures.\n- **`omind backup`** — encrypted, unattended off-machine backup of the OMI\n  folder, wrapping [restic](https://restic.net/) (see\n  [Encrypted backup](#encrypted-backup) below).\n\nThe web UI works **fully offline** (fonts, styles, and the Markdown renderer are\nvendored — no CDN). It shows **backlinks** for the open note, refreshes the list\nlive as other tools write the folder, guards against clobbering external edits,\nand has keyboard shortcuts (`/` search, `n` new, `j`/`k` to move, `Ctrl`/`Cmd`+`S`\nto save, `Esc` to cancel).\n\nEverything runs locally. No accounts, no cloud, no cost.\n\n## Install\n\n**One-step bootstrap** (checks/installs dependencies, installs omind, verifies):\n\n```bash\n# clone, then:\nscripts/bootstrap.sh                       # or: --remote codeberg, --vault PATH\n```\n\nIt auto-installs `uv` (user-local, no root — and it bootstraps Python ≥3.10 for\nyou), checks for `git`/`claude` with install guidance if either is missing,\nthen runs `omind setup` + `omind doctor`. Note: omind has **no Docker and no\nNode.js dependency** — only git and the Claude Code CLI.\n\n**Manual** — an isolated CLI install straight from the git remote:\n\n```bash\n# via uv (recommended — also provides a compatible Python if the system one is \u003c3.10)\nuv tool install git+https://github.com/CryptoJones/omind.git\n\n# or via pipx\npipx install git+https://github.com/CryptoJones/omind.git\n```\n\nEither puts the `omind` command on your `PATH` in its own virtualenv. Codeberg\nworks too — swap in `git+https://codeberg.org/CryptoJones/omind.git`.\n\nFor development, install editable from a clone (see [CONTRIBUTING.md](CONTRIBUTING.md)):\n\n```bash\ngit clone https://github.com/CryptoJones/omind.git\ncd omind\npip install -e \".[dev]\"\n```\n\n## Quick start\n\nProvision the Claude Code MCP wiring (idempotent; safe to re-run):\n\n```bash\nomind setup --vault \"$HOME/Documents/Obsidian Vault\"\n```\n\nPrefer to wire things in yourself? Print the same steps as copy-paste shell\ncommands and JSON, personalized to your paths — nothing is changed for you:\n\n```bash\nomind quickstart --vault \"$HOME/Documents/Obsidian Vault\"\n```\n\nIt covers all four pieces (memory folder scaffold, mesh initialization,\nuser-scope MCP registration, auto-memory hooks), each independently\napplicable. The annotated walkthrough lives in\n[docs/manual-setup.md](docs/manual-setup.md).\n\nRun the web UI over the same memory folder:\n\n```bash\nomind serve --vault \"$HOME/Documents/Obsidian Vault\"\n# open http://127.0.0.1:8765\n```\n\nPreview what setup *would* do without changing anything:\n\n```bash\nomind setup --vault \"$HOME/Documents/Obsidian Vault\" --dry-run\n```\n\nCheck that everything is wired up correctly:\n\n```bash\nomind doctor --vault \"$HOME/Documents/Obsidian Vault\"\n```\n\nAdd or update a single memory note safely — it creates the note, or updates it\nin place if the title already exists, through the same locked, atomic write path\nevery other tool uses (body comes from stdin):\n\n```bash\necho \"the body of the note\" | omind note --title \"An Insight\" --tags thesis,attention\n```\n\nBack up or migrate the whole memory dataset:\n\n```bash\n# export — json (default; portable \u0026 diffable) or targz (full-fidelity snapshot)\nomind export --vault \"$HOME/Documents/Obsidian Vault\" --out omi-export.json\nomind export --vault \"$HOME/Documents/Obsidian Vault\" --format targz --out omi.tar.gz\n\n# import — format auto-detected by extension\nomind import omi-export.json --vault \"$HOME/Documents/Obsidian Vault\"\n```\n\nImport adds new notes and leaves identical ones untouched; a note whose content\ndiffers is kept as-is on disk and reported, unless you pass `--force`. Imports\nnever delete.\n\n## Encrypted backup\n\nThe vault is long-term memory on one disk; `omind backup` keeps an encrypted\ncopy off-machine, wrapping [restic](https://restic.net/):\n\n```bash\n# one-time: generate the password file (0600) and create the encrypted repo\nomind backup init --repo sftp:host:/path     # or a local path, s3:, b2:, …\n\n# snapshot now, with 7-daily / 4-weekly / 6-monthly retention\nomind backup run\n\n# restic check + restore the latest snapshot's index.md and diff it live\nomind backup verify\n\n# unattended: a daily systemd user timer running `backup run`\nomind backup install-timer\n```\n\nEvery external command runs with a timeout, so a restic hung on a dead link\nfails loudly instead of wedging the timer; three consecutive failures write a\n`BACKUP FAILING` note into the vault so the problem surfaces in session\npriming, and `omind doctor` reports backup health either way. If restic is\nabsent, `run` degrades to unencrypted rsync `--link-dest` snapshots and doctor\nwarns about the degradation.\n\n**Copy `~/.config/omind/backup.pass` somewhere safe off-machine.** It encrypts\nevery snapshot; losing it with the disk makes the backups unreadable.\n\n## Other agents: Hermes Agent and OpenClaw\n\nClaude Code is the default, but the same OMI folder can back any agent. `omind\nsetup --agent ...` provisions two more out of the box:\n\n```bash\nomind setup --agent hermes   --vault \"$HOME/Documents/Obsidian Vault\"   # Hermes Agent\nomind setup --agent openclaw --vault \"$HOME/Documents/Obsidian Vault\"   # OpenClaw\n```\n\nEach does the same three things, adjusted for where that agent keeps its\nconfig:\n\n1. The shared steps — OMI folder scaffold, mesh initialization — identical to\n   the Claude Code path, so all agents talk to **one** memory folder through\n   the same `omind node` server.\n2. Registers the MCP server where the agent looks for it: the `mcp_servers`\n   block in `~/.hermes/config.yaml` (Hermes Agent), or the `mcp.servers` block\n   in `~/.openclaw/openclaw.json` (OpenClaw — legacy `~/.clawdbot` /\n   `~/.moltbot` installs are detected too). Only omind's own entry is ever\n   touched; a config file that doesn't parse is never overwritten.\n3. Installs an `omind-omi-memory` skill into the agent's skills directory that\n   teaches it to **read** memory through the MCP tools and **write** it through\n   `omind note` — the single-writer path that keeps concurrently running\n   agents from corrupting the folder (see\n   [docs/mesh.md](docs/mesh.md) → \"Node types \u0026 the single-writer rule\").\n\n`omind doctor --agent hermes|openclaw` diagnoses that agent's wiring, and\n`omind quickstart --agent hermes|openclaw` prints the manual steps (YAML/JSON\nsnippets personalized to your paths) if you'd rather merge them in yourself.\n\nThe auto-memory journal hooks remain Claude Code-only for now — Hermes Agent\nand OpenClaw emit different hook payloads; their actions reach OMI through the\nskill instead.\n\nSee [CHANGELOG.md](CHANGELOG.md) for release notes.\n\n## The memory mesh (2.0)\n\n2.0.0 turned omind from a single-machine tool into a **git-backed mesh** —\nevery machine runs a full local memory node, and the nodes replicate to one\nanother **peer-to-peer over git**, so memory is shared across the house with\n**no central server** and full offline operation. Concurrent writes build on\nthe per-node write safety (advisory `flock` + atomic `os.replace` +\n`note_version` compare-and-swap) and add cross-node **Lamport versioning**\nwith a field-level merge; \"deleting\" a note **archives** it (hidden,\nrestorable) rather than tombstoning it. Design:\n**[docs/mesh.md](docs/mesh.md)**; operation:\n**[docs/mesh-ops.md](docs/mesh-ops.md)**.\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n\nProudly Made in Nebraska. Go Big Red! 🌽 https://xkcd.com/2347/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fomind","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptojones%2Fomind","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptojones%2Fomind/lists"}