elesync 0.1.0__py3-none-any.whl

elesync/__init__.py

@@ -0,0 +1,12 @@
+"""elesync — a local-first, MCP-native unified elesync.
+
+One vault on your disk. Every AI reads from and writes to it over MCP.
+"""
+
+from .models import MemoryItem, MEMORY_TYPES
+from .store import MemoryStore
+from .service import MemoryService
+from . import normalize
+
+__all__ = ["MemoryItem", "MEMORY_TYPES", "MemoryStore", "MemoryService", "normalize"]
+__version__ = "0.1.0"

elesync/cli.py

@@ -0,0 +1,268 @@
+"""Command-line interface for the vault.
+
+    python -m elesync.cli import chatgpt_export.json --source chatgpt
+    python -m elesync.cli search "Helios project"
+    python -m elesync.cli add "Prefers direct, no-fluff answers" --type preference
+    python -m elesync.cli stats
+    python -m elesync.cli reindex          # rebuild the index from notes/*.md
+    python -m elesync.cli export backup.json
+    python -m elesync.cli serve            # start the MCP server
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from . import __version__, normalize
+from .models import MemoryItem
+from .store import MemoryStore
+
+
+def _semantic_on(args) -> bool:
+    return bool(getattr(args, "semantic", False) or os.environ.get("ELESYNC_SEMANTIC"))
+
+
+def _embedder(args):
+    """Load the embedding model only when semantic mode is requested. Returns None
+    (and a friendly note) if requested but the optional extra isn't installed."""
+    if not _semantic_on(args):
+        return None
+    from . import embeddings
+    emb = embeddings.load_embedder()
+    if emb is None:
+        print('Semantic mode requested but the extra is not installed — '
+              'run: pip install "elesync[semantic]". Falling back to keyword search.',
+              file=sys.stderr)
+    return emb
+
+
+def _store(args) -> MemoryStore:
+    return MemoryStore(args.vault or os.environ.get("ELESYNC_DIR", "~/EleSyncVault"),
+                       embedder=_embedder(args))
+
+
+def cmd_import(args) -> int:
+    store = _store(args)
+    try:
+        items = normalize.normalize_file(args.path, source=args.source)
+        result = store.import_many(items)
+        print(f"Imported {result['added']} new memories "
+              f"({result['skipped_duplicates']} duplicates skipped). "
+              f"Vault now holds {result['total']}.")
+        return 0
+    finally:
+        store.close()
+
+
+def cmd_search(args) -> int:
+    store = _store(args)
+    try:
+        hits = store.search(args.query, limit=args.limit, source=args.source, mtype=args.type)
+        if not hits:
+            print("No matches.")
+            return 0
+        for h in hits:
+            print(f"\n[{h.type}/{h.source}] id={h.id[:8]}")
+            print(h.content[:500] + ("…" if len(h.content) > 500 else ""))
+        return 0
+    finally:
+        store.close()
+
+
+def cmd_add(args) -> int:
+    store = _store(args)
+    try:
+        item = MemoryItem(content=args.content, type=args.type,
+                          tags=[t.strip() for t in (args.tags or "").split(",") if t.strip()],
+                          source=args.source or "manual")
+        mem_id, inserted = store.upsert_status(item)
+        print(f"Saved id={mem_id[:8]}." if inserted
+              else f"Already in your vault (id={mem_id[:8]}) — nothing added.")
+        return 0
+    finally:
+        store.close()
+
+
+def cmd_reindex(args) -> int:
+    store = _store(args)
+    try:
+        res = store.reindex()
+        print(f"Reindexed {res['reindexed']} memories from notes/ in {res['vault_dir']}.")
+        return 0
+    finally:
+        store.close()
+
+
+def cmd_embed(args) -> int:
+    from . import embeddings
+    emb = embeddings.load_embedder()
+    if emb is None:
+        print('The semantic extra is not installed. Run: pip install "elesync[semantic]"',
+              file=sys.stderr)
+        return 1
+    store = MemoryStore(args.vault or os.environ.get("ELESYNC_DIR", "~/EleSyncVault"),
+                        embedder=emb)
+    try:
+        print(f"Embedding with {emb.model_name} … (first run downloads the model)")
+        n = store.embed_missing()
+        print(f"Embedded {n} memories. Semantic recall is active — "
+              f"use it with --semantic or ELESYNC_SEMANTIC=1.")
+        return 0
+    finally:
+        store.close()
+
+
+def cmd_export(args) -> int:
+    store = _store(args)
+    try:
+        items = store.all()
+        payload = {
+            "elesync_export": 1,
+            "exported_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat(),
+            "count": len(items),
+            "memories": [i.to_dict() for i in items],
+        }
+        Path(args.path).expanduser().write_text(
+            json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+        print(f"Exported {len(items)} memories to {args.path}. "
+              f"Re-import with: ele import {args.path}")
+        return 0
+    finally:
+        store.close()
+
+
+def cmd_stats(args) -> int:
+    store = _store(args)
+    try:
+        s = store.stats()
+        print(f"Vault: {s['vault_dir']}")
+        print(f"Total memories: {s['total']}   (FTS search: {'on' if s['fts_enabled'] else 'off'})")
+        print(f"Embedded: {s['embedded']}/{s['total']}   "
+              f"(semantic recall: {'available' if s['embedded'] else 'off — run: ele embed'})")
+        print("By source:", s["by_source"] or "—")
+        print("By type:  ", s["by_type"] or "—")
+        return 0
+    finally:
+        store.close()
+
+
+def cmd_serve(args) -> int:
+    from .mcp_server import build_server
+    build_server(args.vault).run()
+    return 0
+
+
+def _vault_path(args) -> str:
+    return args.vault or os.environ.get("ELESYNC_DIR", "~/EleSyncVault")
+
+
+def cmd_onboard(args) -> int:
+    from . import onboarding
+    vault = _vault_path(args)
+    cfg = Path(args.config_path) if args.config_path else onboarding.default_client_config_path()
+
+    # Make sure the vault exists.
+    MemoryStore(vault).close()
+
+    if args.print_only:
+        print("Add this to your MCP client config (e.g. Claude Desktop):\n")
+        print(json.dumps({"mcpServers": {onboarding.SERVER_KEY:
+                          onboarding.server_entry(vault)}}, indent=2))
+        return 0
+
+    res = onboarding.wire_client_config(cfg, vault)
+    print("✅ Onboarded.")
+    print(f"   Vault:  {Path(vault).expanduser()}")
+    print(f"   Config: {res['config_path']}"
+          + (" (existing backed up to *.bak)" if res["backed_up"] else ""))
+    print(f"   Server '{onboarding.SERVER_KEY}' "
+          + ("updated." if res["updated_existing"] else "added."))
+    print('\nNext: install the MCP SDK if you haven\'t —  pip install "mcp[cli]"')
+    print("Then fully quit and reopen Claude Desktop, and ask it: "
+          '"What do you remember about me?"')
+    print("Verify anytime with:  ele doctor")
+    return 0
+
+
+def cmd_doctor(args) -> int:
+    from . import onboarding
+    cfg = Path(args.config_path) if args.config_path else None
+    rows = onboarding.run_doctor(_vault_path(args), config_path=cfg)
+    mark = {"PASS": "✅", "WARN": "⚠️ ", "FAIL": "❌"}
+    print("EleSync — health check\n")
+    for status, check, detail in rows:
+        print(f"  {mark[status]} {check:<32} {detail}")
+    failed = [r for r in rows if r[0] == "FAIL"]
+    print("\n" + ("❌ Fix the FAIL items above." if failed
+                  else "✅ Core looks good. WARNs are optional/until you serve."))
+    return 1 if failed else 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="ele", description="EleSync — local-first, MCP-native unified AI memory vault.")
+    p.add_argument("--version", action="version", version=f"EleSync {__version__}")
+    p.add_argument("--vault", help="Vault directory (default: $ELESYNC_DIR or ~/EleSyncVault)")
+    p.add_argument("--semantic", action="store_true",
+                   help="Use semantic (embedding) search; needs the [semantic] extra")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    pi = sub.add_parser("import", help="Import an AI export file")
+    pi.add_argument("path")
+    pi.add_argument("--source", choices=["chatgpt", "claude", "gemini", "grok", "deepseek"],
+                    help="Force a source adapter (otherwise auto-detected)")
+    pi.set_defaults(func=cmd_import)
+
+    ps = sub.add_parser("search", help="Search the vault")
+    ps.add_argument("query")
+    ps.add_argument("--limit", type=int, default=10)
+    ps.add_argument("--source")
+    ps.add_argument("--type")
+    ps.set_defaults(func=cmd_search)
+
+    pa = sub.add_parser("add", help="Add a memory manually")
+    pa.add_argument("content")
+    pa.add_argument("--type", default="note")
+    pa.add_argument("--tags")
+    pa.add_argument("--source")
+    pa.set_defaults(func=cmd_add)
+
+    pt = sub.add_parser("stats", help="Show vault statistics")
+    pt.set_defaults(func=cmd_stats)
+
+    pr = sub.add_parser("reindex", help="Rebuild the search index from notes/*.md")
+    pr.set_defaults(func=cmd_reindex)
+
+    pm = sub.add_parser("embed", help="Embed memories for semantic recall ([semantic] extra)")
+    pm.set_defaults(func=cmd_embed)
+
+    pe = sub.add_parser("export", help="Export the whole vault to a portable JSON file")
+    pe.add_argument("path", help="Output file, e.g. vault-backup.json")
+    pe.set_defaults(func=cmd_export)
+
+    pv = sub.add_parser("serve", help="Run the MCP server")
+    pv.set_defaults(func=cmd_serve)
+
+    po = sub.add_parser("onboard", help="One-command setup: create vault + wire Claude Desktop")
+    po.add_argument("--config-path", help="Path to the MCP client config (default: auto-detect Claude Desktop)")
+    po.add_argument("--print-only", action="store_true", help="Print the config block instead of writing it")
+    po.set_defaults(func=cmd_onboard)
+
+    pd = sub.add_parser("doctor", help="Verify the install end to end")
+    pd.add_argument("--config-path", help="Path to the MCP client config to check")
+    pd.set_defaults(func=cmd_doctor)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

