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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Security Model

Continue reading this section for the full explanation and source context.

Section STDIO Mode (Zero-Knowledge)

Continue reading this section for the full explanation and source context.

Section SSE Mode (Remote)

Continue reading this section for the full explanation and source context.

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:#99ff99

Security Model

The zero-knowledge architecture ensures that all sensitive processing occurs client-side:

ComponentLocationData Handled
Embedding GenerationLocal (MCP server)Plaintext content
CompressionLocalPlaintext content
CategorizationLocalPlaintext content
EncryptionLocal (AES-256-GCM)Plaintext → Ciphertext
StorageRemote (MemoraEU Cloud)Encrypted blobs + vectors
SearchHybridVector 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

ToolDescriptionRequired Parameters
rememberAutomatically memorizes important information when user expresses preferences, decisions, biographical facts, or technical configscontent
recallSemantic search across stored memories using vector similarityquery
forgetDeletes a memory by its IDmemory_id
list_memoriesLists recent memories with optional category filter-
list_categoriesReturns existing categories sorted by usage-

Sources: memoraeu_mcp/main.py:48-110

Fact Tools

ToolDescriptionRequired Parameters
remember_factStores a structured fact with temporal validity (subject/predicate/object)subject, predicate, object
recall_factsRetrieves active facts for a given subjectsubject
invalidate_factMarks a fact as expired by its IDfact_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 -->|&#60; 94%| E[Local Categorization]
    E --> F[AES-256-GCM Encrypt]
    F --> G[Send to API]

Similarity Thresholds

Similarity ScoreAction
≥ 94%Memory ignored (exact duplicate)
< 94%Proceed with storage

Sources: README.md

Environment Variables

Five distinct variables serve different purposes—they are not interchangeable:

