Metadata-Version: 2.5
Name: memoraeu-mcp
Version: 0.3.0
Summary: Zero-knowledge persistent memory layer for Claude — MCP server
Project-URL: Homepage, https://memoraeu.com
Project-URL: Repository, https://github.com/pquattro/memoraeu-mcp
Project-URL: Documentation, https://memoraeu.com/docs/mcp
Author-email: MemoraEU <contact@memoraeu.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: ai,claude,llm,mcp,memory,zero-knowledge
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: cryptography>=44.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2,>=1.0.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: respx>=0.21; extra == 'test'
Description-Content-Type: text/markdown

# memoraeu-mcp

<!-- mcp-name: io.github.pquattro/memoraeu-mcp -->

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

---

## English

**Zero-knowledge persistent memory layer for Claude — MCP server**

MemoraEU gives Claude a persistent, encrypted memory. All content is encrypted **client-side** with AES-256-GCM before reaching the server — the server never sees your plaintext. Semantic search is powered by Mistral embeddings generated locally on your machine, before encryption.

### Features

- 🔒 **Zero-knowledge** — AES-256-GCM encryption, key never leaves your machine
- 🧠 **Semantic search** — embeddings generated locally before encryption (Qdrant on server)
- 🔄 **Auto memory** — remembers and recalls context automatically
- 🚫 **Deduplication** — detects near-duplicate memories before storing
- 🇪🇺 **EU hosted** — GDPR compliant infrastructure

### Installation

```bash
pip install memoraeu-mcp
```

Or with `uvx` (no install required, recommended):

```bash
uvx memoraeu-mcp
```

### Claude Desktop configuration

Add to your `claude_desktop_config.json`, under `mcpServers`:

```json
{
  "mcpServers": {
    "memoraeu": {
      "command": "uvx",
      "args": ["memoraeu-mcp"],
      "env": {
        "MEMORAEU_API_URL": "https://api.memoraeu.com",
        "MEMORAEU_API_KEY": "meu-sk-...",
        "MEMORAEU_SECRET": "your-memoraeu-password",
        "MEMORAEU_SALT": "your-kdf-salt",
        "MISTRAL_API_KEY": "your-mistral-key"
      }
    }
  }
}
```

### Understanding the variables

These five variables serve three distinct purposes — they are **not interchangeable**:

