<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 telling every AI who you are, over and over again? Yeah, us too. EleSync is a one-command memory vault that lives on your computer. Your AIs share it. You own it. No repeats.

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

— no account needed

<!-- 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:

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:

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

Stable at v1.4.x — used daily by real people, tested against 179 scenarios across Python 3.10 through 3.14, with an automated CI pipeline that checks encryption, search, import/export, MCP connectivity, and the web UI on every commit. The 1.x line is frozen for breaking changes — what works today will work next year. See the CHANGELOG for the full history.

The one-sentence idea

Your AIs all talk to one shared notebook on your computer — a notebook you own.

Under the hood it works through something called MCP (Model Context Protocol), a standard now built into ChatGPT, Claude, and Gemini. EleSync runs a tiny server on your machine that speaks that protocol, so every AI can read from and write to the same vault live — no file-dropping, no copy-pasting.

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 other tools exist?

You may have come across other "AI memory" products. Most are built for developers building AI agents — not for people who just want to stop repeating themselves.

Here's how the everyday-user tools compare:

No server to run. No database to manage. No blockchain. Just markdown files and a local index.

Architecture (for the curious)

At a glance — exports from ChatGPT, Claude, and Gemini all get turned into the same format and stored as plain markdown files, with a local search index built automatically. One small server makes the whole thing available to any AI that speaks MCP:

  ChatGPT export ─┐
  Claude export  ─┤   →  normalized memory item  →  notes/*.md  +  index.db
  Gemini export  ─┘                                   │
                                                       ▼
                                                MCP server — connects to
                                                Claude Desktop, ChatGPT, Gemini

The key pieces:

• `elesync/models.py` — the common memory format every source (ChatGPT, Claude, Gemini) gets mapped into.
• `elesync/store.py` — saves memories as markdown files and keeps a fast search index. Re-importing the same file is harmless (duplicates are auto-skipped).
• `elesync/normalize.py` — reads each AI's export format and turns it into the common format above.
• `elesync/mcp_server.py` — the connector that any MCP-speaking AI uses to read from and write to your vault.
• `elesync/cli.py` — all the commands you run from the terminal (import, search, add, stats, and many more).
• `elesync/embeddings.py` — optional "meaning matching": finds memories by concept, not just by exact words.
• `elesync/crypto.py` — optional encryption for when you want your notes to be unreadable on disk.

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 walks through every step, including where to get your memory export files from ChatGPT, Claude, and Gemini.

1 · Install

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).

ele --version          # → EleSync 1.5.0

2 · Import your memories from ChatGPT / Claude / Gemini

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

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

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>

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:

{
  "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

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:

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

ele search "project notes"
ele add "Prefers direct, no-fluff answers" --type preference
ele stats

ele summary                    # see everything your vault knows about you
ele summary --short            # quick overview — counts + top facts
ele export vault-backup.json   # back up / move your whole vault
ele reindex                    # rebuild the search index from notes/*.md
ele forget <id>                # delete a memory by full id or 8-char prefix

# Auto-import: watches ~/Downloads and imports exports as they arrive
pip install "elesync[watch]"
ele watch                      # Ctrl+C to stop
ele watch --autostart          # register as a login item (runs from boot)

The file paths above are just examples — point them at wherever your export files are. EleSync keeps its vault at ~/EleSyncVault; to use a different folder set ELESYNC_DIR (macOS/Linux: export ELESYNC_DIR=~/my-vault · Windows PowerShell: $env:ELESYNC_DIR="C:\path\to\my-vault").

Now Claude can recall your full cross-AI context at the start of any chat and remember new durable facts back into the same vault that ChatGPT and Gemini read from.

Semantic recall (optional)

By default, search is keyword-based (SQLite FTS) — no dependencies, no model. Install the optional extra to also match on meaning, so recall finds the right memory even when the wording differs:

pip install "elesync[semantic]"     # adds a small local ONNX model (no PyTorch, no cloud)
ele embed                            # embed existing memories (first run downloads the model)
ele --semantic search "where do they live"   # → surfaces "Based in Westbrook"

Vectors are stored as float32 blobs in the same SQLite index — no new datastore — and ranking fuses keyword + vector hits (Reciprocal Rank Fusion), so exact matches stay strong while semantically-close memories surface too. Set ELESYNC_SEMANTIC=1 to make it the default (the MCP server picks this up too). Without the extra, everything works exactly as before.

Encryption at rest (optional)

Plaintext markdown is the default (so the vault stays Obsidian-readable). If you'd rather your notes be unreadable on disk — a stolen laptop, a leaked backup, a synced folder — encrypt the vault with a passphrase:

pip install "elesync[encryption]"
ele encrypt          # encrypts notes/*.md → *.md.enc, drops the plaintext index

Each note is encrypted with XSalsa20-Poly1305 (libsodium); your passphrase is stretched to a key with argon2id (the key is never written to disk — only the salt + params live in vault.json).

Use it while it stays encrypted. You don't have to decrypt the whole vault to use it — just supply the passphrase and EleSync unlocks it live, building the search index only in memory (nothing plaintext ever touches the disk):

ELESYNC_PASSPHRASE=… ele search "project notes"   # or it'll prompt you
ele add "Prefers concise answers" --type preference   # writes a new *.md.enc, still encrypted at rest
ele decrypt                                        # permanently revert to plaintext when you want

The MCP server does the same: set ELESYNC_PASSPHRASE in its config and it serves the encrypted vault live (key held in memory for the session). ele decrypt is only for permanently turning encryption back off.

Threat model — be clear-eyed. This protects data at rest (stolen disk, leaked backup, synced folder). It does not protect a running process, or a host where your passphrase is in memory or in an env var. Lose the passphrase and the data is unrecoverable.

Scoped sharing (optional)

One vault, but not every AI needs to see every memory. Your writing style is fine for any assistant; your legal or health notes are not. Scopes let a single vault present a different slice of itself to each client — the everyday-user version of what Anuma gates by category, with zero new infrastructure.

The model is one rule: a memory with no scope is `general` — visible to everyone, exactly as today — and a memory with a scope is visible only to a client granted that scope. Scoping is opt-in restriction, so every memory you already have is unaffected.

# tag memories into compartments (or scope an existing one in place)
ele add "Lawsuit vs Acme; settle at 10k" --type fact --scopes legal
ele scope 1dc24751 writing,coding        # re-scope by id/prefix (never forks identity)
ele scopes                               # list compartments with counts

# audit exactly what a given client would see, before you trust it
ele --as general,writing scopes           # which compartments are visible — legal/health absent
ele --as general,writing search Acme      # the legal "Acme" memory above won't surface

Each client carries a grant as an env var — the same local-first pattern as ELESYNC_DIR: ELESYNC_SCOPES=general,writing lets that client see general + writing and nothing else, and ELESYNC_WRITE_SCOPE=writing files everything it remembers into the writing compartment. Unset means unrestricted (the full vault), so existing setups are unchanged. ele onboard wires it for you:

# Claude Desktop: writing + general only
ele onboard --scopes general,writing --write-scope writing

# a second, legal-scoped connection in the SAME client (distinct --name)
ele onboard --scopes general,legal --write-scope legal --name elesync-legal

Every read path is grant-aware — recall, find_conflicts, memory_status and even forget filter by the client's scope, so a scoped client can't read or infer the existence of anything outside its compartment (counts and conflict output never leak hidden memories). An AI can discover its own compartments with the list_scopes MCP tool.

Be clear-eyed about the boundary. Scopes are organisational hygiene, not a cryptographic wall: the boundary is the per-client config you control, and a client you point at the vault with no ELESYNC_SCOPES set sees everything, by design. For data that must be unreadable even to a process that opens the vault, use encryption at rest — the two compose (an encrypted vault still scopes).

Spotting contradictions (provenance)

When two AIs record facts that disagree — "Based in Westbrook" (from Claude) vs "Based in Portland" (from ChatGPT) — EleSync surfaces the conflict with provenance instead of silently treating both as true:

ele conflicts
# Found 1 possible conflict(s) — review and `forget` the wrong one:
# 1. Same topic, different values:
#    - [claude, 2026-03-12] Based in Westbrook  (id=ff85b854)
#    - [chatgpt, 2026-05-01] Based in Portland   (id=efbecb07)

recall flags it inline too (so a connected AI notices and can ask you), and there's a find_conflicts MCP tool. Detection is a deliberately simple, local heuristic — it flags facts that look like they're about the same thing but differ — so treat results as candidates to review, not verdicts. EleSync only ever surfaces; you resolve with ele forget <id>.

Portable USB vault (carry your memory anywhere)

Plug in a USB drive, run one command, and your encrypted AI memory goes with you everywhere. On any machine with Python, python RUN_ME.py installs EleSync and connects it to Claude — no prior knowledge needed.

pip install "elesync[mcp,encryption]"

# One-time setup on your USB drive
ele usb install /Volumes/MyUSB          # macOS
ele usb install E:\\                    # Windows
ele usb install /media/myusb            # Linux
# Enter a passphrase when prompted — this encrypts everything on the drive

# Later: import your AI memories onto the drive
ele --vault /Volumes/MyUSB/EleSyncVault import chatgpt_memory.json --source chatgpt
ele --vault /Volumes/MyUSB/EleSyncVault import claude_export.json  --source claude
ele --vault /Volumes/MyUSB/EleSyncVault import gemini_memory.json  --source gemini

# Connect to Claude Desktop (on any machine)
ele usb attach /Volumes/MyUSB           # prompts for passphrase, wires Claude Desktop
# → Fully quit and reopen Claude Desktop

# Before unplugging
ele usb detach /Volumes/MyUSB           # removes Claude Desktop entry
ele usb eject  /Volumes/MyUSB           # safe-eject

# Other commands
ele usb list                            # see all removable drives
ele usb status /Volumes/MyUSB          # check vault health & memory count

On a new machine — plug in the drive and run:

python /Volumes/MyUSB/RUN_ME.py

That's it. RUN_ME.py is a self-contained script the drive carries with it: it installs EleSync via pip (if needed) and wires the USB vault into Claude Desktop — no prior knowledge of pip or MCP required.

Security model — USB vaults are always encrypted (unlike the main vault where encryption is opt-in). Your passphrase is the only thing that unlocks the vault; a lost or stolen drive exposed nothing without it. The same XSalsa20-Poly1305 + argon2id encryption used by ele encrypt is applied automatically at install time.

The USB vault is a standard EleSync vault at <drive>/EleSyncVault. You can run any normal ele command against it by passing --vault <drive>/EleSyncVault. Nothing is synced automatically between the USB vault and your main vault — use ele export + ele import to move memories between them.

Local web UI

No terminal needed once EleSync is installed — ele web opens a clean browser-based vault explorer:

ele web                 # opens http://127.0.0.1:7477 in your browser
ele web --port 8080     # custom port
ele web --no-browser    # start server without auto-opening browser

What you get:

Click any memory to open a slide-in editor — update content, type, tags, or delete it.

Zero extra dependencies — pure Python stdlib http.server. Works with encrypted vaults (prompts for passphrase at startup). Binds to 127.0.0.1 only.

Sync across devices

Your vault is just a folder (notes/*.md + a small vault.json), so sync it however you already sync files — git, iCloud, Syncthing, Dropbox, Drive. No server, no account.

Two things to know:

• Don't sync `index.db` — it's a local, rebuildable cache. ele sync drops a .gitignore in

your vault so git skips it automatically; for other tools, just exclude index.db.

• After pulling changes on another device, run `ele sync`. It rebuilds the index from the notes

and tells you what changed (e.g. "2 added, 1 changed, 0 removed"). Plain ele reindex does the rebuild silently if you don't care about the diff.

# device B, after a git pull / iCloud sync
ele sync        # → "1 added, 0 changed, 0 removed. Vault holds 42."

Encrypted vaults sync safely through even an untrusted service — the notes are *.md.enc ciphertext at rest, so the sync provider only ever sees encrypted blobs.

Troubleshooting

Run this first — it checks everything and tells you in plain words what needs fixing:

ele doctor

<details> <summary>🔴 Claude says it doesn't know anything</summary>

You almost certainly closed the window instead of quitting the app. MCP connections are only loaded when Claude starts.

• Mac: press Cmd + Q to quit, then reopen
• Windows: right-click the Claude icon near the clock → Quit, then reopen

If that doesn't fix it: run ele doctor and check that "Claude Desktop config wired" says PASS. If it says WARN, run ele onboard again. </details>

<details> <summary>🔴 <code>ele: command not found</code> (or <code>'ele' is not recognized</code>)</summary>

The ele shortcut wasn't added to your PATH. Use the full form instead — it works for every command:

python -m elesync.cli --version
python -m elesync.cli onboard
python -m elesync.cli import ~/Downloads/chatgpt_memory.json --source chatgpt

Or add the scripts folder pip printed to your PATH, then restart the command box. </details>

<details> <summary>🔴 <code>pip: command not found</code></summary>

• Windows: use py -m pip install "elesync[mcp]"
• Mac / Linux: use python3 -m pip install "elesync[mcp]"

</details>

<details> <summary>🔴 Python too old or not found</summary>

EleSync needs Python 3.10 or newer. Check: python --version (or python3 --version). Download the latest from [python.org/downloads](https://www.python.org/downloads/). On Windows, tick "Add Python to PATH" during install. </details>

<details> <summary>🔴 <code>ModuleNotFoundError: No module named 'mcp'</code></summary>

Run: pip install "mcp[cli]" then restart Claude. </details>

<details> <summary>🔴 Semantic search not matching on meaning</summary>

Semantic recall is optional. Enable it once:

pip install "elesync[semantic]"
ele embed

Then search with ele --semantic search "your query". </details>

Still stuck? Open an issue at [github.com/darknodebros/EleSync/issues](https://github.com/darknodebros/EleSync/issues) and paste the output of ele doctor. We'll help.

Tests

python -m unittest discover -s tests -v   # 179 tests covering every feature

Where the export files come from (2026 reality)

EleSync ships 3 verified sources (real, user-accessible memory exports today) and 4 experimental adapters (code is ready, but the platforms don't yet offer a native memory export — bring-your-own-format only).

Verified — real exports you can get right now:

• ChatGPT — Settings → Data controls → Export memory (JSON of stored facts/preferences)
• Claude — claude.ai → Settings → Export data → memory export (structured JSON)
• Gemini — Google Takeout → select "Gemini" → download ZIP, extract the memory JSON

Experimental — adapters built, export not yet publicly available:

• Grok — adapter expects {"grok_memories": [...]}; xAI has not shipped a user-accessible memory export
• DeepSeek — adapter expects {"deepseek_memories": [...]}; no native export available
• Perplexity — adapter expects {"perplexity_memories": [...]}; no native export available
• Copilot — adapter expects {"copilot_memories": [...]}; Microsoft has not shipped a memory export

These four platforms do not currently provide user-accessible memory exports. The adapters are ready for when they do. Contributions welcome once formats are confirmed.

EU/EEA availability of the in-app import tools may be restricted; importing your own export file into your own vault sidesteps that entirely.

What's done and what's next

1. Semantic recall (matching by meaning, not just exact words) — ✅ done
2. Encryption at rest (passphrase-protect your vault) — ✅ done
3. Sync (just copy the folder — iCloud, Dropbox, git, anything works) — ✅ built-in by design
4. Scoped sharing (different AIs see different parts of your vault) — ✅ done
5. Conflict spotting (surfaces when two AIs remember different things about the same topic) — ✅ done
6. More AI adapters — 3 ready today (ChatGPT, Claude, Gemini) + 4 experimental (Grok, DeepSeek,

Perplexity, Copilot) waiting on those platforms to offer memory exports.

Privacy

🔒 Zero data collection. Zero ads. Zero tracking. Your data stays on your machine, always.

EleSync never collects, sells, or touches your data — not now, not ever. There are no accounts, no telemetry, no analytics, no ads, and no data selling of any kind. Your memories are plain markdown files on your own disk. We don't see them, we don't want them, and we have no way to access them.

License

MIT — see LICENSE for details.