VariablePurposeSource
MEMORAEU_API_KEYHTTP Bearer token for authenticationDashboard → Settings → API Keys
MEMORAEU_SECRETUser's login password, used as PBKDF2 input to derive the encryption keyUser account password
MEMORAEU_SALTKDF salt unique to the account, combined with SECRET to produce the encryption keyDashboard → Settings → Encryption Keys
MEMORAEU_API_URLAPI endpoint (use https://api.memoraeu.com for hosted service)-
MISTRAL_API_KEYGenerates 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:

ParameterValueSource
AlgorithmAES-256-GCMSymmetric encryption
Key DerivationPBKDF2-HMAC-SHA256Password-based key derivation
Iterations210,000OWASP 2024 recommendation
Ciphertext PrefixENCv1:Version identifier

Sources: CHANGELOG.md

Dependencies

PackageVersionPurpose
mcp≥1.1.0, <1.2.0Model Context Protocol framework
httpx0.28.1HTTP client
python-dotenv1.0.1Environment variable loading
starlette≥0.40.0, <0.42.0ASGI framework
cryptography≥42.0.0Encryption primitives

Sources: requirements.txt

Resources

The MCP server exposes the following resource:

URINameDescription
memoraeu://contextContexte mémoire MemoraEURecent memories automatically injected at session start

Sources: memoraeu_mcp/main.py:115-120

Prompts

NameDescription
memoraeu_systemMemoraEU 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

  1. Create an account at app.memoraeu.com
  2. Navigate to Settings → Encryption Keys → copy MEMORAEU_SALT
  3. MEMORAEU_SECRET is your MemoraEU login password
  4. Navigate to Settings → API Keys → create a key → copy MEMORAEU_API_KEY
  5. 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

ClientSupport Type
Claude DesktopFull STDIO support
Claude.ai WebSSE remote mode
CursorSSE configuration
WindsurfSSE configuration
Other MCP ClientsSTDIO or SSE depending on client capability

Changelog Summary

VersionDateKey Changes
0.1.92026-05-12Added remember_fact, recall_facts, invalidate_fact; PBKDF2 updated to 210k iterations
0.1.52026-04-28PBKDF2 210k iterations + ENCv1: prefix

Sources: CHANGELOG.md

Sources: README.md

Installation Guide

Related topics: Configuration Reference, Deployment Guide

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Required Accounts and Keys

Continue reading this section for the full explanation and source context.

Section Method 1: Local Installation (stdio) — Recommended

Continue reading this section for the full explanation and source context.

Section Method 2: Remote Installation (SSE) — Zero-Knowledge NOT Guaranteed

Continue reading this section for the full explanation and source context.

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:

ModeTransportZero-KnowledgeUse Case
Local (stdio)stdio✅ FullDesktop applications (Claude Desktop, Cursor, Windsurf)
Remote (SSE)SSE⚠️ PartialWeb 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

ServicePurposeSignup Location
MemoraEUMemory storage and syncapp.memoraeu.com
Mistral AILocal embedding generationconsole.mistral.ai

Sources: README.md

Installation Methods

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

  1. Create an account at app.memoraeu.com
  2. Navigate to Settings → Encryption Keys → copy MEMORAEU_SALT
  3. MEMORAEU_SECRET is your MemoraEU login password
  4. 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:

PropertyValue
Endpoint URLhttps://api.memoraeu.com/mcp/sse
AuthenticationBearer token in Authorization header
API Key Formatmeu-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.

VariablePurposeRequiredWhere to Get
MEMORAEU_API_KEYHTTP authentication (Bearer token sent with every request)YesDashboard → Settings → API Keys
MEMORAEU_SECRETYour MemoraEU login password — used as PBKDF2 input to derive the encryption key locallyYes (local)Your account password
MEMORAEU_SALTKDF salt generated by the server, unique to your accountYes (local)Dashboard → Settings → Encryption Keys
MEMORAEU_API_URLAPI endpoint for the hosted serviceYesUse https://api.memoraeu.com
MISTRAL_API_KEYUsed to generate embeddings locally before encryptionYes (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:#FFB6C1

Why is MISTRAL_API_KEY Required Locally?

The zero-knowledge architecture requires that:

  1. Embeddings must be calculated before encryption
  2. This happens on your local machine
  3. The MCP calls Mistral directly with plaintext
  4. 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

ProtocolUse CaseZero-KnowledgeSetup Complexity
stdioLocal desktop apps✅ FullRequires uvx/pip
sseRemote/web clients⚠️ Server sees plaintextQuick 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:

PackageVersionPurpose
mcp≥1.1.0, <1.2.0Model Context Protocol SDK
httpx0.28.1HTTP client for API calls
python-dotenv1.0.1Environment variable loading
starlette≥0.40.0, <0.42.0ASGI framework
cryptography≥42.0.0AES-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:

  1. Check MCP server status in your client
  2. Run a test command using any available tool:
  • list_categories — Should return an empty list or existing categories
  • list_memories — Should confirm connection

Sources: README.md

Troubleshooting

IssueSolution
"Module not found" errorsEnsure uvx or pip installation completed successfully
SSE connection failuresVerify API key format is meu-sk-xxx and endpoint URL is correct
Semantic search not workingCheck MISTRAL_API_KEY is set; falls back to keyword search if missing
Encryption errorsVerify MEMORAEU_SALT and MEMORAEU_SECRET are correct

Sources: README.md

Security Architecture Summary

ComponentLocationDescription
EncryptionClient-sideAES-256-GCM with PBKDF2-HMAC-SHA256 (100k iterations)
Embedding generationClient-sideMistral embeddings computed before encryption
StorageServer-sideOpaque encrypted blobs + vectors
Key derivationClient-sidePassword + salt → encryption key

Sources: CHANGELOG.md

Sources: README.md

System Architecture

Related topics: Security and Encryption, MCP Tools Reference

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Entry Points

Continue reading this section for the full explanation and source context.

Section Core Server Module

Continue reading this section for the full explanation and source context.

Section Tool Registration

Continue reading this section for the full explanation and source context.

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:#f3e5f5

Component Architecture

Entry Points

The project provides multiple entry points for different deployment scenarios:

Entry PointPurposeUse Case
memoraeu_mcp/server.pyPip/uvx installation entryInstalled via package manager
server.pyDevelopment/main serverDirect execution with python server.py
SSE RemoteRemote MCP via Server-Sent EventsWeb 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

ToolFunctionInput Parameters
rememberStores important informationcontent (required), category, tags
recallSemantic search across memoriesquery (required), limit, category
forgetDeletes a memory by IDmemory_id (required)
list_memoriesLists recent memoriescategory, limit
list_categoriesReturns categories sorted by usageNone
remember_factStores structured factsubject, predicate, object, scope, valid_from
recall_factsRetrieves active factssubject, predicate, scope, history
invalidate_factMarks fact as expiredfact_id, valid_to

Resources

The server provides a single resource URI for memory context injection:

Resource URINamePurpose
memoraeu://contextContexte mémoire MemoraEURecent 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 NameDescription
memoraeu_systemInjects 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 --> Server

The security model ensures:

  1. Encryption before transmission - Content is encrypted locally using AES-256-GCM
  2. Client-side embedding - Semantic vectors are generated from plaintext before encryption
  3. Key derivation - PBKDF2-HMAC-SHA256 with 100,000 iterations derives encryption keys

Key Derivation Parameters

ParameterVariableSource
SecretMEMORAEU_SECRETUser's account password
SaltMEMORAEU_SALTServer-generated, unique per account
Iterations100,000Hardcoded in implementation

Sources: memoraeu_mcp/main.py:1-50

API Authentication

Two authentication modes are supported:

ModeConfigurationTransport
Local stdioEnvironment variablesStandard I/O
Remote SSEBearer token headerServer-Sent Events
{
  "mcpServers": {
    "memoraeu": {
      "type": "sse",
      "url": "https://api.memoraeu.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer meu-sk-..."
      }
    }
  }
}

Configuration Architecture

Environment Variables

VariablePurposeRequiredSource
MEMORAEU_API_URLAPI endpointYesFixed for hosted service
MEMORAEU_API_KEYHTTP Bearer authenticationYesDashboard → Settings → API Keys
MEMORAEU_SECRETPassword for key derivationYes (local)User account password
MEMORAEU_SALTKDF saltYes (local)Dashboard → Settings → Encryption Keys
MISTRAL_API_KEYLocal embedding generationYes (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:

PackageVersionPurpose
mcp>=1.1.0, <1.2.0MCP SDK framework
httpx0.28.1HTTP client for API calls
python-dotenv1.0.1Environment variable loading
starlette>=0.40.0, <0.42.0ASGI framework for SSE
cryptography>=42.0.0AES-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:

  1. recall is called automatically with detected topic as query
  2. Recent memories are loaded via memoraeu://context resource
  3. 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 ThresholdAction
≥ 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 installation

Sources: memoraeu_mcp/server.py:1-9

Security and Encryption

Related topics: System Architecture, Configuration Reference

Section Related Pages

Continue reading this section for the full explanation and source context.

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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section 1. Automatic Recall

Continue reading this section for the full explanation and source context.

Section 2. Automatic Remember

Continue reading this section for the full explanation and source context.

Section 3. System Prompt Injection

Continue reading this section for the full explanation and source context.

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://context resource
  • 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 Prompt

2. 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

ToolDescriptionInput Schema
rememberMemorizes important information automaticallycontent, category, tags
recallSemantic search across stored memoriesquery, limit (default: 3), category
forgetDeletes a memory by IDmemory_id
list_memoriesLists recent memories with optional category filtercategory, limit (default: 20)
list_categoriesReturns existing categories sorted by usage
remember_factStores structured fact with temporal validitysubject, predicate, object, valid_from, valid_to, scope
recall_factsRetrieves active facts for a subjectsubject, predicate, scope, history
invalidate_factMarks a fact as expiredfact_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

StepDescriptionPurpose
1. CompressionSummarizes text via Mistral if > 500 charsToken optimization
2. CategorizationSuggests category using existing categoriesOrganization
3. EmbeddingGenerates vector via Mistral EmbedSemantic search
4. DeduplicationChecks vector similarityAvoid 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 ScoreAction
≥ 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, supersedes links them
  • recall_facts with history=False returns 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

ParameterValue
AlgorithmAES-256-GCM
Key DerivationPBKDF2-HMAC-SHA256
Iterations210,000 (OWASP 2024)
Ciphertext PrefixENCv1:
SaltPer-account, from dashboard

Configuration Variables

VariablePurposeRequired
MEMORAEU_API_KEYHTTP Bearer authenticationYes
MEMORAEU_SECRETUser password for key derivationYes
MEMORAEU_SALTKDF salt from dashboardYes
MEMORAEU_API_URLAPI endpoint (default: https://api.memoraeu.com)Yes
MISTRAL_API_KEYEmbedding generationYes

Sources: README.md:95-115

Dependencies

PackageVersionPurpose
mcp≥1.1.0, <1.2.0MCP protocol implementation
httpx0.28.1HTTP client
python-dotenv1.0.1Environment configuration
starlette≥0.40.0, <0.42.0Web framework
cryptography≥42.0.0AES encryption

Sources: requirements.txt:1-5

Version History

VersionDateChanges
0.1.92026-05-12Added remember_fact, recall_facts, invalidate_fact; PBKDF2 210k iterations
0.1.52026-04-28Added 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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Purpose and Scope

Continue reading this section for the full explanation and source context.

Section Compression Threshold

Continue reading this section for the full explanation and source context.

Section The compresslocally Function

Continue reading this section for the full explanation and source context.

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

ParameterDescriptionDefault Value
COMPRESSION_THRESHOLDMinimum content length to trigger compressionConfigurable 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| C

Sources: memoraeu_mcp/main.py

The `compress_locally` Function

The compression function compress_locally() implements the following workflow:

  1. Threshold Check: Only processes content exceeding COMPRESSION_THRESHOLD characters
  2. Prompt Engineering: Sends the content to Mistral Chat with a French-language summarization prompt
  3. Validation: Accepts the summary only if it's shorter than the original
  4. 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 ScoreAction
≥ 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:#FFE4B5

Sources: 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 --> E

Sources: 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:

PackageVersionPurpose
httpx0.28.1Async HTTP client for Mistral API calls
starlette≥0.40.0,<0.42.0Web framework components
cryptography≥42.0.0Encryption primitives
python-dotenv1.0.1Environment variable management

Sources: requirements.txt

Configuration Variables

The system uses environment variables for Mistral API integration:

VariablePurposeRequired
MISTRAL_API_KEYAuthentication for Mistral Embed and Chat APIsYes (for stdio install)
MEMORAEU_API_KEYMemoraEU API authenticationYes
MEMORAEU_SECRETPassword for key derivationYes (stdio)
MEMORAEU_SALTKDF salt for encryptionYes (stdio)

Sources: README.md

Version History

VersionDateChanges
0.1.92026-05-12PBKDF2 updated to 210,000 iterations, ENCv1: prefix added
0.1.52026-04-28PBKDF2 updated to 210k iterations, refactoring
InitialNear-duplicate detection with 0.94 threshold

Sources: CHANGELOG.md

Security Considerations

Zero-Knowledge Guarantee

The optimization pipeline preserves zero-knowledge encryption by:

  1. Embedding before encryption: Vector embeddings are computed from plaintext locally
  2. Compression before encryption: Summarization occurs on plaintext content
  3. Local-only processing: All LLM calls (Mistral) happen client-side
  4. 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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Fact Validity States

Continue reading this section for the full explanation and source context.

Section rememberfact

Continue reading this section for the full explanation and source context.

Section recallfacts

Continue reading this section for the full explanation and source context.

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]
    end

Data Model

Each structured fact follows this schema:

FieldTypeRequiredDescription
idUUIDAutoUnique fact identifier
subjectstringYesEntity being described
predicatestringYesProperty or relation name
objectstringYesEncrypted value (E2E)
scopeenumNoprivate (default) or org
valid_fromdateAutoWhen fact became true
valid_todateNoWhen fact ceased to be true
supersedesUUIDAutoPrevious 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:

ParameterTypeRequiredDescription
subjectstringYesEntity name
predicatestringYesProperty name
objectstringYesValue (encrypted before storage)
scopestringNoprivate or org (default: private)
valid_fromstringNoStart date YYYY-MM-DD

Response Format:

✅ Fait mémorisé 🔒 (remplace {id}…)
  {subject} → {predicate}
  Depuis: {valid_from} | ID: {id}…

Key Behaviors:

  1. Encryption: object value is encrypted client-side before transmission
  2. Auto-supersession: If a fact with the same subject + predicate exists, the new fact automatically replaces it (old one marked invalid via supersedes field)
  3. Timestamp: valid_from defaults to today if not specified

Sources: memoraeu_mcp/main.py:76-106

recall_facts

Retrieves active facts for a specific subject entity.

Parameters:

ParameterTypeRequiredDescription
subjectstringYesEntity to query
predicatestringNoFilter by specific property
scopestringNoprivate or org (default: private)
historybooleanNoInclude 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:

ParameterTypeRequiredDescription
fact_idstringYesUUID of fact to expire
valid_tostringNoEnd date YYYY-MM-DD (default: today)

Behavior:

  • Sets valid_to to specified date or current date
  • Expired facts are excluded from default recall_facts queries
  • Use history=true in recall_facts to 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 ID

Querying 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 only

Security Model

All structured facts leverage the same zero-knowledge encryption as regular memories:

LayerImplementation
Key DerivationPBKDF2-HMAC-SHA256, 210,000 iterations (OWASP 2024)
Symmetric CipherAES-256-GCM
Ciphertext FormatENCv1:{base64_ciphertext}

Sources: CHANGELOG.md:18-19

Encryption Flow for Facts:

  1. object value encrypted client-side before API transmission
  2. subject and predicate transmitted in plaintext (used for routing/indexing)
  3. 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

AspectRegular MemoryStructured Facts
ContentFree-form textSubject-predicate-object
QuerySemantic searchEntity-based retrieval
DeduplicationVector similarity ≥94%Auto-supersession by predicate
TemporalImplicitExplicit valid_from/valid_to
Use CaseContext, preferences, notesEntity state, relationships

Sources: README.md:34-45

Configuration

Structured Facts require no additional configuration beyond the base MCP server setup:

VariablePurposeRequired
MEMORAEU_API_KEYBearer token authenticationYes
MEMORAEU_SECRETPassword for PBKDF2 key derivationYes (for encryption)
MEMORAEU_SALTKDF salt from serverYes (for encryption)
MEMORAEU_API_URLAPI endpointYes
MISTRAL_API_KEYEmbedding generationYes (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

ToolEndpointMethod
remember_fact/factsPOST
recall_facts/factsGET
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

VersionDateChanges
0.1.92026-05-12Initial 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

Section Related Pages

Continue reading this section for the full explanation and source context.

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

Section Related Pages

Continue reading this section for the full explanation and source context.

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

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Python Dependencies

Continue reading this section for the full explanation and source context.

Section Architecture

Continue reading this section for the full explanation and source context.

Section Configuration Steps

Continue reading this section for the full explanation and source context.

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 ModeUse CaseEncryptionSetup Complexity
Local (stdio)Full zero-knowledge guaranteesClient-side, server never sees plaintextHigher
Remote (SSE)Quick testing, no installServer processes plaintextMinimal

Sources: README.md

Prerequisites

Before deploying, ensure you have:

  • Python 3.10+ with uvx or 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:#f3e5f5

Configuration Steps

#### 1. Create Claude Desktop Configuration

Edit your Claude Desktop config file:

OSConfig 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

VariablePurposeRequiredSource
MEMORAEU_API_KEYHTTP Bearer authenticationYesDashboard → Settings → API Keys
MEMORAEU_SECRETPBKDF2 password input for key derivationYesYour MemoraEU login password
MEMORAEU_SALTKDF salt unique to your accountYesDashboard → Settings → Encryption Keys
MEMORAEU_API_URLAPI endpointYesUse https://api.memoraeu.com for hosted
MISTRAL_API_KEYLocal embedding generationYes*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 plaintext

Sources: 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

PropertyValue
ProtocolServer-Sent Events (SSE)
Endpointhttps://api.memoraeu.com/mcp/sse
AuthenticationBearer token in header
EncryptionNot 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

  1. Create account at app.memoraeu.com

Step 2: Get Encryption Salt

  1. Go to Settings → Encryption Keys
  2. Copy the MEMORAEU_SALT value

Step 3: Set Secret

  1. MEMORAEU_SECRET is your MemoraEU login password
  2. Used as PBKDF2 input to derive encryption key

Step 4: Get API Key

  1. Go to Settings → API Keys
  2. Create a new key
  3. Copy the MEMORAEU_API_KEY (format: meu-sk-xxx)

Step 5: Get Mistral API Key

  1. Obtain key at console.mistral.ai
  2. Required for local embedding generation

Sources: README.md

Security Considerations

Encryption Implementation

AspectDetail
AlgorithmAES-256-GCM
Key DerivationPBKDF2-HMAC-SHA256
Iterations210,000 (OWASP 2024 recommendation)
Ciphertext PrefixENCv1:
SaltServer-generated, unique per account

Sources: CHANGELOG.md

Security Comparison

Featurestdio (Local)SSE (Remote)
Zero-knowledge✅ Yes❌ No
EmbeddingsLocal (via Mistral)Server-processed
Content encryptionClient-sideServer-side
PBKDF2 iterations210,000210,000

Sources: README.md

Available MCP Tools

Once deployed, the following tools are available:

ToolDescription
rememberAutomatically memorize important information
recallSemantic search across stored memories
forgetDelete a memory by ID
list_memoriesList recent memories with optional category filter
list_categoriesReturn existing categories sorted by usage
remember_factStore structured fact with temporal validity
recall_factsRetrieve active facts for a subject
invalidate_factMark a fact as expired

Sources: memoraeu_mcp/main.py

Troubleshooting

Common Issues

IssueSolution
MISTRAL_API_KEY missingMCP continues working but semantic search falls back to keyword matching
Authentication failedVerify MEMORAEU_API_KEY format is meu-sk-xxx
Encryption errorsEnsure MEMORAEU_SECRET and MEMORAEU_SALT are correct
stdio connection refusedRestart Claude Desktop after config changes

Verification Steps

  1. Check config file syntax is valid JSON
  2. Verify all required environment variables are set
  3. Confirm API keys are active in MemoraEU dashboard
  4. Restart the MCP client after configuration changes

Version History

VersionDateKey Changes
0.1.92026-05-12Added fact tools, PBKDF2 210k iterations, ENCv1 prefix
0.1.52026-04-28Initial 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.

medium Configuration risk needs validation

Users may get misleading failures or incomplete behavior unless configuration is checked carefully.

medium README/documentation is current enough for a first validation pass.

The project should not be treated as fully validated until this signal is reviewed.

medium Maintainer activity is unknown

Users cannot judge support quality until recent activity, releases, and issue response are checked.

medium no_demo

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.

Sources 1

Count of project-level external discussion links exposed on this manual page.

Use Review before install

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.

Source: Project Pack community evidence and pitfall evidence