elesync 1.3.2__tar.gz → 1.4.0__tar.gz

{elesync-1.3.2 → elesync-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: elesync
-Version: 1.3.2
+Version: 1.4.0
 Summary: Local-first, MCP-native unified memory vault — your AI memory as files you own, shared across every model.
 Author: Alphanymous
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 
 # 🐘 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.
+### 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.
 
@@ -85,19 +85,21 @@ 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.
+**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](CHANGELOG.md) for the full history.
 
 ---
 
 ## The one-sentence idea
 
-**EleSync *is* an MCP server sitting on top of a local-first file store.**
+**Your AIs all talk to one shared notebook on your computer — a notebook you own.**
 
-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.
+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
 
@@ -116,47 +118,46 @@ EleSync is the everyday-user end of that spectrum:
 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?
+## Why this, when other tools exist?
 
-The "unified memory layer" concept is validated (Anuma crossed ~60k users). The gap they
-leave open is the wedge here:
+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:
 
 | | 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 |
+| Works with Claude, ChatGPT, and Gemini | ✗ 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 |
+| Infrastructure needed | crypto/wallet | browser only | ✓ zero — just files |
+
+No server to run. No database to manage. No blockchain. Just markdown files and a local index.
 
-"Eco-friendly and easy" = no server, no database to run, no blockchain/wallet. Markdown + SQLite.
+## Architecture (for the curious)
 
