EleSync

<!--
mcp-name: io.github.darknodebros/elesync

The line above is the MCP Registry ownership token. The registry validates
it inside the PyPI README of the exact published version. Do not remove it.
-->

# EleSync

[![CI](https://github.com/darknodebros/EleSync/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/darknodebros/EleSync/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/elesync)](https://pypi.org/project/elesync/)
[![Python versions](https://img.shields.io/pypi/pyversions/elesync)](https://pypi.org/project/elesync/)
[![License: MIT](https://img.shields.io/pypi/l/elesync)](https://github.com/darknodebros/EleSync/blob/master/LICENSE)
[![EleSync MCP server](https://glama.ai/mcp/servers/darknodebros/EleSync/badges/card.svg)](https://glama.ai/mcp/servers/darknodebros/EleSync)

EleSync is a local memory vault for your AI tools.

It keeps your notes, preferences, project facts, study material, and AI memories in a folder you control. Your AI clients can then read and write useful memories from the same place instead of each app keeping its own isolated history.

No account registration required. No cloud database. No e-mail, telemetry, freemium, subscriptions, or upsells. Your vault stays on your computer, in files you control. You can optionally lock the dashboard with a passcode, and optionally encrypt a vault (for example before carrying it on a USB drive).

## What you can do with it

- Install EleSync and choose where your vault lives.
- Import memory exports or notes from other AI tools.
- Search, edit, and organize memories from the local dashboard.
- Let compatible AI clients retrieve and save useful memories.
- Lock the dashboard with a passcode.
- Encrypt a vault and carry it on a USB drive.
- Use the CLI when you want automation, scripting, backups, or advanced setup.

## Install

### Windows: easiest path

Download the latest Windows installer:

[Download EleSync-Setup.exe](https://github.com/darknodebros/EleSync/releases/latest/download/EleSync-Setup.exe)

Run it, then follow the first-run setup. EleSync will open a local dashboard and guide you through:

1. choosing your vault location;
2. importing existing memories or notes;
3. optionally adding a dashboard passcode;
4. optionally preparing an encrypted USB vault;
5. connecting an AI client when you are ready.

### Windows: Scoop

If you already use Scoop:

```powershell
scoop install https://raw.githubusercontent.com/darknodebros/EleSync/master/elesync.json
```

Update later with:

```powershell
scoop update elesync
```

### Python / pipx

For macOS, Linux, or users who prefer Python tooling:

```bash
pipx install elesync
ele onboard
```

Requires Python 3.10 or newer. You can also use `pip install elesync`.

### Standalone builds

Standalone Windows, macOS, and Linux builds are attached to each GitHub release:

[View releases](https://github.com/darknodebros/EleSync/releases)

## First run

After installing, open EleSync from the Start menu or run:

```bash
ele web
```

The dashboard runs locally at `127.0.0.1`. It is meant to be the normal path for non-technical users: pick a vault, import data, review what came in, and connect tools without memorizing commands.

If you prefer the terminal:

```bash
ele onboard
ele doctor
```

`ele onboard` walks through setup. `ele doctor` checks that the vault is writable, search works, and client wiring is valid.

## Everyday commands

```bash
ele web                         # open the local dashboard
ele doctor                      # check installation health
ele import memories.json        # import exported memories or notes
ele remember "Prefer short answers with examples"
ele recall "how should my AI answer me?"
ele sync                        # rebuild the local search index
ele summary                     # show a vault summary
ele watch Downloads             # auto-import new supported export files
```

Advanced commands are available for encryption, backups, USB vaults, scopes, conflict resolution, HTTP serving, and client wiring. See [SETUP.md](SETUP.md) for the full user walkthrough.

## Using it with AI clients

EleSync exposes your vault through the Model Context Protocol, the open protocol many AI apps use to connect to local tools.

For ChatGPT, Grok, or Gemini custom connectors:

```bash
ele connect chatgpt --allowed-host your-tunnel-or-domain.example
ele connect grok --allowed-host your-tunnel-or-domain.example
ele connect gemini --allowed-host your-tunnel-or-domain.example
```

EleSync will create or reuse a Bearer token, print the MCP URL to paste into the client, and print the matching `ele serve --transport http ...` command to run locally. Use an HTTPS tunnel or reverse proxy for the public URL.

For Cursor or Claude Desktop:

```bash
ele connect cursor
ele connect claude
```

These print the local `ele onboard --target ...` setup command and restart instructions.

For local desktop/editor clients, EleSync usually runs through stdio:

```bash
ele serve
```

For clients that need a network endpoint, EleSync can serve a local or remote HTTP transport with authentication.

The goal is simple: your AI client should be able to answer questions like:

- “What do you remember about this project?”
- “Find my notes about the biology assignment.”
- “Save this preference for next time.”
- “What changed since the last summary?”

## Privacy and safety

EleSync is local-first:

- The markdown files in your vault are the source of truth.
- The SQLite search index and embedding files are rebuildable caches.
- No EleSync account is required.
- No cloud sync is required.
- You decide where the vault lives.
- You can encrypt backups or create an encrypted portable USB vault.

Important: if you connect an AI client, that client may read memories you make available to it. Use separate vaults, scopes, or read-only client settings when you want limits.

## Troubleshooting

Run:

```bash
ele doctor
```

Common fixes:

- If the dashboard does not open, run `ele web` from a terminal and copy the error.
- If an AI client cannot see memories, restart the client after setup.
- If search looks stale, run `ele sync`.
- If an import looks wrong, keep the original export file and re-import after checking the source format.
- If the Windows app is still running, close it before using Scoop update.

For step-by-step help, start with [SETUP.md](SETUP.md).

## Documentation

- [Setup guide](SETUP.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Security policy](SECURITY.md)
- [Contributing](CONTRIBUTING.md)
- [Release process](RELEASING.md)
- [Changelog](CHANGELOG.md)

## Project status

EleSync is at **1.21.1** (828 tests, ~12,500 LOC). The 1.x line is intended to keep vault format, client tool names, and everyday CLI behavior stable until a future 2.0.

Current focus:

- simpler first-run onboarding;
- better import verification;
- clearer AI-client connection checks;
- stronger non-technical installer flow;
- mobile companion planning after the desktop path is solid.

## License

MIT. See [LICENSE](LICENSE).