From 3335b4d59a50a7a5fb810702bbfa1b8d30a7776d Mon Sep 17 00:00:00 2001 From: vreshch Date: Sun, 21 Jun 2026 12:48:27 +0200 Subject: [PATCH] docs: trim README to non-technical (drop Building from source / How it works / Mobile sections) --- README.md | 35 +++++++---------------------------- 1 file changed, 7 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index cf829d4..9ecac8d 100644 --- a/README.md +++ b/README.md @@ -8,15 +8,15 @@ Two-way **Git** sync between your Obsidian vault and your private [Agentage Memory](https://agentage.io) - the shared memory layer for every AI. Your notes stay plain Markdown that you own, and Claude, ChatGPT, Cursor, and any MCP client read and write the *same* files. -> ⚠️ **Status:** **desktop only** today (`isDesktopOnly`). Desktop git sync + Agentage sign-in (OAuth 2.1 / PKCE) work. Mobile is planned (see [Mobile](#mobile-planned)); background auto-sync is next. +> ⚠️ **Status:** **desktop only** for now - mobile is on the way. ## Features - 🔄 **Two-way Git sync** - clone / pull / commit / push your vault to `sync.agentage.io`. The server is a bare git repo per memory that you can clone or export anytime. - 🧠 **Pick or create a memory** - choose which memory this vault syncs into, or create a new one, from a single dialog (search your memories, see file/folder counts). - 🤝 **Shared with every AI over MCP** - the same memory is exposed at `memory.agentage.io`, so Claude / ChatGPT / Cursor read and write the same notes. [How to connect →](https://agentage.io/connect) -- 🔐 **Sign in once** - OAuth 2.1 / PKCE; the token is kept in Obsidian's encrypted secret storage, never in your notes or config. -- 🧩 **Plain Markdown, safe merges** - notes stay `.md`; concurrent edits reconcile with a 3-way merge (per-field frontmatter + diff3 body), and conflicts surface as markers + a note - never a silent drop. +- 🔐 **Sign in once** - a secure browser sign-in; your access is kept in Obsidian's encrypted storage, never in your notes or config. +- 🧩 **Plain Markdown, safe merges** - notes stay `.md`; edits from different places merge automatically, and anything that can't be is flagged with a note - never a silent drop. - 📊 **Status at a glance** - a status-bar dot (green / red / gray) with a click menu: Sync now, Open dashboard, settings. The same actions are in the command palette and the ribbon. ## Installation @@ -46,16 +46,6 @@ From the [latest release](https://github.com/agentage/obsidian-sync/releases/lat - **Memory** - the memory this vault syncs into; change it or create one via the chooser. - **Expose remote MCP** - let AI apps read and write this memory (on by default). -## How it works - -- Your notes are normal `.md` files in your vault - and a bare git repo per memory on the server, which is the source of truth. -- **Sync** runs a real git client (vendored [isomorphic-git](https://github.com/isomorphic-git/isomorphic-git)) over Obsidian's network layer, authenticated with your sign-in token (sent only as an `Authorization` header, never in the URL). It never force-pushes - it commits before pulling and 3-way merges. -- The same repo is what AI apps read and write over MCP - one memory, every AI. - -## Mobile (planned) - -This release is **desktop only** (`isDesktopOnly: true`), so Obsidian won't offer it on phones yet. The git engine already runs over Obsidian's vault adapter (no Node APIs on the sync path), so the groundwork is in place - what's left is verifying sign-in and first sync on real iOS/Android. Mobile will be re-enabled once that's solid. - ## Privacy & network use - **Account required:** you need an agentage account to sign in and sync. @@ -65,17 +55,6 @@ This release is **desktop only** (`isDesktopOnly: true`), so Obsidian won't offe - **Privacy policy:** . **Terms of Service:** . - **No client-side telemetry.** Your notes live in your own per-tenant git repo (EU-hosted) and as plain Markdown on your machine; the OAuth token is kept in Obsidian's encrypted secret storage, never in `vaults.json` or `data.json`. -## Building from source - -```bash -npm install -npm run dev # esbuild watch → main.js -npm run build # production bundle -npm run verify # type-check + lint + format + test + build + doc/host/bundle checks -``` - -Tests run in Node with Vitest (the git round-trips spawn git's own `git-http-backend`, so the `git` binary must be on `PATH`). App-level end-to-end tests live in the [`agentage/e2e`](https://github.com/agentage/e2e) repo. - ## Third-party - **[isomorphic-git](https://github.com/isomorphic-git/isomorphic-git)** (MIT) - pure-JS git client. @@ -83,10 +62,10 @@ Tests run in Node with Vitest (the git round-trips spawn git's own `git-http-bac ## FAQ -- **Why desktop only?** Mobile sign-in (the `obsidian://` callback inside Obsidian's mobile WebView) isn't device-verified yet, so the plugin is `isDesktopOnly` until it is. The git engine is already mobile-safe - see [Mobile (planned)](#mobile-planned). -- **Where is my sign-in token stored?** In Obsidian's encrypted secret storage (and a 0600 `~/.agentage/auth.json` on desktop, shared with the agentage CLI) - never in `vaults.json` or `data.json`. -- **What happens on a conflict?** Nothing is silently dropped. Concurrent edits 3-way merge (per-field frontmatter + diff3 body); anything that can't auto-merge gets conflict markers and an **Agentage Sync Conflicts** note listing the files. Resolve the markers, then sync again. -- **Can I leave / export?** Yes - your memory is a plain git repo you can clone or export anytime, and your notes stay as Markdown on disk. +- **Why desktop only?** Mobile sign-in isn't fully tested on phones yet, so the plugin is desktop-only for now. Mobile is on the way. +- **Where is my sign-in token stored?** In Obsidian's encrypted storage - never in your notes or plugin settings. +- **What happens on a conflict?** Nothing is silently dropped. If the same note changed in two places, anything that can't be merged automatically is flagged in an **Agentage Sync Conflicts** note listing the files. Fix them, then sync again. +- **Can I leave or export?** Yes - you can export your memory anytime, and your notes stay as plain Markdown files on your computer. ## Support