EleSync

<p align="center">
  <img src="https://raw.githubusercontent.com/darknodebros/EleSync/master/assets/logo-small.png" alt="EleSync — a neon circuit elephant" width="220">
</p>

# 🐘 EleSync

### Tired of re-explaining yourself to every AI? I bet you are, that's why we created EleSync, a One command setup memory vault, nicely encrypted, accessible to continue your conversations without repeating yourself to every model.

🔰 **You're not a developer?** Perfect — EleSync is designed for regular people first. Read the **[plain-English setup guide](SETUP.md)** — covers everything from first install to USB vault, step by step. ~10 minutes, no coding knowledge needed.

<p align="center">
  <img src="Elesyncdemo.gif" alt="EleSync demo" width="640">
</p>

[![PyPI](https://img.shields.io/pypi/v/elesync.svg)](https://pypi.org/project/elesync/)
[![CI](https://github.com/darknodebros/EleSync/actions/workflows/ci.yml/badge.svg)](https://github.com/darknodebros/EleSync/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-native-8A2BE2.svg)](https://modelcontextprotocol.io)
[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/Darknodebros)

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

You use Claude, ChatGPT, and Gemini. Each one knows a different slice of you, and none
of them share. **EleSync** is one private vault on your own computer that every AI
plugs into — so anything one AI learns about you is instantly available in all of them.

> No accounts. No cloud. No subscriptions. Your memories are plain text files on your
> own disk — readable in any text editor, synced however you already sync files.

```
Tell ChatGPT something  →  it lands in your vault  →  Claude already knows it.
```

**Two commands and you're done:**

```bash
pip install "elesync[mcp]"   # install
ele onboard                  # connect to Claude Desktop — that's it
```

**Want it fully automatic?** Install the watch extra once — after that, just export from any AI and Claude already knows:

```bash
pip install "elesync[watch]"
ele watch --autostart        # runs in the background from now on
```

**Stable at v1.3** — a 179-test suite, CI across Python 3.10–3.14 (including a dev-extras job
covering encryption and real-model semantic recall) plus ruff lint/format and mypy type-checking,
and a public surface (CLI commands, MCP tools, vault layout, export format) you can build on
without breakage inside 1.x. See the [CHANGELOG](CHANGELOG.md) for the full history.

---

## The one-sentence idea

**EleSync *is* an MCP server sitting on top of a local-first file store.**

Because MCP is now supported natively by OpenAI, Google and Anthropic, a single server
makes one vault you own readable and writable by all of them — live and bidirectionally.

## Who it's for

EleSync is for **people who _use_ AI — not engineers building agents.**

"AI memory" is having a moment, but most of it is **developer infrastructure**: memory layers
and SDKs you wire into agents you're coding (mem0, Letta, Zep), or autonomous-agent products
that manage their own memory (Manus). Powerful — *for builders.*

EleSync is the everyday-user end of that spectrum:

- **No code, no agent to build, no cloud account.** Install it, run `ele onboard`, done.
- **It plugs into the apps you already talk to** — Claude, ChatGPT, Gemini — instead of asking you to adopt a new one.
- **The memory is yours:** plain markdown files on your disk, not rows in someone else's database.

If you've ever had to re-explain yourself to a fresh chat, EleSync is for you. If you're wiring
a memory store into a fleet of autonomous agents, one of the developer tools above is the better fit.

## Why this, when Anuma / Memory Forge exist?

The "unified memory layer" concept is validated (Anuma crossed ~60k users). The gap they
leave open is the wedge here:

| | Anuma | Memory Forge | **EleSync (this)** |
|---|---|---|---|
| Open / inspectable | ✗ closed app | partial | ✓ your files, your code |
| MCP server | ✗ none | ✗ | ✓ core feature |
| Keep using Claude/ChatGPT/Gemini apps | ✗ must switch in | n/a | ✓ they connect to you |
| Live read **+ write back** | within app | ✗ static file | ✓ |
| Infrastructure | crypto/wallet | browser only | ✓ zero — files + SQLite |

"Eco-friendly and easy" = no server, no database to run, no blockchain/wallet. Markdown + SQLite.

## Architecture

```
  ChatGPT export ─┐
  Claude export  ─┤   adapters/normalize.py      ┌─ notes/*.md   (source of truth, Obsidian-compatible)
  Gemini export  ─┼─►  → MemoryItem (schema) ──►  │
  manual notes   ─┘                               └─ index.db    (SQLite + FTS5 full-text search)
                                                         │
                                                         ▼
                                              mcp_server.py  (the connector)
                                                         │
                       ┌─────────────────────────────────┼─────────────────────────────────┐
                   Claude Desktop                     ChatGPT                            Gemini / any MCP client
                   recall / remember / forget / memory_status / list_scopes
```

- **`elesync/models.py`** — the normalized `MemoryItem` schema every source maps into.
- **`elesync/store.py`** — local-first store: markdown files + SQLite FTS index, with
  content-hash dedup (re-importing is idempotent).
- **`elesync/normalize.py`** — tolerant ingest adapters that sniff each provider's export shape.
- **`elesync/mcp_server.py`** — exposes the vault over MCP (`recall`, `remember`, `forget`, `memory_status`, `find_conflicts`, `list_scopes`).
- **`elesync/cli.py`** — `import`, `search`, `add`, `stats`, `reindex`, `sync`, `conflicts`, `scope`, `scopes`, `embed`, `export`, `encrypt`, `decrypt`, `serve`.
- **`elesync/embeddings.py`** — optional semantic recall: vectors stored alongside the
  SQLite index, brute-force cosine, hybrid keyword+vector ranking. Degrades to keyword-only.
- **`elesync/crypto.py`** — optional encryption at rest: argon2id key + libsodium per-file
  AEAD; the index is a rebuildable cache. Plaintext stays the default.

## Install

Works on **macOS, Windows, and Linux**. Needs **Python 3.10+** and **[Claude Desktop](https://claude.ai/download)**.

> **Not a developer?** The [plain-English setup guide](SETUP.md) walks through every step, including where to get your memory export files from ChatGPT, Claude, and Gemini.

**1 · Install**

```bash
pip install "elesync[mcp]"
```

> No Python yet? Download from **[python.org/downloads](https://www.python.org/downloads/)** — on Windows tick **"Add Python to PATH"** during install. If `pip` isn't found: use `py -m pip …` (Windows) or `python3 -m pip …` (Mac/Linux).

```bash
ele --version          # → EleSync 1.3.0
```

**2 · Import your memories from ChatGPT / Claude / Gemini**

```bash
ele import ~/Downloads/chatgpt_memory.json   --source chatgpt
ele import ~/Downloads/claude_export.json    --source claude
ele import ~/Downloads/gemini_memory.json    --source gemini
```

Re-importing is always safe — duplicates are skipped automatically.

**3 · Connect to Claude Desktop — one command**

```bash
ele onboard
```

Finds the Claude config file automatically on macOS/Windows/Linux, backs it up, and wires EleSync in. Then **fully quit and reopen Claude Desktop** (not just close the window — quit the whole app).

**4 · Verify**

```bash
ele doctor
```

Then ask Claude: *"What do you remember about me?"* — that's your live confirmation. 🎉

<details>
<summary>Install from source instead (for contributors / latest <code>master</code>)</summary>

```bash
git clone https://github.com/darknodebros/EleSync.git
cd EleSync
pip install -e ".[mcp]"
```
No git? Use the green **Code → Download ZIP** button on the repo page, unzip, and run the `pip install` from inside the folder.
</details>

<details>
<summary>Prefer to wire Claude by hand?</summary>

`ele onboard --print-only` prints the exact block to paste into your Claude Desktop config file:

```json
{
  "mcpServers": {
    "elesync": {
      "command": "python",
      "args": ["-m", "elesync.mcp_server"],
      "env": { "ELESYNC_DIR": "/path/to/your/EleSyncVault" }
    }
  }
}
```
</details>

## Use it with other AI apps (any MCP client)

EleSync is a standard **MCP server**, so the *same vault* works with any app that can act as an MCP client — not just Claude Desktop. Tools like **[Manus](https://manus.im)**, Cursor, and other MCP-capable apps can connect and `recall` / `remember` against your vault live — **no adapter, no export/import**.

The how-to is the same everywhere: point the client at EleSync's MCP server. Print the config block with

```bash
ele onboard --print-only
```

then add that `mcpServers` entry wherever the app keeps its MCP config (in Manus: **Settings → Connectors**; in Cursor: its MCP settings), with `ELESYNC_DIR` pointing at your vault. Done — that app now reads and writes the one vault every other AI shares.

> Note: the `ele import` adapters are for chat assistants that expose a **memory export**. Three platforms offer verified exports today (ChatGPT, Claude, Gemini); four more have adapters ready for when exports become available (Grok, DeepSeek, Perplexity, Copilot). Agent tools like Manus don't offer one — and don't need it: they connect as a live MCP client instead.

## Everyday use

Import what your AIs already exported, then search across all of them at once:

```bash
ele import ~/Downloads/chatgpt_memory.json --source chatgpt
ele import ~/Downloads/claude_export.json   --source claude

ele sea