elesync/embeddings.py

@@ -0,0 +1,71 @@
+"""Optional semantic-embedding support.
+
+The core stays dependency-free: everything here degrades gracefully when no
+embedding model is installed. Enable semantic recall with the optional extra:
+
+    pip install "elesync[semantic]"
+
+Design choices that keep the "no infrastructure" promise:
+  * Vectors live as float32 blobs in the same SQLite index — no new datastore.
+  * Similarity is brute-force cosine in pure Python — fast enough for a personal
+    vault of thousands of memories, and nothing to run or tune.
+  * The model is a small local ONNX model (no PyTorch), loaded only on demand.
+"""
+
+from __future__ import annotations
+
+import math
+from array import array
+
+# Small, fast, local (fastembed uses ONNX runtime — no PyTorch). 384 dims.
+DEFAULT_MODEL = "BAAI/bge-small-en-v1.5"
+
+
+def pack(vec) -> bytes:
+    """Serialise a float vector to a compact float32 blob."""
+    return array("f", vec).tobytes()
+
+
+def unpack(blob: bytes) -> list[float]:
+    """Inverse of `pack`."""
+    a = array("f")
+    a.frombytes(blob)
+    return list(a)
+
+
+def cosine(a, b) -> float:
+    """Cosine similarity of two equal-length vectors (pure stdlib)."""
+    dot = sa = sb = 0.0
+    for x, y in zip(a, b):
+        dot += x * y
+        sa += x * x
+        sb += y * y
+    if sa == 0.0 or sb == 0.0:
+        return 0.0
+    return dot / (math.sqrt(sa) * math.sqrt(sb))
+
+
+class Embedder:
+    """Wraps a fastembed model behind a tiny `str -> list[float]` interface.
+
+    Any object exposing `embed_one(str) -> list[float]` works as an embedder, so
+    the store can be driven by a stub in tests without pulling in the model."""
+
+    def __init__(self, model_name: str = DEFAULT_MODEL):
+        from fastembed import TextEmbedding  # optional dep, imported lazily
+        self.model_name = model_name
+        self._model = TextEmbedding(model_name)
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        return [list(map(float, v)) for v in self._model.embed(list(texts))]
+
+    def embed_one(self, text: str) -> list[float]:
+        return self.embed([text])[0]
+
+
+def load_embedder(model_name: str = DEFAULT_MODEL):
+    """Return an `Embedder` if the `semantic` extra is installed, else None."""
+    try:
+        return Embedder(model_name)
+    except ImportError:
+        return None

