Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 7 additions & 28 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -65,28 +55,17 @@ This release is **desktop only** (`isDesktopOnly: true`), so Obsidian won't offe
- **Privacy policy:** <https://agentage.io/privacy>. **Terms of Service:** <https://agentage.io/terms>.
- **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.
- **js-yaml** (MIT) + **diff3** - frontmatter parsing and 3-way merge.

## 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

Expand Down