memoraeu 0.1.1__tar.gz

memoraeu-0.1.1/.gitignore

@@ -0,0 +1,21 @@
+# Environment
+env/
+.env
+
+# MCP config (contains secrets — use .mcp.json.example as template)
+.mcp.json
+
+# Database
+memoraeu.db
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store
+
+# Node
+dashboard/node_modules/
+landing/node_modules/
+dashboard/dist/
+landing/dist/

memoraeu-0.1.1/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: memoraeu
+Version: 0.1.1
+Summary: Couche mémoire persistante zero-knowledge pour LLMs — client Python
+Project-URL: Homepage, https://memoraeu.com
+Project-URL: Repository, https://github.com/pquattro/memoraeu
+Project-URL: Documentation, https://docs.memoraeu.com
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# MemoraEU SDK — Python
+
+Couche mémoire persistante **zero-knowledge** pour LLMs.  
+Compatible avec n'importe quel projet Python — sync ou async.
+
+## Installation
+
+```bash
+pip install memoraeu
+```
+
+## Démarrage rapide
+
+### 1. Obtenir vos clés
+
+1. Créez un compte sur [app.memoraeu.com](https://app.memoraeu.com)
+2. **Paramètres → Clés de chiffrement** → copiez `MEMORAEU_SALT`
+3. **Paramètres → Clés API** → créez une clé → copiez `MEMORAEU_API_KEY` (`meu-sk-…`)
+4. `secret` = votre mot de passe de connexion MemoraEU
+
+### 2. Client sync
+
+```python
+from memoraeu import MemoraEU
+
+client = MemoraEU(
+    api_url="https://api.memoraeu.com",
+    api_key="meu-sk-...",        # clé API (authentification HTTP)
+    secret="votre-mot-de-passe", # mot de passe MemoraEU (dérivation de clé locale)
+    salt="votre-kdf-salt",       # salt unique à votre compte (depuis les Paramètres)
+)
+
+# Mémoriser
+memory = client.remember(
+    "Philippe préfère Python et FastAPI",
+    category="prefs",
+    tags=["python", "stack"]
+)
+
+# Rechercher
+results = client.recall("préférences tech", limit=3)
+for r in results:
+    print(f"[{round(r.score*100)}%] {r.memory.content}")
+
+# Supprimer
+client.forget(memory.id)
+```
+
+### 3. Client async
+
+```python
+from memoraeu import AsyncMemoraEU
+
+async with AsyncMemoraEU(
+    api_url="https://api.memoraeu.com",
+    api_key="meu-sk-...",
+    secret="votre-mot-de-passe",
+    salt="votre-kdf-salt",
+) as client:
+    memory = await client.remember("...")
+    results = await client.recall("...")
+```
+
+## Comprendre les paramètres
+
+| Paramètre | Rôle |
+|---|---|
+| `api_key` | Authentification HTTP — Bearer token envoyé à chaque requête (`meu-sk-…`) |
+| `secret` | Votre mot de passe MemoraEU — utilisé comme entrée PBKDF2 pour dériver la clé de chiffrement localement |
+| `salt` | Salt KDF unique à votre compte, généré par le serveur — combiné avec `secret` pour produire la clé AES |
+
+> **Zero-knowledge** : la clé de chiffrement est dérivée sur votre machine avec `PBKDF2(secret, salt, 210 000 itérations)`. Le serveur reçoit uniquement le contenu chiffré — il ne peut pas le lire même s'il est compromis.
+>
+> ⚠️ Si vous perdez votre `secret` ou votre `salt`, vos mémoires chiffrées sont irrécupérables.
+
+## Référence
+
+| Méthode | Description |
+|---------|-------------|
+| `remember(content, category?, tags?, scope?)` | Mémorise une information |
+| `recall(query, limit=3, category?, scope?)` | Recherche sémantique |
+| `forget(memory_id)` | Supprime une mémoire |
+| `list_memories(category?, limit=20, scope?)` | Liste les mémoires |
+| `list_categories()` | Catégories triées par usage |
+
+## Gestion des erreurs
+
+```python
+from memoraeu import APIError, CryptoError, ConnectionError
+
+try:
+    client.remember("...")
+except APIError as e:
+    print(e.status_code, str(e))  # ex: 401, 409
+except CryptoError as e:
+    print("Problème de chiffrement", e)
+except ConnectionError as e:
+    print("API inaccessible", e)
+```
+
+## Auto-hébergement
+
+```python
+client = MemoraEU(
+    api_url="http://localhost:8000",
+    api_key="meu-sk-...",
+    secret="...",
+    salt="...",
+)
+```
+
+## Licence
+
+MIT © MemoraEU

memoraeu-0.1.1/README.md

@@ -0,0 +1,114 @@
+# MemoraEU SDK — Python
+
+Couche mémoire persistante **zero-knowledge** pour LLMs.  
+Compatible avec n'importe quel projet Python — sync ou async.
+
+## Installation
+
+```bash
+pip install memoraeu
+```
+
+## Démarrage rapide
+
+### 1. Obtenir vos clés
+
+1. Créez un compte sur [app.memoraeu.com](https://app.memoraeu.com)
+2. **Paramètres → Clés de chiffrement** → copiez `MEMORAEU_SALT`
+3. **Paramètres → Clés API** → créez une clé → copiez `MEMORAEU_API_KEY` (`meu-sk-…`)
+4. `secret` = votre mot de passe de connexion MemoraEU
+
+### 2. Client sync
+
+```python
+from memoraeu import MemoraEU
+
+client = MemoraEU(
+    api_url="https://api.memoraeu.com",
+    api_key="meu-sk-...",        # clé API (authentification HTTP)
+    secret="votre-mot-de-passe", # mot de passe MemoraEU (dérivation de clé locale)
+    salt="votre-kdf-salt",       # salt unique à votre compte (depuis les Paramètres)
+)
+
+# Mémoriser
+memory = client.remember(
+    "Philippe préfère Python et FastAPI",
+    category="prefs",
+    tags=["python", "stack"]
+)
+
+# Rechercher
+results = client.recall("préférences tech", limit=3)
+for r in results:
+    print(f"[{round(r.score*100)}%] {r.memory.content}")
+
+# Supprimer
+client.forget(memory.id)
+```
+
+### 3. Client async
+
+```python
+from memoraeu import AsyncMemoraEU
+
+async with AsyncMemoraEU(
+    api_url="https://api.memoraeu.com",
+    api_key="meu-sk-...",
+    secret="votre-mot-de-passe",
+    salt="votre-kdf-salt",
+) as client:
+    memory = await client.remember("...")
+    results = await client.recall("...")
+```
+
+## Comprendre les paramètres
+
+| Paramètre | Rôle |
+|---|---|
+| `api_key` | Authentification HTTP — Bearer token envoyé à chaque requête (`meu-sk-…`) |
+| `secret` | Votre mot de passe MemoraEU — utilisé comme entrée PBKDF2 pour dériver la clé de chiffrement localement |
+| `salt` | Salt KDF unique à votre compte, généré par le serveur — combiné avec `secret` pour produire la clé AES |
+
+> **Zero-knowledge** : la clé de chiffrement est dérivée sur votre machine avec `PBKDF2(secret, salt, 210 000 itérations)`. Le serveur reçoit uniquement le contenu chiffré — il ne peut pas le lire même s'il est compromis.
+>
+> ⚠️ Si vous perdez votre `secret` ou votre `salt`, vos mémoires chiffrées sont irrécupérables.
+
+## Référence
+
+| Méthode | Description |
+|---------|-------------|
+| `remember(content, category?, tags?, scope?)` | Mémorise une information |
+| `recall(query, limit=3, category?, scope?)` | Recherche sémantique |
+| `forget(memory_id)` | Supprime une mémoire |
+| `list_memories(category?, limit=20, scope?)` | Liste les mémoires |
+| `list_categories()` | Catégories triées par usage |
+
+## Gestion des erreurs
+
+```python
+from memoraeu import APIError, CryptoError, ConnectionError
+
+try:
+    client.remember("...")
+except APIError as e:
+    print(e.status_code, str(e))  # ex: 401, 409
+except CryptoError as e:
+    print("Problème de chiffrement", e)
+except ConnectionError as e:
+    print("API inaccessible", e)
+```
+
+## Auto-hébergement
+
+```python
+client = MemoraEU(
+    api_url="http://localhost:8000",
+    api_key="meu-sk-...",
+    secret="...",
+    salt="...",
+)
+```
+
+## Licence
+
+MIT © MemoraEU

memoraeu-0.1.1/memoraeu/__init__.py

@@ -0,0 +1,20 @@
+"""
+MemoraEU SDK — Couche mémoire persistante zero-knowledge pour LLMs
+"""
+from .client import AsyncMemoraEU, MemoraEU
+from .exceptions import APIError, ConnectionError, CryptoError, MemoraEUError
+from .models import Category, Memory, SearchResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "MemoraEU",
+    "AsyncMemoraEU",
+    "Memory",
+    "SearchResult",
+    "Category",
+    "MemoraEUError",
+    "APIError",
+    "CryptoError",
+    "ConnectionError",
+]

memoraeu-0.1.1/memoraeu/client.py

@@ -0,0 +1,273 @@
+"""
+MemoraEU SDK — Client sync et async
+
+Usage sync :
+    from memoraeu import MemoraEU
+    client = MemoraEU(api_url="http://localhost:8000", secret="...", salt="...")
+    memory = client.remember("Philippe préfère Python", category="prefs")
+    results = client.recall("préférences stack")
+
+Usage async :
+    from memoraeu import AsyncMemoraEU
+    async with AsyncMemoraEU(api_url="...", secret="...", salt="...") as client:
+        memory = await client.remember("...")
+        results = await client.recall("...")
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from .crypto import derive_key, encrypt, decrypt, is_encrypted
+from .exceptions import APIError, CryptoError
+from .exceptions import ConnectionError as MemoraEUConnectionError
+from .models import Category, Memory, SearchResult
+
+
+class _BaseClient:
+    """Logique commune : crypto, sérialisation."""
+
+    def __init__(
+        self,
+        api_url: str = "http://localhost:8000",
+        api_key: str = "",
+        secret: str = "",
+        salt: str = "memoraeu-default-salt-v1",
+        timeout: float = 90.0,
+    ):
+        self.api_url = api_url.rstrip("/")
+        self.timeout = timeout
+        self._headers = {"Authorization": f"Bearer {api_key}"} if api_key else {}
+        self._key: Optional[bytes] = None
+        if secret:
+            try:
+                self._key = derive_key(secret, salt)
+            except Exception as e:
+                raise CryptoError(f"Dérivation de clé échouée : {e}") from e
+
+    # ── Crypto ────────────────────────────────────────────────────────────
+
+    def _encrypt(self, content: str) -> str:
+        if not self._key:
+            return content
+        return encrypt(content, self._key)
+
+    def _decrypt(self, value: str) -> str:
+        if not self._key:
+            return value
+        if not is_encrypted(value):
+            return value
+        try:
+            return decrypt(value, self._key)
+        except Exception as e:
+            raise CryptoError(f"Déchiffrement échoué : {e}") from e
+
+    # ── Réponses ──────────────────────────────────────────────────────────
+
+    def _handle_response(self, response: httpx.Response) -> dict:
+        try:
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise APIError(response.status_code, response.text) from e
+        return response.json()
+
+    def _parse_memory(self, data: dict) -> Memory:
+        return Memory.from_dict(data, decrypt_fn=self._decrypt)
+
+    def _parse_search_results(self, data: dict) -> list[SearchResult]:
+        return [SearchResult.from_dict(r, decrypt_fn=self._decrypt) for r in data.get("results", [])]
+
+
+# ══════════════════════════════════════════════════════════════════════════
+#  Client synchrone
+# ══════════════════════════════════════════════════════════════════════════
+
+class MemoraEU(_BaseClient):
+    """Client synchrone MemoraEU."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._http = httpx.Client(timeout=self.timeout)
+
+    def close(self):
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _post(self, path: str, body: dict) -> dict:
+        try:
+            r = self._http.post(f"{self.api_url}{path}", json=body, headers=self._headers)
+        except httpx.ConnectError as e:
+            raise MemoraEUConnectionError(f"Impossible de joindre {self.api_url}") from e
+        return self._handle_response(r)
+
+    def _get(self, path: str, params: dict = None) -> dict | list:
+        try:
+            r = self._http.get(f"{self.api_url}{path}", params=params, headers=self._headers)
+        except httpx.ConnectError as e:
+            raise MemoraEUConnectionError(f"Impossible de joindre {self.api_url}") from e
+        return self._handle_response(r)
+
+    def _delete(self, path: str) -> bool:
+        try:
+            r = self._http.delete(f"{self.api_url}{path}", headers=self._headers)
+        except httpx.ConnectError as e:
+            raise MemoraEUConnectionError(f"Impossible de joindre {self.api_url}") from e
+        return r.status_code == 204
+
+    # ── API publique ──────────────────────────────────────────────────────
+
+    def remember(
+        self,
+        content: str,
+        category: Optional[str] = None,
+        tags: list[str] = None,
+        source: str = "sdk",
+        scope: str = "private",
+    ) -> Memory:
+        """Mémorise une information. Le contenu est chiffré côté client si secret fourni."""
+        data = self._post("/memories", {
+            "content": self._encrypt(content),
+            "category": category,
+            "tags": tags or [],
+            "source": source,
+            "scope": scope,
+        })
+        return self._parse_memory(data)
+
+    def recall(
+        self,
+        query: str,
+        limit: int = 3,
+        category: Optional[str] = None,
+        scope: str = "private",
+    ) -> list[SearchResult]:
+        """Recherche sémantique dans les mémoires."""
+        data = self._post("/memories/search", {
+            "query": query,
+            "limit": limit,
+            "category": category,
+            "scope": scope,
+        })
+        return self._parse_search_results(data)
+
+    def forget(self, memory_id: str) -> bool:
+        """Supprime une mémoire par son ID."""
+        return self._delete(f"/memories/{memory_id}")
+
+    def list_memories(
+        self,
+        category: Optional[str] = None,
+        limit: int = 20,
+        scope: str = "private",
+    ) -> list[Memory]:
+        """Liste les mémoires récentes."""
+        params = {"limit": limit, "scope": scope}
+        if category:
+            params["category"] = category
+        data = self._get("/memories", params=params)
+        return [self._parse_memory(m) for m in data]
+
+    def list_categories(self) -> list[Category]:
+        """Retourne les catégories triées par usage."""
+        data = self._get("/memories/categories")
+        return [Category(name=c["name"], usage_count=c["usage_count"]) for c in data.get("categories", [])]
+
+
+# ══════════════════════════════════════════════════════════════════════════
+#  Client asynchrone
+# ══════════════════════════════════════════════════════════════════════════
+
+class AsyncMemoraEU(_BaseClient):
+    """Client asynchrone MemoraEU."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self._http: Optional[httpx.AsyncClient] = None
+
+    async def __aenter__(self):
+        self._http = httpx.AsyncClient(timeout=self.timeout)
+        return self
+
+    async def __aexit__(self, *args):
+        if self._http:
+            await self._http.aclose()
+
+    async def _post(self, path: str, body: dict) -> dict:
+        try:
+            r = await self._http.post(f"{self.api_url}{path}", json=body, headers=self._headers)
+        except httpx.ConnectError as e:
+            raise MemoraEUConnectionError(f"Impossible de joindre {self.api_url}") from e
+        return self._handle_response(r)
+
+    async def _get(self, path: str, params: dict = None) -> dict | list:
+        try:
+            r = await self._http.get(f"{self.api_url}{path}", params=params, headers=self._headers)
+        except httpx.ConnectError as e:
+            raise MemoraEUConnectionError(f"Impossible de joindre {self.api_url}") from e
+        return self._handle_response(r)
+
+    async def _delete(self, path: str) -> bool:
+        try:
+            r = await self._http.delete(f"{self.api_url}{path}", headers=self._headers)
+        except httpx.ConnectError as e:
+            raise MemoraEUConnectionError(f"Impossible de joindre {self.api_url}") from e
+        return r.status_code == 204
+
+    # ── API publique ──────────────────────────────────────────────────────
+
+    async def remember(
+        self,
+        content: str,
+        category: Optional[str] = None,
+        tags: list[str] = None,
+        source: str = "sdk",
+        scope: str = "private",
+    ) -> Memory:
+        data = await self._post("/memories", {
+            "content": self._encrypt(content),
+            "category": category,
+            "tags": tags or [],
+            "source": source,
+            "scope": scope,
+        })
+        return self._parse_memory(data)
+
+    async def recall(
+        self,
+        query: str,
+        limit: int = 3,
+        category: Optional[str] = None,
+        scope: str = "private",
+    ) -> list[SearchResult]:
+        data = await self._post("/memories/search", {
+            "query": query,
+            "limit": limit,
+            "category": category,
+            "scope": scope,
+        })
+        return self._parse_search_results(data)
+
+    async def forget(self, memory_id: str) -> bool:
+        return await self._delete(f"/memories/{memory_id}")
+
+    async def list_memories(
+        self,
+        category: Optional[str] = None,
+        limit: int = 20,
+        scope: str = "private",
+    ) -> list[Memory]:
+        params = {"limit": limit, "scope": scope}
+        if category:
+            params["category"] = category
+        data = await self._get("/memories", params=params)
+        return [self._parse_memory(m) for m in data]
+
+    async def list_categories(self) -> list[Category]:
+        data = await self._get("/memories/categories")
+        return [Category(name=c["name"], usage_count=c["usage_count"]) for c in data.get("categories", [])]

memoraeu-0.1.1/memoraeu/crypto.py

@@ -0,0 +1,68 @@
+"""
+MemoraEU — Chiffrement zero-knowledge côté client
+AES-256-GCM + PBKDF2-HMAC-SHA256
+
+Le serveur ne voit jamais le texte clair ni la clé.
+"""
+import os
+import base64
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+from cryptography.hazmat.primitives import hashes
+
+
+# 210 000 itérations (recommandation OWASP 2024 pour PBKDF2-SHA256)
+PBKDF2_ITERATIONS = 210_000
+
+# Préfixe pour détecter les valeurs chiffrées sans ambiguïté
+ENC_PREFIX = "ENCv1:"
+
+
+def derive_key(password: str, salt: str) -> bytes:
+    """Dérive une clé AES-256 depuis un mot de passe et un salt."""
+    salt_bytes = salt.encode() if isinstance(salt, str) else salt
+    kdf = PBKDF2HMAC(
+        algorithm=hashes.SHA256(),
+        length=32,
+        salt=salt_bytes,
+        iterations=PBKDF2_ITERATIONS,
+    )
+    return kdf.derive(password.encode())
+
+
+def encrypt(plaintext: str, key: bytes) -> str:
+    """
+    Chiffre un texte avec AES-256-GCM.
+    Retourne : ENCv1:<base64(nonce[12] + ciphertext + tag[16])>
+    """
+    nonce = os.urandom(12)
+    ciphertext = AESGCM(key).encrypt(nonce, plaintext.encode("utf-8"), None)
+    return ENC_PREFIX + base64.b64encode(nonce + ciphertext).decode("ascii")
+
+
+def decrypt(ciphertext_b64: str, key: bytes) -> str:
+    """
+    Déchiffre un texte chiffré par encrypt().
+    Accepte les anciens formats (sans préfixe ENCv1:) pour rétrocompatibilité.
+    Lève une exception si la clé est mauvaise ou les données corrompues.
+    """
+    raw = ciphertext_b64[len(ENC_PREFIX):] if ciphertext_b64.startswith(ENC_PREFIX) else ciphertext_b64
+    data = base64.b64decode(raw)
+    nonce = data[:12]
+    ciphertext = data[12:]
+    plaintext = AESGCM(key).decrypt(nonce, ciphertext, None)
+    return plaintext.decode("utf-8")
+
+
+def is_encrypted(value: str) -> bool:
+    """
+    Détecte si une valeur est chiffrée via le préfixe ENCv1:.
+    Rétrocompatible : accepte aussi les anciens blobs base64 bruts (≥ 28 octets).
+    """
+    if value.startswith(ENC_PREFIX):
+        return True
+    try:
+        data = base64.b64decode(value)
+        return len(data) >= 28  # nonce(12) + tag(16) minimum
+    except Exception:
+        return False

memoraeu-0.1.1/memoraeu/exceptions.py

@@ -0,0 +1,23 @@
+"""
+MemoraEU SDK — Exceptions
+"""
+
+
+class MemoraEUError(Exception):
+    """Erreur générique MemoraEU."""
+
+
+class APIError(MemoraEUError):
+    """Erreur retournée par l'API (HTTP 4xx/5xx)."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        super().__init__(f"[{status_code}] {message}")
+
+
+class CryptoError(MemoraEUError):
+    """Erreur de chiffrement/déchiffrement."""
+
+
+class ConnectionError(MemoraEUError):
+    """Impossible de joindre l'API MemoraEU."""

memoraeu-0.1.1/memoraeu/models.py

@@ -0,0 +1,57 @@
+"""
+MemoraEU SDK — Modèles de données
+"""
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class Memory:
+    id: str
+    content: str
+    category: Optional[str]
+    tags: list[str]
+    source: str
+    scope: str
+    org_id: str
+    user_id: str
+    created_at: datetime
+    updated_at: datetime
+
+    @classmethod
+    def from_dict(cls, data: dict, decrypt_fn=None) -> "Memory":
+        content = data["content"]
+        if decrypt_fn:
+            content = decrypt_fn(content)
+        return cls(
+            id=data["id"],
+            content=content,
+            category=data.get("category"),
+            tags=data.get("tags", []),
+            source=data.get("source", "sdk"),
+            scope=data.get("scope", "private"),
+            org_id=data.get("org_id", ""),
+            user_id=data.get("user_id", ""),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            updated_at=datetime.fromisoformat(data["updated_at"]),
+        )
+
+
+@dataclass
+class SearchResult:
+    memory: Memory
+    score: float
+
+    @classmethod
+    def from_dict(cls, data: dict, decrypt_fn=None) -> "SearchResult":
+        return cls(
+            memory=Memory.from_dict(data["memory"], decrypt_fn=decrypt_fn),
+            score=data["score"],
+        )
+
+
+@dataclass
+class Category:
+    name: str
+    usage_count: int

memoraeu-0.1.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memoraeu"
+version = "0.1.1"
+description = "Couche mémoire persistante zero-knowledge pour LLMs — client Python"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.27",
+    "cryptography>=42.0",
+]
+
+[project.urls]
+Homepage = "https://memoraeu.com"
+Repository = "https://github.com/pquattro/memoraeu"
+Documentation = "https://docs.memoraeu.com"