elesync/mcp_server.py

@@ -0,0 +1,83 @@
+"""MCP server — the connector.
+
+This is the heart of the whole idea. It exposes your local vault over the Model
+Context Protocol, which OpenAI, Google and Anthropic all support natively. Point
+Claude Desktop / ChatGPT / any MCP client at this server and they can all
+`recall` from and `remember` into the *same* vault, live. No pasting, no static
+"memory chips", no switching apps.
+
+The actual logic lives in service.py (and is unit-tested); this file is the thin
+protocol wrapper around it.
+
+Run:
+    pip install "mcp[cli]"          # or:  pip install -e ".[mcp]"
+    ELESYNC_DIR=~/EleSyncVault python -m elesync.mcp_server
+
+Easiest path:  `ele onboard`  wires this into Claude Desktop for you.
+"""
+
+from __future__ import annotations
+
+import os
+
+from .service import MemoryService
+from .store import MemoryStore
+
+# `mcp` is an external dependency. Imported lazily so the rest of the package —
+# and the test suite — work without it installed.
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError:  # pragma: no cover
+    FastMCP = None
+
+
+def build_server(vault_dir: str | None = None):
+    if FastMCP is None:  # pragma: no cover
+        raise ImportError('MCP SDK not installed. Run:  pip install "mcp[cli]"')
+
+    vault_dir = vault_dir or os.environ.get("ELESYNC_DIR", "~/EleSyncVault")
+    # Opt into semantic recall when ELESYNC_SEMANTIC is set and the extra is present.
+    embedder = None
+    if os.environ.get("ELESYNC_SEMANTIC"):
+        from . import embeddings
+        embedder = embeddings.load_embedder()
+    svc = MemoryService(MemoryStore(vault_dir, embedder=embedder))
+    mcp = FastMCP("elesync")
+
+    @mcp.tool()
+    def recall(query: str, limit: int = 8, source: str = "", type: str = "") -> str:
+        """Search the user's unified memory across all AIs. Use this at the start of
+        a task to recover context. `source` filters to one AI (chatgpt/claude/gemini);
+        `type` filters by fact/preference/project/relationship/conversation/note."""
+        return svc.recall(query, limit=limit, source=source, type=type)
+
+    @mcp.tool()
+    def remember(content: str, type: str = "note", tags: str = "", source: str = "claude") -> str:
+        """Save a new memory to the user's vault so every other AI can see it too.
+        Use for durable facts, preferences, project state — not throwaway chatter."""
+        return svc.remember(content, type=type, tags=tags, source=source)
+
+    @mcp.tool()
+    def forget(memory_id: str) -> str:
+        """Delete a memory by id (full or 8-char prefix shown by recall)."""
+        return svc.forget(memory_id)
+
+    @mcp.tool()
+    def memory_status() -> str:
+        """Summary of what's in the vault: totals by source and type."""
+        return svc.status()
+
+    @mcp.resource("memory://recent")
+    def recent() -> str:
+        """The most recent memories, as a readable digest."""
+        return svc.recent()
+
+    return mcp
+
+
+def main() -> None:  # pragma: no cover
+    build_server().run()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

