elesync 0.1.0

Local-first, MCP-native unified memory vault — your AI memory as files you own, shared across every model.

🐘 EleSync

Your AI memory, as files you own. One vault. Every model.

You use Claude, ChatGPT, and Gemini. Each one knows a different slice of you, and none of them share. EleSync is one local-first vault on your own disk that every AI plugs into over the Model Context Protocol — so context you build in one AI is instantly available in all of them. Local-first. MCP-native. Yours.

No pasting context around. No static "memory chips." No switching apps. The AIs you already use connect to a vault you control.

Teach ChatGPT a fact  →  it lands in your vault  →  Claude already knows it.

This is a working seed (MVP), not a toy: the core has a passing 50-test suite and a CLI you can run today.

---

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.

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

• 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).
• elesync/cli.py — import, search, add, stats, reindex, embed, export, serve.
• elesync/embeddings.py — optional semantic recall: vectors stored alongside the SQLite index, brute-force cosine, hybrid keyword+vector ranking. Degrades to keyword-only.

Install

No prior setup knowledge needed — five steps, ~5 minutes. Works on macOS, Windows, and Linux.

You need: Python 3.10 or newer. To use EleSync as a live connector you also need a desktop AI app that speaks MCP — e.g. Claude Desktop.

Shortcut (once it's on PyPI): pip install elesync (add "elesync[mcp]" for the connector), then jump to step 4. Until the first PyPI release lands, use the from-source steps below.

1 · Check you have Python 3.10+

python --version

If that prints 2.x or "command not found", try python3 --version. Still nothing? Install it from python.org/downloads — on Windows, tick "Add Python to PATH" in the installer.

2 · Download EleSync

With git:

git clone https://github.com/darknodebros/EleSync.git
cd EleSync

No git? On the repo page, click the green Code button → Download ZIP, unzip it, then open a terminal inside the unzipped folder.

3 · Install it

pip install -e ".[mcp]"

If pip isn't found: Windows → py -m pip install -e ".[mcp]"; macOS/Linux → python3 -m pip install -e ".[mcp]".

This adds the ele command. Confirm it worked:

ele --version          # → EleSync 0.1.0

4 · Connect it to Claude — one command

ele onboard

This creates your vault (default: ~/EleSyncVault) and writes the EleSync entry into your Claude Desktop config automatically — it finds the right file on macOS/Windows/Linux and backs up any existing config first. Then fully quit and reopen Claude Desktop.

5 · Verify

ele doctor             # checks Python, vault, search, MCP SDK, and the Claude wiring

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

Prefer to wire Claude by hand?

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

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 export vault-backup.json   # back up / move your whole vault
ele reindex                    # rebuild the search index from notes/*.md

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.

Troubleshooting

First move for anything weird: run ele doctor — it checks your Python version, the vault, search, the MCP SDK, and the Claude wiring, and tells you exactly what's wrong.

ele: command not found (or 'ele' is not recognized)

The install put the ele launcher in a folder that isn't on your PATH (pip usually prints a "Scripts installed in '…' which is not on PATH" warning).

• Quickest workaround — run it as a module instead: python -m elesync.cli --version (works for every command: python -m elesync.cli onboard, etc.).
• Proper fix — add the folder pip mentioned to your PATH, or use a virtual environment (recommended), which puts ele on PATH automatically while active:

  python -m venv .venv
  # macOS/Linux:           source .venv/bin/activate
  # Windows (PowerShell):  .venv\Scripts\Activate.ps1
  pip install -e ".[mcp]"
  

pip: command not found

Use Python's bundled pip: Windows → py -m pip …; macOS/Linux → python3 -m pip ….

Wrong / too-old Python, or several Pythons installed

EleSync needs 3.10+. Check with ele doctor (or python --version). On Windows you can pick a specific version: py -3.12 -m pip install -e ".[mcp]".

Claude doesn't seem to know anything / EleSync isn't showing up

1. Fully quit Claude Desktop — quit the app (Cmd/Ctrl+Q, or quit from the menu-bar/tray icon), not just close the window — then reopen it. MCP servers are only picked up at launch.
2. Run ele doctor — confirm the line "Claude Desktop config wired" says PASS (it shows which file). If it says WARN, run ele onboard.
3. Make sure the MCP SDK is installed: pip install "mcp[cli]".

ModuleNotFoundError: No module named 'mcp' when serving

The MCP SDK isn't installed (it's optional and only needed to serve). Install it: pip install "mcp[cli]" — or reinstall EleSync with the extra: pip install -e ".[mcp]".

Semantic search isn't matching on meaning

Semantic recall is an optional extra. Install it and embed your memories:

pip install "elesync[semantic]"
ele embed                 # first run downloads a small model (one time)
ele --semantic search "…"

Still stuck? Open an issue with the output of ele doctor and we'll help.

Tests

python -m unittest discover -s tests -v   # 50 tests, stdlib only — no MCP SDK required

Where the export files come from (2026 reality)

All three majors shipped memory export in March 2026 (GDPR Article 20 + competition), but the formats are uneven and there's no clean memory API — so the adapters normalize the mess:

• ChatGPT — JSON of stored facts/preferences
• Claude — structured memory export from claude.ai
• Gemini — via Google Takeout (ZIP)
• Grok — xAI memory/personalization export ({"grok_memories": [...]})
• DeepSeek — memory export ({"deepseek_memories": [...]})

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

Roadmap (the honest next 20%)

1. Semantic recall — ✅ landed (optional [semantic] extra: local ONNX embeddings, hybrid keyword+vector ranking — see above). Next: semantic dedup (near-duplicate detection), and pgvector/sqlite-vec if a vault ever outgrows brute-force cosine.
2. Encryption at rest — age/libsodium per-file encryption; keep markdown plaintext optional for the privacy-conscious vs. Obsidian-readable tradeoff.
3. Sync — it's just files: git, iCloud, Syncthing, or Drive. No server to build. After syncing the notes to another machine, ele reindex rebuilds the search index from the markdown so the vault and its index agree again.
4. Scoped sharing — per-client memory scopes (let Claude see writing style without exposing legal/health context), the way Anuma gates by category.
5. Provenance & conflict resolution — when two AIs assert contradictory facts, surface it instead of silently picking one.
6. More adapters — Grok and DeepSeek have landed; Manus is next (note: Manus is an autonomous agent, not a chat-with-memory product — confirm it exposes an exportable memory before building the adapter). Each new source is a ~40-line file in normalize.py; the launch does not depend on any of them beyond the core three.

License

MIT — see LICENSE for details.