Metadata-Version: 2.4
Name: elesync
Version: 1.23.22
Summary: Local-first AI project workspace — a private vault where approved assistants share context, knowledge, and tasks.
Author: Alphanymous
License: MIT
Project-URL: Homepage, https://github.com/darknodebros/EleSync
Project-URL: Repository, https://github.com/darknodebros/EleSync
Project-URL: Issues, https://github.com/darknodebros/EleSync/issues
Keywords: mcp,ai-memory,local-first,claude,chatgpt,gemini,grok,deepseek,memory,elesync
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<2,>=1.2.0
Requires-Dist: pynacl>=1.5
Requires-Dist: bcrypt>=4.0
Requires-Dist: cryptography>=42.0
Provides-Extra: semantic
Requires-Dist: fastembed<0.9.0,>=0.7.0; extra == "semantic"
Provides-Extra: dev
Requires-Dist: httpx2>=2.8.0; extra == "dev"
Requires-Dist: ruff==0.15.20; extra == "dev"
Requires-Dist: mypy==2.1.0; extra == "dev"
Requires-Dist: pre-commit==4.6.0; extra == "dev"
Dynamic: license-file

<!--
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-first AI project workspace.

It is a private vault where approved AI assistants can share project context, knowledge sheets, tasks, decisions, conversations, and memories. Start work with one assistant, continue with another, and keep the context you choose in a folder you control.

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 JSON, CSV, TXT, Markdown, ZIP archives, WhatsApp conversations, and Grok exports from other tools.
- Search, edit, and organize memories and conversations from the local dashboard.
- Install the dashboard as a private PWA companion on your phone.
- 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.

project_context:
Use when starting or resuming work on a known EleSync project and you need its curated knowledge sheets, tasks, decisions, AI handoffs, and collected memories together. If you only know the project name, call list_projects first to get its ID. Use recall_project instead when you need to search a project for a specific question or keyword. Use recall for broader searches across the entire vault. Do not use this tool for listing projects, general memory search, or saving new information; use save_project_document for durable project context and remember for ordinary memories.

list_projects:
Use when the user refers to a project by name, or before any project-specific tool when the project ID is unknown. Do not use for searching project content; use recall_project or project_context.

recall_project:
Use for targeted searches within one known project, especially when looking for a specific fact, conversation, or memory. Use project_context instead when beginning work and needing the project’s complete curated context. Use recall for searches spanning multiple projects or the whole vault.
## 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

On first launch, EleSync asks where to create the vault. You can also protect the dashboard with a passcode and continue directly to encrypted USB vault setup. The USB vault option remains available later from the dashboard menu.

## Mobile companion (PWA)

EleSync can be installed on a phone without a separate mobile app.

1. Start EleSync on your computer with `ele web`.
2. Open the **Use on another device** page in the dashboard.
3. Put your phone and computer on the same Wi-Fi network.
4. Open the displayed address on your phone.
5. Use your browser menu and choose **Add to Home Screen** or **Install app**.

The phone is a companion to the EleSync instance running on your computer. The computer must be running for live vault access. The PWA can prepare shared text, links, and titles as a memory, and encrypted offline drafts are retried when the computer becomes reachable again. Do not expose the dashboard publicly without HTTPS and a passcode.

## WhatsApp conversations

EleSync supports WhatsApp's local export format without media:

1. In WhatsApp, open a chat and choose **More → Export chat → Without media**.
2. Open EleSync's **Import** page.
3. Drop the exported `.txt` file into the import area.
4. Review the privacy notice and messages before saving anything.
5. Save the full conversation or select only approved messages.

The review can redact phone numbers, remove links, remove media-only messages, and limit the import to one sender. Nothing is saved until approval. WhatsApp content is stored locally; decide explicitly whether approved content should be added to a Project or shared with a connected AI client.

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
echo "I prefer dark mode" | ele import -   # import plain text from stdin
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
```

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.23.22** (850 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;
- privacy-reviewed WhatsApp conversation imports;
- encrypted offline PWA drafts and phone share capture;
- clearer AI-client and Project connection flows;
- stronger non-technical installer and mobile companion experience.

## License

MIT. See [LICENSE](LICENSE).