elesync/models.py

@@ -0,0 +1,115 @@
+"""Normalized memory schema.
+
+Every source (ChatGPT, Claude, Gemini, manual notes, ...) is mapped into a single
+`MemoryItem` shape. This is the contract the whole system depends on: adapters
+produce MemoryItems, the store persists MemoryItems, and the MCP server serves
+MemoryItems back to any AI client.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+
+# Coarse taxonomy. Kept deliberately small so it stays useful across providers.
+MEMORY_TYPES = {
+    "fact",          # "User's name is Alex", "Lives in Westbrook"
+    "preference",    # "Prefers direct, no-fluff answers"
+    "project",       # "Helios side project", "open-source CLI tool"
+    "relationship",  # "Has a younger sister"
+    "conversation",  # a captured exchange, summarised or raw
+    "note",          # free-form, manually added
+}
+
+VALID_SOURCES_HINT = ("chatgpt", "claude", "gemini", "grok", "deepseek", "manual")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+
+
+def _normalize_for_hash(text: str) -> str:
+    """Lower-case + collapse whitespace so trivially-different copies of the same
+    memory (e.g. re-exported across sessions) hash identically and dedupe."""
+    return re.sub(r"\s+", " ", text.strip().lower())
+
+
+@dataclass
+class MemoryItem:
+    content: str
+    source: str = "manual"
+    type: str = "note"
+    tags: list[str] = field(default_factory=list)
+    confidence: float = 1.0
+    created_at: str = field(default_factory=_now)
+    source_ref: str = ""          # provenance: original conversation id / export filename
+    id: str = ""                  # stable uuid (assigned on creation if blank)
+    content_hash: str = ""        # for dedup / near-dup detection
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.tags, list):
+            self.tags = [t for t in re.split(r"[,;]", str(self.tags)) if t.strip()]
+        if self.type not in MEMORY_TYPES:
+            self.type = "note"
+        self.confidence = max(0.0, min(1.0, float(self.confidence)))
+        if not self.content_hash:
+            self.content_hash = self.compute_hash()
+        if not self.id:
+            self.id = uuid.uuid4().hex
+
+    def compute_hash(self) -> str:
+        basis = f"{self.source}|{self.type}|{_normalize_for_hash(self.content)}"
+        return hashlib.sha1(basis.encode("utf-8")).hexdigest()
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "MemoryItem":
+        known = {k: d.get(k) for k in cls.__dataclass_fields__ if k in d}
+        return cls(**known)
+
+    @classmethod
+    def from_markdown(cls, text: str) -> "MemoryItem":
+        """Inverse of `to_markdown`: parse a note's YAML front-matter + body back
+        into a MemoryItem. Tolerant of hand-edits (extra blank lines, missing
+        optional keys); preserves the stored id and content_hash so a reindex is a
+        faithful rebuild rather than a reimport. Raises ValueError if there's no
+        front-matter block to parse."""
+        if not text.startswith("---"):
+            raise ValueError("note has no front-matter block")
+        _, fm, body = text.split("---", 2)
+        meta: dict = {}
+        for line in fm.splitlines():
+            if ":" not in line:
+                continue
+            key, _, val = line.partition(":")
+            key, val = key.strip(), val.strip()
+            if not key:
+                continue
+            if key == "tags":
+                val = [t.strip() for t in val.strip("[]").split(",") if t.strip()]
+            meta[key] = val
+        meta["content"] = body.lstrip("\n").rstrip("\n")
+        return cls.from_dict(meta)
+
+    def to_markdown(self) -> str:
+        """Human-readable, Obsidian-compatible: YAML front-matter + body.
+        This is what makes the vault *yours* — readable in any text editor."""
+        tags = ", ".join(self.tags)
+        return (
+            "---\n"
+            f"id: {self.id}\n"
+            f"source: {self.source}\n"
+            f"type: {self.type}\n"
+            f"tags: [{tags}]\n"
+            f"confidence: {self.confidence}\n"
+            f"created_at: {self.created_at}\n"
+            f"source_ref: {self.source_ref}\n"
+            f"content_hash: {self.content_hash}\n"
+            "---\n\n"
+            f"{self.content}\n"
+        )