Metadata-Version: 2.5
Name: memoraeu
Version: 0.2.0
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-python
Project-URL: Documentation, https://memoraeu.com/docs/python
License: MIT
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Description-Content-Type: text/markdown

# MemoraEU SDK — Python

🇬🇧 [English](#english) | 🇫🇷 [Français](#français)

---

## English

**Zero-knowledge persistent memory layer for AI agents — official Python SDK**

MemoraEU gives your agents a persistent, encrypted memory. All content is encrypted **client-side** with AES-256-GCM before reaching the server — the server never sees your plaintext. Compatible with any Python project, sync or async.

### Installation

```bash
pip install memoraeu
```

Requires Python ≥ 3.11. Dependencies: `httpx`, `cryptography`.

### Quick start

#### 1. Get your credentials

1. Create an account at [app.memoraeu.com](https://app.memoraeu.com)
2. **Settings → Encryption keys** → copy `MEMORAEU_SALT`
3. **Settings → API keys** → create a key → copy `MEMORAEU_API_KEY` (`meu-sk-…`)
4. `secret` = your MemoraEU login password

#### 2. Sync client

```python
from memoraeu import MemoraEU

client = MemoraEU(
    api_url="https://api.memoraeu.com",
    api_key="meu-sk-...",        # API key (HTTP auth)
    secret="your-password",      # MemoraEU password (local key derivation)
    salt="your-kdf-salt",        # account-unique salt (from Settings)
)

# Store a memory
memory = client.remember(
    "Philippe prefers Python and FastAPI",
    category="prefs",
    tags=["python", "stack"],
)
print(memory.id)  # mem_01HV...

# Semantic search
results = client.recall("tech preferences", limit=3)
for r in results:
    print(f"[{round(r.score*100)}%] {r.memory.content}")

# List memories
memories = client.list_memories(category="prefs", limit=20)

# Typed memory (decision), replacing an earlier one
adr = client.remember("Stripe over Paddle", mtype="decision", title="Billing provider",
                      fields={"decision": "Stripe"}, supersedes=["a1b2c3d4"])
print(adr.seq)  # ADR number

# List categories
categories = client.list_categories()

# Delete
client.forget(memory.id)
```

#### 3. Async client

```python
from memoraeu import AsyncMemoraEU

async with AsyncMemoraEU(
    api_url="https://api.memoraeu.com",
    api_key="meu-sk-...",
    secret="your-password",
    salt="your-kdf-salt",
) as client:
    memory = await client.remember("...")
    results = await client.recall("...")
```

### Understanding the parameters

| Parameter | Role |
|---|---|
| `api_key` | HTTP authentication — Bearer token sent with every request (`meu-sk-…`) |
| `secret` | Your MemoraEU password — used as PBKDF2 input to derive the encryption key **locally** |
| `salt` | Account-unique KDF salt generated by the server — combined with `secret` to produce the AES key |

> **Zero-knowledge**: the encryption key is derived on your machine using `PBKDF2(secret, salt, 210 000 iterations)`. The server receives only the encrypted ciphertext — it cannot read it even if compromised.
>
> ⚠️ If you lose your `secret` or `salt`, your encrypted memories are unrecoverable.

### Method reference

| Method | Description |
|--------|-------------|
| `remember(content, category?, tags?, scope?)` | Store a memory (client-side encrypted) |
| `recall(query, limit=3, category?, scope?)` | Semantic search in natural language |
| `forget(memory_id)` | Delete a memory by its ID |
| `list_memories(category?, limit=20, scope?)` | List recent memories |
| `list_categories()` | Categories sorted by usage |

### Error handling

```python
from memoraeu import APIError, CryptoError, ConnectionError

try:
    client.remember("...")
except APIError as e:
    print(e.status_code, str(e))   # e.g. 401, 409
except CryptoError as e:
    print("Encryption error:", e)
except ConnectionError as e:
    print("API unreachable:", e)
```

### Self-hosting

```python
client = MemoraEU(
    api_url="http://localhost:8000",
    api_key="meu-sk-...",
    secret="...",
    salt="...",
)
```

### Links

- [Documentation](https://memoraeu.com/docs/python)
- [REST API reference](https://memoraeu.com/docs/api)
- [MemoraEU app](https://app.memoraeu.com)
- [GitHub — main repo](https://github.com/pquattro/memoraEu)

### License

MIT © 2026 MemoraEU — ISQUARECUBE SAS

---

## Français

**Couche mémoire persistante zero-knowledge pour agents IA — SDK Python officiel**

MemoraEU donne à vos agents une mémoire persistante et chiffrée. Tout le contenu est chiffré **côté client** en AES-256-GCM avant d'atteindre le serveur — le serveur ne voit jamais le texte en clair. Compatible avec tout projet Python, sync ou async.

### Installation

```bash
pip install memoraeu
```

Nécessite Python ≥ 3.11. Dépendances : `httpx`, `cryptography`.

### 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"],
)
print(memory.id)  # mem_01HV...

# Recherche sémantique
results = client.recall("préférences tech", limit=3)
for r in results:
    print(f"[{round(r.score*100)}%] {r.memory.content}")

# Lister les mémoires
memories = client.list_memories(category="prefs", limit=20)

# Mémoire typée (décision), qui en remplace une autre
adr = client.remember("Stripe plutôt que Paddle", mtype="decision", title="Fournisseur de facturation",
                      fields={"decision": "Stripe"}, supersedes=["a1b2c3d4"])
print(adr.seq)  # numéro ADR

# Lister les catégories
categories = client.list_categories()

# 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 des méthodes

| Méthode | Description |
|---------|-------------|
| `remember(content, category?, tags?, scope?)` | Mémorise une information (chiffrée côté client) |
| `recall(query, limit=3, category?, scope?)` | Recherche sémantique en langage naturel |
| `forget(memory_id)` | Supprime une mémoire par son ID |
| `list_memories(category?, limit=20, scope?)` | Liste les mémoires récentes |
| `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="...",
)
```

### Liens

- [Documentation](https://memoraeu.com/docs/python)
- [Référence API REST](https://memoraeu.com/docs/api)
- [Application MemoraEU](https://app.memoraeu.com)
- [GitHub — dépôt principal](https://github.com/pquattro/memoraEu)

### Licence

MIT © 2026 MemoraEU — ISQUARECUBE SAS