| Variable | Purpose | Where to get it |
|---|---|---|
| `MEMORAEU_API_KEY` | HTTP authentication (Bearer token sent with every request) | Dashboard → Settings → API Keys |
| `MEMORAEU_SECRET` | Your MemoraEU login password — used as the PBKDF2 input to derive the encryption key locally | Your account password |
| `MEMORAEU_SALT` | KDF salt generated by the server, unique to your account — combined with `MEMORAEU_SECRET` to produce the encryption key | Dashboard → Settings → Encryption Keys |
| `MEMORAEU_API_URL` | API endpoint (use `https://api.memoraeu.com` for the hosted service) | — |
| `MISTRAL_API_KEY` | Used to generate embeddings **locally** before encryption — required for zero-knowledge search (see below) | [console.mistral.ai](https://console.mistral.ai) |

> **Why does the MCP need its own Mistral key?**
>
> Zero-knowledge means the server never sees your plaintext. To enable semantic search, embeddings must be computed **before** the content is encrypted — on your machine. The MCP calls Mistral directly with the plaintext, gets the embedding vector, encrypts the content, then sends both to the server. The server stores the opaque blob and the vector, but cannot reconstruct the original text. Without `MISTRAL_API_KEY`, semantic search will not work.

> **Without `MISTRAL_API_KEY`:** The MCP will still work — `remember` and `recall` will function, but semantic search will fall back to keyword-based search on the server side. Zero-knowledge encryption is unaffected.

### Getting your keys

1. Sign up at [app.memoraeu.com](https://app.memoraeu.com)
2. Go to **Settings → Encryption Keys** → copy `MEMORAEU_SALT`
3. `MEMORAEU_SECRET` is your MemoraEU login password
4. Go to **Settings → API Keys** → create a key → copy `MEMORAEU_API_KEY`
5. Get a Mistral API key at [console.mistral.ai](https://console.mistral.ai)

### Remote MCP via SSE (no local install)

You can connect directly from claude.ai web, Cursor, Windsurf or any remote MCP client without installing anything locally:

```
SSE endpoint: https://api.memoraeu.com/mcp/sse
Auth: Authorization: Bearer meu-sk-...
```

Example config for Cursor / Windsurf:

```json
{
  "mcpServers": {
    "memoraeu": {
      "type": "sse",
      "url": "https://api.memoraeu.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer meu-sk-..."
      }
    }
  }
}
```

> **Note:** In SSE remote mode, content is not zero-knowledge encrypted (the server handles plaintext). Use the local `stdio` install for full zero-knowledge guarantees.

### Available tools

| Tool | Description |
|------|-------------|
| `remember` | Memorizes important information automatically |
| `recall` | Semantic search across stored memories |
| `forget` | Deletes a memory by ID |
| `list_memories` | Lists recent memories with optional category filter |
| `list_categories` | Returns existing categories sorted by usage |
| `remember_fact` | Stores a structured fact (subject/predicate/object) with temporal validity |
| `recall_facts` | Retrieves active facts for a subject |
| `invalidate_fact` | Marks a fact as expired by its ID |
| `find_related` | Finds memories related to a topic, optionally for one type (vector search with Mistral; without Mistral, lists accepted memories of that type) |
| `accept` | Moves a proposed typed memory to accepted |
| `export_docs` | Writes decisions to `docs/adr/NNNN-title.md` and accepted terms to `GLOSSARY.md` under `root` (decrypted locally, plaintext output) |
| `import_adrs` | Imports existing Markdown ADRs from `root/docs/adr/` as decisions (dry run by default) |

`remember` also takes `type` (`decision`, `constraint`, `component`, `risk`, `term`), `title`, `fields`, `supersedes` (full id or unique prefix of at least 8 characters) and `scope` (defaults to your default scope). `list_memories` filters on `type` and `status`. Typed memory behavior depends on the *Structured memory* setting (Dashboard → Settings): `off`, `suggest` (default) or `auto`. Mistral is optional; if the server is older, the mode falls back to `off`. The MCP reads the mode once (on its first tool call) and caches it: a change made in the dashboard takes effect after restarting Claude (or the MCP).

**When is something an ADR?** In `suggest` and `auto` modes, Claude proposes (or records) a decision only when all three hold: the decision is hard to reverse; a future reader would be surprised without its context; it came from a real trade-off between alternatives. Otherwise it is not typed as a decision (a constraint, risk or term may fit, or a plain memory).

**Export to `docs/adr` and `GLOSSARY.md`** — `export_docs(root, lang="fr"|"en", glossary=true)` takes the absolute path of an existing directory (typically your repository). It fetches every decision (any status) and the accepted terms, decrypts them locally and writes one `docs/adr/NNNN-slug.md` per decision (status, superseded-by / supersedes links, date, Context / Decision / Consequences / Alternatives sections, Notes) plus `GLOSSARY.md`. Each generated file starts with a `<!-- memoraeu:… -->` marker: only files carrying it are overwritten, identical files are left untouched, hand-written files are skipped and reported, nothing is ever deleted. Undecryptable memories are skipped and counted. **The exported files are plaintext: once committed to git, they leave zero-knowledge.**

**Import existing ADRs** — `import_adrs(root, dry_run=true, scope)` reads `root/docs/adr/*.md` in filename order (Nygard / adr-tools, MADR or home-grown format, English or French), skips MemoraEU-generated files and titles that already exist, and maps `Status` and the Context / Decision / Consequences / Alternatives sections (other sections go to the text). `Supersedes: 0003` / `Remplace : ADR-3` / `Supersedes [ADR 3](…)` refer to an ADR imported earlier in the same run: the new decision supersedes it, which rebuilds the chain server-side. `dry_run=true` (default) only prints the plan; `dry_run=false` creates the decisions (encrypted locally) and reports each file, without stopping on errors.

### Auto-memory behavior

The MCP server is designed to work without manual intervention:

**Automatic recall** — On the first user message of each session, `recall` is called automatically
with the detected topic as query. Recent memories are also loaded via the `memoraeu://context`
resource and injected as session context.

**Automatic remember** — When Claude detects a memorable piece of information (preference, decision,
biographical fact, technical constraint), it calls `remember` autonomously without waiting to be asked.
It confirms with a single discreet line.

**System prompt injection** — On the first `recall` call, the full behavior system prompt is injected
into Claude's context, reinforcing the auto-memory rules for the rest of the session.

This behavior is encoded directly in the tool descriptions. Claude models follow these instructions
as part of tool use — no additional configuration is required.

### Deduplication & compression

Before storing a memory, the MCP checks for near-duplicates using vector similarity:

| Similarity | Action |
|---|---|
| ≥ 94% | Memory skipped — exact duplicate detected |
| 85–94% | Warning logged, memory stored anyway |
| < 85% | Memory stored normally |

Long memories (> 300 characters) are compressed by Mistral before encryption, reducing token usage
and improving search relevance. Compression happens in plaintext, before the content is encrypted —
the server never sees the uncompressed original either.

### Self-hosting

The API is open source. Deploy your own instance with Docker:

```bash
git clone https://github.com/pquattro/memoraEu
cd memoraEu
docker compose up -d
```

---

## Français

**Couche mémoire persistante zero-knowledge pour Claude — serveur MCP**

MemoraEU donne à Claude 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. La recherche sémantique repose sur des embeddings Mistral générés localement, avant chiffrement.

### Fonctionnalités

- 🔒 **Zero-knowledge** — chiffrement AES-256-GCM, la clé ne quitte jamais votre machine
- 🧠 **Recherche sémantique** — embeddings générés localement avant chiffrement (Qdrant côté serveur)
- 🔄 **Mémoire automatique** — mémorise et rappelle le contexte sans intervention
- 🚫 **Déduplication** — détecte les doublons avant stockage
- 🇪🇺 **Hébergé en Europe** — infrastructure conforme RGPD

### Installation

```bash
pip install memoraeu-mcp
```

Ou avec `uvx` (sans installation, recommandé) :

```bash
uvx memoraeu-mcp
```

### Configuration Claude Desktop

Ajoutez dans votre `claude_desktop_config.json`, section `mcpServers` :

```json
{
  "mcpServers": {
    "memoraeu": {
      "command": "uvx",
      "args": ["memoraeu-mcp"],
      "env": {
        "MEMORAEU_API_URL": "https://api.memoraeu.com",
        "MEMORAEU_API_KEY": "meu-sk-...",
        "MEMORAEU_SECRET": "votre-mot-de-passe-memoraeu",
        "MEMORAEU_SALT": "votre-kdf-salt",
        "MISTRAL_API_KEY": "votre-clé-mistral"
      }
    }
  }
}
```

### Rôle de chaque variable

Ces cinq variables ont trois rôles distincts — elles **ne sont pas interchangeables** :

| Variable | Rôle | Où la trouver |
|---|---|---|
| `MEMORAEU_API_KEY` | Authentification HTTP (Bearer token envoyé à chaque requête) | Dashboard → Paramètres → Clés API |
| `MEMORAEU_SECRET` | Votre mot de passe MemoraEU — utilisé comme entrée PBKDF2 pour dériver la clé de chiffrement localement | Votre mot de passe de connexion |
| `MEMORAEU_SALT` | Salt KDF généré par le serveur, unique à votre compte — combiné avec `MEMORAEU_SECRET` pour produire la clé de chiffrement | Dashboard → Paramètres → Clés de chiffrement |
| `MEMORAEU_API_URL` | Endpoint API (utilisez `https://api.memoraeu.com` pour le service hébergé) | — |
| `MISTRAL_API_KEY` | Génération des embeddings **localement** avant chiffrement — requis pour la recherche zero-knowledge (voir ci-dessous) | [console.mistral.ai](https://console.mistral.ai) |

> **Pourquoi le MCP a-t-il besoin d'une clé Mistral ?**
>
> Le zero-knowledge signifie que le serveur ne voit jamais votre texte en clair. Pour permettre la recherche sémantique, les embeddings doivent être calculés **avant** le chiffrement — sur votre machine. Le MCP appelle Mistral directement avec le texte clair, obtient le vecteur d'embedding, chiffre le contenu, puis envoie les deux au serveur. Le serveur stocke le blob opaque et le vecteur, mais ne peut pas reconstituer le texte original. Sans `MISTRAL_API_KEY`, la recherche sémantique ne fonctionnera pas.

> **Sans `MISTRAL_API_KEY` :** Le MCP continue de fonctionner — `remember` et `recall` restent opérationnels, mais la recherche sémantique bascule sur une recherche par mots-clés côté serveur. Le chiffrement zero-knowledge n'est pas affecté.

### Obtenir vos clés

1. Créez un compte sur [app.memoraeu.com](https://app.memoraeu.com)
2. Allez dans **Paramètres → Clés de chiffrement** → copiez `MEMORAEU_SALT`
3. `MEMORAEU_SECRET` est votre mot de passe de connexion MemoraEU
4. Allez dans **Paramètres → Clés API** → créez une clé → copiez `MEMORAEU_API_KEY`
5. Obtenez une clé Mistral sur [console.mistral.ai](https://console.mistral.ai)

### MCP Remote via SSE (sans installation locale)

Connectez-vous directement depuis claude.ai web, Cursor, Windsurf ou tout client MCP distant sans rien installer :

```
Endpoint SSE : https://api.memoraeu.com/mcp/sse
Auth : Authorization: Bearer meu-sk-...
```

Exemple de config Cursor / Windsurf :

```json
{
  "mcpServers": {
    "memoraeu": {
      "type": "sse",
      "url": "https://api.memoraeu.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer meu-sk-..."
      }
    }
  }
}
```

> **Note :** En mode SSE distant, le contenu n'est pas chiffré zero-knowledge (le serveur traite le texte en clair). Utilisez l'installation locale `stdio` pour les garanties zero-knowledge complètes.

### Outils disponibles

| Outil | Description |
|-------|-------------|
| `remember` | Mémorise automatiquement les informations importantes |
| `recall` | Recherche sémantique dans les mémoires stockées |
| `forget` | Supprime une mémoire par son ID |
| `list_memories` | Liste les mémoires récentes avec filtre optionnel |
| `list_categories` | Retourne les catégories existantes triées par usage |
| `remember_fact` | Stocke un fait structuré (sujet/prédicat/objet) avec validité temporelle |
| `recall_facts` | Récupère les faits actifs pour un sujet |
| `invalidate_fact` | Marque un fait comme expiré par son ID |
| `find_related` | Retrouve les mémoires proches d'un sujet, éventuellement pour un type (recherche vectorielle avec Mistral ; sans Mistral, liste des mémoires acceptées du type) |
| `accept` | Passe une mémoire typée de « proposée » à « acceptée » |
| `export_docs` | Écrit les décisions dans `docs/adr/NNNN-titre.md` et les termes acceptés dans `GLOSSARY.md` sous `root` (déchiffrement local, fichiers en clair) |
| `import_adrs` | Importe les ADR Markdown existants de `root/docs/adr/` comme décisions (simulation par défaut) |

`remember` accepte aussi `type` (`decision`, `constraint`, `component`, `risk`, `term`), `title`, `fields`, `supersedes` (id complet ou préfixe unique d'au moins 8 caractères) et `scope` (par défaut : votre scope par défaut). `list_memories` filtre par `type` et `status`. Le comportement des mémoires typées dépend du réglage « Mémoire structurée » (Dashboard → Paramètres) : `off`, `suggest` (défaut) ou `auto`. Mistral est optionnel ; si le serveur est plus ancien, le mode retombe sur `off`. Le MCP lit le mode une seule fois (au premier appel d'outil) puis le garde en mémoire : un changement dans le dashboard prend effet après redémarrage de Claude (ou du MCP).

**Quand est-ce un ADR ?** En mode `suggest` et `auto`, Claude ne propose (ou n'enregistre) une décision que si les trois conditions sont réunies : elle est difficilement réversible ; un futur lecteur serait surpris sans son contexte ; elle résulte d'un vrai arbitrage entre des alternatives. Sinon, elle n'est pas typée comme décision (une contrainte, un risque ou un terme peut convenir, ou une mémoire simple).

**Export vers `docs/adr` et `GLOSSARY.md`** — `export_docs(root, lang="fr"|"en", glossary=true)` prend le chemin absolu d'un dossier existant (en général votre dépôt). Il récupère toutes les décisions (tous statuts) et les termes acceptés, les déchiffre localement et écrit un fichier `docs/adr/NNNN-slug.md` par décision (statut, liens « remplacée par » / « remplace », date, sections Contexte / Décision / Conséquences / Alternatives, Notes) ainsi que `GLOSSARY.md`. Chaque fichier généré commence par un marqueur `<!-- memoraeu:… -->` : seuls les fichiers qui le portent sont réécrits, les fichiers identiques ne sont pas touchés, les fichiers écrits à la main sont ignorés et signalés, rien n'est jamais supprimé. Les mémoires indéchiffrables sont ignorées et comptées. **Les fichiers exportés sont en clair : une fois versionnés dans git, ils sortent du zero-knowledge.**

**Import d'ADR existants** — `import_adrs(root, dry_run=true, scope)` lit `root/docs/adr/*.md` dans l'ordre des noms de fichier (format Nygard / adr-tools, MADR ou maison, en anglais ou en français), ignore les fichiers générés par MemoraEU et les titres déjà présents, et reprend `Statut` ainsi que les sections Contexte / Décision / Conséquences / Alternatives (les autres sections vont dans le texte). `Supersedes: 0003` / `Remplace : ADR-3` / `Supersedes [ADR 3](…)` désignent un ADR importé plus tôt dans la même exécution : la nouvelle décision le remplace, ce qui reconstruit la chaîne côté serveur. `dry_run=true` (défaut) affiche seulement le plan ; `dry_run=false` crée les décisions (chiffrées localement) et rend compte fichier par fichier, sans s'arrêter sur une erreur.

### Comportement de mémoire automatique

Le serveur MCP est conçu pour fonctionner sans intervention manuelle :

**Rappel automatique** — Au premier message de chaque session, `recall` est appelé automatiquement
avec le sujet détecté comme requête. Les mémoires récentes sont également chargées via la ressource
`memoraeu://context` et injectées dans le contexte de session.

**Mémorisation automatique** — Lorsque Claude détecte une information durable (préférence, décision,
fait biographique, contrainte technique), il appelle `remember` de façon autonome, sans attendre qu'on
le lui demande. Il confirme par une simple ligne discrète.

**Injection du prompt système** — Au premier appel à `recall`, le prompt système complet de comportement
est injecté dans le contexte de Claude, renforçant les règles de mémoire automatique pour le reste
de la session.

Ce comportement est encodé directement dans les descriptions des outils. Les modèles Claude suivent
ces instructions dans le cadre de l'utilisation des outils — aucune configuration supplémentaire
n'est requise.

### Déduplication et compression

Avant de stocker une mémoire, le MCP vérifie les quasi-doublons par similarité vectorielle :

| Similarité | Action |
|---|---|
| ≥ 94 % | Mémoire ignorée — doublon exact détecté |
| 85–94 % | Avertissement journalisé, mémoire stockée quand même |
| < 85 % | Mémoire stockée normalement |

Les mémoires longues (> 300 caractères) sont compressées par Mistral avant chiffrement, réduisant
la consommation de tokens et améliorant la pertinence des recherches. La compression s'effectue en
texte clair, avant chiffrement du contenu — le serveur ne voit jamais l'original non compressé non plus.

### Auto-hébergement

L'API est open source. Déployez votre propre instance avec Docker :

```bash
git clone https://github.com/pquattro/memoraEu
cd memoraEu
docker compose up -d
```

---

## License

MIT © 2026 MemoraEU
