Skip to content

mesh-ops.md

Latest commit

 

History

History
111 lines (82 loc) · 3.96 KB

mesh-ops.md

File metadata and controls

111 lines (82 loc) · 3.96 KB
Raw

Mesh operations

How to run the 2.0 memory mesh day to day. The architecture and the reasoning behind it live in mesh.md.

Bootstrap the first node

omind setup            # scaffolds the folder, initializes the mesh node,
                       # registers the `omi` MCP server (omind node)
omind mesh install-service   # start the replication daemon (systemd/launchd)
omind doctor           # everything should be green

omind setup --no-mesh keeps a machine single-node (no git, hard deletes — the 1.x behavior).

Add a second machine

On the new machine (with ssh access to an existing node):

omind mesh clone ssh://firstbox/home/you/Documents/Obsidian\ Vault/OMI
omind setup                       # register the MCP server + hooks here
omind mesh add-peer firstbox ssh://firstbox/...   # if clone's origin isn't enough
omind mesh install-service

Back on the first machine, point it at the new one too:

omind mesh add-peer newbox ssh://newbox/home/you/Documents/Obsidian\ Vault/OMI

Every node should know every node (full peer-to-peer). An unreachable peer is skipped and retried on the next cycle — partitions are normal, not errors.

Add a seed (and optionally a hosted mirror)

A seed is a passive bare repo on a usually-up box — a rendezvous and a bootstrap source, not a hub (nodes keep syncing peer-to-peer without it). One command provisions it end to end:

omind mesh add-seed seed ssh://pluto/home/you/omi-mesh.git \
    --mirror [email protected]:you/omi-mesh.git

This creates the bare repo over ssh (or at a local path), installs its post-receive hook — after every push it points main at the freshest node ref and, with --mirror, mirror-pushes the whole seed to the hosted repo — and registers it as a peer on this node. Register the same URL on the other nodes with plain omind mesh add-peer, and bootstrap new machines with omind mesh clone <seed-or-mirror-url>.

Notes travel to the mirror in plaintext — make the hosted repo private. The seed's host needs push access to the mirror (an ssh key GitHub knows). The mirror only updates when a node pushes to the seed, so a powered-off seed host just means a stale mirror, never lost data. Re-running add-seed is safe: every step converges.

Daily operation

There is nothing to do. The daemon commits local writes (debounced) and syncs on an interval. To force a pass:

omind mesh sync

omind doctor shows: node identity, merge-driver health, per-peer ahead/behind, last-sync age, unresolved conflict markers, archived-note count.

Deleting notes

  • Delete = archive. Deleting from any client sets Disabled: true; the note vanishes from listings but stays on disk and merges conflict-free. Restore from the web UI (show archived → Restore) or the restore-note MCP tool.
  • Purge is the rare exception — removes the file from every node via a replicated tombstone:
omind mesh purge "Old Note.md"

Conflicts

Concurrent edits to the same note merge field by field (see mesh.md). When the same lines of Details truly diverge, both versions are kept under conflict markers, the note is tagged #merge-conflict, and doctor warns. Open the note, keep what's right, remove the markers and the tag, save — the fix replicates like any other edit.

Privacy

  • Meshes never interact unless explicitly peered: there is no discovery and no network listener — replication is outbound git over ssh, gated by your keys.
  • mesh init locks the OMI folder to owner-only (0700) on POSIX: on a shared host, a traversable folder would let another local user read the whole memory history via a file:// fetch. Doctor warns if permissions loosen.
  • Never add-peer a repository you don't own; a peer can read everything.

Windows

Replication works (git + the same commands); the daemon has no auto-installed service — run it at logon, e.g.:

schtasks /Create /SC ONLOGON /TN omind-mesh /TR "omind mesh daemon"