Doramagic Project Pack · Human Manual
memoraeu-mcp
MemoraEU MCP bridges the gap between ephemeral AI conversations and persistent memory. When integrated with Claude Desktop or other MCP-compatible clients, it allows the AI to:
Home
Related topics: Installation Guide, System Architecture
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Installation Guide, System Architecture
Home
MemoraEU MCP is a Model Context Protocol (MCP) server that provides zero-knowledge memory and fact storage capabilities for AI assistants. The server enables AI models to automatically remember user preferences, biographical facts, technical configurations, and structured knowledge across conversations while maintaining end-to-end encryption.
Overview
MemoraEU MCP bridges the gap between ephemeral AI conversations and persistent memory. When integrated with Claude Desktop or other MCP-compatible clients, it allows the AI to:
- Automatically recall relevant memories at the start of each conversation
- Persistently remember user preferences, decisions, and facts without explicit requests
- Search semantically across encrypted memory stores
- Manage structured facts with temporal validity (subject/predicate/object triplets)
The architecture is designed around the principle of zero-knowledge: embeddings are computed locally before encryption, ensuring the server never sees plaintext content. Sources: README.md
Architecture
graph TD
subgraph "Client Side (Local)"
A[Claude Desktop / MCP Client] --> B[MemoraEU MCP Server]
B --> C[Mistral API<br/>Embedding Generation]
B --> D[PBKDF2 Key Derivation]
B --> E[AES-256-GCM Encryption]
end
subgraph "MemoraEU Cloud"
F[API Endpoint<br/>api.memoraeu.com] --> G[Encrypted Storage]
F --> H[Vector Search Index]
end
C -->|Plaintext| E
D -->|Derived Key| E
E -->|Encrypted Blob| F
C -->|Embedding Vector| F
style C fill:#ff9999
style D fill:#ff9999
style E fill:#ff9999
style F fill:#99ccff
style G fill:#99ff99
style H fill:#99ff99Security Model
The zero-knowledge architecture ensures that all sensitive processing occurs client-side:
| Component | Location | Data Handled |
|---|---|---|
| Embedding Generation | Local (MCP server) | Plaintext content |
| Compression | Local | Plaintext content |
| Categorization | Local | Plaintext content |
| Encryption | Local (AES-256-GCM) | Plaintext → Ciphertext |
| Storage | Remote (MemoraEU Cloud) | Encrypted blobs + vectors |
| Search | Hybrid | Vector similarity on encrypted index |
Sources: README.md
Installation Modes
MemoraEU MCP supports two deployment modes with different security guarantees:
STDIO Mode (Zero-Knowledge)
Full zero-knowledge encryption with all processing happening locally.
{
"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"
}
}
}
}
Sources: README.md
SSE Mode (Remote)
Direct connection without local installation, suitable for web clients.
{
"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 since the server processes plaintext. Sources: README.md
Available Tools
The MCP server exposes 9 tools for memory and fact management:
Memory Tools
| Tool | Description | Required Parameters |
|---|---|---|
remember | Automatically memorizes important information when user expresses preferences, decisions, biographical facts, or technical configs | content |
recall | Semantic search across stored memories using vector similarity | query |
forget | Deletes a memory by its ID | memory_id |
list_memories | Lists recent memories with optional category filter | - |
list_categories | Returns existing categories sorted by usage | - |
Sources: memoraeu_mcp/main.py:48-110
Fact Tools
| Tool | Description | Required Parameters |
|---|---|---|
remember_fact | Stores a structured fact with temporal validity (subject/predicate/object) | subject, predicate, object |
recall_facts | Retrieves active facts for a given subject | subject |
invalidate_fact | Marks a fact as expired by its ID | fact_id |
Sources: server.py:48-80
Auto-Memory Behavior
The MCP server is designed to operate autonomously without manual intervention.
sequenceDiagram
participant U as User
participant C as Claude
participant M as MemoraEU MCP
U->>C: First message
C->>M: recall(topic)
M-->>C: Relevant memories
C->>M: load_session_context()
M-->>C: Recent memories via memoraeu://context
Note over C: System prompt auto-injected
U->>C: Expresses preference
C->>M: remember(content, category)
M-->>C: ✅ Memorized (ID: xxx)Automatic Recall
On the first user message of each session, recall is called automatically with the detected topic as the query. Recent memories are also loaded via the memoraeu://context resource and injected as session context. Sources: README.md
Automatic Remember
When the AI 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. Sources: README.md
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. Sources: README.md
Deduplication & Compression
Before storing a memory, the MCP performs several preprocessing steps:
graph LR
A[Raw Content] --> B[Local Compression]
B --> C[Vector Similarity Check]
C -->|≥ 94%| D[Duplicate - Skip]
C -->|< 94%| E[Local Categorization]
E --> F[AES-256-GCM Encrypt]
F --> G[Send to API]Similarity Thresholds
| Similarity Score | Action |
|---|---|
| ≥ 94% | Memory ignored (exact duplicate) |
| < 94% | Proceed with storage |
Sources: README.md
Environment Variables
Five distinct variables serve different purposes—they are not interchangeable:
| Variable | Purpose | Source |
|---|---|---|
MEMORAEU_API_KEY | HTTP Bearer token for authentication | Dashboard → Settings → API Keys |
MEMORAEU_SECRET | User's login password, used as PBKDF2 input to derive the encryption key | User account password |
MEMORAEU_SALT | KDF salt unique to the account, combined with SECRET to produce the encryption key | Dashboard → Settings → Encryption Keys |
MEMORAEU_API_URL | API endpoint (use https://api.memoraeu.com for hosted service) | - |
MISTRAL_API_KEY | Generates embeddings locally before encryption (required for zero-knowledge semantic search) | Mistral Console |
Sources: README.md
Without MISTRAL_API_KEY
The MCP continues to function—remember and recall remain operational—but semantic search falls back to server-side keyword search. Zero-knowledge encryption is not affected. Sources: README.md
Encryption Details
The encryption scheme uses industry-standard practices:
| Parameter | Value | Source |
|---|---|---|
| Algorithm | AES-256-GCM | Symmetric encryption |
| Key Derivation | PBKDF2-HMAC-SHA256 | Password-based key derivation |
| Iterations | 210,000 | OWASP 2024 recommendation |
| Ciphertext Prefix | ENCv1: | Version identifier |
Sources: CHANGELOG.md
Dependencies
| Package | Version | Purpose |
|---|---|---|
mcp | ≥1.1.0, <1.2.0 | Model Context Protocol framework |
httpx | 0.28.1 | HTTP client |
python-dotenv | 1.0.1 | Environment variable loading |
starlette | ≥0.40.0, <0.42.0 | ASGI framework |
cryptography | ≥42.0.0 | Encryption primitives |
Sources: requirements.txt
Resources
The MCP server exposes the following resource:
| URI | Name | Description |
|---|---|---|
memoraeu://context | Contexte mémoire MemoraEU | Recent memories automatically injected at session start |
Sources: memoraeu_mcp/main.py:115-120
Prompts
| Name | Description |
|---|---|
memoraeu_system | MemoraEU automatic memory behavior system prompt—injectable into Claude's context |
Sources: memoraeu_mcp/main.py:137-145
Quick Start Guide
1. Create Account and Obtain Keys
- Create an account at app.memoraeu.com
- Navigate to Settings → Encryption Keys → copy
MEMORAEU_SALT MEMORAEU_SECRETis your MemoraEU login password- Navigate to Settings → API Keys → create a key → copy
MEMORAEU_API_KEY - Obtain a Mistral API key from console.mistral.ai
2. Configure Claude Desktop
Add the following to your claude_desktop_config.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"
}
}
}
}
Sources: README.md
Supported Clients
| Client | Support Type |
|---|---|
| Claude Desktop | Full STDIO support |
| Claude.ai Web | SSE remote mode |
| Cursor | SSE configuration |
| Windsurf | SSE configuration |
| Other MCP Clients | STDIO or SSE depending on client capability |
Changelog Summary
| Version | Date | Key Changes |
|---|---|---|
| 0.1.9 | 2026-05-12 | Added remember_fact, recall_facts, invalidate_fact; PBKDF2 updated to 210k iterations |
| 0.1.5 | 2026-04-28 | PBKDF2 210k iterations + ENCv1: prefix |
Sources: CHANGELOG.md
Sources: README.md
Installation Guide
Related topics: Configuration Reference, Deployment Guide
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Configuration Reference, Deployment Guide
Installation Guide
This guide covers all supported installation methods for the memoraeu-mcp server, a Model Context Protocol server that provides zero-knowledge encrypted memory capabilities for AI assistants.
Overview
memoraeu-mcp can be installed in two modes:
| Mode | Transport | Zero-Knowledge | Use Case |
|---|---|---|---|
| Local (stdio) | stdio | ✅ Full | Desktop applications (Claude Desktop, Cursor, Windsurf) |
| Remote (SSE) | SSE | ⚠️ Partial | Web clients, shared environments |
Sources: README.md
Prerequisites
Before installation, ensure you have:
- Python 3.11+ — Required for the MCP server
- uvx or pip — For package installation
- MemoraEU Account — Required for API access
- Mistral API Key — For local embedding generation (required for zero-knowledge semantic search)
Required Accounts and Keys
| Service | Purpose | Signup Location |
|---|---|---|
| MemoraEU | Memory storage and sync | app.memoraeu.com |
| Mistral AI | Local embedding generation | console.mistral.ai |
Sources: README.md
Installation Methods
Method 1: Local Installation (stdio) — Recommended
This method provides full zero-knowledge encryption where embeddings are generated locally before any data leaves your machine.
#### Step 1: Install the Package
uvx memoraeu-mcp
Or using pip:
pip install memoraeu-mcp
#### Step 2: Obtain MemoraEU Credentials
- Create an account at app.memoraeu.com
- Navigate to Settings → Encryption Keys → copy
MEMORAEU_SALT MEMORAEU_SECRETis your MemoraEU login password- Navigate to Settings → API Keys → create a key → copy
MEMORAEU_API_KEY
#### Step 3: Configure Claude Desktop
Add the following to your claude_desktop_config.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"
}
}
}
}
Sources: README.md
Method 2: Remote Installation (SSE) — Zero-Knowledge NOT Guaranteed
Use this method when you cannot install locally or need quick access from web clients.
⚠️ Security Notice: In remote SSE mode, content is not zero-knowledge encrypted. The server processes plaintext. Use local stdio installation for full zero-knowledge guarantees.
#### Configuration for Remote Clients
Configure your MCP client (Cursor, Windsurf, or any SSE-compatible client):
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
SSE Endpoint Details:
| Property | Value |
|---|---|
| Endpoint URL | https://api.memoraeu.com/mcp/sse |
| Authentication | Bearer token in Authorization header |
| API Key Format | meu-sk-xxx |
Sources: README.md
Environment Variables Reference
All configuration is done via environment variables. These five variables serve three distinct purposes — they are not interchangeable.
| Variable | Purpose | Required | Where to Get |
|---|---|---|---|
MEMORAEU_API_KEY | HTTP authentication (Bearer token sent with every request) | Yes | Dashboard → Settings → API Keys |
MEMORAEU_SECRET | Your MemoraEU login password — used as PBKDF2 input to derive the encryption key locally | Yes (local) | Your account password |
MEMORAEU_SALT | KDF salt generated by the server, unique to your account | Yes (local) | Dashboard → Settings → Encryption Keys |
MEMORAEU_API_URL | API endpoint for the hosted service | Yes | Use https://api.memoraeu.com |
MISTRAL_API_KEY | Used to generate embeddings locally before encryption | Yes (local) | console.mistral.ai |
Sources: README.md
Variable Dependency Matrix
graph TD
A[Local Installation] --> B{MISTRAL_API_KEY set?}
B -->|Yes| C[Full Zero-Knowledge Mode]
B -->|No| D[Keyword Search Fallback]
C --> E[Embeddings generated locally<br/>before encryption]
D --> F[Server-side keyword search<br/>Zero-knowledge encryption preserved]
G[Remote SSE Mode] --> H[No Local Processing<br/>Server sees plaintext]
style C fill:#90EE90
style D fill:#FFE4B5
style H fill:#FFB6C1Why is MISTRAL_API_KEY Required Locally?
The zero-knowledge architecture requires that:
- Embeddings must be calculated before encryption
- This happens on your local machine
- The MCP calls Mistral directly with plaintext
- The server receives an opaque blob + vector it cannot decrypt
Without MISTRAL_API_KEY, semantic search falls back to keyword search on the server side, but zero-knowledge encryption remains intact.
Sources: README.md
Configuration Examples by Client
Claude Desktop
{
"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"
}
}
}
}
Cursor / Windsurf (Local)
{
"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"
}
}
}
}
Cursor / Windsurf (Remote SSE)
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
Sources: README.md
Supported Transport Protocols
| Protocol | Use Case | Zero-Knowledge | Setup Complexity |
|---|---|---|---|
stdio | Local desktop apps | ✅ Full | Requires uvx/pip |
sse | Remote/web clients | ⚠️ Server sees plaintext | Quick setup |
The MCP server implements both protocols via the MCP SDK:
Sources: memoraeu_mcp/main.py
Package Dependencies
The following dependencies are required and specified in requirements.txt:
| Package | Version | Purpose |
|---|---|---|
mcp | ≥1.1.0, <1.2.0 | Model Context Protocol SDK |
httpx | 0.28.1 | HTTP client for API calls |
python-dotenv | 1.0.1 | Environment variable loading |
starlette | ≥0.40.0, <0.42.0 | ASGI framework |
cryptography | ≥42.0.0 | AES-256-GCM encryption |
Sources: requirements.txt
Installation Flow Diagram
flowchart TD
A[Start Installation] --> B{Choose Mode}
B -->|Local stdio| C[Install via uvx or pip]
B -->|Remote SSE| D[Configure client directly]
C --> E[Create MemoraEU Account]
E --> F[Get API Key & Salt]
F --> G[Get Mistral API Key]
G --> H[Configure claude_desktop_config.json]
H --> I[Verify Installation]
D --> J[Get Bearer Token]
J --> K[Configure SSE in client]
K --> L[Verify Connection]
I --> M[✅ Zero-Knowledge Ready]
L --> N[⚠️ Remote Mode Active]Verifying Installation
After installation, verify the MCP server is working by:
- Check MCP server status in your client
- Run a test command using any available tool:
list_categories— Should return an empty list or existing categorieslist_memories— Should confirm connection
Sources: README.md
Troubleshooting
| Issue | Solution |
|---|---|
| "Module not found" errors | Ensure uvx or pip installation completed successfully |
| SSE connection failures | Verify API key format is meu-sk-xxx and endpoint URL is correct |
| Semantic search not working | Check MISTRAL_API_KEY is set; falls back to keyword search if missing |
| Encryption errors | Verify MEMORAEU_SALT and MEMORAEU_SECRET are correct |
Sources: README.md
Security Architecture Summary
| Component | Location | Description |
|---|---|---|
| Encryption | Client-side | AES-256-GCM with PBKDF2-HMAC-SHA256 (100k iterations) |
| Embedding generation | Client-side | Mistral embeddings computed before encryption |
| Storage | Server-side | Opaque encrypted blobs + vectors |
| Key derivation | Client-side | Password + salt → encryption key |
Sources: CHANGELOG.md
Sources: README.md
System Architecture
Related topics: Security and Encryption, MCP Tools Reference
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Security and Encryption, MCP Tools Reference
System Architecture
Overview
The memoraeu-mcp is a Model Context Protocol (MCP) server that provides zero-knowledge memory capabilities for AI assistants. It enables automatic memorization and semantic recall of user information while maintaining end-to-end encryption where the server never sees plaintext data.
The architecture follows a client-side encryption model where all sensitive operations (compression, embedding generation, categorization, and encryption) occur locally before any data is transmitted to the remote API.
High-Level Architecture
graph TD
subgraph Client["Client Side (Local)"]
MCP["MCP Client<br/>(Claude Desktop, Cursor, etc.)"]
Tools["Tool Handlers<br/>remember, recall, forget, etc."]
Crypto["Encryption Module<br/>AES-256-GCM + PBKDF2"]
Embed["Embedding Generator<br/>(Mistral API)"]
Compress["Local Compression"]
Categorize["Local Categorization"]
end
subgraph External["External Services"]
Mistral["Mistral API<br/>(Embeddings)"]
end
subgraph Server["MemoraEU Remote API"]
API["API Endpoint<br/>api.memoraeu.com"]
Storage["Encrypted Storage"]
end
MCP --> Tools
Tools --> Crypto
Tools --> Embed
Tools --> Compress
Tools --> Categorize
Embed --> Mistral
Tools --> API
API --> Storage
style Client fill:#e1f5fe
style Server fill:#fff3e0
style External fill:#f3e5f5Component Architecture
Entry Points
The project provides multiple entry points for different deployment scenarios:
| Entry Point | Purpose | Use Case |
|---|---|---|
memoraeu_mcp/server.py | Pip/uvx installation entry | Installed via package manager |
server.py | Development/main server | Direct execution with python server.py |
| SSE Remote | Remote MCP via Server-Sent Events | Web clients without local install |
Sources: memoraeu_mcp/server.py:1-9
"""Entry point pour memoraeu-mcp installé via pip/uvx."""
import asyncio
def run():
from memoraeu_mcp.main import main
asyncio.run(main())
Core Server Module
The memoraeu_mcp/main.py file contains the complete MCP server implementation with all tool handlers, resource providers, and prompt managers.
Sources: memoraeu_mcp/main.py:1-200
MCP Protocol Implementation
Tool Registration
graph LR
A[list_tools] --> B[Tool Definitions]
B --> C[remember]
B --> D[recall]
B --> E[forget]
B --> F[list_memories]
B --> G[list_categories]
B --> H[remember_fact]
B --> I[recall_facts]
B --> J[invalidate_fact]All tools are defined using the MCP SDK Tool class with JSON schemas:
Tool(
name="remember",
description="Mémorise automatiquement une information importante...",
inputSchema={
"type": "object",
"properties": {
"content": {"type": "string"},
"category": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}}
},
"required": ["content"]
}
)
Sources: memoraeu_mcp/main.py:73-106
Available Tools
| Tool | Function | Input Parameters |
|---|---|---|
remember | Stores important information | content (required), category, tags |
recall | Semantic search across memories | query (required), limit, category |
forget | Deletes a memory by ID | memory_id (required) |
list_memories | Lists recent memories | category, limit |
list_categories | Returns categories sorted by usage | None |
remember_fact | Stores structured fact | subject, predicate, object, scope, valid_from |
recall_facts | Retrieves active facts | subject, predicate, scope, history |
invalidate_fact | Marks fact as expired | fact_id, valid_to |
Resources
The server provides a single resource URI for memory context injection:
| Resource URI | Name | Purpose |
|---|---|---|
memoraeu://context | Contexte mémoire MemoraEU | Recent memories injected automatically at session start |
Sources: memoraeu_mcp/main.py:148-165
@app.list_resources()
async def list_resources() -> list[Resource]:
return [
Resource(
uri="memoraeu://context",
name="Contexte mémoire MemoraEU",
description="Mémoires récentes injectées automatiquement en début de session",
mimeType="text/plain"
)
]
Prompts
A single system prompt is available for memory behavior injection:
| Prompt Name | Description |
|---|---|
memoraeu_system | Injects automatic memory behavior rules into Claude's context |
Sources: memoraeu_mcp/main.py:132-147
Data Flow Architecture
Memory Storage Flow
graph TD
A[User Input] --> B[remember tool]
B --> C{API Key Available?}
C -->|Yes| D[Generate Embedding via Mistral]
C -->|No| E[Skip Embedding]
D --> F[Compress Content Locally]
E --> F
F --> G[Categorize Locally]
G --> H[Check Duplicate Similarity]
H --> I{Similarity >= 94%?}
I -->|Yes| J[Ignore - Duplicate]
I -->|No| K[Encrypt Content AES-256-GCM]
K --> L[API POST /memories]
L --> M[Server Stores Encrypted Blob]Memory Retrieval Flow
graph TD
A[recall tool] --> B[First recall of session?]
B -->|Yes| C[Load Session Context]
B -->|No| D[Skip Context]
C --> E[Inject System Prompt]
D --> F[API POST /memories/search]
E --> F
F --> G[Receive Encrypted Results]
G --> H[Decrypt Content Locally]
H --> I[Return Plaintext to Client]Security Architecture
Zero-Knowledge Model
graph LR
subgraph Client["Client"]
P[Plaintext Content]
E[Encryption]
K[Key Derivation]
end
subgraph Server["Server"]
C[Encrypted Blob]
V[Vector Embedding]
end
P --> E
E --> C
P --> K
K --> E
C --> Server
V --> ServerThe security model ensures:
- Encryption before transmission - Content is encrypted locally using AES-256-GCM
- Client-side embedding - Semantic vectors are generated from plaintext before encryption
- Key derivation - PBKDF2-HMAC-SHA256 with 100,000 iterations derives encryption keys
Key Derivation Parameters
| Parameter | Variable | Source |
|---|---|---|
| Secret | MEMORAEU_SECRET | User's account password |
| Salt | MEMORAEU_SALT | Server-generated, unique per account |
| Iterations | 100,000 | Hardcoded in implementation |
Sources: memoraeu_mcp/main.py:1-50
API Authentication
Two authentication modes are supported:
| Mode | Configuration | Transport |
|---|---|---|
| Local stdio | Environment variables | Standard I/O |
| Remote SSE | Bearer token header | Server-Sent Events |
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
Configuration Architecture
Environment Variables
| Variable | Purpose | Required | Source |
|---|---|---|---|
MEMORAEU_API_URL | API endpoint | Yes | Fixed for hosted service |
MEMORAEU_API_KEY | HTTP Bearer authentication | Yes | Dashboard → Settings → API Keys |
MEMORAEU_SECRET | Password for key derivation | Yes (local) | User account password |
MEMORAEU_SALT | KDF salt | Yes (local) | Dashboard → Settings → Encryption Keys |
MISTRAL_API_KEY | Local embedding generation | Yes (zero-knowledge) | Mistral Console |
Sources: README.md:1-50
Configuration File Structure
{
"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"
}
}
}
}
Dependencies
The project depends on the following packages:
| Package | Version | Purpose |
|---|---|---|
mcp | >=1.1.0, <1.2.0 | MCP SDK framework |
httpx | 0.28.1 | HTTP client for API calls |
python-dotenv | 1.0.1 | Environment variable loading |
starlette | >=0.40.0, <0.42.0 | ASGI framework for SSE |
cryptography | >=42.0.0 | AES-256-GCM encryption |
Sources: requirements.txt:1-5
Auto-Memory Behavior System
The MCP server implements automatic memory management without manual intervention:
Automatic Recall
On the first user message of each session:
recallis called automatically with detected topic as query- Recent memories are loaded via
memoraeu://contextresource - Context is injected into the session
Automatic Remember
When Claude detects memorable information:
- Preferences
- Decisions
- Biographical facts
- Technical configurations
- Durable constraints
It calls remember autonomously with a single discreet confirmation.
System Prompt Injection
On the first recall call, the full behavior system prompt is injected:
SYSTEM_PROMPT_TEXT contains:
- Memory objectives (preferences, decisions, biographical facts)
- Automatic recall rules
- Token optimization guidelines
Deduplication System
Before storing a memory, the system checks for near-duplicates:
| Similarity Threshold | Action |
|---|---|
| ≥ 94% | Memory ignored (exact duplicate) |
| < 94% | Memory stored normally |
This prevents storage of redundant information while allowing similar but distinct memories.
Error Handling Architecture
All tool handlers follow a consistent error handling pattern:
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "remember":
try:
# Tool implementation
return [TextContent(type="text", text="✅ Success message")]
except Exception as e:
return [TextContent(type="text", text=f"❌ Error : {e}")]
This ensures all errors return user-friendly messages rather than raw exceptions.
Module Structure Summary
memoraeu_mcp/
├── main.py # Core MCP server implementation
│ ├── @app decorators (tools, resources, prompts)
│ ├── Tool handlers (remember, recall, forget, etc.)
│ ├── Encryption functions
│ ├── API communication
│ └── Local processing (compression, categorization)
└── server.py # Entry point for pip/uvx installationSources: memoraeu_mcp/server.py:1-9
Security and Encryption
Related topics: System Architecture, Configuration Reference
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: System Architecture, Configuration Reference
Security and Encryption
Overview
MemoraEU implements a zero-knowledge encryption architecture where all memory content is encrypted client-side before transmission to the server. The server never receives plaintext data or encryption keys, ensuring complete privacy of stored memories.
The system uses industry-standard cryptographic primitives:
- AES-256-GCM for authenticated encryption
- PBKDF2-HMAC-SHA256 with 210,000 iterations for key derivation
Sources: memoraeu_mcp/crypto.py:1-15
Sources: memoraeu_mcp/crypto.py:1-15
Auto-Memory System
Related topics: MCP Tools Reference, Structured Facts System
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: MCP Tools Reference, Structured Facts System
Auto-Memory System
The Auto-Memory System is a zero-knowledge, privacy-preserving memory management layer built into the MemoraEU MCP (Model Context Protocol) server. It enables AI assistants to automatically remember user preferences, decisions, biographical facts, and technical constraints across conversations without requiring manual intervention.
Overview
The system operates on a client-side encryption model where:
- All memory content is encrypted locally before transmission
- Embeddings for semantic search are computed from plaintext before encryption
- The server processes encrypted data without visibility into content
- A PBKDF2-HMAC-SHA256 key derivation scheme (210,000 iterations) protects the encryption key derived from the user's password
graph TD
A[User Message] --> B{Auto-Recall Trigger}
B --> C[Extract Topic Query]
C --> D[Semantic Search<br/>memoraeu://context]
D --> E[Load Recent Memories]
E --> F[Inject into Session Context]
G[User Expresses<br/>Preference/Fact] --> H{Auto-Remember Trigger}
H --> I[Compress Content]
I --> J[Categorize Locally]
J --> K[Generate Embedding]
K --> L{Check Duplicates<br/>Similarity ≥ 94%}
L -->|No Duplicate| M[Encrypt Content]
L -->|Duplicate Found| N[Skip Storage]
M --> O[Store Memory]Core Components
1. Automatic Recall
On the first user message of each session, the MCP server automatically triggers a recall operation using the detected topic as the search query. Sources: README.md:40-45
Behavior:
- Retrieves relevant memories via semantic search
- Loads recent memories through the
memoraeu://contextresource - Injects memories as session context automatically
- No manual invocation required
sequenceDiagram
participant U as User
participant MCP as MCP Server
participant API as MemoraEU API
participant LLM as Claude Model
U->>MCP: First Message
MCP->>MCP: Detect Topic
MCP->>API: recall(topic, limit=3)
API->>MCP: Relevant Memories
MCP->>LLM: Inject Context
MCP->>LLM: Inject System Prompt2. Automatic Remember
When the LLM detects a durable piece of information (preference, decision, biographical fact, or technical constraint), it autonomously calls the remember tool without waiting to be asked. Sources: README.md:47-52
Triggers for automatic memory:
- User expresses a preference
- User makes a decision
- User shares biographical information
- User mentions technical constraints or configurations
Confirmation: The system confirms storage with a single discreet line.
3. System Prompt Injection
On the first recall call of a session, the full behavior system prompt is injected into Claude's context. This reinforces the auto-memory rules for the remainder of the session. Sources: README.md:54-58
The system prompt includes:
## Ce qu'il faut mémoriser
- Préférences et configurations utilisateur
- Décisions et choix récurrents ou contraintes durables
- Informations techniques propres à l'utilisateur (stack, config, credentials non-sensibles)
## Rappel automatique
Dès le premier message de l'utilisateur, utilise `recall` avec le sujet détecté comme query.
N'attends pas qu'on te le demande — c'est automatique.
## Règles
- Ne mémorise pas les informations générales ou éphémères (météo du jour, blagues, calculs ponctuels)
- Si l'utilisateur dit "oublie ça" ou "ne retiens pas", utilise `forget`
- Confirme discrètement les mémorisations : une ligne, pas plus
- Optimisation tokens : limite recall à 3 résultats par défaut, mémoires compactes
Available Tools
| Tool | Description | Input Schema |
|---|---|---|
remember | Memorizes important information automatically | content, category, tags |
recall | Semantic search across stored memories | query, limit (default: 3), category |
forget | Deletes a memory by ID | memory_id |
list_memories | Lists recent memories with optional category filter | category, limit (default: 20) |
list_categories | Returns existing categories sorted by usage | — |
remember_fact | Stores structured fact with temporal validity | subject, predicate, object, valid_from, valid_to, scope |
recall_facts | Retrieves active facts for a subject | subject, predicate, scope, history |
invalidate_fact | Marks a fact as expired | fact_id, valid_to |
Tool Configuration in MCP
Tools are registered via the MCP manifest in list_tools():
Tool(
name="remember",
description=(
"Mémorise automatiquement une information importante. "
"UTILISE CET OUTIL SANS QU'ON TE LE DEMANDE dès que l'utilisateur exprime "
"une préférence, une décision, un fait biographique, une config technique, "
"ou une contrainte durable. Confirme en une ligne discrète."
),
inputSchema={
"type": "object",
"properties": {
"content": {"type": "string"},
"category": {"type": "string"},
"tags": {"type": "array", "items": {"type": "string"}}
},
"required": ["content"]
}
)
Sources: memoraeu_mcp/main.py:60-80
Data Processing Pipeline
Memory Storage Flow
graph LR
A[Content Input] --> B[Compression<br/>via Mistral]
B --> C[Category Suggestion<br/>via Mistral]
C --> D[Embedding Generation<br/>via Mistral]
D --> E{Duplicate Check<br/>Similarity ≥ 0.94?}
E -->|Similar Found| F[Skip or Warn]
E -->|No Duplicate| G[AES-256-GCM Encryption]
G --> H[API POST /memories]
H --> I[Return Memory ID]Pre-Processing Steps (Before Encryption)
The system performs several operations on plaintext before encryption: Sources: memoraeu_mcp/main.py:140-180
| Step | Description | Purpose |
|---|---|---|
| 1. Compression | Summarizes text via Mistral if > 500 chars | Token optimization |
| 2. Categorization | Suggests category using existing categories | Organization |
| 3. Embedding | Generates vector via Mistral Embed | Semantic search |
| 4. Deduplication | Checks vector similarity | Avoid storage bloat |
Local Processing Functions
async def compress_locally(content: str) -> str:
"""Compression en clair (avant chiffrement)."""
if len(content) <= COMPRESSION_THRESHOLD:
return content
prompt = (
"Résume ce texte en 1-3 phrases concises, en français, en gardant l'essentiel. "
"Réponds uniquement avec le résumé, sans introduction ni conclusion.\n\n"
f"{content}"
)
compressed = await _mistral_chat(prompt)
if compressed and len(compressed) < len(content):
return compressed
return content
Sources: memoraeu_mcp/main.py:145-160
async def suggest_category_locally(content: str, existing: list[str]) -> str:
"""Suggère une catégorie pour le contenu en clair."""
existing_str = ", ".join(existing) if existing else "aucune"
prompt = (
f"Catégories existantes : {existing_str}\n\n"
f"Texte : {content[:500]}\n\n"
"Quelle catégorie courte (1-2 mots, en français, minuscules) correspond le mieux ? "
"Utilise une existante si pertinent, sinon crée-en une. Réponds uniquement avec la catégorie."
)
cat = await _mistral_chat(prompt)
if cat:
return cat.lower().strip().strip('"').strip("'")[:30]
return "personnel"
Sources: memoraeu_mcp/main.py:162-175
Deduplication & Compression
Similarity Thresholds
Before storing a memory, the MCP checks for near-duplicates using vector similarity:
| Similarity Score | Action |
|---|---|
| ≥ 94% | Memory ignored — exact duplicate |
| < 94% | Memory stored (with warning logged) |
Sources: README.md:70-76
Duplicate Detection Implementation
async def check_duplicate(embedding: list[float]) -> dict | None:
"""
Recherche une mémoire similaire via le vecteur pré-calculé (zero-knowledge).
Retourne la mémoire existante si similarité ≥ seuil, sinon None.
"""
# Implementation checks against stored embeddings
# Returns duplicate info if similarity threshold met
Sources: memoraeu_mcp/main.py:177-185
Structured Facts System
For temporal data that changes over time, the system provides structured fact management:
Fact Data Model
{
"id": "uuid-string",
"subject": "User/Entity name",
"predicate": "property-name",
"object": "encrypted-value",
"valid_from": "YYYY-MM-DD",
"valid_to": "YYYY-MM-DD | null",
"scope": "private | org",
"supersedes": "previous-fact-id | null"
}
Temporal Validity
Facts support time-bound validity:
valid_from: Start date (defaults to today)valid_to: End date (null means currently active)- When a new fact replaces an old one,
supersedeslinks them recall_factswithhistory=Falsereturns only active facts
Sources: server.py:35-55
Resource Injection
The MCP server exposes a resource endpoint for automatic context loading:
@app.list_resources()
async def list_resources() -> list[Resource]:
return [
Resource(
uri="memoraeu://context",
name="Contexte mémoire MemoraEU",
description="Mémoires récentes injectées automatiquement en début de session",
mimeType="text/plain"
)
]
@app.read_resource()
async def read_resource(uri: str) -> list[ResourceContents]:
if uri == "memoraeu://context":
context = await load_session_context()
text = context if context else "Aucune mémoire enregistrée."
return [TextResourceContents(uri=uri, mimeType="text/plain", text=text)]
Sources: memoraeu_mcp/main.py:90-105
Session Context Loading
async def load_session_context() -> str:
"""Charge le contexte de session depuis l'API."""
try:
memories = await api_get("/memories", params={"limit": 10, "scope": "private"})
if not memories:
return ""
lines = []
for m in memories:
content = decrypt_content(m["content"])
preview = content[:100] + ("…" if len(content) > 100 else "")
lines.append(f"[{m.get('category') or '—'}] {preview}")
return "\n".join(lines)
except Exception:
return ""
Recall Flow Implementation
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
if name == "recall":
global _first_recall
is_first = _first_recall
_first_recall = False
# Load session context on first recall
context = await load_session_context()
response = await api_post("/memories/search", {
"query": arguments["query"],
"limit": arguments.get("limit", 3),
"category": arguments.get("category"),
"scope": "private"
})
results = response.get("results", [])
lines = []
# Inject system prompt only on first recall
if is_first:
lines.append(SYSTEM_PROMPT_TEXT)
lines.append("---")
# ... format results
Sources: memoraeu_mcp/main.py:220-250
Zero-Knowledge Architecture
graph TD
subgraph Client["Client (MCP)"]
A[Plaintext Content] --> B[Mistral Embedding]
A --> C[Compression]
A --> D[Categorization]
B --> E[Duplicate Check]
C --> F[AES-256-GCM Encryption]
D --> F
E -->|No Duplicate| F
end
subgraph Server["MemoraEU Server"]
G[Encrypted Payload] --> H[Store]
H --> I[Semantic Search]
G --> I
end
F --> G
I --> J[Return Encrypted Results]
J --> K[Client Decrypts]Encryption Specification
| Parameter | Value |
|---|---|
| Algorithm | AES-256-GCM |
| Key Derivation | PBKDF2-HMAC-SHA256 |
| Iterations | 210,000 (OWASP 2024) |
| Ciphertext Prefix | ENCv1: |
| Salt | Per-account, from dashboard |
Configuration Variables
| Variable | Purpose | Required |
|---|---|---|
MEMORAEU_API_KEY | HTTP Bearer authentication | Yes |
MEMORAEU_SECRET | User password for key derivation | Yes |
MEMORAEU_SALT | KDF salt from dashboard | Yes |
MEMORAEU_API_URL | API endpoint (default: https://api.memoraeu.com) | Yes |
MISTRAL_API_KEY | Embedding generation | Yes |
Sources: README.md:95-115
Dependencies
| Package | Version | Purpose |
|---|---|---|
mcp | ≥1.1.0, <1.2.0 | MCP protocol implementation |
httpx | 0.28.1 | HTTP client |
python-dotenv | 1.0.1 | Environment configuration |
starlette | ≥0.40.0, <0.42.0 | Web framework |
cryptography | ≥42.0.0 | AES encryption |
Sources: requirements.txt:1-5
Version History
| Version | Date | Changes |
|---|---|---|
| 0.1.9 | 2026-05-12 | Added remember_fact, recall_facts, invalidate_fact; PBKDF2 210k iterations |
| 0.1.5 | 2026-04-28 | Added ENCv1: prefix; deduplication threshold refinement |
Sources: CHANGELOG.md:1-30
Sources: memoraeu_mcp/main.py:60-80
Deduplication and Compression
Related topics: Auto-Memory System, Security and Encryption
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Auto-Memory System, Security and Encryption
Deduplication and Compression
The MemoraEU MCP server implements intelligent data optimization through two complementary mechanisms: compression and deduplication. These features operate on plaintext data locally before encryption, ensuring that only processed, non-redundant information is transmitted to the server.
Overview
MemoraEU's optimization pipeline runs entirely on the client side before any data leaves the user's machine. This approach provides several benefits:
- Token efficiency: Reduced payload sizes minimize API costs and response times
- Bandwidth optimization: Less data transmitted over the network
- Storage savings: Server-side storage requirements are reduced
- Zero-knowledge preservation: Compression and deduplication occur before encryption, maintaining the security model
Compression System
Purpose and Scope
The compression system applies text summarization to memory content that exceeds a configurable length threshold. Unlike generic compression algorithms, this system uses LLM-based summarization to distill essential information into concise, human-readable summaries.
Sources: memoraeu_mcp/main.py:1-200
Compression Threshold
| Parameter | Description | Default Value |
|---|---|---|
COMPRESSION_THRESHOLD | Minimum content length to trigger compression | Configurable in source |
The compression logic follows a decision tree:
graph TD
A[New Memory Content] --> B{Content Length > Threshold?}
B -->|No| C[Return Original Content]
B -->|Yes| D[Call Mistral Chat API]
D --> E{Summary Shorter Than Original?}
E -->|Yes| F[Return Compressed Summary]
E -->|No| CSources: memoraeu_mcp/main.py
The `compress_locally` Function
The compression function compress_locally() implements the following workflow:
- Threshold Check: Only processes content exceeding
COMPRESSION_THRESHOLDcharacters - Prompt Engineering: Sends the content to Mistral Chat with a French-language summarization prompt
- Validation: Accepts the summary only if it's shorter than the original
- Fallback: Returns original content if compression doesn't yield improvement
async def compress_locally(content: str) -> str:
"""Compress content locally before encryption."""
if len(content) <= COMPRESSION_THRESHOLD:
return content
prompt = (
"Résume ce texte en 1-3 phrases concises, en français, en gardant l'essentiel. "
"Réponds uniquement avec le résumé, sans introduction ni conclusion.\n\n"
f"{content}"
)
compressed = await _mistral_chat(prompt)
if compressed and len(compressed) < len(content):
print(f"[mcp] Compression: {len(content)} → {len(compressed)} chars", file=sys.stderr)
return compressed
return content
Sources: memoraeu_mcp/main.py
Integration with `remember` Tool
Compression is automatically applied during the remember tool execution:
sequenceDiagram
participant User
participant MCP as MCP Server
participant Mistral as Mistral API
User->>MCP: remember(content)
MCP->>MCP: compress_locally(content)
MCP->>Mistral: Summarization Request
Mistral-->>MCP: Compressed Summary
MCP->>MCP: encrypt_content()
MCP->>MCP: api_post("/memories")Sources: memoraeu_mcp/main.py and server.py
Deduplication System
Purpose and Scope
The deduplication system prevents storing near-identical memories by comparing content embeddings before storage. This feature uses vector similarity to detect duplicates while maintaining zero-knowledge guarantees.
Sources: README.md and CHANGELOG.md
Similarity Thresholds
| Similarity Score | Action |
|---|---|
| ≥ 94% (0.94) | Memory ignored — exact duplicate |
| < 94% | Memory stored with warning logged |
Sources: README.md
The `check_duplicate` Function
The check_duplicate() function searches for similar memories using pre-computed vector embeddings:
async def check_duplicate(embedding: list[float]) -> dict | None:
"""
Recherche une mémoire similaire via le vecteur pré-calculé (zero-knowledge).
Retourne la mémoire la plus similaire si le seuil est dépassé.
"""
Sources: memoraeu_mcp/main.py
Zero-Knowledge Embedding Model
Embeddings are computed from plaintext content locally using the Mistral Embed API before any encryption occurs. This ensures the server never receives unencrypted content or embeddings derived from it.
graph LR
A[Plaintext Content] -->|Before Encryption| B[Mistral Embed API]
B --> C[Embedding Vector]
C --> D[check_duplicate]
A -->|After Encryption| E[Encrypted Content]
E --> F[Server Storage]
style B fill:#90EE90
style D fill:#FFE4B5Sources: CHANGELOG.md and memoraeu_mcp/main.py
Deduplication Workflow
graph TD
A[New Memory] --> B[Generate Embedding]
B --> C[Call check_duplicate]
C --> D{Similar Memory Found?}
D -->|No| E[Store Memory Normally]
D -->|Yes| F{Score >= 94%?}
F -->|Yes| G[Skip - Show Duplicate Warning]
F -->|No| H[Log Warning - Store Anyway]
G --> I[Display Existing Memory ID]
H --> ESources: memoraeu_mcp/main.py and server.py
Duplicate Detection Response
When a duplicate is detected, the system returns a formatted warning message:
⚠️ Doublon détecté (95% similaire) — mémoire non créée.
→ Existante : [memory preview] (ID: abc12345...)
Sources: server.py
Processing Pipeline
The complete optimization pipeline executes in the following order during the remember operation:
flowchart LR
subgraph Phase1["Phase 1: Pre-Encryption Processing"]
A1[Raw Content] --> B1[Compression<br/>compress_locally]
B1 --> C1[Categorization<br/>suggest_category_locally]
C1 --> D1[Embedding<br/>embed_locally]
end
subgraph Phase2["Phase 2: Deduplication Check"]
D1 --> E1[check_duplicate]
E1 --> F1{Skip?}
end
subgraph Phase3["Phase 3: Encryption & Storage"]
F1 -->|No| G1[encrypt_content]
G1 --> H1[api_post /memories]
end
F1 -->|Yes| I1[Return Duplicate Warning]Sources: memoraeu_mcp/main.py
Dependencies
The optimization features depend on the following packages:
| Package | Version | Purpose |
|---|---|---|
httpx | 0.28.1 | Async HTTP client for Mistral API calls |
starlette | ≥0.40.0,<0.42.0 | Web framework components |
cryptography | ≥42.0.0 | Encryption primitives |
python-dotenv | 1.0.1 | Environment variable management |
Sources: requirements.txt
Configuration Variables
The system uses environment variables for Mistral API integration:
| Variable | Purpose | Required |
|---|---|---|
MISTRAL_API_KEY | Authentication for Mistral Embed and Chat APIs | Yes (for stdio install) |
MEMORAEU_API_KEY | MemoraEU API authentication | Yes |
MEMORAEU_SECRET | Password for key derivation | Yes (stdio) |
MEMORAEU_SALT | KDF salt for encryption | Yes (stdio) |
Sources: README.md
Version History
| Version | Date | Changes |
|---|---|---|
| 0.1.9 | 2026-05-12 | PBKDF2 updated to 210,000 iterations, ENCv1: prefix added |
| 0.1.5 | 2026-04-28 | PBKDF2 updated to 210k iterations, refactoring |
| Initial | — | Near-duplicate detection with 0.94 threshold |
Sources: CHANGELOG.md
Security Considerations
Zero-Knowledge Guarantee
The optimization pipeline preserves zero-knowledge encryption by:
- Embedding before encryption: Vector embeddings are computed from plaintext locally
- Compression before encryption: Summarization occurs on plaintext content
- Local-only processing: All LLM calls (Mistral) happen client-side
- Server receives encrypted data: Only encrypted content and pre-computed embeddings travel to the server
Limitations
- Compression quality depends on Mistral model's summarization capabilities
- Deduplication threshold (94%) is fixed and not configurable at runtime
- Similarity search requires pre-computed embeddings, which must be generated during initial storage
Source: https://github.com/pquattro/memoraeu-mcp / Human Manual
Structured Facts System
Related topics: MCP Tools Reference, Auto-Memory System
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: MCP Tools Reference, Auto-Memory System
Structured Facts System
The Structured Facts System is a feature within the MemoraEU MCP server that provides persistent, temporally-validated knowledge storage. Unlike free-form memories, structured facts use a subject-predicate-object (SPO) pattern commonly found in knowledge graphs, enabling precise entity state tracking with automatic validity periods.
Overview
Traditional memory tools store unstructured text that must be parsed semantically. The Structured Facts System introduces typed, queryable assertions about entities with built-in temporal semantics:
- Subject: The entity being described (e.g., "Project Alpha")
- Predicate: The property or relation (e.g., "status", "manager")
- Object: The value or target (e.g., "active", "John Doe")
- Validity Period: Time-bounded truth (from/to dates)
Sources: CHANGELOG.md:12-14
graph TD
subgraph "Structured Facts Architecture"
A[User Query] --> B[recall_facts]
B --> C[API GET /facts]
D[New Fact] --> E[remember_fact]
E --> F[Client Encryption]
F --> G[API POST /facts]
G --> H[(Encrypted Storage)]
C --> I[Decrypt & Filter]
I --> J[Active Facts Only]
K[Expired Fact] --> L[invalidate_fact]
L --> M[API PUT /facts/:id]
endData Model
Each structured fact follows this schema:
| Field | Type | Required | Description |
|---|---|---|---|
id | UUID | Auto | Unique fact identifier |
subject | string | Yes | Entity being described |
predicate | string | Yes | Property or relation name |
object | string | Yes | Encrypted value (E2E) |
scope | enum | No | private (default) or org |
valid_from | date | Auto | When fact became true |
valid_to | date | No | When fact ceased to be true |
supersedes | UUID | Auto | Previous fact ID this replaces |
Sources: memoraeu_mcp/main.py:60-75
Fact Validity States
stateDiagram-v2
[*] --> Active: valid_from <= today
Active --> Expired: invalidate_fact called
Active --> Superseded: remember_fact same subject+predicate
Expired --> [*]
Superseded --> [*]
state Active {
[*] --> Current
}MCP Tools
remember_fact
Stores a structured fact with automatic encryption and temporal tracking.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
subject | string | Yes | Entity name |
predicate | string | Yes | Property name |
object | string | Yes | Value (encrypted before storage) |
scope | string | No | private or org (default: private) |
valid_from | string | No | Start date YYYY-MM-DD |
Response Format:
✅ Fait mémorisé 🔒 (remplace {id}…)
{subject} → {predicate}
Depuis: {valid_from} | ID: {id}…
Key Behaviors:
- Encryption:
objectvalue is encrypted client-side before transmission - Auto-supersession: If a fact with the same
subject+predicateexists, the new fact automatically replaces it (old one marked invalid viasupersedesfield) - Timestamp:
valid_fromdefaults to today if not specified
Sources: memoraeu_mcp/main.py:76-106
recall_facts
Retrieves active facts for a specific subject entity.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
subject | string | Yes | Entity to query |
predicate | string | No | Filter by specific property |
scope | string | No | private or org (default: private) |
history | boolean | No | Include expired facts (default: false) |
Response Format:
📊 {count} fait(s) pour '{subject}' :
• {predicate}: {decrypted_value}
[{valid_from} → {valid_to}] | ID: {id}…
Sources: memoraeu_mcp/main.py:107-136
invalidate_fact
Marks a fact as expired, indicating the information is no longer true.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
fact_id | string | Yes | UUID of fact to expire |
valid_to | string | No | End date YYYY-MM-DD (default: today) |
Behavior:
- Sets
valid_toto specified date or current date - Expired facts are excluded from default
recall_factsqueries - Use
history=trueinrecall_factsto see expired facts
Sources: memoraeu_mcp/main.py:137-152
Workflows
Creating a New Fact
sequenceDiagram
participant U as User/Claude
participant M as MCP Server
participant C as Crypto Layer
participant A as MemoraEU API
U->>M: remember_fact(subject, predicate, object)
M->>C: encrypt_content(object)
C-->>M: encrypted_blob
M->>M: Check for existing fact (same subject+predicate)
M->>A: POST /facts {subject, predicate, encrypted_blob, scope}
A->>A: Set valid_from=today
A->>A: Mark old fact as superseded
A-->>M: {id, supersedes, valid_from}
M-->>U: Confirmation with IDQuerying Facts
sequenceDiagram
participant U as User/Claude
participant M as MCP Server
participant A as MemoraEU API
participant C as Crypto Layer
U->>M: recall_facts(subject, history=false)
M->>A: GET /facts?subject={subject}
A-->>M: [facts with valid_to=null]
M->>C: decrypt_content(facts[].object)
C-->>M: decrypted_values
M-->>U: Active facts onlySecurity Model
All structured facts leverage the same zero-knowledge encryption as regular memories:
| Layer | Implementation |
|---|---|
| Key Derivation | PBKDF2-HMAC-SHA256, 210,000 iterations (OWASP 2024) |
| Symmetric Cipher | AES-256-GCM |
| Ciphertext Format | ENCv1:{base64_ciphertext} |
Sources: CHANGELOG.md:18-19
Encryption Flow for Facts:
objectvalue encrypted client-side before API transmissionsubjectandpredicatetransmitted in plaintext (used for routing/indexing)- Server never sees decrypted values
# From memoraeu_mcp/main.py:78-79
encrypted_object = encrypt_content(arguments["object"])
payload = {
"subject": arguments["subject"],
"predicate": arguments["predicate"],
"object": encrypted_object,
...
}
Use Cases
Preference Tracking
remember_fact(subject="Alice", predicate="preferred_language", object="French")
Status Changes
remember_fact(subject="Project X", predicate="status", object="completed", valid_from="2024-01-15")
Configuration State
remember_fact(subject="dev-environment", predicate="python_version", object="3.12.1")
Relationship Management
remember_fact(subject="Team Alpha", predicate="lead", object="[email protected]")
Comparison with Regular Memories
| Aspect | Regular Memory | Structured Facts |
|---|---|---|
| Content | Free-form text | Subject-predicate-object |
| Query | Semantic search | Entity-based retrieval |
| Deduplication | Vector similarity ≥94% | Auto-supersession by predicate |
| Temporal | Implicit | Explicit valid_from/valid_to |
| Use Case | Context, preferences, notes | Entity state, relationships |
Sources: README.md:34-45
Configuration
Structured Facts require no additional configuration beyond the base MCP server setup:
| Variable | Purpose | Required |
|---|---|---|
MEMORAEU_API_KEY | Bearer token authentication | Yes |
MEMORAEU_SECRET | Password for PBKDF2 key derivation | Yes (for encryption) |
MEMORAEU_SALT | KDF salt from server | Yes (for encryption) |
MEMORAEU_API_URL | API endpoint | Yes |
MISTRAL_API_KEY | Embedding generation | Yes (stdio mode) |
Sources: README.md:60-74
Implementation Notes
Duplicate Detection Strategy
Unlike regular memories which use vector similarity thresholds, structured facts handle duplicates through predicate-based supersession:
Same subject + Same predicate = Automatic supersession
Same subject + Different predicate = Distinct facts (no conflict)
API Endpoints Used
| Tool | Endpoint | Method |
|---|---|---|
remember_fact | /facts | POST |
recall_facts | /facts | GET |
invalidate_fact | /facts/{id} | PUT |
Response Formatting
The system uses emoji indicators in responses:
- 🔒 — Indicates content is encrypted
- 📝 — Indicates content is unencrypted (no key configured)
- 📊 — Prefixed fact list headers
Sources: memoraeu_mcp/main.py:93-98
Version History
| Version | Date | Changes |
|---|---|---|
| 0.1.9 | 2026-05-12 | Initial structured facts release: remember_fact, recall_facts, invalidate_fact |
Sources: CHANGELOG.md:10-15
Sources: CHANGELOG.md:12-14
MCP Tools Reference
Related topics: Auto-Memory System, Structured Facts System
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Auto-Memory System, Structured Facts System
MCP Tools Reference
Overview
The memoraeu-mcp project exposes a comprehensive set of MCP (Model Context Protocol) tools that enable AI assistants to persistently store, retrieve, and manage semantic memories. The MCP server acts as a bridge between the AI client and the MemoraEU cloud API, providing zero-knowledge encrypted storage with local pre-processing capabilities.
Sources: requirements.txt:1
Key Capabilities:
- Semantic memory storage with automatic categorization
- Structured fact management with temporal validity
- Client-side encryption using AES-256-GCM
- Near-duplicate detection before storage
- Automatic context injection on session start
Sources: README.md
Source: https://github.com/pquattro/memoraeu-mcp / Human Manual
Configuration Reference
Related topics: Installation Guide, Security and Encryption
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Installation Guide, Security and Encryption
Configuration Reference
This page provides comprehensive documentation for configuring the MemoraEU MCP (Model Context Protocol) server. It covers environment variables, MCP client configuration, zero-knowledge encryption setup, and tool-specific parameters.
Source: https://github.com/pquattro/memoraeu-mcp / Human Manual
Deployment Guide
Related topics: Installation Guide, Configuration Reference
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Continue reading this section for the full explanation and source context.
Related Pages
Related topics: Installation Guide, Configuration Reference
Deployment Guide
This guide covers all deployment scenarios for the memoraeu-mcp Model Context Protocol server, including local stdio installations for zero-knowledge encryption guarantees and remote SSE connections for quick setup without local dependencies.
Overview
memoraeu-mcp is an MCP server that enables semantic memory management with client-side AES-256-GCM encryption. The server supports two deployment modes:
| Deployment Mode | Use Case | Encryption | Setup Complexity |
|---|---|---|---|
| Local (stdio) | Full zero-knowledge guarantees | Client-side, server never sees plaintext | Higher |
| Remote (SSE) | Quick testing, no install | Server processes plaintext | Minimal |
Sources: README.md
Prerequisites
Before deploying, ensure you have:
- Python 3.10+ with
uvxor pip access - API Keys: MemoraEU account, Mistral API key for embeddings
- MCP-compatible client: Claude Desktop, Cursor, Windsurf, or any MCP client
Python Dependencies
mcp>=1.1.0,<1.2.0
httpx==0.28.1
python-dotenv==1.0.1
starlette>=0.40.0,<0.42.0
cryptography>=42.0.0
Sources: requirements.txt
Local Deployment (stdio)
The stdio mode provides complete zero-knowledge encryption. All content is encrypted on the client before transmission.
Architecture
graph TD
subgraph "Client Machine"
A[MCP Client] -->|stdio| B[memoraeu-mcp]
B --> C[Mistral API]
B -->|Encrypt| D[Encrypted Payload]
end
D -->|AES-256-GCM| E[MemoraEU API]
C -->|Embedding| B
style A fill:#e1f5fe
style E fill:#fff3e0
style D fill:#f3e5f5Configuration Steps
#### 1. Create Claude Desktop Configuration
Edit your Claude Desktop config file:
| OS | Config Location |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
#### 2. Add Server Configuration
{
"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"
}
}
}
}
Sources: README.md
Environment Variables Reference
| Variable | Purpose | Required | Source |
|---|---|---|---|
MEMORAEU_API_KEY | HTTP Bearer authentication | Yes | Dashboard → Settings → API Keys |
MEMORAEU_SECRET | PBKDF2 password input for key derivation | Yes | Your MemoraEU login password |
MEMORAEU_SALT | KDF salt unique to your account | Yes | Dashboard → Settings → Encryption Keys |
MEMORAEU_API_URL | API endpoint | Yes | Use https://api.memoraeu.com for hosted |
MISTRAL_API_KEY | Local embedding generation | Yes* | Mistral Console |
*Without MISTRAL_API_KEY, semantic search falls back to server-side keyword matching.
Sources: README.md
Why Local Embeddings?
The zero-knowledge architecture requires embeddings to be computed before encryption:
sequenceDiagram
participant User
participant MCP as memoraeu-mcp
participant Mistral
participant Server
User->>MCP: remember("I prefer dark mode")
MCP->>Mistral: Generate embedding
Mistral-->>MCP: Embedding vector
MCP->>MCP: AES-256-GCM encrypt content
MCP->>Server: Encrypted content + embedding
Note over Server: Never sees plaintextSources: README.md
Remote Deployment (SSE)
SSE mode connects directly to the hosted MemoraEU MCP endpoint without local installation.
Configuration for Cursor/Windsurf
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
Sources: README.md
SSE Endpoint Details
| Property | Value |
|---|---|
| Protocol | Server-Sent Events (SSE) |
| Endpoint | https://api.memoraeu.com/mcp/sse |
| Authentication | Bearer token in header |
| Encryption | Not zero-knowledge* |
Warning: In remote SSE mode, content is processed as plaintext by the server. Use local stdio installation for zero-knowledge guarantees.
Sources: README.md
Obtaining Credentials
Follow these steps to obtain all required credentials:
Step 1: MemoraEU Account
- Create account at app.memoraeu.com
Step 2: Get Encryption Salt
- Go to Settings → Encryption Keys
- Copy the
MEMORAEU_SALTvalue
Step 3: Set Secret
MEMORAEU_SECRETis your MemoraEU login password- Used as PBKDF2 input to derive encryption key
Step 4: Get API Key
- Go to Settings → API Keys
- Create a new key
- Copy the
MEMORAEU_API_KEY(format:meu-sk-xxx)
Step 5: Get Mistral API Key
- Obtain key at console.mistral.ai
- Required for local embedding generation
Sources: README.md
Security Considerations
Encryption Implementation
| Aspect | Detail |
|---|---|
| Algorithm | AES-256-GCM |
| Key Derivation | PBKDF2-HMAC-SHA256 |
| Iterations | 210,000 (OWASP 2024 recommendation) |
| Ciphertext Prefix | ENCv1: |
| Salt | Server-generated, unique per account |
Sources: CHANGELOG.md
Security Comparison
| Feature | stdio (Local) | SSE (Remote) |
|---|---|---|
| Zero-knowledge | ✅ Yes | ❌ No |
| Embeddings | Local (via Mistral) | Server-processed |
| Content encryption | Client-side | Server-side |
| PBKDF2 iterations | 210,000 | 210,000 |
Sources: README.md
Available MCP Tools
Once deployed, the following tools are available:
| Tool | Description |
|---|---|
remember | Automatically memorize important information |
recall | Semantic search across stored memories |
forget | Delete a memory by ID |
list_memories | List recent memories with optional category filter |
list_categories | Return existing categories sorted by usage |
remember_fact | Store structured fact with temporal validity |
recall_facts | Retrieve active facts for a subject |
invalidate_fact | Mark a fact as expired |
Sources: memoraeu_mcp/main.py
Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
MISTRAL_API_KEY missing | MCP continues working but semantic search falls back to keyword matching |
| Authentication failed | Verify MEMORAEU_API_KEY format is meu-sk-xxx |
| Encryption errors | Ensure MEMORAEU_SECRET and MEMORAEU_SALT are correct |
| stdio connection refused | Restart Claude Desktop after config changes |
Verification Steps
- Check config file syntax is valid JSON
- Verify all required environment variables are set
- Confirm API keys are active in MemoraEU dashboard
- Restart the MCP client after configuration changes
Version History
| Version | Date | Key Changes |
|---|---|---|
| 0.1.9 | 2026-05-12 | Added fact tools, PBKDF2 210k iterations, ENCv1 prefix |
| 0.1.5 | 2026-04-28 | Initial fact support, PBKDF2 updates |
Sources: CHANGELOG.md
Sources: README.md
Doramagic Pitfall Log
Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.
Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
The project should not be treated as fully validated until this signal is reviewed.
Users cannot judge support quality until recent activity, releases, and issue response are checked.
The project may affect permissions, credentials, data exposure, or host boundaries.
Doramagic Pitfall Log
Doramagic extracted 7 source-linked risk signals. Review them before installing or handing real data to the project.
1. Configuration risk: Configuration risk needs validation
- Severity: medium
- Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
- User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
- Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
- Evidence: capability.host_targets | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | host_targets=mcp_host, claude
2. Capability assumption: README/documentation is current enough for a first validation pass.
- Severity: medium
- Finding: README/documentation is current enough for a first validation pass.
- User impact: The project should not be treated as fully validated until this signal is reviewed.
- Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
- Evidence: capability.assumptions | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | README/documentation is current enough for a first validation pass.
3. Maintenance risk: Maintainer activity is unknown
- Severity: medium
- Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
- User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
- Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | last_activity_observed missing
4. Security or permission risk: no_demo
- Severity: medium
- Finding: no_demo
- User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
- Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
- Evidence: downstream_validation.risk_items | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium
5. Security or permission risk: no_demo
- Severity: medium
- Finding: no_demo
- User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
- Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
- Evidence: risks.scoring_risks | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium
6. Maintenance risk: issue_or_pr_quality=unknown
- Severity: low
- Finding: issue_or_pr_quality=unknown。
- User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
- Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | issue_or_pr_quality=unknown
7. Maintenance risk: release_recency=unknown
- Severity: low
- Finding: release_recency=unknown。
- User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
- Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | release_recency=unknown
Source: Doramagic discovery, validation, and Project Pack records
Community Discussion Evidence
These external discussion links are review inputs, not standalone proof that the project is production-ready.
Count of project-level external discussion links exposed on this manual page.
Open the linked issues or discussions before treating the pack as ready for your environment.
Community Discussion Evidence
Doramagic exposes project-level community discussion separately from official documentation. Review these links before using memoraeu-mcp with real data or production workflows.
- Configuration risk needs validation - GitHub / issue
Source: Project Pack community evidence and pitfall evidence