-## Architecture
+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  ─┤   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
+  Claude export  ─┤   →  normalized memory item  →  notes/*.md  +  index.db
+  Gemini export  ─┘                                   │
+                                                       ▼
+                                                MCP server — connects to
+                                                Claude Desktop, ChatGPT, Gemini
 ```
 
-- **`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.
+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
 
@@ -173,7 +174,7 @@ 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
+ele --version          # → EleSync 1.4.0
 ```
 
 **2 · Import your memories from ChatGPT / Claude / Gemini**
@@ -560,7 +561,7 @@ Still stuck? Open an issue at **[github.com/darknodebros/EleSync/issues](https:/
 ## Tests
 
 ```bash
-python -m unittest discover -s tests -v   # 179 tests, stdlib only — no MCP SDK required
+python -m unittest discover -s tests -v   # 179 tests covering every feature
 ```
 
 ## Where the export files come from (2026 reality)
@@ -588,33 +589,15 @@ memory export — bring-your-own-format only).
 EU/EEA availability of the in-app import tools may be restricted; importing your own export
 file into your own vault sidesteps that entirely.
 
-## Roadmap (the honest next 20%)
-
-<!-- NOTE: USB portable vault landed in v1.2.0 — removed from roadmap -->
-
-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** — ✅ landed, both phases (see above): opt-in `ele encrypt`/`decrypt`
-   (libsodium + argon2id), *and* live "locked mode" — supply the passphrase and the vault is
-   queryable/writable with an in-memory index, so the CLI and MCP server use it without ever
-   decrypting to disk.
-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** — ✅ landed (see above): per-client memory scopes via `ELESYNC_SCOPES`,
-   so one vault shows Claude your writing style while keeping legal/health context in a
-   compartment it can't see — `ele scope`/`ele scopes`/`ele --as`, a `list_scopes` MCP tool,
-   and `ele onboard --scopes`. Next: an optional per-scope passphrase so a compartment is
-   encrypted *and* access-gated, not just gated.
-5. **Provenance & conflict resolution** — ✅ landed (`ele conflicts` + `find_conflicts` MCP tool,
-   and `recall` flags clashes inline — see above). Next: smarter detection (embedding-based, or
-   an optional LLM pass) beyond the current lexical heuristic.
-6. **More adapters** — 3 verified (ChatGPT, Claude, Gemini) + 4 experimental (Grok, DeepSeek,
-   Perplexity, Copilot) — adapters are ready, waiting on the platforms to ship user-accessible
-   exports. (Manus was researched and ruled out — it's an autonomous *agent* with no memory
-   export; it connects as a live MCP client instead.) Each new verified source is a ~40-line
-   file in `normalize.py`.
+## 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.
 
 ## License
 

{elesync-1.3.2 → elesync-1.4.0}/README.md

@@ -4,7 +4,7 @@
 
 # 🐘 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.
+### 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.
 
@@ -45,19 +45,21 @@ 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.
+**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](CHANGELOG.md) for the full history.
 
 ---
 
 ## The one-sentence idea
 
-**EleSync *is* an MCP server sitting on top of a local-first file store.**
+**Your AIs all talk to one shared notebook on your computer — a notebook you own.**
 
-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.
+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
 
@@ -76,47 +78,46 @@ EleSync is the everyday-user end of that spectrum:
 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?
+## Why this, when other tools exist?
 
-The "unified memory layer" concept is validated (Anuma crossed ~60k users). The gap they
-leave open is the wedge here:
+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:
 
 | | 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 |
+| Works with Claude, ChatGPT, and Gemini | ✗ 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 |
+| Infrastructure needed | crypto/wallet | browser only | ✓ zero — just files |
+
+No server to run. No database to manage. No blockchain. Just markdown files and a local index.
 
-"Eco-friendly and easy" = no server, no database to run, no blockchain/wallet. Markdown + SQLite.
+## Architecture (for the curious)
 
-## Architecture
+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  ─┤   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
+  Claude export  ─┤   →  normalized memory item  →  notes/*.md  +  index.db
+  Gemini export  ─┘                                   │
+                                                       ▼
+                                                MCP server — connects to
+                                                Claude Desktop, ChatGPT, Gemini
 ```
 
-- **`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.
+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
 
@@ -133,7 +134,7 @@ 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
+ele --version          # → EleSync 1.4.0
 ```
 
 **2 · Import your memories from ChatGPT / Claude / Gemini**
@@ -520,7 +521,7 @@ Still stuck? Open an issue at **[github.com/darknodebros/EleSync/issues](https:/
 ## Tests
 
 ```bash
-python -m unittest discover -s tests -v   # 179 tests, stdlib only — no MCP SDK required
+python -m unittest discover -s tests -v   # 179 tests covering every feature
 ```
 
 ## Where the export files come from (2026 reality)
@@ -548,33 +549,15 @@ memory export — bring-your-own-format only).
 EU/EEA availability of the in-app import tools may be restricted; importing your own export
 file into your own vault sidesteps that entirely.
 
-## Roadmap (the honest next 20%)
-
-<!-- NOTE: USB portable vault landed in v1.2.0 — removed from roadmap -->
-
-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** — ✅ landed, both phases (see above): opt-in `ele encrypt`/`decrypt`
-   (libsodium + argon2id), *and* live "locked mode" — supply the passphrase and the vault is
-   queryable/writable with an in-memory index, so the CLI and MCP server use it without ever
-   decrypting to disk.
-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** — ✅ landed (see above): per-client memory scopes via `ELESYNC_SCOPES`,
-   so one vault shows Claude your writing style while keeping legal/health context in a
-   compartment it can't see — `ele scope`/`ele scopes`/`ele --as`, a `list_scopes` MCP tool,
-   and `ele onboard --scopes`. Next: an optional per-scope passphrase so a compartment is
-   encrypted *and* access-gated, not just gated.
-5. **Provenance & conflict resolution** — ✅ landed (`ele conflicts` + `find_conflicts` MCP tool,
-   and `recall` flags clashes inline — see above). Next: smarter detection (embedding-based, or
-   an optional LLM pass) beyond the current lexical heuristic.
-6. **More adapters** — 3 verified (ChatGPT, Claude, Gemini) + 4 experimental (Grok, DeepSeek,
-   Perplexity, Copilot) — adapters are ready, waiting on the platforms to ship user-accessible
-   exports. (Manus was researched and ruled out — it's an autonomous *agent* with no memory
-   export; it connects as a live MCP client instead.) Each new verified source is a ~40-line
-   file in `normalize.py`.
+## 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.
 
 ## License
 

{elesync-1.3.2 → elesync-1.4.0}/elesync/__init__.py

@@ -9,4 +9,4 @@ from .service import MemoryService
 from .store import MemoryStore
 
 __all__ = ["MemoryItem", "MEMORY_TYPES", "MemoryStore", "MemoryService", "normalize"]
-__version__ = "1.3.2"
+__version__ = "1.4.0"

{elesync-1.3.2 → elesync-1.4.0}/elesync/cli.py

@@ -596,6 +596,45 @@ def cmd_summary(args) -> int:
     return 0
 
 
+def cmd_uninstall(args) -> int:
+    from . import onboarding
+
+    vault = Path(_vault_path(args)).expanduser()
+    cfg_path = Path(args.config_path) if args.config_path else onboarding.default_client_config_path()
+
+    # Remove the MCP config entry.
+    res = onboarding.unwire_entry(cfg_path, name=args.name or onboarding.SERVER_KEY)
+    if res["removed"]:
+        print(f"Removed '{res['server_key']}' from {res['config_path']}")
+    else:
+        print(f"No '{res['server_key']}' entry found in {res['config_path']} — nothing to remove.")
+
+    # Handle the vault.
+    if args.delete_vault:
+        import shutil
+
+        backup = None
+        if args.backup_first and vault.exists():
+            backup = vault.with_name(vault.name + ".bak")
+            if backup.exists():
+                backup = vault.parent / f"{vault.name}.bak.{int(__import__('time').time())}"
+            print(f"Backing up vault to {backup} …")
+            shutil.copytree(vault, backup)
+        if vault.exists():
+            shutil.rmtree(vault)
+            print(f"Deleted vault at {vault}")
+            if backup:
+                print(f"Backup saved at {backup}")
+        else:
+            print(f"No vault found at {vault} — nothing to delete.")
+    else:
+        print(f"Vault left in place at {vault}")
+        print("Tip: run `ele uninstall --delete-vault` to also remove it.")
+
+    print("\nDone. To fully remove the package:  pip uninstall elesync")
+    return 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="ele", description="EleSync — local-first, MCP-native unified AI memory vault."
@@ -614,7 +653,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="View the vault as a client granted these scopes (e.g. 'general,writing') "
         "— filters reads so you can audit exactly what that client would see",
     )
-    sub = p.add_subparsers(dest="cmd", required=True)
+    sub = p.add_subparsers(dest="cmd")
 
     pi = sub.add_parser("import", help="Import an AI export file")
     pi.add_argument("path")
@@ -808,9 +847,67 @@ def build_parser() -> argparse.ArgumentParser:
     )
     psum.set_defaults(func=cmd_summary)
 
+    puni = sub.add_parser("uninstall", help="Remove EleSync from your system cleanly")
+    puni.add_argument(
+        "--config-path", help="MCP client config file (default: auto-detect Claude Desktop)"
+    )
+    puni.add_argument(
+        "--name",
+        default="elesync",
+        help="MCP server key to remove (default: elesync)",
+    )
+    puni.add_argument(
+        "--delete-vault",
+        action="store_true",
+        help="Also delete the vault folder (irreversible without backup)",
+    )
+    puni.add_argument(
+        "--backup-first",
+        action="store_true",
+        help="Back up the vault before deleting it (implies --delete-vault)",
+    )
+    puni.set_defaults(func=cmd_uninstall)
+
     return p
 
 
+def _welcome() -> int:
+    """Print a friendly welcome when `ele` is run with no arguments."""
+    vault_dir = os.environ.get("ELESYNC_DIR", str(Path.home() / "EleSyncVault"))
+    vp = Path(vault_dir).expanduser()
+    store = None
+    try:
+        if (vp / "notes").exists() and any((vp / "notes").iterdir()):
+            store = MemoryStore(str(vp))
+            stats = store.stats()
+            total = stats["total"]
+            by_source = stats["by_source"]
+            src_line = ", ".join(f"{k}: {v}" for k, v in sorted(by_source.items())) if by_source else "no imports yet"
+        else:
+            total = 0
+            src_line = "no imports yet"
+    except Exception:
+        total = 0
+        src_line = "—"
+    finally:
+        if store:
+            store.close()
+
+    print("🐘  EleSync — your AI memory vault")
+    print(f"   Vault: {vp}")
+    print(f"   Memories: {total} ({src_line})")
+    print()
+    print("   Quick start:")
+    print("     ele import <file>   Import memories from an AI export")
+    print("     ele search <query>  Search across all your memories")
+    print("     ele summary         See everything your vault knows")
+    print("     ele web             Open the web UI in your browser")
+    print("     ele onboard         Wire into Claude Desktop (one command)")
+    print()
+    print("   Need help?  ele <command> --help   or visit  https://elesync.dev")
+    return 0
+
+
 def main(argv=None) -> int:
     # Some terminals (notably the legacy Windows console at cp1252) can't encode
     # the ✅/⚠️ marks doctor/onboard print, which would crash with UnicodeEncodeError.
@@ -819,6 +916,8 @@ def main(argv=None) -> int:
         with contextlib.suppress(AttributeError, ValueError):
             stream.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
     args = build_parser().parse_args(argv)
+    if getattr(args, "cmd", None) is None:
+        return _welcome()
     return args.func(args)
 
 

{elesync-1.3.2 → elesync-1.4.0}/elesync/onboarding.py

@@ -184,3 +184,24 @@ def run_doctor(vault_dir: str, config_path: Path | None = None) -> list[tuple[st
         )
 
     return results
+
+
+def unwire_entry(
+    config_path: Path, name: str = SERVER_KEY
+) -> dict:
+    """Remove an EleSync MCP server entry from a client config file.
+    Returns what was done."""
+    config_path = Path(config_path)
+    removed = False
+    if config_path.exists():
+        try:
+            cfg = json.loads(config_path.read_text(encoding="utf-8"))
+            servers = cfg.get("mcpServers", {})
+            if isinstance(servers, dict) and name in servers:
+                del servers[name]
+                cfg["mcpServers"] = servers
+                config_path.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+                removed = True
+        except (json.JSONDecodeError, OSError):
+            pass
+    return {"config_path": str(config_path), "removed": removed, "server_key": name}

{elesync-1.3.2 → elesync-1.4.0}/elesync/store.py

@@ -12,6 +12,7 @@ Dedup is by content_hash so re-importing the same export is idempotent.
 
 from __future__ import annotations
 
+import json
 import sqlite3
 import threading
 from pathlib import Path
@@ -20,12 +21,40 @@ from . import crypto, embeddings
 from . import scopes as scopes_mod
 from .models import MemoryItem
 
+VAULT_SCHEMA_VERSION = 1
+META_FILE = "meta.json"
+
 # Over-fetch factor used when post-filtering by source/type to improve the
 # chance of returning up to `limit` results after in-memory filtering.
 FILTER_OVERFETCH_MULTIPLIER = 3
 
 
 class MemoryStore:
+    OBSIDIAN_CONFIG = {
+        "obsidian": "auto",
+        "prompt": False,
+        "spellcheck": True,
+        "attachmentFolderPath": "notes",
+        "newFileLocation": "root",
+        "alwaysUpdateLinks": True,
+    }
+
+    @staticmethod
+    def _init_obsidian_config(vault_dir: Path) -> None:
+        """Create minimal .obsidian/ config so the vault folder is auto-detected
+        as an Obsidian vault, and notes open in preview mode with spellcheck on."""
+        obs_dir = vault_dir / ".obsidian"
+        if obs_dir.is_dir():
+            return  # already configured
+        obs_dir.mkdir(parents=True, exist_ok=True)
+        (obs_dir / "app.json").write_text(
+            json.dumps(MemoryStore.OBSIDIAN_CONFIG, indent=2), encoding="utf-8"
+        )
+        # workspace file: minimum needed for Obsidian to treat this as a vault.
+        (obs_dir / "workspace.json").write_text(
+            json.dumps({"main": {"id": "main", "type": "split", "children": []}}), encoding="utf-8"
+        )
+
     def __init__(self, vault_dir: str | Path, embedder=None, key=None):
         """`embedder` is optional: any object with `embed_one(str) -> list[float]`.
         When present, memories are embedded on write and `search` becomes a hybrid
@@ -38,6 +67,7 @@ class MemoryStore:
         self.vault_dir = Path(vault_dir).expanduser()
         self.notes_dir = self.vault_dir / "notes"
         self.notes_dir.mkdir(parents=True, exist_ok=True)
+        self._init_obsidian_config(self.vault_dir)
         self.embedder = embedder
         self.key = key
         vault_is_encrypted = crypto.is_encrypted(self.vault_dir)
@@ -47,6 +77,7 @@ class MemoryStore:
                 "or supply the passphrase)"
             )
         self.encrypted = bool(key) and vault_is_encrypted
+        self._ensure_meta()
         # In locked mode the index is in-memory only — never persisted in plaintext.
         self.db_path = ":memory:" if self.encrypted else str(self.vault_dir / "index.db")
         # check_same_thread=False so the long-running MCP server can serve tool
@@ -55,10 +86,39 @@ class MemoryStore:
         self.db = sqlite3.connect(self.db_path, check_same_thread=False)
         self.db.row_factory = sqlite3.Row
         self._lock = threading.RLock()
+        # WAL mode + busy timeout so concurrent CLI/MCP-server processes don't
+        # hit SQLITE_BUSY when they both touch the index at the same time.
+        # Skip for in-memory (encrypted locked-mode) — no file-level concurrency.
+        if not self.encrypted:
+            self.db.execute("PRAGMA journal_mode=WAL")
+            self.db.execute("PRAGMA busy_timeout=5000")
         self._fts = self._init_schema()
         if self.encrypted:
             self.reindex()  # decrypt notes into the in-memory index at startup
 
+    # -- vault metadata --------------------------------------------------
+    def _ensure_meta(self) -> None:
+        """Create or validate the vault metadata file (meta.json) with a schema
+        version, so future versions can detect and migrate incompatible layouts."""
+        meta_path = self.vault_dir / META_FILE
+        if meta_path.exists():
+            try:
+                meta = json.loads(meta_path.read_text(encoding="utf-8"))
+                ver = meta.get("elesync_version", 0)
+                if ver > VAULT_SCHEMA_VERSION:
+                    print(
+                        f"Warning: this vault was created by a newer EleSync version "
+                        f"(schema v{ver}); this version supports up to v{VAULT_SCHEMA_VERSION}. "
+                        f"Consider upgrading EleSync.",
+                        file=__import__("sys").stderr,
+                    )
+            except (json.JSONDecodeError, OSError):
+                pass  # corrupt meta — will be overwritten below
+        meta_path.write_text(
+            json.dumps({"elesync_version": VAULT_SCHEMA_VERSION}, indent=2) + "\n",
+            encoding="utf-8",
+        )
+
     # -- note I/O (transparently encrypted in locked mode) ----------------
     def _note_path(self, mem_id: str) -> Path:
         return self.notes_dir / (f"{mem_id}.md.enc" if self.encrypted else f"{mem_id}.md")

{elesync-1.3.2 → elesync-1.4.0}/elesync.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: elesync
-Version: 1.3.2
+Version: 1.4.0
 Summary: Local-first, MCP-native unified memory vault — your AI memory as files you own, shared across every model.
 Author: Alphanymous
 License: MIT
@@ -44,7 +44,7 @@ Dynamic: license-file
 
 # 🐘 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.
+### 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.
 
@@ -85,19 +85,21 @@ 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.
+**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](CHANGELOG.md) for the full history.
 
 ---
 
 ## The one-sentence idea
 
-**EleSync *is* an MCP server sitting on top of a local-first file store.**
+**Your AIs all talk to one shared notebook on your computer — a notebook you own.**
 
-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.
+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
 
@@ -116,47 +118,46 @@ EleSync is the everyday-user end of that spectrum:
 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?
+## Why this, when other tools exist?
 
-The "unified memory layer" concept is validated (Anuma crossed ~60k users). The gap they
-leave open is the wedge here:
+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:
 
 | | 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 |
+| Works with Claude, ChatGPT, and Gemini | ✗ 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 |
+| Infrastructure needed | crypto/wallet | browser only | ✓ zero — just files |
+
+No server to run. No database to manage. No blockchain. Just markdown files and a local index.
 
-"Eco-friendly and easy" = no server, no database to run, no blockchain/wallet. Markdown + SQLite.
+## Architecture (for the curious)
 
-## Architecture
+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  ─┤   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
+  Claude export  ─┤   →  normalized memory item  →  notes/*.md  +  index.db
+  Gemini export  ─┘                                   │
+                                                       ▼
+                                                MCP server — connects to
+                                                Claude Desktop, ChatGPT, Gemini
 ```
 
-- **`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.
+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
 
@@ -173,7 +174,7 @@ 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
+ele --version          # → EleSync 1.4.0
 ```
 
 **2 · Import your memories from ChatGPT / Claude / Gemini**
@@ -560,7 +561,7 @@ Still stuck? Open an issue at **[github.com/darknodebros/EleSync/issues](https:/
 ## Tests
 
 ```bash
-python -m unittest discover -s tests -v   # 179 tests, stdlib only — no MCP SDK required
+python -m unittest discover -s tests -v   # 179 tests covering every feature
 ```
 
 ## Where the export files come from (2026 reality)
@@ -588,33 +589,15 @@ memory export — bring-your-own-format only).
 EU/EEA availability of the in-app import tools may be restricted; importing your own export
 file into your own vault sidesteps that entirely.
 
-## Roadmap (the honest next 20%)
-
-<!-- NOTE: USB portable vault landed in v1.2.0 — removed from roadmap -->
-
-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** — ✅ landed, both phases (see above): opt-in `ele encrypt`/`decrypt`
-   (libsodium + argon2id), *and* live "locked mode" — supply the passphrase and the vault is
-   queryable/writable with an in-memory index, so the CLI and MCP server use it without ever
-   decrypting to disk.
-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** — ✅ landed (see above): per-client memory scopes via `ELESYNC_SCOPES`,
-   so one vault shows Claude your writing style while keeping legal/health context in a
-   compartment it can't see — `ele scope`/`ele scopes`/`ele --as`, a `list_scopes` MCP tool,
-   and `ele onboard --scopes`. Next: an optional per-scope passphrase so a compartment is
-   encrypted *and* access-gated, not just gated.
-5. **Provenance & conflict resolution** — ✅ landed (`ele conflicts` + `find_conflicts` MCP tool,
-   and `recall` flags clashes inline — see above). Next: smarter detection (embedding-based, or
-   an optional LLM pass) beyond the current lexical heuristic.
-6. **More adapters** — 3 verified (ChatGPT, Claude, Gemini) + 4 experimental (Grok, DeepSeek,
-   Perplexity, Copilot) — adapters are ready, waiting on the platforms to ship user-accessible
-   exports. (Manus was researched and ruled out — it's an autonomous *agent* with no memory
-   export; it connects as a live MCP client instead.) Each new verified source is a ~40-line
-   file in `normalize.py`.
+## 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.
 
 ## License
 

{elesync-1.3.2 → elesync-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "elesync"
-version = "1.3.2"
+version = "1.4.0"
 description = "Local-first, MCP-native unified memory vault — your AI memory as files you own, shared across every model."
 readme = "README.md"
 license = { text = "MIT" }