{
"canonical_name": "pquattro/memoraeu-mcp",
"compilation_id": "pack_bca6338dce324c88acd67d984f3ed4de",
"created_at": "2026-05-24T14:18:52.289758+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install memoraeu-mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install memoraeu-mcp",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_1af7e5f3b3994096b8cd7bb41c987140"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_fac6d5e17d6e0ecd8a20c3dfb9a14239",
"canonical_name": "pquattro/memoraeu-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/pquattro/memoraeu-mcp",
"slug": "memoraeu-mcp",
"source_packet_id": "phit_e63dddb047ec422882b5d98045a4180c",
"source_validation_id": "dval_017644bf19ad4842aff2692e2be4439b"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 1,
"one_liner_en": "Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.",
"one_liner_zh": "Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude 等宿主 AI 的用户",
"title_en": "memoraeu-mcp",
"title_zh": "memoraeu-mcp 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"type": "core_capability"
},
{
"label_en": "Automated Workflow",
"label_zh": "自动化工作流",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-automated-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_e63dddb047ec422882b5d98045a4180c",
"page_model": {
"artifacts": {
"artifact_slug": "memoraeu-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install memoraeu-mcp",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/pquattro/memoraeu-mcp#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"知识库问答",
"流程自动化",
"自动化工作流",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | host_targets=mcp_host, claude"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1
},
"source_url": "https://github.com/pquattro/memoraeu-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.",
"title": "memoraeu-mcp 能力包",
"trial_prompt": "# memoraeu-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for pquattro/memoraeu-mcp.\n\nProject:\n- Name: memoraeu-mcp\n- Repository: https://github.com/pquattro/memoraeu-mcp\n- Summary: Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-home: Home. Produce one small intermediate artifact and wait for confirmation.\n2. page-installation: Installation Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-security-encryption: Security and Encryption. Produce one small intermediate artifact and wait for confirmation.\n5. page-auto-memory: Auto-Memory System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/pquattro/memoraeu-mcp\n- https://github.com/pquattro/memoraeu-mcp#readme\n- README.md\n- memoraeu_mcp/__init__.py\n- server.json\n- pyproject.toml\n- memoraeu_mcp/main.py\n- memoraeu_mcp/server.py\n- server.py\n- memoraeu_mcp/crypto.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "memoraeu-mcp 能力包",
"risk": "需复核",
"slug": "memoraeu-mcp",
"stars": 1,
"tags": [
"安全审查与权限治理",
"知识库问答",
"流程自动化",
"自动化工作流",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/pquattro/memoraeu-mcp 项目说明书\n\n生成时间：2026-05-15 22:45:24 UTC\n\n## 目录\n\n- [Home](#page-home)\n- [Installation Guide](#page-installation)\n- [System Architecture](#page-architecture)\n- [Security and Encryption](#page-security-encryption)\n- [Auto-Memory System](#page-auto-memory)\n- [Deduplication and Compression](#page-deduplication)\n- [Structured Facts System](#page-structured-facts)\n- [MCP Tools Reference](#page-mcp-tools)\n- [Configuration Reference](#page-configuration)\n- [Deployment Guide](#page-deployment)\n\n\n\n## Home\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [System Architecture](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# Home\n\nMemoraEU 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.\n\n## Overview\n\nMemoraEU 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:\n\n- **Automatically recall** relevant memories at the start of each conversation\n- **Persistently remember** user preferences, decisions, and facts without explicit requests\n- **Search semantically** across encrypted memory stores\n- **Manage structured facts** with temporal validity (subject/predicate/object triplets)\n\nThe architecture is designed around the principle of zero-knowledge: embeddings are computed locally before encryption, ensuring the server never sees plaintext content. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Side (Local)\"\n A[Claude Desktop / MCP Client] --> B[MemoraEU MCP Server]\n B --> C[Mistral API
Embedding Generation]\n B --> D[PBKDF2 Key Derivation]\n B --> E[AES-256-GCM Encryption]\n end\n \n subgraph \"MemoraEU Cloud\"\n F[API Endpoint
api.memoraeu.com] --> G[Encrypted Storage]\n F --> H[Vector Search Index]\n end\n \n C -->|Plaintext| E\n D -->|Derived Key| E\n E -->|Encrypted Blob| F\n C -->|Embedding Vector| F\n \n style C fill:#ff9999\n style D fill:#ff9999\n style E fill:#ff9999\n style F fill:#99ccff\n style G fill:#99ff99\n style H fill:#99ff99\n```\n\n### Security Model\n\nThe zero-knowledge architecture ensures that all sensitive processing occurs client-side:\n\n| Component | Location | Data Handled |\n|-----------|----------|---------------|\n| Embedding Generation | Local (MCP server) | Plaintext content |\n| Compression | Local | Plaintext content |\n| Categorization | Local | Plaintext content |\n| Encryption | Local (AES-256-GCM) | Plaintext → Ciphertext |\n| Storage | Remote (MemoraEU Cloud) | Encrypted blobs + vectors |\n| Search | Hybrid | Vector similarity on encrypted index |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Installation Modes\n\nMemoraEU MCP supports two deployment modes with different security guarantees:\n\n### STDIO Mode (Zero-Knowledge)\n\nFull zero-knowledge encryption with all processing happening locally.\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### SSE Mode (Remote)\n\nDirect connection without local installation, suitable for web clients.\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n**Note:** In SSE remote mode, content is not zero-knowledge encrypted since the server processes plaintext. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Available Tools\n\nThe MCP server exposes 9 tools for memory and fact management:\n\n### Memory Tools\n\n| Tool | Description | Required Parameters |\n|------|-------------|---------------------|\n| `remember` | Automatically memorizes important information when user expresses preferences, decisions, biographical facts, or technical configs | `content` |\n| `recall` | Semantic search across stored memories using vector similarity | `query` |\n| `forget` | Deletes a memory by its ID | `memory_id` |\n| `list_memories` | Lists recent memories with optional category filter | - |\n| `list_categories` | Returns existing categories sorted by usage | - |\n\n资料来源：[memoraeu_mcp/main.py:48-110](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Fact Tools\n\n| Tool | Description | Required Parameters |\n|------|-------------|---------------------|\n| `remember_fact` | Stores a structured fact with temporal validity (subject/predicate/object) | `subject`, `predicate`, `object` |\n| `recall_facts` | Retrieves active facts for a given subject | `subject` |\n| `invalidate_fact` | Marks a fact as expired by its ID | `fact_id` |\n\n资料来源：[server.py:48-80](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n## Auto-Memory Behavior\n\nThe MCP server is designed to operate autonomously without manual intervention.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant C as Claude\n participant M as MemoraEU MCP\n \n U->>C: First message\n C->>M: recall(topic)\n M-->>C: Relevant memories\n C->>M: load_session_context()\n M-->>C: Recent memories via memoraeu://context\n \n Note over C: System prompt auto-injected\n \n U->>C: Expresses preference\n C->>M: remember(content, category)\n M-->>C: ✅ Memorized (ID: xxx)\n```\n\n### Automatic Recall\n\nOn 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Automatic Remember\n\nWhen 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### System Prompt Injection\n\nOn 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Deduplication & Compression\n\nBefore storing a memory, the MCP performs several preprocessing steps:\n\n```mermaid\ngraph LR\n A[Raw Content] --> B[Local Compression]\n B --> C[Vector Similarity Check]\n C -->|≥ 94%| D[Duplicate - Skip]\n C -->|< 94%| E[Local Categorization]\n E --> F[AES-256-GCM Encrypt]\n F --> G[Send to API]\n```\n\n### Similarity Thresholds\n\n| Similarity Score | Action |\n|-----------------|--------|\n| ≥ 94% | Memory ignored (exact duplicate) |\n| < 94% | Proceed with storage |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Environment Variables\n\nFive distinct variables serve different purposes—they are not interchangeable:\n\n| Variable | Purpose | Source |\n|----------|---------|--------|\n| `MEMORAEU_API_KEY` | HTTP Bearer token for authentication | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | User's login password, used as PBKDF2 input to derive the encryption key | User account password |\n| `MEMORAEU_SALT` | KDF salt unique to the account, combined with SECRET to produce the encryption key | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint (use `https://api.memoraeu.com` for hosted service) | - |\n| `MISTRAL_API_KEY` | Generates embeddings locally before encryption (required for zero-knowledge semantic search) | Mistral Console |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Without MISTRAL_API_KEY\n\nThe 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Encryption Details\n\nThe encryption scheme uses industry-standard practices:\n\n| Parameter | Value | Source |\n|-----------|-------|--------|\n| Algorithm | AES-256-GCM | Symmetric encryption |\n| Key Derivation | PBKDF2-HMAC-SHA256 | Password-based key derivation |\n| Iterations | 210,000 | OWASP 2024 recommendation |\n| Ciphertext Prefix | `ENCv1:` | Version identifier |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | Model Context Protocol framework |\n| `httpx` | 0.28.1 | HTTP client |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | ≥0.40.0, <0.42.0 | ASGI framework |\n| `cryptography` | ≥42.0.0 | Encryption primitives |\n\n资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Resources\n\nThe MCP server exposes the following resource:\n\n| URI | Name | Description |\n|-----|------|-------------|\n| `memoraeu://context` | Contexte mémoire MemoraEU | Recent memories automatically injected at session start |\n\n资料来源：[memoraeu_mcp/main.py:115-120](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Prompts\n\n| Name | Description |\n|------|-------------|\n| `memoraeu_system` | MemoraEU automatic memory behavior system prompt—injectable into Claude's context |\n\n资料来源：[memoraeu_mcp/main.py:137-145](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Quick Start Guide\n\n### 1. Create Account and Obtain Keys\n\n1. Create an account at [app.memoraeu.com](https://app.memoraeu.com)\n2. Navigate to **Settings → Encryption Keys** → copy `MEMORAEU_SALT`\n3. `MEMORAEU_SECRET` is your MemoraEU login password\n4. Navigate to **Settings → API Keys** → create a key → copy `MEMORAEU_API_KEY`\n5. Obtain a Mistral API key from [console.mistral.ai](https://console.mistral.ai)\n\n### 2. Configure Claude Desktop\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Supported Clients\n\n| Client | Support Type |\n|--------|--------------|\n| Claude Desktop | Full STDIO support |\n| Claude.ai Web | SSE remote mode |\n| Cursor | SSE configuration |\n| Windsurf | SSE configuration |\n| Other MCP Clients | STDIO or SSE depending on client capability |\n\n## Changelog Summary\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 0.1.9 | 2026-05-12 | Added `remember_fact`, `recall_facts`, `invalidate_fact`; PBKDF2 updated to 210k iterations |\n| 0.1.5 | 2026-04-28 | PBKDF2 210k iterations + `ENCv1:` prefix |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Configuration Reference](#page-configuration), [Deployment Guide](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [memoraeu_mcp/server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# Installation Guide\n\nThis 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.\n\n## Overview\n\nmemoraeu-mcp can be installed in two modes:\n\n| Mode | Transport | Zero-Knowledge | Use Case |\n|------|-----------|----------------|----------|\n| **Local (stdio)** | `stdio` | ✅ Full | Desktop applications (Claude Desktop, Cursor, Windsurf) |\n| **Remote (SSE)** | `SSE` | ⚠️ Partial | Web clients, shared environments |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Prerequisites\n\nBefore installation, ensure you have:\n\n- **Python 3.11+** — Required for the MCP server\n- **uvx** or **pip** — For package installation\n- **MemoraEU Account** — Required for API access\n- **Mistral API Key** — For local embedding generation (required for zero-knowledge semantic search)\n\n### Required Accounts and Keys\n\n| Service | Purpose | Signup Location |\n|---------|---------|-----------------|\n| MemoraEU | Memory storage and sync | [app.memoraeu.com](https://app.memoraeu.com) |\n| Mistral AI | Local embedding generation | [console.mistral.ai](https://console.mistral.ai) |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: Local Installation (stdio) — Recommended\n\nThis method provides **full zero-knowledge encryption** where embeddings are generated locally before any data leaves your machine.\n\n#### Step 1: Install the Package\n\n```bash\nuvx memoraeu-mcp\n```\n\nOr using pip:\n\n```bash\npip install memoraeu-mcp\n```\n\n#### Step 2: Obtain MemoraEU Credentials\n\n1. Create an account at [app.memoraeu.com](https://app.memoraeu.com)\n2. Navigate to **Settings → Encryption Keys** → copy `MEMORAEU_SALT`\n3. `MEMORAEU_SECRET` is your MemoraEU login password\n4. Navigate to **Settings → API Keys** → create a key → copy `MEMORAEU_API_KEY`\n\n#### Step 3: Configure Claude Desktop\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Method 2: Remote Installation (SSE) — Zero-Knowledge NOT Guaranteed\n\nUse this method when you cannot install locally or need quick access from web clients.\n\n> ⚠️ **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.\n\n#### Configuration for Remote Clients\n\nConfigure your MCP client (Cursor, Windsurf, or any SSE-compatible client):\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n**SSE Endpoint Details:**\n\n| Property | Value |\n|----------|-------|\n| Endpoint URL | `https://api.memoraeu.com/mcp/sse` |\n| Authentication | Bearer token in `Authorization` header |\n| API Key Format | `meu-sk-xxx` |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Environment Variables Reference\n\nAll configuration is done via environment variables. These five variables serve **three distinct purposes** — they are **not interchangeable**.\n\n| Variable | Purpose | Required | Where to Get |\n|----------|---------|----------|--------------|\n| `MEMORAEU_API_KEY` | HTTP authentication (Bearer token sent with every request) | Yes | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | Your MemoraEU login password — used as PBKDF2 input to derive the encryption key locally | Yes (local) | Your account password |\n| `MEMORAEU_SALT` | KDF salt generated by the server, unique to your account | Yes (local) | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint for the hosted service | Yes | Use `https://api.memoraeu.com` |\n| `MISTRAL_API_KEY` | Used to generate embeddings locally before encryption | Yes (local) | [console.mistral.ai](https://console.mistral.ai) |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Variable Dependency Matrix\n\n```mermaid\ngraph TD\n A[Local Installation] --> B{MISTRAL_API_KEY set?}\n B -->|Yes| C[Full Zero-Knowledge Mode]\n B -->|No| D[Keyword Search Fallback]\n C --> E[Embeddings generated locally
before encryption]\n D --> F[Server-side keyword search
Zero-knowledge encryption preserved]\n \n G[Remote SSE Mode] --> H[No Local Processing
Server sees plaintext]\n \n style C fill:#90EE90\n style D fill:#FFE4B5\n style H fill:#FFB6C1\n```\n\n### Why is MISTRAL_API_KEY Required Locally?\n\nThe zero-knowledge architecture requires that:\n1. Embeddings must be calculated **before** encryption\n2. This happens on your local machine\n3. The MCP calls Mistral directly with plaintext\n4. The server receives an opaque blob + vector it cannot decrypt\n\nWithout `MISTRAL_API_KEY`, semantic search falls back to keyword search on the server side, but **zero-knowledge encryption remains intact**.\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Configuration Examples by Client\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n### Cursor / Windsurf (Local)\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n### Cursor / Windsurf (Remote SSE)\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Supported Transport Protocols\n\n| Protocol | Use Case | Zero-Knowledge | Setup Complexity |\n|----------|----------|----------------|------------------|\n| `stdio` | Local desktop apps | ✅ Full | Requires uvx/pip |\n| `sse` | Remote/web clients | ⚠️ Server sees plaintext | Quick setup |\n\nThe MCP server implements both protocols via the MCP SDK:\n\n资料来源：[memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Package Dependencies\n\nThe following dependencies are required and specified in `requirements.txt`:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | Model Context Protocol SDK |\n| `httpx` | 0.28.1 | HTTP client for API calls |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | ≥0.40.0, <0.42.0 | ASGI framework |\n| `cryptography` | ≥42.0.0 | AES-256-GCM encryption |\n\n资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Installation Flow Diagram\n\n```mermaid\nflowchart TD\n A[Start Installation] --> B{Choose Mode}\n \n B -->|Local stdio| C[Install via uvx or pip]\n B -->|Remote SSE| D[Configure client directly]\n \n C --> E[Create MemoraEU Account]\n E --> F[Get API Key & Salt]\n F --> G[Get Mistral API Key]\n G --> H[Configure claude_desktop_config.json]\n H --> I[Verify Installation]\n \n D --> J[Get Bearer Token]\n J --> K[Configure SSE in client]\n K --> L[Verify Connection]\n \n I --> M[✅ Zero-Knowledge Ready]\n L --> N[⚠️ Remote Mode Active]\n```\n\n## Verifying Installation\n\nAfter installation, verify the MCP server is working by:\n\n1. **Check MCP server status** in your client\n2. **Run a test command** using any available tool:\n - `list_categories` — Should return an empty list or existing categories\n - `list_memories` — Should confirm connection\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| \"Module not found\" errors | Ensure `uvx` or `pip` installation completed successfully |\n| SSE connection failures | Verify API key format is `meu-sk-xxx` and endpoint URL is correct |\n| Semantic search not working | Check `MISTRAL_API_KEY` is set; falls back to keyword search if missing |\n| Encryption errors | Verify `MEMORAEU_SALT` and `MEMORAEU_SECRET` are correct |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Security Architecture Summary\n\n| Component | Location | Description |\n|-----------|----------|-------------|\n| Encryption | Client-side | AES-256-GCM with PBKDF2-HMAC-SHA256 (100k iterations) |\n| Embedding generation | Client-side | Mistral embeddings computed before encryption |\n| Storage | Server-side | Opaque encrypted blobs + vectors |\n| Key derivation | Client-side | Password + salt → encryption key |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Security and Encryption](#page-security-encryption), [MCP Tools Reference](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [memoraeu_mcp/server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/server.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n \n\n# System Architecture\n\n## Overview\n\nThe **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.\n\nThe 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.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph Client[\"Client Side (Local)\"]\n MCP[\"MCP Client
(Claude Desktop, Cursor, etc.)\"]\n Tools[\"Tool Handlers
remember, recall, forget, etc.\"]\n Crypto[\"Encryption Module
AES-256-GCM + PBKDF2\"]\n Embed[\"Embedding Generator
(Mistral API)\"]\n Compress[\"Local Compression\"]\n Categorize[\"Local Categorization\"]\n end\n\n subgraph External[\"External Services\"]\n Mistral[\"Mistral API
(Embeddings)\"]\n end\n\n subgraph Server[\"MemoraEU Remote API\"]\n API[\"API Endpoint
api.memoraeu.com\"]\n Storage[\"Encrypted Storage\"]\n end\n\n MCP --> Tools\n Tools --> Crypto\n Tools --> Embed\n Tools --> Compress\n Tools --> Categorize\n Embed --> Mistral\n Tools --> API\n API --> Storage\n\n style Client fill:#e1f5fe\n style Server fill:#fff3e0\n style External fill:#f3e5f5\n```\n\n## Component Architecture\n\n### Entry Points\n\nThe project provides multiple entry points for different deployment scenarios:\n\n| Entry Point | Purpose | Use Case |\n|-------------|---------|----------|\n| `memoraeu_mcp/server.py` | Pip/uvx installation entry | Installed via package manager |\n| `server.py` | Development/main server | Direct execution with `python server.py` |\n| SSE Remote | Remote MCP via Server-Sent Events | Web clients without local install |\n\n资料来源：[memoraeu_mcp/server.py:1-9]()\n\n```python\n\"\"\"Entry point pour memoraeu-mcp installé via pip/uvx.\"\"\"\nimport asyncio\n\ndef run():\n from memoraeu_mcp.main import main\n asyncio.run(main())\n```\n\n### Core Server Module\n\nThe `memoraeu_mcp/main.py` file contains the complete MCP server implementation with all tool handlers, resource providers, and prompt managers.\n\n资料来源：[memoraeu_mcp/main.py:1-200]()\n\n## MCP Protocol Implementation\n\n### Tool Registration\n\n```mermaid\ngraph LR\n A[list_tools] --> B[Tool Definitions]\n B --> C[remember]\n B --> D[recall]\n B --> E[forget]\n B --> F[list_memories]\n B --> G[list_categories]\n B --> H[remember_fact]\n B --> I[recall_facts]\n B --> J[invalidate_fact]\n```\n\nAll tools are defined using the MCP SDK `Tool` class with JSON schemas:\n\n```python\nTool(\n name=\"remember\",\n description=\"Mémorise automatiquement une information importante...\",\n inputSchema={\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n)\n```\n\n资料来源：[memoraeu_mcp/main.py:73-106]()\n\n### Available Tools\n\n| Tool | Function | Input Parameters |\n|------|----------|-------------------|\n| `remember` | Stores important information | `content` (required), `category`, `tags` |\n| `recall` | Semantic search across memories | `query` (required), `limit`, `category` |\n| `forget` | Deletes a memory by ID | `memory_id` (required) |\n| `list_memories` | Lists recent memories | `category`, `limit` |\n| `list_categories` | Returns categories sorted by usage | None |\n| `remember_fact` | Stores structured fact | `subject`, `predicate`, `object`, `scope`, `valid_from` |\n| `recall_facts` | Retrieves active facts | `subject`, `predicate`, `scope`, `history` |\n| `invalidate_fact` | Marks fact as expired | `fact_id`, `valid_to` |\n\n### Resources\n\nThe server provides a single resource URI for memory context injection:\n\n| Resource URI | Name | Purpose |\n|--------------|------|---------|\n| `memoraeu://context` | Contexte mémoire MemoraEU | Recent memories injected automatically at session start |\n\n资料来源：[memoraeu_mcp/main.py:148-165]()\n\n```python\n@app.list_resources()\nasync def list_resources() -> list[Resource]:\n return [\n Resource(\n uri=\"memoraeu://context\",\n name=\"Contexte mémoire MemoraEU\",\n description=\"Mémoires récentes injectées automatiquement en début de session\",\n mimeType=\"text/plain\"\n )\n ]\n```\n\n### Prompts\n\nA single system prompt is available for memory behavior injection:\n\n| Prompt Name | Description |\n|-------------|-------------|\n| `memoraeu_system` | Injects automatic memory behavior rules into Claude's context |\n\n资料来源：[memoraeu_mcp/main.py:132-147]()\n\n## Data Flow Architecture\n\n### Memory Storage Flow\n\n```mermaid\ngraph TD\n A[User Input] --> B[remember tool]\n B --> C{API Key Available?}\n C -->|Yes| D[Generate Embedding via Mistral]\n C -->|No| E[Skip Embedding]\n D --> F[Compress Content Locally]\n E --> F\n F --> G[Categorize Locally]\n G --> H[Check Duplicate Similarity]\n H --> I{Similarity >= 94%?}\n I -->|Yes| J[Ignore - Duplicate]\n I -->|No| K[Encrypt Content AES-256-GCM]\n K --> L[API POST /memories]\n L --> M[Server Stores Encrypted Blob]\n```\n\n### Memory Retrieval Flow\n\n```mermaid\ngraph TD\n A[recall tool] --> B[First recall of session?]\n B -->|Yes| C[Load Session Context]\n B -->|No| D[Skip Context]\n C --> E[Inject System Prompt]\n D --> F[API POST /memories/search]\n E --> F\n F --> G[Receive Encrypted Results]\n G --> H[Decrypt Content Locally]\n H --> I[Return Plaintext to Client]\n```\n\n## Security Architecture\n\n### Zero-Knowledge Model\n\n```mermaid\ngraph LR\n subgraph Client[\"Client\"]\n P[Plaintext Content]\n E[Encryption]\n K[Key Derivation]\n end\n\n subgraph Server[\"Server\"]\n C[Encrypted Blob]\n V[Vector Embedding]\n end\n\n P --> E\n E --> C\n P --> K\n K --> E\n C --> Server\n V --> Server\n```\n\nThe security model ensures:\n\n1. **Encryption before transmission** - Content is encrypted locally using AES-256-GCM\n2. **Client-side embedding** - Semantic vectors are generated from plaintext before encryption\n3. **Key derivation** - PBKDF2-HMAC-SHA256 with 100,000 iterations derives encryption keys\n\n### Key Derivation Parameters\n\n| Parameter | Variable | Source |\n|-----------|----------|--------|\n| Secret | `MEMORAEU_SECRET` | User's account password |\n| Salt | `MEMORAEU_SALT` | Server-generated, unique per account |\n| Iterations | 100,000 | Hardcoded in implementation |\n\n资料来源：[memoraeu_mcp/main.py:1-50]()\n\n### API Authentication\n\nTwo authentication modes are supported:\n\n| Mode | Configuration | Transport |\n|------|--------------|-----------|\n| Local stdio | Environment variables | Standard I/O |\n| Remote SSE | Bearer token header | Server-Sent Events |\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n## Configuration Architecture\n\n### Environment Variables\n\n| Variable | Purpose | Required | Source |\n|----------|---------|----------|--------|\n| `MEMORAEU_API_URL` | API endpoint | Yes | Fixed for hosted service |\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Yes | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | Password for key derivation | Yes (local) | User account password |\n| `MEMORAEU_SALT` | KDF salt | Yes (local) | Dashboard → Settings → Encryption Keys |\n| `MISTRAL_API_KEY` | Local embedding generation | Yes (zero-knowledge) | Mistral Console |\n\n资料来源：[README.md:1-50]()\n\n### Configuration File Structure\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n## Dependencies\n\nThe project depends on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | >=1.1.0, <1.2.0 | MCP SDK framework |\n| `httpx` | 0.28.1 | HTTP client for API calls |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | >=0.40.0, <0.42.0 | ASGI framework for SSE |\n| `cryptography` | >=42.0.0 | AES-256-GCM encryption |\n\n资料来源：[requirements.txt:1-5]()\n\n## Auto-Memory Behavior System\n\nThe MCP server implements automatic memory management without manual intervention:\n\n### Automatic Recall\n\nOn the first user message of each session:\n1. `recall` is called automatically with detected topic as query\n2. Recent memories are loaded via `memoraeu://context` resource\n3. Context is injected into the session\n\n### Automatic Remember\n\nWhen Claude detects memorable information:\n- Preferences\n- Decisions\n- Biographical facts\n- Technical configurations\n- Durable constraints\n\nIt calls `remember` autonomously with a single discreet confirmation.\n\n### System Prompt Injection\n\nOn the first `recall` call, the full behavior system prompt is injected:\n\n```\nSYSTEM_PROMPT_TEXT contains:\n- Memory objectives (preferences, decisions, biographical facts)\n- Automatic recall rules\n- Token optimization guidelines\n```\n\n## Deduplication System\n\nBefore storing a memory, the system checks for near-duplicates:\n\n| Similarity Threshold | Action |\n|---------------------|--------|\n| ≥ 94% | Memory ignored (exact duplicate) |\n| < 94% | Memory stored normally |\n\nThis prevents storage of redundant information while allowing similar but distinct memories.\n\n## Error Handling Architecture\n\nAll tool handlers follow a consistent error handling pattern:\n\n```python\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict) -> list[TextContent]:\n if name == \"remember\":\n try:\n # Tool implementation\n return [TextContent(type=\"text\", text=\"✅ Success message\")]\n except Exception as e:\n return [TextContent(type=\"text\", text=f\"❌ Error : {e}\")]\n```\n\nThis ensures all errors return user-friendly messages rather than raw exceptions.\n\n## Module Structure Summary\n\n```\nmemoraeu_mcp/\n├── main.py # Core MCP server implementation\n│ ├── @app decorators (tools, resources, prompts)\n│ ├── Tool handlers (remember, recall, forget, etc.)\n│ ├── Encryption functions\n│ ├── API communication\n│ └── Local processing (compression, categorization)\n└── server.py # Entry point for pip/uvx installation\n\n---\n\n\n\n## Security and Encryption\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Configuration Reference](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/crypto.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/crypto.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n \n\n# Security and Encryption\n\n## Overview\n\nMemoraEU 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.\n\nThe system uses industry-standard cryptographic primitives:\n- **AES-256-GCM** for authenticated encryption\n- **PBKDF2-HMAC-SHA256** with 210,000 iterations for key derivation\n\n资料来源：[memoraeu_mcp/crypto.py:1-15]()\n\n---\n\n## Architecture\n\n### Zero-Knowledge Flow\n\n```mermaid\ngraph TD\n A[User Data] -->|Plaintext| B[Client-Side MCP Server]\n B --> C[Mistral Embeddings
Generated from plaintext]\n C --> D[encrypt_content]\n D --> E[AES-256-GCM
Encryption]\n E --> F[ENCv1:... ciphertext]\n F --> G[MemoraEU API]\n F --> H[Stored in DB]\n \n I[API Request] -->|encrypted data only| G\n G -->|cannot decrypt| H\n \n J[MEMORAEU_SECRET
+ MEMORAEU_SALT] -->|derive_key| K[AES-256 Key]\n K -->|in memory only| D\n```\n\nThe embedding generation happens **before** encryption to preserve semantic search capabilities while maintaining zero-knowledge guarantees. The server stores encrypted content and pre-computed embeddings but cannot decrypt the actual memory content.\n\n资料来源：[memoraeu_mcp/crypto.py:1-15]()\n\n---\n\n## Key Derivation\n\n### PBKDF2 Configuration\n\n| Parameter | Value | Notes |\n|-----------|-------|-------|\n| Algorithm | PBKDF2-HMAC-SHA256 | NIST recommended |\n| Iterations | 210,000 | OWASP 2024 recommendation |\n| Key Length | 32 bytes | AES-256 requirement |\n| Salt | User-specific | Server-generated, stored in dashboard |\n\nThe key derivation uses a high iteration count to make brute-force attacks computationally expensive. The salt is unique per user account and generated server-side to prevent rainbow table attacks.\n\n资料来源：[memoraeu_mcp/crypto.py:22-23]()\n\n### Derivation Function\n\n```python\ndef derive_key(password: str, salt: str) -> bytes:\n salt_bytes = salt.encode() if isinstance(salt, str) else salt\n kdf = PBKDF2HMAC(\n algorithm=hashes.SHA256(),\n length=32,\n salt=salt_bytes,\n iterations=PBKDF2_ITERATIONS,\n )\n return kdf.derive(password.encode())\n```\n\nThe function accepts `MEMORAEU_SECRET` (user's account password) and `MEMORAEU_SALT` (server-generated salt) to derive the encryption key.\n\n资料来源：[memoraeu_mcp/crypto.py:28-41]()\n\n---\n\n## Encryption\n\n### AES-256-GCM\n\nThe implementation uses the `cryptography` library's AESGCM implementation for authenticated encryption. GCM mode provides both confidentiality and integrity protection.\n\n| Property | Value |\n|----------|-------|\n| Cipher | AES-256 |\n| Mode | GCM (Galois/Counter Mode) |\n| Nonce | Random per encryption |\n| Authentication | Included in GCM mode |\n\n### Encrypted Value Format\n\nEncrypted values are prefixed with `ENCv1:` to enable detection:\n\n```\nENCv1:\n```\n\nThis prefix allows the decryption function to distinguish between encrypted and plaintext values.\n\n资料来源：[memoraeu_mcp/crypto.py:20-23]()\n\n---\n\n## Key Management\n\n### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant App as MCP Server\n participant Crypto as crypto module\n participant Env as Environment\n \n App->>Env: Read MEMORAEU_SECRET, MEMORAEU_SALT\n App->>App: init_crypto()\n App->>Crypto: derive_key(secret, salt)\n Crypto-->>App: 32-byte AES key\n App->>App: Store in _key global\n \n Note over App: Key held only in memory\n```\n\n### Environment Variables\n\n| Variable | Purpose | Source |\n|----------|---------|--------|\n| `MEMORAEU_SECRET` | User password for key derivation | User's account password |\n| `MEMORAEU_SALT` | KDF salt, unique per account | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Dashboard → Settings → API Keys |\n\n资料来源：[server.py:1-30]()\n\n### Key Storage\n\nThe derived key is stored in the `_key` global variable and is never persisted to disk or transmitted to the server:\n\n```python\n_key: bytes | None = None\n\ndef get_key() -> bytes | None:\n return _key\n```\n\n资料来源：[memoraeu_mcp/main.py:1-30]()\n\n---\n\n## Encryption/Decryption Wrappers\n\n### Content Encryption\n\n```python\ndef encrypt_content(content: str) -> str:\n key = get_key()\n if not key:\n return content # Fallback to plaintext\n from memoraeu_mcp.crypto import encrypt\n return encrypt(content, key)\n```\n\nIf the encryption key is not available (e.g., `MEMORAEU_SECRET` not configured), content is stored in plaintext with a warning message.\n\n资料来源：[server.py:50-60]()\n\n### Content Decryption\n\n```python\ndef decrypt_content(value: str) -> str:\n key = get_key()\n if not key:\n return value\n from memoraeu_mcp.crypto import decrypt, is_encrypted\n if not is_encrypted(value):\n return value\n try:\n return decrypt(value, key)\n except Exception:\n return \"[contenu chiffré — clé incorrecte]\"\n```\n\nDecryption failures (e.g., wrong key) return a placeholder message rather than exposing error details.\n\n资料来源：[memoraeu_mcp/main.py:60-80]()\n\n---\n\n## Dependency Requirements\n\nThe security implementation requires the `cryptography` library:\n\n```\ncryptography>=42.0.0\n```\n\nThis ensures access to the `cryptography.hazmat` primitives used for AES-GCM and PBKDF2.\n\n资料来源：[requirements.txt:1-5]()\n\n---\n\n## Security Properties\n\n### Guarantees\n\n| Property | Implementation |\n|----------|----------------|\n| Confidentiality | AES-256-GCM encryption, key never leaves client |\n| Integrity | GCM authentication tag verification |\n| Authentication | PBKDF2 key derivation from user password |\n| Non-repudiation | User-specific salt ensures key uniqueness |\n\n### Threat Model\n\n| Threat | Mitigation |\n|--------|------------|\n| Server compromise | Server stores only encrypted data |\n| Man-in-middle | HTTPS transport + client-side encryption |\n| Brute force | 210,000 PBKDF2 iterations |\n| Rainbow tables | Unique per-user salt |\n| Replay attacks | Random nonce per encryption operation |\n\n---\n\n## Configuration Examples\n\n### Full Zero-Knowledge Setup\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"server-generated-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n### Remote SSE Mode (Reduced Security)\n\nIn remote SSE mode, content is processed on the server and is **not zero-knowledge encrypted**:\n\n> **Note:** En mode SSE distant, le contenu n'est pas chiffré zero-knowledge (le serveur traite le texte en clair). Utilisez l'installation locale `stdio` pour les garanties zero-knowledge complètes.\n\n资料来源：[README.md:1-30]()\n\n---\n\n## Startup Behavior\n\nOn server initialization:\n\n```\n[memoraeu] ✅ Chiffrement zero-knowledge activé\n```\n\nOr if `MEMORAEU_SECRET` is missing:\n\n```\n[memoraeu] ⚠️ MEMORAEU_SECRET absent — stockage en clair\n```\n\n资料来源：[server.py:45-50]()\n\n---\n\n\n\n## Auto-Memory System\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [Structured Facts System](#page-structured-facts)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n \n\n# Auto-Memory System\n\nThe 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.\n\n## Overview\n\nThe system operates on a **client-side encryption** model where:\n\n- All memory content is encrypted locally before transmission\n- Embeddings for semantic search are computed from plaintext before encryption\n- The server processes encrypted data without visibility into content\n- A PBKDF2-HMAC-SHA256 key derivation scheme (210,000 iterations) protects the encryption key derived from the user's password\n\n```mermaid\ngraph TD\n A[User Message] --> B{Auto-Recall Trigger}\n B --> C[Extract Topic Query]\n C --> D[Semantic Search
memoraeu://context]\n D --> E[Load Recent Memories]\n E --> F[Inject into Session Context]\n \n G[User Expresses
Preference/Fact] --> H{Auto-Remember Trigger}\n H --> I[Compress Content]\n I --> J[Categorize Locally]\n J --> K[Generate Embedding]\n K --> L{Check Duplicates
Similarity ≥ 94%}\n L -->|No Duplicate| M[Encrypt Content]\n L -->|Duplicate Found| N[Skip Storage]\n M --> O[Store Memory]\n```\n\n## Core Components\n\n### 1. Automatic Recall\n\nOn the first user message of each session, the MCP server automatically triggers a `recall` operation using the detected topic as the search query. 资料来源：[README.md:40-45]()\n\n**Behavior:**\n- Retrieves relevant memories via semantic search\n- Loads recent memories through the `memoraeu://context` resource\n- Injects memories as session context automatically\n- No manual invocation required\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant MCP as MCP Server\n participant API as MemoraEU API\n participant LLM as Claude Model\n \n U->>MCP: First Message\n MCP->>MCP: Detect Topic\n MCP->>API: recall(topic, limit=3)\n API->>MCP: Relevant Memories\n MCP->>LLM: Inject Context\n MCP->>LLM: Inject System Prompt\n```\n\n### 2. Automatic Remember\n\nWhen 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. 资料来源：[README.md:47-52]()\n\n**Triggers for automatic memory:**\n- User expresses a preference\n- User makes a decision\n- User shares biographical information\n- User mentions technical constraints or configurations\n\n**Confirmation:** The system confirms storage with a single discreet line.\n\n### 3. System Prompt Injection\n\nOn 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. 资料来源：[README.md:54-58]()\n\nThe system prompt includes:\n```\n## Ce qu'il faut mémoriser\n- Préférences et configurations utilisateur\n- Décisions et choix récurrents ou contraintes durables\n- Informations techniques propres à l'utilisateur (stack, config, credentials non-sensibles)\n\n## Rappel automatique\nDès le premier message de l'utilisateur, utilise `recall` avec le sujet détecté comme query.\nN'attends pas qu'on te le demande — c'est automatique.\n\n## Règles\n- Ne mémorise pas les informations générales ou éphémères (météo du jour, blagues, calculs ponctuels)\n- Si l'utilisateur dit \"oublie ça\" ou \"ne retiens pas\", utilise `forget`\n- Confirme discrètement les mémorisations : une ligne, pas plus\n- Optimisation tokens : limite recall à 3 résultats par défaut, mémoires compactes\n```\n\n## Available Tools\n\n| Tool | Description | Input Schema |\n|------|-------------|--------------|\n| `remember` | Memorizes important information automatically | `content`, `category`, `tags` |\n| `recall` | Semantic search across stored memories | `query`, `limit` (default: 3), `category` |\n| `forget` | Deletes a memory by ID | `memory_id` |\n| `list_memories` | Lists recent memories with optional category filter | `category`, `limit` (default: 20) |\n| `list_categories` | Returns existing categories sorted by usage | — |\n| `remember_fact` | Stores structured fact with temporal validity | `subject`, `predicate`, `object`, `valid_from`, `valid_to`, `scope` |\n| `recall_facts` | Retrieves active facts for a subject | `subject`, `predicate`, `scope`, `history` |\n| `invalidate_fact` | Marks a fact as expired | `fact_id`, `valid_to` |\n\n### Tool Configuration in MCP\n\nTools are registered via the MCP manifest in `list_tools()`:\n\n```python\nTool(\n name=\"remember\",\n description=(\n \"Mémorise automatiquement une information importante. \"\n \"UTILISE CET OUTIL SANS QU'ON TE LE DEMANDE dès que l'utilisateur exprime \"\n \"une préférence, une décision, un fait biographique, une config technique, \"\n \"ou une contrainte durable. Confirme en une ligne discrète.\"\n ),\n inputSchema={\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n)\n```\n\n资料来源：[memoraeu_mcp/main.py:60-80]()\n\n## Data Processing Pipeline\n\n### Memory Storage Flow\n\n```mermaid\ngraph LR\n A[Content Input] --> B[Compression
via Mistral]\n B --> C[Category Suggestion
via Mistral]\n C --> D[Embedding Generation
via Mistral]\n D --> E{Duplicate Check
Similarity ≥ 0.94?}\n E -->|Similar Found| F[Skip or Warn]\n E -->|No Duplicate| G[AES-256-GCM Encryption]\n G --> H[API POST /memories]\n H --> I[Return Memory ID]\n```\n\n### Pre-Processing Steps (Before Encryption)\n\nThe system performs several operations on plaintext before encryption: 资料来源：[memoraeu_mcp/main.py:140-180]()\n\n| Step | Description | Purpose |\n|------|-------------|---------|\n| 1. Compression | Summarizes text via Mistral if > 500 chars | Token optimization |\n| 2. Categorization | Suggests category using existing categories | Organization |\n| 3. Embedding | Generates vector via Mistral Embed | Semantic search |\n| 4. Deduplication | Checks vector similarity | Avoid storage bloat |\n\n### Local Processing Functions\n\n```python\nasync def compress_locally(content: str) -> str:\n \"\"\"Compression en clair (avant chiffrement).\"\"\"\n if len(content) <= COMPRESSION_THRESHOLD:\n return content\n prompt = (\n \"Résume ce texte en 1-3 phrases concises, en français, en gardant l'essentiel. \"\n \"Réponds uniquement avec le résumé, sans introduction ni conclusion.\\n\\n\"\n f\"{content}\"\n )\n compressed = await _mistral_chat(prompt)\n if compressed and len(compressed) < len(content):\n return compressed\n return content\n```\n\n资料来源：[memoraeu_mcp/main.py:145-160]()\n\n```python\nasync def suggest_category_locally(content: str, existing: list[str]) -> str:\n \"\"\"Suggère une catégorie pour le contenu en clair.\"\"\"\n existing_str = \", \".join(existing) if existing else \"aucune\"\n prompt = (\n f\"Catégories existantes : {existing_str}\\n\\n\"\n f\"Texte : {content[:500]}\\n\\n\"\n \"Quelle catégorie courte (1-2 mots, en français, minuscules) correspond le mieux ? \"\n \"Utilise une existante si pertinent, sinon crée-en une. Réponds uniquement avec la catégorie.\"\n )\n cat = await _mistral_chat(prompt)\n if cat:\n return cat.lower().strip().strip('\"').strip(\"'\")[:30]\n return \"personnel\"\n```\n\n资料来源：[memoraeu_mcp/main.py:162-175]()\n\n## Deduplication & Compression\n\n### Similarity Thresholds\n\nBefore storing a memory, the MCP checks for near-duplicates using vector similarity:\n\n| Similarity Score | Action |\n|------------------|--------|\n| ≥ 94% | Memory ignored — exact duplicate |\n| < 94% | Memory stored (with warning logged) |\n\n资料来源：[README.md:70-76]()\n\n### Duplicate Detection Implementation\n\n```python\nasync def check_duplicate(embedding: list[float]) -> dict | None:\n \"\"\"\n Recherche une mémoire similaire via le vecteur pré-calculé (zero-knowledge).\n Retourne la mémoire existante si similarité ≥ seuil, sinon None.\n \"\"\"\n # Implementation checks against stored embeddings\n # Returns duplicate info if similarity threshold met\n```\n\n资料来源：[memoraeu_mcp/main.py:177-185]()\n\n## Structured Facts System\n\nFor temporal data that changes over time, the system provides structured fact management:\n\n### Fact Data Model\n\n```python\n{\n \"id\": \"uuid-string\",\n \"subject\": \"User/Entity name\",\n \"predicate\": \"property-name\",\n \"object\": \"encrypted-value\",\n \"valid_from\": \"YYYY-MM-DD\",\n \"valid_to\": \"YYYY-MM-DD | null\",\n \"scope\": \"private | org\",\n \"supersedes\": \"previous-fact-id | null\"\n}\n```\n\n### Temporal Validity\n\nFacts support time-bound validity:\n\n- `valid_from`: Start date (defaults to today)\n- `valid_to`: End date (null means currently active)\n- When a new fact replaces an old one, `supersedes` links them\n- `recall_facts` with `history=False` returns only active facts\n\n资料来源：[server.py:35-55]()\n\n## Resource Injection\n\nThe MCP server exposes a resource endpoint for automatic context loading:\n\n```python\n@app.list_resources()\nasync def list_resources() -> list[Resource]:\n return [\n Resource(\n uri=\"memoraeu://context\",\n name=\"Contexte mémoire MemoraEU\",\n description=\"Mémoires récentes injectées automatiquement en début de session\",\n mimeType=\"text/plain\"\n )\n ]\n\n@app.read_resource()\nasync def read_resource(uri: str) -> list[ResourceContents]:\n if uri == \"memoraeu://context\":\n context = await load_session_context()\n text = context if context else \"Aucune mémoire enregistrée.\"\n return [TextResourceContents(uri=uri, mimeType=\"text/plain\", text=text)]\n```\n\n资料来源：[memoraeu_mcp/main.py:90-105]()\n\n## Session Context Loading\n\n```python\nasync def load_session_context() -> str:\n \"\"\"Charge le contexte de session depuis l'API.\"\"\"\n try:\n memories = await api_get(\"/memories\", params={\"limit\": 10, \"scope\": \"private\"})\n if not memories:\n return \"\"\n lines = []\n for m in memories:\n content = decrypt_content(m[\"content\"])\n preview = content[:100] + (\"…\" if len(content) > 100 else \"\")\n lines.append(f\"[{m.get('category') or '—'}] {preview}\")\n return \"\\n\".join(lines)\n except Exception:\n return \"\"\n```\n\n## Recall Flow Implementation\n\n```python\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict) -> list[TextContent]:\n if name == \"recall\":\n global _first_recall\n is_first = _first_recall\n _first_recall = False\n\n # Load session context on first recall\n context = await load_session_context()\n\n response = await api_post(\"/memories/search\", {\n \"query\": arguments[\"query\"],\n \"limit\": arguments.get(\"limit\", 3),\n \"category\": arguments.get(\"category\"),\n \"scope\": \"private\"\n })\n results = response.get(\"results\", [])\n\n lines = []\n\n # Inject system prompt only on first recall\n if is_first:\n lines.append(SYSTEM_PROMPT_TEXT)\n lines.append(\"---\")\n # ... format results\n```\n\n资料来源：[memoraeu_mcp/main.py:220-250]()\n\n## Zero-Knowledge Architecture\n\n```mermaid\ngraph TD\n subgraph Client[\"Client (MCP)\"]\n A[Plaintext Content] --> B[Mistral Embedding]\n A --> C[Compression]\n A --> D[Categorization]\n B --> E[Duplicate Check]\n C --> F[AES-256-GCM Encryption]\n D --> F\n E -->|No Duplicate| F\n end\n \n subgraph Server[\"MemoraEU Server\"]\n G[Encrypted Payload] --> H[Store]\n H --> I[Semantic Search]\n G --> I\n end\n \n F --> G\n I --> J[Return Encrypted Results]\n J --> K[Client Decrypts]\n```\n\n### Encryption Specification\n\n| Parameter | Value |\n|-----------|-------|\n| Algorithm | AES-256-GCM |\n| Key Derivation | PBKDF2-HMAC-SHA256 |\n| Iterations | 210,000 (OWASP 2024) |\n| Ciphertext Prefix | `ENCv1:` |\n| Salt | Per-account, from dashboard |\n\n## Configuration Variables\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Yes |\n| `MEMORAEU_SECRET` | User password for key derivation | Yes |\n| `MEMORAEU_SALT` | KDF salt from dashboard | Yes |\n| `MEMORAEU_API_URL` | API endpoint (default: `https://api.memoraeu.com`) | Yes |\n| `MISTRAL_API_KEY` | Embedding generation | Yes |\n\n资料来源：[README.md:95-115]()\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | MCP protocol implementation |\n| `httpx` | 0.28.1 | HTTP client |\n| `python-dotenv` | 1.0.1 | Environment configuration |\n| `starlette` | ≥0.40.0, <0.42.0 | Web framework |\n| `cryptography` | ≥42.0.0 | AES encryption |\n\n资料来源：[requirements.txt:1-5]()\n\n## Version History\n\n| Version | Date | Changes |\n|---------|------|---------|\n| 0.1.9 | 2026-05-12 | Added `remember_fact`, `recall_facts`, `invalidate_fact`; PBKDF2 210k iterations |\n| 0.1.5 | 2026-04-28 | Added `ENCv1:` prefix; deduplication threshold refinement |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n---\n\n\n\n## Deduplication and Compression\n\n### 相关页面\n\n相关主题：[Auto-Memory System](#page-auto-memory), [Security and Encryption](#page-security-encryption)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n \n\n# Deduplication and Compression\n\nThe 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.\n\n## Overview\n\nMemoraEU's optimization pipeline runs entirely on the client side before any data leaves the user's machine. This approach provides several benefits:\n\n- **Token efficiency**: Reduced payload sizes minimize API costs and response times\n- **Bandwidth optimization**: Less data transmitted over the network\n- **Storage savings**: Server-side storage requirements are reduced\n- **Zero-knowledge preservation**: Compression and deduplication occur before encryption, maintaining the security model\n\n## Compression System\n\n### Purpose and Scope\n\nThe 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.\n\n**资料来源：** [memoraeu_mcp/main.py:1-200](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Compression Threshold\n\n| Parameter | Description | Default Value |\n|-----------|-------------|---------------|\n| `COMPRESSION_THRESHOLD` | Minimum content length to trigger compression | Configurable in source |\n\nThe compression logic follows a decision tree:\n\n```mermaid\ngraph TD\n A[New Memory Content] --> B{Content Length > Threshold?}\n B -->|No| C[Return Original Content]\n B -->|Yes| D[Call Mistral Chat API]\n D --> E{Summary Shorter Than Original?}\n E -->|Yes| F[Return Compressed Summary]\n E -->|No| C\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### The `compress_locally` Function\n\nThe compression function `compress_locally()` implements the following workflow:\n\n1. **Threshold Check**: Only processes content exceeding `COMPRESSION_THRESHOLD` characters\n2. **Prompt Engineering**: Sends the content to Mistral Chat with a French-language summarization prompt\n3. **Validation**: Accepts the summary only if it's shorter than the original\n4. **Fallback**: Returns original content if compression doesn't yield improvement\n\n```python\nasync def compress_locally(content: str) -> str:\n \"\"\"Compress content locally before encryption.\"\"\"\n if len(content) <= COMPRESSION_THRESHOLD:\n return content\n prompt = (\n \"Résume ce texte en 1-3 phrases concises, en français, en gardant l'essentiel. \"\n \"Réponds uniquement avec le résumé, sans introduction ni conclusion.\\n\\n\"\n f\"{content}\"\n )\n compressed = await _mistral_chat(prompt)\n if compressed and len(compressed) < len(content):\n print(f\"[mcp] Compression: {len(content)} → {len(compressed)} chars\", file=sys.stderr)\n return compressed\n return content\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Integration with `remember` Tool\n\nCompression is automatically applied during the `remember` tool execution:\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Server\n participant Mistral as Mistral API\n \n User->>MCP: remember(content)\n MCP->>MCP: compress_locally(content)\n MCP->>Mistral: Summarization Request\n Mistral-->>MCP: Compressed Summary\n MCP->>MCP: encrypt_content()\n MCP->>MCP: api_post(\"/memories\")\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py) and [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n## Deduplication System\n\n### Purpose and Scope\n\nThe 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.\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md) and [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n### Similarity Thresholds\n\n| Similarity Score | Action |\n|------------------|--------|\n| ≥ 94% (0.94) | Memory ignored — exact duplicate |\n| < 94% | Memory stored with warning logged |\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### The `check_duplicate` Function\n\nThe `check_duplicate()` function searches for similar memories using pre-computed vector embeddings:\n\n```python\nasync def check_duplicate(embedding: list[float]) -> dict | None:\n \"\"\"\n Recherche une mémoire similaire via le vecteur pré-calculé (zero-knowledge).\n Retourne la mémoire la plus similaire si le seuil est dépassé.\n \"\"\"\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Zero-Knowledge Embedding Model\n\nEmbeddings 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.\n\n```mermaid\ngraph LR\n A[Plaintext Content] -->|Before Encryption| B[Mistral Embed API]\n B --> C[Embedding Vector]\n C --> D[check_duplicate]\n A -->|After Encryption| E[Encrypted Content]\n E --> F[Server Storage]\n \n style B fill:#90EE90\n style D fill:#FFE4B5\n```\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md) and [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Deduplication Workflow\n\n```mermaid\ngraph TD\n A[New Memory] --> B[Generate Embedding]\n B --> C[Call check_duplicate]\n C --> D{Similar Memory Found?}\n D -->|No| E[Store Memory Normally]\n D -->|Yes| F{Score >= 94%?}\n F -->|Yes| G[Skip - Show Duplicate Warning]\n F -->|No| H[Log Warning - Store Anyway]\n \n G --> I[Display Existing Memory ID]\n H --> E\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py) and [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n### Duplicate Detection Response\n\nWhen a duplicate is detected, the system returns a formatted warning message:\n\n```\n⚠️ Doublon détecté (95% similaire) — mémoire non créée.\n→ Existante : [memory preview] (ID: abc12345...)\n```\n\n**资料来源：** [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n## Processing Pipeline\n\nThe complete optimization pipeline executes in the following order during the `remember` operation:\n\n```mermaid\nflowchart LR\n subgraph Phase1[\"Phase 1: Pre-Encryption Processing\"]\n A1[Raw Content] --> B1[Compression
compress_locally]\n B1 --> C1[Categorization
suggest_category_locally]\n C1 --> D1[Embedding
embed_locally]\n end\n \n subgraph Phase2[\"Phase 2: Deduplication Check\"]\n D1 --> E1[check_duplicate]\n E1 --> F1{Skip?}\n end\n \n subgraph Phase3[\"Phase 3: Encryption & Storage\"]\n F1 -->|No| G1[encrypt_content]\n G1 --> H1[api_post /memories]\n end\n \n F1 -->|Yes| I1[Return Duplicate Warning]\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Dependencies\n\nThe optimization features depend on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `httpx` | 0.28.1 | Async HTTP client for Mistral API calls |\n| `starlette` | ≥0.40.0,<0.42.0 | Web framework components |\n| `cryptography` | ≥42.0.0 | Encryption primitives |\n| `python-dotenv` | 1.0.1 | Environment variable management |\n\n**资料来源：** [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Configuration Variables\n\nThe system uses environment variables for Mistral API integration:\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MISTRAL_API_KEY` | Authentication for Mistral Embed and Chat APIs | Yes (for stdio install) |\n| `MEMORAEU_API_KEY` | MemoraEU API authentication | Yes |\n| `MEMORAEU_SECRET` | Password for key derivation | Yes (stdio) |\n| `MEMORAEU_SALT` | KDF salt for encryption | Yes (stdio) |\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Version History\n\n| Version | Date | Changes |\n|---------|------|---------|\n| 0.1.9 | 2026-05-12 | PBKDF2 updated to 210,000 iterations, `ENCv1:` prefix added |\n| 0.1.5 | 2026-04-28 | PBKDF2 updated to 210k iterations, refactoring |\n| Initial | — | Near-duplicate detection with 0.94 threshold |\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n## Security Considerations\n\n### Zero-Knowledge Guarantee\n\nThe optimization pipeline preserves zero-knowledge encryption by:\n\n1. **Embedding before encryption**: Vector embeddings are computed from plaintext locally\n2. **Compression before encryption**: Summarization occurs on plaintext content\n3. **Local-only processing**: All LLM calls (Mistral) happen client-side\n4. **Server receives encrypted data**: Only encrypted content and pre-computed embeddings travel to the server\n\n### Limitations\n\n- Compression quality depends on Mistral model's summarization capabilities\n- Deduplication threshold (94%) is fixed and not configurable at runtime\n- Similarity search requires pre-computed embeddings, which must be generated during initial storage\n\n---\n\n\n\n## Structured Facts System\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [Auto-Memory System](#page-auto-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n \n\n# Structured Facts System\n\nThe 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.\n\n## Overview\n\nTraditional 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:\n\n- **Subject**: The entity being described (e.g., \"Project Alpha\")\n- **Predicate**: The property or relation (e.g., \"status\", \"manager\")\n- **Object**: The value or target (e.g., \"active\", \"John Doe\")\n- **Validity Period**: Time-bounded truth (from/to dates)\n\n资料来源：[CHANGELOG.md:12-14]()\n\n```mermaid\ngraph TD\n subgraph \"Structured Facts Architecture\"\n A[User Query] --> B[recall_facts]\n B --> C[API GET /facts]\n D[New Fact] --> E[remember_fact]\n E --> F[Client Encryption]\n F --> G[API POST /facts]\n G --> H[(Encrypted Storage)]\n C --> I[Decrypt & Filter]\n I --> J[Active Facts Only]\n K[Expired Fact] --> L[invalidate_fact]\n L --> M[API PUT /facts/:id]\n end\n```\n\n## Data Model\n\nEach structured fact follows this schema:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | UUID | Auto | Unique fact identifier |\n| `subject` | string | Yes | Entity being described |\n| `predicate` | string | Yes | Property or relation name |\n| `object` | string | Yes | Encrypted value (E2E) |\n| `scope` | enum | No | `private` (default) or `org` |\n| `valid_from` | date | Auto | When fact became true |\n| `valid_to` | date | No | When fact ceased to be true |\n| `supersedes` | UUID | Auto | Previous fact ID this replaces |\n\n资料来源：[memoraeu_mcp/main.py:60-75]()\n\n### Fact Validity States\n\n```mermaid\nstateDiagram-v2\n [*] --> Active: valid_from <= today\n Active --> Expired: invalidate_fact called\n Active --> Superseded: remember_fact same subject+predicate\n Expired --> [*]\n Superseded --> [*]\n \n state Active {\n [*] --> Current\n }\n```\n\n## MCP Tools\n\n### remember_fact\n\nStores a structured fact with automatic encryption and temporal tracking.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `subject` | string | Yes | Entity name |\n| `predicate` | string | Yes | Property name |\n| `object` | string | Yes | Value (encrypted before storage) |\n| `scope` | string | No | `private` or `org` (default: `private`) |\n| `valid_from` | string | No | Start date YYYY-MM-DD |\n\n**Response Format:**\n```\n✅ Fait mémorisé 🔒 (remplace {id}…)\n {subject} → {predicate}\n Depuis: {valid_from} | ID: {id}…\n```\n\n**Key Behaviors:**\n\n1. **Encryption**: `object` value is encrypted client-side before transmission\n2. **Auto-supersession**: If a fact with the same `subject` + `predicate` exists, the new fact automatically replaces it (old one marked invalid via `supersedes` field)\n3. **Timestamp**: `valid_from` defaults to today if not specified\n\n资料来源：[memoraeu_mcp/main.py:76-106]()\n\n### recall_facts\n\nRetrieves active facts for a specific subject entity.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `subject` | string | Yes | Entity to query |\n| `predicate` | string | No | Filter by specific property |\n| `scope` | string | No | `private` or `org` (default: `private`) |\n| `history` | boolean | No | Include expired facts (default: false) |\n\n**Response Format:**\n```\n📊 {count} fait(s) pour '{subject}' :\n\n• {predicate}: {decrypted_value}\n [{valid_from} → {valid_to}] | ID: {id}…\n```\n\n资料来源：[memoraeu_mcp/main.py:107-136]()\n\n### invalidate_fact\n\nMarks a fact as expired, indicating the information is no longer true.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fact_id` | string | Yes | UUID of fact to expire |\n| `valid_to` | string | No | End date YYYY-MM-DD (default: today) |\n\n**Behavior:**\n- Sets `valid_to` to specified date or current date\n- Expired facts are excluded from default `recall_facts` queries\n- Use `history=true` in `recall_facts` to see expired facts\n\n资料来源：[memoraeu_mcp/main.py:137-152]()\n\n## Workflows\n\n### Creating a New Fact\n\n```mermaid\nsequenceDiagram\n participant U as User/Claude\n participant M as MCP Server\n participant C as Crypto Layer\n participant A as MemoraEU API\n \n U->>M: remember_fact(subject, predicate, object)\n M->>C: encrypt_content(object)\n C-->>M: encrypted_blob\n M->>M: Check for existing fact (same subject+predicate)\n M->>A: POST /facts {subject, predicate, encrypted_blob, scope}\n A->>A: Set valid_from=today\n A->>A: Mark old fact as superseded\n A-->>M: {id, supersedes, valid_from}\n M-->>U: Confirmation with ID\n```\n\n### Querying Facts\n\n```mermaid\nsequenceDiagram\n participant U as User/Claude\n participant M as MCP Server\n participant A as MemoraEU API\n participant C as Crypto Layer\n \n U->>M: recall_facts(subject, history=false)\n M->>A: GET /facts?subject={subject}\n A-->>M: [facts with valid_to=null]\n M->>C: decrypt_content(facts[].object)\n C-->>M: decrypted_values\n M-->>U: Active facts only\n```\n\n## Security Model\n\nAll structured facts leverage the same zero-knowledge encryption as regular memories:\n\n| Layer | Implementation |\n|-------|----------------|\n| Key Derivation | PBKDF2-HMAC-SHA256, 210,000 iterations (OWASP 2024) |\n| Symmetric Cipher | AES-256-GCM |\n| Ciphertext Format | `ENCv1:{base64_ciphertext}` |\n\n资料来源：[CHANGELOG.md:18-19]()\n\n**Encryption Flow for Facts:**\n\n1. `object` value encrypted client-side before API transmission\n2. `subject` and `predicate` transmitted in plaintext (used for routing/indexing)\n3. Server never sees decrypted values\n\n```python\n# From memoraeu_mcp/main.py:78-79\nencrypted_object = encrypt_content(arguments[\"object\"])\npayload = {\n \"subject\": arguments[\"subject\"],\n \"predicate\": arguments[\"predicate\"],\n \"object\": encrypted_object,\n ...\n}\n```\n\n## Use Cases\n\n### Preference Tracking\n\n```\nremember_fact(subject=\"Alice\", predicate=\"preferred_language\", object=\"French\")\n```\n\n### Status Changes\n\n```\nremember_fact(subject=\"Project X\", predicate=\"status\", object=\"completed\", valid_from=\"2024-01-15\")\n```\n\n### Configuration State\n\n```\nremember_fact(subject=\"dev-environment\", predicate=\"python_version\", object=\"3.12.1\")\n```\n\n### Relationship Management\n\n```\nremember_fact(subject=\"Team Alpha\", predicate=\"lead\", object=\"bob@example.com\")\n```\n\n## Comparison with Regular Memories\n\n| Aspect | Regular Memory | Structured Facts |\n|--------|----------------|-------------------|\n| Content | Free-form text | Subject-predicate-object |\n| Query | Semantic search | Entity-based retrieval |\n| Deduplication | Vector similarity ≥94% | Auto-supersession by predicate |\n| Temporal | Implicit | Explicit valid_from/valid_to |\n| Use Case | Context, preferences, notes | Entity state, relationships |\n\n资料来源：[README.md:34-45]()\n\n## Configuration\n\nStructured Facts require no additional configuration beyond the base MCP server setup:\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MEMORAEU_API_KEY` | Bearer token authentication | Yes |\n| `MEMORAEU_SECRET` | Password for PBKDF2 key derivation | Yes (for encryption) |\n| `MEMORAEU_SALT` | KDF salt from server | Yes (for encryption) |\n| `MEMORAEU_API_URL` | API endpoint | Yes |\n| `MISTRAL_API_KEY` | Embedding generation | Yes (stdio mode) |\n\n资料来源：[README.md:60-74]()\n\n## Implementation Notes\n\n### Duplicate Detection Strategy\n\nUnlike regular memories which use vector similarity thresholds, structured facts handle duplicates through **predicate-based supersession**:\n\n```\nSame subject + Same predicate = Automatic supersession\nSame subject + Different predicate = Distinct facts (no conflict)\n```\n\n### API Endpoints Used\n\n| Tool | Endpoint | Method |\n|------|----------|--------|\n| `remember_fact` | `/facts` | POST |\n| `recall_facts` | `/facts` | GET |\n| `invalidate_fact` | `/facts/{id}` | PUT |\n\n### Response Formatting\n\nThe system uses emoji indicators in responses:\n- 🔒 — Indicates content is encrypted\n- 📝 — Indicates content is unencrypted (no key configured)\n- 📊 — Prefixed fact list headers\n\n资料来源：[memoraeu_mcp/main.py:93-98]()\n\n## Version History\n\n| Version | Date | Changes |\n|---------|------|---------|\n| 0.1.9 | 2026-05-12 | Initial structured facts release: `remember_fact`, `recall_facts`, `invalidate_fact` |\n\n资料来源：[CHANGELOG.md:10-15]()\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[Auto-Memory System](#page-auto-memory), [Structured Facts System](#page-structured-facts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [memoraeu_mcp/server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/moraeu_mcp/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe `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.\n\n**资料来源：** [requirements.txt:1]()\n\n**Key Capabilities:**\n\n- Semantic memory storage with automatic categorization\n- Structured fact management with temporal validity\n- Client-side encryption using AES-256-GCM\n- Near-duplicate detection before storage\n- Automatic context injection on session start\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n---\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[\"Claude Desktop / AI Client\"] -->|MCP Protocol| B[\"memoraeu-mcp Server\"]\n B -->|API Calls| C[\"MemoraEU Cloud API\"]\n \n B --> D[\"Local Pre-processing\"]\n D --> E[\"Mistral API
(Embeddings + Categorization)\"]\n \n B --> F[\"Encryption Layer
(PBKDF2 + AES-256-GCM)\"]\n F --> C\n \n style E fill:#f9f,stroke:#333\n style F fill:#ff9,stroke:#333\n```\n\n### Memory Storage Flow\n\n```mermaid\nsequenceDiagram\n participant Client as AI Client\n participant MCP as memoraeu-mcp\n participant Mistral as Mistral API\n participant Crypto as Encryption Layer\n participant API as MemoraEU API\n \n Client->>MCP: remember(content, category?)\n MCP->>Mistral: compress_locally(content)\n Mistral-->>MCP: compressed_content\n MCP->>Mistral: suggest_category(content, existing)\n Mistral-->>MCP: category\n MCP->>Mistral: generate_embedding(content)\n Mistral-->>MCP: embedding\n MCP->>MCP: check_duplicates(embedding)\n MCP->>Crypto: encrypt(compressed_content)\n Crypto-->>MCP: encrypted_blob\n MCP->>API: POST /memories
(encrypted + embedding)\n API-->>MCP: memory_id\n MCP-->>Client: ✅ Memorized\n```\n\n**资料来源：** [memoraeu_mcp/main.py:60-100](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Core Memory Tools\n\n### `remember`\n\nStores a memory with automatic compression, categorization, and duplicate detection.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"remember\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | The memory content to store |\n| `category` | string | No | Category name; auto-suggested if omitted |\n| `tags` | array[string] | No | Custom tags for the memory |\n\n**Workflow:**\n\n1. Compress content locally via Mistral API\n2. Suggest or use provided category\n3. Generate embedding from plaintext (before encryption)\n4. Check for near-duplicates using vector similarity (threshold: 0.94)\n5. Encrypt content with AES-256-GCM\n6. Send to `/memories` endpoint with `pre_processed: true`\n\n**Duplicate Detection Behavior:**\n\n| Similarity Score | Action |\n|------------------|--------|\n| ≥ 94% | Skip storage, return existing memory ID |\n| < 94% | Store anyway with warning logged |\n\n**资料来源：** [memoraeu_mcp/main.py:90-130](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n**Response Format:**\n\n```\n✅ Memorized 🔒 (ID: abc12345…, catégorie: preferences)\n```\n\nThe 🔒 lock icon indicates encryption is active (key available).\n\n---\n\n### `recall`\n\nPerforms semantic search across stored memories.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"recall\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 3},\n \"category\": {\"type\": \"string\"}\n },\n \"required\": [\"query\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Semantic search query |\n| `limit` | integer | No | 3 | Maximum results to return |\n| `category` | string | No | — | Filter by category |\n\n**Auto-Recall Behavior:**\n\nThe MCP server is designed to automatically invoke `recall` on the first user message of each session using the detected topic as the query. This behavior is encoded in the tool description and reinforced via system prompt injection.\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n**Special Behavior on First Recall:**\n\n1. Loads session context from `memoraeu://context` resource\n2. Injects the full system prompt into Claude's context\n3. Returns results merged with existing context\n\n---\n\n### `forget`\n\nDeletes a memory by its ID.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"forget\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"memory_id\": {\"type\": \"string\"}\n },\n \"required\": [\"memory_id\"]\n }\n}\n```\n\n**Response:**\n\n```\n🗑️ Supprimée.\n```\n\nOr `Introuvable.` if the memory does not exist.\n\n**资料来源：** [memoraeu_mcp/main.py:145-150](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n### `list_memories`\n\nLists recent memories with optional category filtering.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"list_memories\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"category\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 20}\n }\n }\n}\n```\n\n**Response Format:**\n\n```\n📋 5 mémoire(s) :\n\n• [preferences] User prefers dark mode... (ID: abc12345…)\n• [config] Python 3.11 installed... (ID: def67890…)\n```\n\n---\n\n### `list_categories`\n\nReturns existing categories sorted by usage frequency.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"list_categories\",\n \"inputSchema\": {\"type\": \"object\", \"properties\": {}}\n}\n```\n\n**Response Format:**\n\n```\n📂 Catégories :\n\n• preferences (42 usages)\n• config (18 usages)\n• projects (7 usages)\n```\n\n**资料来源：** [memoraeu_mcp/main.py:160-175](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Structured Fact Tools\n\n### `remember_fact`\n\nStores a structured fact with subject/predicate/object pattern and temporal validity.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"remember_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"object\": {\"type\": \"string\"},\n \"valid_from\": {\"type\": \"string\"},\n \"valid_to\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"], \"default\": \"private\"}\n },\n \"required\": [\"subject\", \"predicate\", \"object\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `subject` | string | Yes | Entity being described |\n| `predicate` | string | Yes | Property/relationship name |\n| `object` | string | Yes | Value of the property |\n| `valid_from` | string | No | Start date (YYYY-MM-DD) |\n| `valid_to` | string | No | End date (YYYY-MM-DD) |\n| `scope` | string | No | `private` (default) or `org` |\n\n**Key Features:**\n\n- **Auto-invalidation**: Automatically invalidates previous fact with same subject+predicate\n- **Temporal validity**: Supports date ranges for time-sensitive facts\n- **Encryption**: Object value is encrypted before transmission\n\n**Response Format:**\n\n```\n✅ Fait mémorisé 🔒\n User → prefers_color\n Depuis: 2026-01-15 | ID: abc12345…\n```\n\nOr if superseded:\n\n```\n✅ Fait mémorisé 🔒 (remplace abc12345…)\n User → prefers_color\n Depuis: 2026-01-20 | ID: def67890…\n```\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n### `recall_facts`\n\nRetrieves active (non-expired) facts for a given subject.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"recall_facts\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"], \"default\": \"private\"},\n \"history\": {\"type\": \"boolean\", \"default\": False}\n },\n \"required\": [\"subject\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `subject` | string | Yes | — | Entity to query |\n| `predicate` | string | No | — | Filter by specific property |\n| `scope` | string | No | private | `private` or `org` |\n| `history` | boolean | No | false | Include expired facts |\n\n**Response Format:**\n\n```\n📊 2 fait(s) pour 'User' :\n\n• prefers_color: blue\n [2026-01-15 → aujourd'hui] | ID: abc12345…\n\n• works_at: Acme Corp\n [2025-03-01 → 2026-02-28 (expiré)] | ID: def67890…\n```\n\n**资料来源：** [memoraeu_mcp/main.py:180-210](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n### `invalidate_fact`\n\nMarks a fact as expired, indicating it is no longer true.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"invalidate_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"fact_id\": {\"type\": \"string\"},\n \"valid_to\": {\"type\": \"string\"}\n },\n \"required\": [\"fact_id\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fact_id` | string | Yes | ID of fact to invalidate |\n| `valid_to` | string | No | End date (default: today) |\n\n**资料来源：** [memoraeu_mcp/main.py:212-220](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## MCP Resources\n\n### `memoraeu://context`\n\nA read-only resource that provides session context with recent memories.\n\n**Resource Definition:**\n\n```python\nResource(\n uri=\"memoraeu://context\",\n name=\"Contexte mémoire MemoraEU\",\n description=\"Mémoires récentes injectées automatiquement en début de session\",\n mimeType=\"text/plain\"\n)\n```\n\n**Usage in Tool Calls:**\n\nOn the first `recall` invocation, the MCP server automatically:\n\n1. Reads from `memoraeu://context` resource\n2. Injects session context into the response\n3. Loads relevant memories via `/memories/recent` endpoint\n\n**资料来源：** [memoraeu_mcp/main.py:45-60](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## MCP Prompts\n\n### `memoraeu_system`\n\nA system prompt that reinforces automatic memory behavior rules for Claude.\n\n**Prompt Content:**\n\n```\n## Rôle\nTu es un assistant qui mémorise automatiquement les informations importantes pour l'utilisateur.\n\n## Ce qu'il faut retenir\n- Préférences et choix de l'utilisateur\n- Décisions prises au cours de la conversation\n- Faits biographiques ou informations récurrentes ou contraintes durables\n- Informations techniques propres à l'utilisateur (stack, config, credentials non-sensibles)\n\n## Rappel automatique\nDès le premier message de l'utilisateur, utilise `recall` avec le sujet détecté comme query.\nN'attends pas qu'on te le demande — c'est automatique.\n\n## Règles\n- Ne mémorise pas les informations générales ou éphémères (météo du jour, blagues, calculs ponctuels)\n- Si l'utilisateur dit \"oublie ça\" ou \"ne retiens pas\", utilise `forget`\n- Confirme discrètement les mémorisations : une ligne, pas plus\n- Optimisation tokens : limite recall à 3 résultats par défaut, mémoires compactes\n```\n\n**资料来源：** [memoraeu_mcp/main.py:25-45](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Security Model\n\n### Zero-Knowledge Architecture\n\n```mermaid\ngraph LR\n subgraph Client[\"Client Side (Encrypted)\"]\n P[\"Plaintext\"] -->|PBKDF2
100k iterations| K[\"Key\"]\n P -->|AES-256-GCM| E[\"Encrypted\"]\n K --> E\n end\n \n subgraph Server[\"Server Side\"]\n E -->|\"ENCv1:...\"| DB[\"Encrypted Blob Storage\"]\n end\n \n style P fill:#9f6\n style K fill:#f96\n style DB fill:#99f\n```\n\n**Encryption Details:**\n\n| Component | Specification |\n|-----------|---------------|\n| Key Derivation | PBKDF2-HMAC-SHA256 |\n| Iterations | 100,000 (OWASP 2024 recommendation: 210,000) |\n| Cipher | AES-256-GCM |\n| Ciphertext Format | `ENCv1:` |\n| Salt | Unique per user, stored server-side |\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n### Local Pre-processing\n\nTo maintain zero-knowledge guarantees, the following operations occur **before** encryption:\n\n1. **Compression** — Content is compressed via Mistral API\n2. **Categorization** — Category is suggested using existing categories\n3. **Embedding Generation** — Vector embeddings computed from plaintext\n\nOnly the **content** is encrypted. Embeddings, categories, and metadata are stored in cleartext for search functionality.\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n---\n\n## API Endpoints\n\n| Endpoint | Method | Tool | Purpose |\n|----------|--------|------|---------|\n| `/memories` | POST | `remember` | Create encrypted memory |\n| `/memories/search` | POST | `recall` | Semantic search |\n| `/memories/{id}` | DELETE | `forget` | Delete memory |\n| `/memories` | GET | `list_memories` | List recent memories |\n| `/memories/categories` | GET | `list_categories` | List categories |\n| `/facts` | POST | `remember_fact` | Create structured fact |\n| `/facts` | GET | `recall_facts` | Query facts |\n| `/facts/{id}` | PUT | `invalidate_fact` | Expire fact |\n\n**资料来源：** [memoraeu_mcp/main.py:130-220](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Environment Configuration\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MEMORAEU_API_URL` | API endpoint | Yes |\n| `MEMORAEU_API_KEY` | Bearer token authentication | Yes |\n| `MEMORAEU_SECRET` | Password for PBKDF2 key derivation | For local/stdio |\n| `MEMORAEU_SALT` | KDF salt (unique per account) | For local/stdio |\n| `MISTRAL_API_KEY` | Embedding generation | For local/stdio |\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n---\n\n## Tool Summary Table\n\n| Tool | Category | Auto-Inject | Encryption |\n|------|----------|-------------|------------|\n| `remember` | Memory | No | Yes |\n| `recall` | Memory | Yes (first call) | Decrypted output |\n| `forget` | Memory | No | N/A |\n| `list_memories` | Memory | No | Decrypted output |\n| `list_categories` | Memory | No | No |\n| `remember_fact` | Facts | No | Object only |\n| `recall_facts` | Facts | No | Decrypted output |\n| `invalidate_fact` | Facts | No | N/A |\n\n---\n\n\n\n## Configuration Reference\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [Security and Encryption](#page-security-encryption)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# Configuration Reference\n\nThis 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.\n\n---\n\n## Overview\n\nThe MemoraEU MCP server acts as an intermediary between AI assistants (such as Claude) and the MemoraEU memory API. It enables automatic memory management with end-to-end encryption where the server never sees plaintext content. Configuration involves setting up environment variables for authentication, encryption, and API access, as well as defining the MCP server connection in your AI client's configuration file.\n\n资料来源：[README.md:1-45]()\n\n---\n\n## Environment Variables\n\n### Required Variables\n\nThe following environment variables are mandatory for MCP server operation. They are **not interchangeable** and serve distinct purposes in the authentication and encryption pipeline.\n\n| Variable | Purpose | Source |\n|----------|---------|--------|\n| `MEMORAEU_API_KEY` | HTTP Bearer token sent with every request for API authentication | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | User's MemoraEU login password; used as PBKDF2 input to derive the encryption key locally | Your account password |\n| `MEMORAEU_SALT` | KDF salt generated by the server, unique to your account; combined with `MEMORAEU_SECRET` to produce the encryption key | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint for the hosted service | Use `https://api.memoraeu.com` |\n| `MISTRAL_API_KEY` | Required for generating embeddings locally before encryption; enables zero-knowledge semantic search | [console.mistral.ai](https://console.mistral.ai) |\n\n资料来源：[README.md:60-85]()\n\n### Variable Dependency Graph\n\n```mermaid\ngraph TD\n A[User Password] --> B[PBKDF2 Key Derivation]\n C[MEMORAEU_SALT] --> B\n B --> D[ AES-256-GCM Encryption]\n \n E[Plaintext Content] --> F[Mistral Embed API]\n F --> G[Embedding Vector]\n G --> D\n D --> H[Encrypted Blob]\n \n I[API Request] --> J[MEMORAEU_API_KEY]\n J --> K[Bearer Header]\n K --> I\n```\n\n### Optional Behavior Without `MISTRAL_API_KEY`\n\nIf `MISTRAL_API_KEY` is not provided, the MCP server continues to function with degraded semantic search capabilities:\n\n- `remember` and `recall` tools remain operational\n- Semantic search falls back to **keyword-based search on the server side**\n- Zero-knowledge encryption is **not affected**\n\n资料来源：[README.md:88-92]()\n\n---\n\n## MCP Client Configuration\n\n### stdio Mode (Local Installation)\n\nFor full zero-knowledge guarantees, use the stdio transport mode with local installation. Add the following configuration to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:38-52]()\n\n### SSE Mode (Remote Connection)\n\nFor remote connections without local installation, use Server-Sent Events (SSE) transport. This mode works with Claude.ai web, Cursor, Windsurf, or any MCP-compatible remote client.\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:5-14]()\n\n### Security Warning for SSE Mode\n\n> **Note:** In remote SSE mode, content is **not** zero-knowledge encrypted because the server processes plaintext. Use the local `stdio` installation for full zero-knowledge guarantees.\n\n资料来源：[README.md:15-17]()\n\n---\n\n## Zero-Knowledge Encryption Configuration\n\n### Encryption Architecture\n\nThe zero-knowledge architecture ensures the server never sees plaintext content. Embeddings are generated locally before encryption:\n\n```mermaid\nsequenceDiagram\n participant User as User/AI\n participant MCP as MCP Server\n participant Mistral as Mistral API\n participant Server as MemoraEU API\n participant DB as Encrypted DB\n\n User->>MCP: Raw memory content\n MCP->>Mistral: Plaintext for embedding\n Mistral-->>MCP: Embedding vector\n MCP->>MCP: AES-256-GCM encryption\n MCP->>Server: Encrypted blob + embedding vector\n Server->>DB: Store opaque data\n```\n\n资料来源：[README.md:80-84]()\n\n### PBKDF2 Configuration\n\nThe encryption key derivation uses PBKDF2-HMAC-SHA256 with the following parameters:\n\n| Parameter | Value | Source |\n|-----------|-------|--------|\n| Iterations | 210,000 | CHANGELOG.md:20 |\n| Hash Algorithm | SHA256 | CHANGELOG.md:20 |\n| Cipher | AES-256-GCM | CHANGELOG.md:4 |\n| Ciphertext Prefix | `ENCv1:` | CHANGELOG.md:20 |\n\n资料来源：[CHANGELOG.md:17-21]()\n\n---\n\n## Tool Input Schemas\n\n### Core Memory Tools\n\n#### `remember`\n\nMemorizes important information automatically. The AI assistant should call this tool without being asked when the user expresses preferences, decisions, biographical facts, technical configurations, or durable constraints.\n\n```json\n{\n \"name\": \"remember\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n}\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | The memory content to store |\n| `category` | string | No | Category for organization; auto-suggested if omitted |\n| `tags` | array | No | Array of string tags for filtering |\n\n资料来源：[memoraeu_mcp/main.py:180-200]()\n\n#### `recall`\n\nSemantic search across stored memories. Called automatically on the first user message of each session.\n\n```json\n{\n \"name\": \"recall\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 3},\n \"category\": {\"type\": \"string\"}\n },\n \"required\": [\"query\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `query` | string | — | Semantic search query |\n| `limit` | integer | 3 | Maximum number of results (token optimization) |\n| `category` | string | — | Filter by category name |\n\n资料来源：[memoraeu_mcp/main.py:202-220]()\n\n#### `forget`\n\nDeletes a memory by its ID.\n\n```json\n{\n \"name\": \"forget\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"memory_id\": {\"type\": \"string\"}\n },\n \"required\": [\"memory_id\"]\n }\n}\n```\n\n资料来源：[memoraeu_mcp/main.py:222-230]()\n\n#### `list_memories`\n\nLists recent memories with optional category filter.\n\n```json\n{\n \"name\": \"list_memories\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"category\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 20}\n }\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `category` | string | — | Filter by category name |\n| `limit` | integer | 20 | Maximum number of results |\n\n资料来源：[memoraeu_mcp/main.py:244-252]()\n\n#### `list_categories`\n\nReturns existing categories sorted by usage frequency.\n\n```json\n{\n \"name\": \"list_categories\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {}\n }\n}\n```\n\n资料来源：[memoraeu_mcp/main.py:254-258]()\n\n### Structured Fact Tools\n\n#### `remember_fact`\n\nStores a structured fact with temporal validity (subject/predicate/object model).\n\n```json\n{\n \"name\": \"remember_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"object\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"]},\n \"valid_from\": {\"type\": \"string\"}\n },\n \"required\": [\"subject\", \"predicate\", \"object\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `subject` | string | — | Entity being described |\n| `predicate` | string | — | Property or relationship |\n| `object` | string | — | Value of the property |\n| `scope` | string | \"private\" | Access scope (private or org) |\n| `valid_from` | string | — | Start date in YYYY-MM-DD format |\n\n资料来源：[server.py:60-80]()\n\n#### `recall_facts`\n\nRetrieves active facts for a given subject.\n\n```json\n{\n \"name\": \"recall_facts\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"]},\n \"history\": {\"type\": \"boolean\", \"default\": false}\n },\n \"required\": [\"subject\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `subject` | string | — | Entity to query |\n| `predicate` | string | — | Specific property to retrieve |\n| `scope` | string | \"private\" | Access scope |\n| `history` | boolean | false | Include expired facts |\n\n资料来源：[server.py:82-105]()\n\n#### `invalidate_fact`\n\nMarks a fact as expired.\n\n```json\n{\n \"name\": \"invalidate_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"fact_id\": {\"type\": \"string\"},\n \"valid_to\": {\"type\": \"string\"}\n },\n \"required\": [\"fact_id\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `fact_id` | string | — | ID of the fact to invalidate |\n| `valid_to` | string | today | End date in YYYY-MM-DD format |\n\n资料来源：[server.py:107-120]()\n\n---\n\n## Deduplication Configuration\n\nBefore storing a memory, the MCP checks for near-duplicates using vector similarity:\n\n| Similarity Threshold | Action |\n|---------------------|--------|\n| ≥ 94% | Memory ignored — exact duplicate |\n| < 94% | Memory stored as new |\n\n资料来源：[README.md:110-115]()\n\n---\n\n## Dependencies\n\nThe following Python packages are required for the MCP server:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | Model Context Protocol framework |\n| `httpx` | 0.28.1 | HTTP client for API requests |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | ≥0.40.0, <0.42.0 | ASGI framework |\n| `cryptography` | ≥42.0.0 | Encryption utilities |\n\n资料来源：[requirements.txt:1-5]()\n\n---\n\n## API Endpoints\n\nThe MCP server communicates with the MemoraEU API using the following endpoints:\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| `POST` | `/memories/search` | Semantic search for memories |\n| `POST` | `/facts` | Store structured facts |\n| `GET` | `/facts` | Retrieve facts for a subject |\n| `PUT` | `/facts/{id}/invalidate` | Mark fact as expired |\n| `GET` | `/memories` | List recent memories |\n| `DELETE` | `/memories/{id}` | Delete a memory |\n| `GET` | `/memories/categories` | Get existing categories |\n\n资料来源：[memoraeu_mcp/main.py:280-310]()\n\n---\n\n## Quick Setup Checklist\n\n1. Create an account at [app.memoraeu.com](https://app.memoraeu.com)\n2. Navigate to **Settings → Encryption Keys** → copy `MEMORAEU_SALT`\n3. Set `MEMORAEU_SECRET` to your MemoraEU login password\n4. Navigate to **Settings → API Keys** → create a key → copy `MEMORAEU_API_KEY`\n5. Obtain a Mistral API key from [console.mistral.ai](https://console.mistral.ai)\n6. Add the MCP server configuration to your client's config file\n7. Set all five environment variables in your configuration\n\n资料来源：[README.md:93-99]()\n\n---\n\n## Security Considerations\n\n| Concern | Mitigation |\n|---------|------------|\n| Server sees plaintext | Use local `stdio` mode; SSE sends plaintext |\n| API key exposure | Store in environment variables, not in config files |\n| Encryption key derivation | PBKDF2 with 210k iterations per OWASP 2024 |\n| Near-duplicate leakage | 94% similarity threshold prevents similar content storage |\n\n---\n\n\n\n## Deployment Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [Configuration Reference](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n \n\n# Deployment Guide\n\nThis 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.\n\n## Overview\n\nmemoraeu-mcp is an MCP server that enables semantic memory management with client-side AES-256-GCM encryption. The server supports two deployment modes:\n\n| Deployment Mode | Use Case | Encryption | Setup Complexity |\n|-----------------|----------|------------|------------------|\n| **Local (stdio)** | Full zero-knowledge guarantees | Client-side, server never sees plaintext | Higher |\n| **Remote (SSE)** | Quick testing, no install | Server processes plaintext | Minimal |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Prerequisites\n\nBefore deploying, ensure you have:\n\n- **Python 3.10+** with `uvx` or pip access\n- **API Keys**: MemoraEU account, Mistral API key for embeddings\n- **MCP-compatible client**: Claude Desktop, Cursor, Windsurf, or any MCP client\n\n### Python Dependencies\n\n```text\nmcp>=1.1.0,<1.2.0\nhttpx==0.28.1\npython-dotenv==1.0.1\nstarlette>=0.40.0,<0.42.0\ncryptography>=42.0.0\n```\n\n资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Local Deployment (stdio)\n\nThe stdio mode provides complete zero-knowledge encryption. All content is encrypted on the client before transmission.\n\n### Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Machine\"\n A[MCP Client] -->|stdio| B[memoraeu-mcp]\n B --> C[Mistral API]\n B -->|Encrypt| D[Encrypted Payload]\n end\n D -->|AES-256-GCM| E[MemoraEU API]\n C -->|Embedding| B\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n style D fill:#f3e5f5\n```\n\n### Configuration Steps\n\n#### 1. Create Claude Desktop Configuration\n\nEdit your Claude Desktop config file:\n\n| OS | Config Location |\n|----|-----------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n#### 2. Add Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Environment Variables Reference\n\n| Variable | Purpose | Required | Source |\n|----------|---------|----------|--------|\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Yes | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | PBKDF2 password input for key derivation | Yes | Your MemoraEU login password |\n| `MEMORAEU_SALT` | KDF salt unique to your account | Yes | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint | Yes | Use `https://api.memoraeu.com` for hosted |\n| `MISTRAL_API_KEY` | Local embedding generation | Yes* | Mistral Console |\n\n*Without `MISTRAL_API_KEY`, semantic search falls back to server-side keyword matching.\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Why Local Embeddings?\n\nThe zero-knowledge architecture requires embeddings to be computed **before encryption**:\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as memoraeu-mcp\n participant Mistral\n participant Server\n \n User->>MCP: remember(\"I prefer dark mode\")\n MCP->>Mistral: Generate embedding\n Mistral-->>MCP: Embedding vector\n MCP->>MCP: AES-256-GCM encrypt content\n MCP->>Server: Encrypted content + embedding\n Note over Server: Never sees plaintext\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Remote Deployment (SSE)\n\nSSE mode connects directly to the hosted MemoraEU MCP endpoint without local installation.\n\n### Configuration for Cursor/Windsurf\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### SSE Endpoint Details\n\n| Property | Value |\n|----------|-------|\n| Protocol | Server-Sent Events (SSE) |\n| Endpoint | `https://api.memoraeu.com/mcp/sse` |\n| Authentication | Bearer token in header |\n| Encryption | Not zero-knowledge* |\n\n> **Warning**: In remote SSE mode, content is processed as plaintext by the server. Use local stdio installation for zero-knowledge guarantees.\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Obtaining Credentials\n\nFollow these steps to obtain all required credentials:\n\n### Step 1: MemoraEU Account\n\n1. Create account at [app.memoraeu.com](https://app.memoraeu.com)\n\n### Step 2: Get Encryption Salt\n\n1. Go to **Settings → Encryption Keys**\n2. Copy the `MEMORAEU_SALT` value\n\n### Step 3: Set Secret\n\n1. `MEMORAEU_SECRET` is your MemoraEU login password\n2. Used as PBKDF2 input to derive encryption key\n\n### Step 4: Get API Key\n\n1. Go to **Settings → API Keys**\n2. Create a new key\n3. Copy the `MEMORAEU_API_KEY` (format: `meu-sk-xxx`)\n\n### Step 5: Get Mistral API Key\n\n1. Obtain key at [console.mistral.ai](https://console.mistral.ai)\n2. Required for local embedding generation\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Security Considerations\n\n### Encryption Implementation\n\n| Aspect | Detail |\n|--------|--------|\n| Algorithm | AES-256-GCM |\n| Key Derivation | PBKDF2-HMAC-SHA256 |\n| Iterations | 210,000 (OWASP 2024 recommendation) |\n| Ciphertext Prefix | `ENCv1:` |\n| Salt | Server-generated, unique per account |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n### Security Comparison\n\n| Feature | stdio (Local) | SSE (Remote) |\n|---------|---------------|--------------|\n| Zero-knowledge | ✅ Yes | ❌ No |\n| Embeddings | Local (via Mistral) | Server-processed |\n| Content encryption | Client-side | Server-side |\n| PBKDF2 iterations | 210,000 | 210,000 |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Available MCP Tools\n\nOnce deployed, the following tools are available:\n\n| Tool | Description |\n|------|-------------|\n| `remember` | Automatically memorize important information |\n| `recall` | Semantic search across stored memories |\n| `forget` | Delete a memory by ID |\n| `list_memories` | List recent memories with optional category filter |\n| `list_categories` | Return existing categories sorted by usage |\n| `remember_fact` | Store structured fact with temporal validity |\n| `recall_facts` | Retrieve active facts for a subject |\n| `invalidate_fact` | Mark a fact as expired |\n\n资料来源：[memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `MISTRAL_API_KEY` missing | MCP continues working but semantic search falls back to keyword matching |\n| Authentication failed | Verify `MEMORAEU_API_KEY` format is `meu-sk-xxx` |\n| Encryption errors | Ensure `MEMORAEU_SECRET` and `MEMORAEU_SALT` are correct |\n| stdio connection refused | Restart Claude Desktop after config changes |\n\n### Verification Steps\n\n1. Check config file syntax is valid JSON\n2. Verify all required environment variables are set\n3. Confirm API keys are active in MemoraEU dashboard\n4. Restart the MCP client after configuration changes\n\n## Version History\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 0.1.9 | 2026-05-12 | Added fact tools, PBKDF2 210k iterations, ENCv1 prefix |\n| 0.1.5 | 2026-04-28 | Initial fact support, PBKDF2 updates |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: pquattro/memoraeu-mcp\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | host_targets=mcp_host, claude\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | release_recency=unknown\n\n\n",
"markdown_key": "memoraeu-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1215050856",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/pquattro/memoraeu-mcp"
},
{
"evidence_id": "art_b715631d1f33478782bb801a9cb243c4",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/pquattro/memoraeu-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "memoraeu-mcp 说明书",
"toc": [
"https://github.com/pquattro/memoraeu-mcp 项目说明书",
"目录",
"Home",
"Overview",
"Architecture",
"Installation Modes",
"Available Tools",
"Auto-Memory Behavior",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "5600d79e94ffc31019ff0cc0fd4f59613c31b04d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"requirements.txt"
],
"repo_inspection_verified": true,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# memoraeu-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 memoraeu-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `pip install memoraeu-mcp` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `git clone https://github.com/pquattro/memoraEu` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude-plugin/marketplace.json`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`.claude-plugin/marketplace.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude-plugin/marketplace.json`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`.claude-plugin/marketplace.json`, `README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `memoraeu_mcp/main.py`, `server.json`, `server.py`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0007` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0008` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`.claude-plugin/marketplace.json` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：15\n- 重要文件覆盖：15/15\n- 证据索引条目：15\n- 角色 / Skill 条目：2\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 memoraeu-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 memoraeu-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 memoraeu-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 2 个角色 / Skill / 项目文档条目。\n\n- **memoraeu-mcp**（project_doc）：🇬🇧 English english 🇫🇷 Français français 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Changelog**（project_doc）：All notable changes to memoraeu-mcp are documented here. Toutes les modifications notables sont documentées ici. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n\n## 证据索引\n\n- 共索引 15 条证据。\n\n- **memoraeu-mcp**（documentation）：🇬🇧 English english 🇫🇷 Français français 证据：`README.md`\n- **Marketplace**（structured_config）：{ \"name\": \"memoraeu\", \"owner\": { \"name\": \"MemoraEU\", \"email\": \"contact@memoraeu.com\", \"url\": \"https://memoraeu.com\" }, \"plugins\": { \"name\": \"memoraeu-mcp\", \"source\": \"./\", \"description\": \"Zero-knowledge persistent memory for Claude — encrypted, semantic search, EU hosted.\", \"version\": \"0.1.7\" } } 证据：`.claude-plugin/marketplace.json`\n- **License**（source_file）：Copyright c 2026 Philippe Quattrociocchi 证据：`LICENSE`\n- **Changelog**（documentation）：All notable changes to memoraeu-mcp are documented here. Toutes les modifications notables sont documentées ici. 证据：`CHANGELOG.md`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"io.github.pquattro/memoraeu-mcp\", \"title\": \"MemoraEU\", \"description\": \"Zero-knowledge persistent memory for Claude — encrypted, semantic search, EU hosted.\", \"repository\": { \"url\": \"https://github.com/pquattro/memoraeu-mcp.git\", \"source\": \"github\" }, \"version\": \"0.1.2\", \"packages\": { \"registryType\": \"pypi\", \"identifier\": \"memoraeu-mcp\", \"version\": \"0.1.2\", \"runtimeHint\": \"uvx\", \"transport\": { \"type\": \"stdio\" }, \"environmentVariables\": { \"name\": \"MEMORAEU API URL\", \"description\": \"MemoraEU API endpoint default: https://api.memoraeu.com \", \"isRequired\": false, \"isSecret\": false }, { \"name\": \"… 证据：`server.json`\n- **.gitignore**（source_file）：pycache / .pyc .pyo dist/ build/ .egg-info/ .env .env. .db 证据：`.gitignore`\n- **Salt fixe par installation stocké dans .env**（source_file）：\"\"\" MemoraEU — Chiffrement zero-knowledge côté client AES-256-GCM + PBKDF2-HMAC-SHA256 证据：`crypto.py`\n- **Init**（source_file）：\"\"\"memoraeu-mcp — Zero-knowledge MCP server for MemoraEU.\"\"\" version = \"0.1.2\" 证据：`memoraeu_mcp/__init__.py`\n- **M6 — 210 000 itérations recommandation OWASP 2024 pour PBKDF2-SHA256**（source_file）：\"\"\" MemoraEU — Chiffrement zero-knowledge côté client AES-256-GCM + PBKDF2-HMAC-SHA256 证据：`memoraeu_mcp/crypto.py`\n- **Mémorisation automatique**（source_file）：\"\"\" MemoraEU MCP Server Transport : stdio Claude Desktop 证据：`memoraeu_mcp/main.py`\n- **Server**（source_file）：\"\"\"Entry point pour memoraeu-mcp installé via pip/uvx.\"\"\" import asyncio 证据：`memoraeu_mcp/server.py`\n- **Pyproject**（source_file）：build-system requires = \"hatchling\" build-backend = \"hatchling.build\" 证据：`pyproject.toml`\n- **Requirements**（source_file）：mcp =1.1.0, =0.40.0, =42.0.0 证据：`requirements.txt`\n- **Mémorisation automatique**（source_file）：\"\"\" MemoraEU MCP Server Transport : stdio Claude Desktop 证据：`server.py`\n- **Smithery**（source_file）：configSchema: type: object required: - apiKey properties: apiKey: type: string title: \"MemoraEU API Key\" description: \"Your API key from app.memoraeu.com → Settings → API Keys\" x-from: header: \"x-memoraeu-api-key\" x-to: query: \"token\" 证据：`smithery.yaml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `.claude-plugin/marketplace.json`, `LICENSE`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `.claude-plugin/marketplace.json`, `LICENSE`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Home**：importance `high`\n - source_paths: README.md, memoraeu_mcp/__init__.py\n- **Installation Guide**：importance `high`\n - source_paths: README.md, server.json, pyproject.toml\n- **System Architecture**：importance `high`\n - source_paths: memoraeu_mcp/main.py, memoraeu_mcp/server.py, server.py\n- **Security and Encryption**：importance `high`\n - source_paths: memoraeu_mcp/crypto.py, crypto.py\n- **Auto-Memory System**：importance `high`\n - source_paths: memoraeu_mcp/main.py\n- **Deduplication and Compression**：importance `medium`\n - source_paths: memoraeu_mcp/main.py\n- **Structured Facts System**：importance `medium`\n - source_paths: memoraeu_mcp/main.py, CHANGELOG.md\n- **MCP Tools Reference**：importance `high`\n - source_paths: memoraeu_mcp/main.py\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `5600d79e94ffc31019ff0cc0fd4f59613c31b04d`\n- inspected_files: `pyproject.toml`, `README.md`, `requirements.txt`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | host_targets=mcp_host, claude\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | last_activity_observed missing\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | issue_or_pr_quality=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | release_recency=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: pquattro/memoraeu-mcp\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host, claude\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## Project-Specific Pitfalls\n\n- 可能修改宿主 AI 配置 (medium): 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项 (medium): 下游已经要求复核，不能在页面中弱化。 Suggested check: 进入安全/权限治理复核队列。\n- 存在评分风险 (medium): 风险会影响是否适合普通用户安装。 Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"title": "Boundary & Risk Card"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/pquattro/memoraeu-mcp 项目说明书\n\n生成时间：2026-05-15 22:45:24 UTC\n\n## 目录\n\n- [Home](#page-home)\n- [Installation Guide](#page-installation)\n- [System Architecture](#page-architecture)\n- [Security and Encryption](#page-security-encryption)\n- [Auto-Memory System](#page-auto-memory)\n- [Deduplication and Compression](#page-deduplication)\n- [Structured Facts System](#page-structured-facts)\n- [MCP Tools Reference](#page-mcp-tools)\n- [Configuration Reference](#page-configuration)\n- [Deployment Guide](#page-deployment)\n\n\n\n## Home\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [System Architecture](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# Home\n\nMemoraEU 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.\n\n## Overview\n\nMemoraEU 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:\n\n- **Automatically recall** relevant memories at the start of each conversation\n- **Persistently remember** user preferences, decisions, and facts without explicit requests\n- **Search semantically** across encrypted memory stores\n- **Manage structured facts** with temporal validity (subject/predicate/object triplets)\n\nThe architecture is designed around the principle of zero-knowledge: embeddings are computed locally before encryption, ensuring the server never sees plaintext content. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Side (Local)\"\n A[Claude Desktop / MCP Client] --> B[MemoraEU MCP Server]\n B --> C[Mistral API
Embedding Generation]\n B --> D[PBKDF2 Key Derivation]\n B --> E[AES-256-GCM Encryption]\n end\n \n subgraph \"MemoraEU Cloud\"\n F[API Endpoint
api.memoraeu.com] --> G[Encrypted Storage]\n F --> H[Vector Search Index]\n end\n \n C -->|Plaintext| E\n D -->|Derived Key| E\n E -->|Encrypted Blob| F\n C -->|Embedding Vector| F\n \n style C fill:#ff9999\n style D fill:#ff9999\n style E fill:#ff9999\n style F fill:#99ccff\n style G fill:#99ff99\n style H fill:#99ff99\n```\n\n### Security Model\n\nThe zero-knowledge architecture ensures that all sensitive processing occurs client-side:\n\n| Component | Location | Data Handled |\n|-----------|----------|---------------|\n| Embedding Generation | Local (MCP server) | Plaintext content |\n| Compression | Local | Plaintext content |\n| Categorization | Local | Plaintext content |\n| Encryption | Local (AES-256-GCM) | Plaintext → Ciphertext |\n| Storage | Remote (MemoraEU Cloud) | Encrypted blobs + vectors |\n| Search | Hybrid | Vector similarity on encrypted index |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Installation Modes\n\nMemoraEU MCP supports two deployment modes with different security guarantees:\n\n### STDIO Mode (Zero-Knowledge)\n\nFull zero-knowledge encryption with all processing happening locally.\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### SSE Mode (Remote)\n\nDirect connection without local installation, suitable for web clients.\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n**Note:** In SSE remote mode, content is not zero-knowledge encrypted since the server processes plaintext. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Available Tools\n\nThe MCP server exposes 9 tools for memory and fact management:\n\n### Memory Tools\n\n| Tool | Description | Required Parameters |\n|------|-------------|---------------------|\n| `remember` | Automatically memorizes important information when user expresses preferences, decisions, biographical facts, or technical configs | `content` |\n| `recall` | Semantic search across stored memories using vector similarity | `query` |\n| `forget` | Deletes a memory by its ID | `memory_id` |\n| `list_memories` | Lists recent memories with optional category filter | - |\n| `list_categories` | Returns existing categories sorted by usage | - |\n\n资料来源：[memoraeu_mcp/main.py:48-110](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Fact Tools\n\n| Tool | Description | Required Parameters |\n|------|-------------|---------------------|\n| `remember_fact` | Stores a structured fact with temporal validity (subject/predicate/object) | `subject`, `predicate`, `object` |\n| `recall_facts` | Retrieves active facts for a given subject | `subject` |\n| `invalidate_fact` | Marks a fact as expired by its ID | `fact_id` |\n\n资料来源：[server.py:48-80](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n## Auto-Memory Behavior\n\nThe MCP server is designed to operate autonomously without manual intervention.\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant C as Claude\n participant M as MemoraEU MCP\n \n U->>C: First message\n C->>M: recall(topic)\n M-->>C: Relevant memories\n C->>M: load_session_context()\n M-->>C: Recent memories via memoraeu://context\n \n Note over C: System prompt auto-injected\n \n U->>C: Expresses preference\n C->>M: remember(content, category)\n M-->>C: ✅ Memorized (ID: xxx)\n```\n\n### Automatic Recall\n\nOn 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Automatic Remember\n\nWhen 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### System Prompt Injection\n\nOn 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Deduplication & Compression\n\nBefore storing a memory, the MCP performs several preprocessing steps:\n\n```mermaid\ngraph LR\n A[Raw Content] --> B[Local Compression]\n B --> C[Vector Similarity Check]\n C -->|≥ 94%| D[Duplicate - Skip]\n C -->|< 94%| E[Local Categorization]\n E --> F[AES-256-GCM Encrypt]\n F --> G[Send to API]\n```\n\n### Similarity Thresholds\n\n| Similarity Score | Action |\n|-----------------|--------|\n| ≥ 94% | Memory ignored (exact duplicate) |\n| < 94% | Proceed with storage |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Environment Variables\n\nFive distinct variables serve different purposes—they are not interchangeable:\n\n| Variable | Purpose | Source |\n|----------|---------|--------|\n| `MEMORAEU_API_KEY` | HTTP Bearer token for authentication | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | User's login password, used as PBKDF2 input to derive the encryption key | User account password |\n| `MEMORAEU_SALT` | KDF salt unique to the account, combined with SECRET to produce the encryption key | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint (use `https://api.memoraeu.com` for hosted service) | - |\n| `MISTRAL_API_KEY` | Generates embeddings locally before encryption (required for zero-knowledge semantic search) | Mistral Console |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Without MISTRAL_API_KEY\n\nThe 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. 资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Encryption Details\n\nThe encryption scheme uses industry-standard practices:\n\n| Parameter | Value | Source |\n|-----------|-------|--------|\n| Algorithm | AES-256-GCM | Symmetric encryption |\n| Key Derivation | PBKDF2-HMAC-SHA256 | Password-based key derivation |\n| Iterations | 210,000 | OWASP 2024 recommendation |\n| Ciphertext Prefix | `ENCv1:` | Version identifier |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | Model Context Protocol framework |\n| `httpx` | 0.28.1 | HTTP client |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | ≥0.40.0, <0.42.0 | ASGI framework |\n| `cryptography` | ≥42.0.0 | Encryption primitives |\n\n资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Resources\n\nThe MCP server exposes the following resource:\n\n| URI | Name | Description |\n|-----|------|-------------|\n| `memoraeu://context` | Contexte mémoire MemoraEU | Recent memories automatically injected at session start |\n\n资料来源：[memoraeu_mcp/main.py:115-120](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Prompts\n\n| Name | Description |\n|------|-------------|\n| `memoraeu_system` | MemoraEU automatic memory behavior system prompt—injectable into Claude's context |\n\n资料来源：[memoraeu_mcp/main.py:137-145](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Quick Start Guide\n\n### 1. Create Account and Obtain Keys\n\n1. Create an account at [app.memoraeu.com](https://app.memoraeu.com)\n2. Navigate to **Settings → Encryption Keys** → copy `MEMORAEU_SALT`\n3. `MEMORAEU_SECRET` is your MemoraEU login password\n4. Navigate to **Settings → API Keys** → create a key → copy `MEMORAEU_API_KEY`\n5. Obtain a Mistral API key from [console.mistral.ai](https://console.mistral.ai)\n\n### 2. Configure Claude Desktop\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Supported Clients\n\n| Client | Support Type |\n|--------|--------------|\n| Claude Desktop | Full STDIO support |\n| Claude.ai Web | SSE remote mode |\n| Cursor | SSE configuration |\n| Windsurf | SSE configuration |\n| Other MCP Clients | STDIO or SSE depending on client capability |\n\n## Changelog Summary\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 0.1.9 | 2026-05-12 | Added `remember_fact`, `recall_facts`, `invalidate_fact`; PBKDF2 updated to 210k iterations |\n| 0.1.5 | 2026-04-28 | PBKDF2 210k iterations + `ENCv1:` prefix |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Configuration Reference](#page-configuration), [Deployment Guide](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [memoraeu_mcp/server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# Installation Guide\n\nThis 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.\n\n## Overview\n\nmemoraeu-mcp can be installed in two modes:\n\n| Mode | Transport | Zero-Knowledge | Use Case |\n|------|-----------|----------------|----------|\n| **Local (stdio)** | `stdio` | ✅ Full | Desktop applications (Claude Desktop, Cursor, Windsurf) |\n| **Remote (SSE)** | `SSE` | ⚠️ Partial | Web clients, shared environments |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Prerequisites\n\nBefore installation, ensure you have:\n\n- **Python 3.11+** — Required for the MCP server\n- **uvx** or **pip** — For package installation\n- **MemoraEU Account** — Required for API access\n- **Mistral API Key** — For local embedding generation (required for zero-knowledge semantic search)\n\n### Required Accounts and Keys\n\n| Service | Purpose | Signup Location |\n|---------|---------|-----------------|\n| MemoraEU | Memory storage and sync | [app.memoraeu.com](https://app.memoraeu.com) |\n| Mistral AI | Local embedding generation | [console.mistral.ai](https://console.mistral.ai) |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: Local Installation (stdio) — Recommended\n\nThis method provides **full zero-knowledge encryption** where embeddings are generated locally before any data leaves your machine.\n\n#### Step 1: Install the Package\n\n```bash\nuvx memoraeu-mcp\n```\n\nOr using pip:\n\n```bash\npip install memoraeu-mcp\n```\n\n#### Step 2: Obtain MemoraEU Credentials\n\n1. Create an account at [app.memoraeu.com](https://app.memoraeu.com)\n2. Navigate to **Settings → Encryption Keys** → copy `MEMORAEU_SALT`\n3. `MEMORAEU_SECRET` is your MemoraEU login password\n4. Navigate to **Settings → API Keys** → create a key → copy `MEMORAEU_API_KEY`\n\n#### Step 3: Configure Claude Desktop\n\nAdd the following to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Method 2: Remote Installation (SSE) — Zero-Knowledge NOT Guaranteed\n\nUse this method when you cannot install locally or need quick access from web clients.\n\n> ⚠️ **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.\n\n#### Configuration for Remote Clients\n\nConfigure your MCP client (Cursor, Windsurf, or any SSE-compatible client):\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n**SSE Endpoint Details:**\n\n| Property | Value |\n|----------|-------|\n| Endpoint URL | `https://api.memoraeu.com/mcp/sse` |\n| Authentication | Bearer token in `Authorization` header |\n| API Key Format | `meu-sk-xxx` |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Environment Variables Reference\n\nAll configuration is done via environment variables. These five variables serve **three distinct purposes** — they are **not interchangeable**.\n\n| Variable | Purpose | Required | Where to Get |\n|----------|---------|----------|--------------|\n| `MEMORAEU_API_KEY` | HTTP authentication (Bearer token sent with every request) | Yes | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | Your MemoraEU login password — used as PBKDF2 input to derive the encryption key locally | Yes (local) | Your account password |\n| `MEMORAEU_SALT` | KDF salt generated by the server, unique to your account | Yes (local) | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint for the hosted service | Yes | Use `https://api.memoraeu.com` |\n| `MISTRAL_API_KEY` | Used to generate embeddings locally before encryption | Yes (local) | [console.mistral.ai](https://console.mistral.ai) |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Variable Dependency Matrix\n\n```mermaid\ngraph TD\n A[Local Installation] --> B{MISTRAL_API_KEY set?}\n B -->|Yes| C[Full Zero-Knowledge Mode]\n B -->|No| D[Keyword Search Fallback]\n C --> E[Embeddings generated locally
before encryption]\n D --> F[Server-side keyword search
Zero-knowledge encryption preserved]\n \n G[Remote SSE Mode] --> H[No Local Processing
Server sees plaintext]\n \n style C fill:#90EE90\n style D fill:#FFE4B5\n style H fill:#FFB6C1\n```\n\n### Why is MISTRAL_API_KEY Required Locally?\n\nThe zero-knowledge architecture requires that:\n1. Embeddings must be calculated **before** encryption\n2. This happens on your local machine\n3. The MCP calls Mistral directly with plaintext\n4. The server receives an opaque blob + vector it cannot decrypt\n\nWithout `MISTRAL_API_KEY`, semantic search falls back to keyword search on the server side, but **zero-knowledge encryption remains intact**.\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Configuration Examples by Client\n\n### Claude Desktop\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n### Cursor / Windsurf (Local)\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n### Cursor / Windsurf (Remote SSE)\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Supported Transport Protocols\n\n| Protocol | Use Case | Zero-Knowledge | Setup Complexity |\n|----------|----------|----------------|------------------|\n| `stdio` | Local desktop apps | ✅ Full | Requires uvx/pip |\n| `sse` | Remote/web clients | ⚠️ Server sees plaintext | Quick setup |\n\nThe MCP server implements both protocols via the MCP SDK:\n\n资料来源：[memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Package Dependencies\n\nThe following dependencies are required and specified in `requirements.txt`:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | Model Context Protocol SDK |\n| `httpx` | 0.28.1 | HTTP client for API calls |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | ≥0.40.0, <0.42.0 | ASGI framework |\n| `cryptography` | ≥42.0.0 | AES-256-GCM encryption |\n\n资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Installation Flow Diagram\n\n```mermaid\nflowchart TD\n A[Start Installation] --> B{Choose Mode}\n \n B -->|Local stdio| C[Install via uvx or pip]\n B -->|Remote SSE| D[Configure client directly]\n \n C --> E[Create MemoraEU Account]\n E --> F[Get API Key & Salt]\n F --> G[Get Mistral API Key]\n G --> H[Configure claude_desktop_config.json]\n H --> I[Verify Installation]\n \n D --> J[Get Bearer Token]\n J --> K[Configure SSE in client]\n K --> L[Verify Connection]\n \n I --> M[✅ Zero-Knowledge Ready]\n L --> N[⚠️ Remote Mode Active]\n```\n\n## Verifying Installation\n\nAfter installation, verify the MCP server is working by:\n\n1. **Check MCP server status** in your client\n2. **Run a test command** using any available tool:\n - `list_categories` — Should return an empty list or existing categories\n - `list_memories` — Should confirm connection\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| \"Module not found\" errors | Ensure `uvx` or `pip` installation completed successfully |\n| SSE connection failures | Verify API key format is `meu-sk-xxx` and endpoint URL is correct |\n| Semantic search not working | Check `MISTRAL_API_KEY` is set; falls back to keyword search if missing |\n| Encryption errors | Verify `MEMORAEU_SALT` and `MEMORAEU_SECRET` are correct |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Security Architecture Summary\n\n| Component | Location | Description |\n|-----------|----------|-------------|\n| Encryption | Client-side | AES-256-GCM with PBKDF2-HMAC-SHA256 (100k iterations) |\n| Embedding generation | Client-side | Mistral embeddings computed before encryption |\n| Storage | Server-side | Opaque encrypted blobs + vectors |\n| Key derivation | Client-side | Password + salt → encryption key |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n\n\n## System Architecture\n\n### 相关页面\n\n相关主题：[Security and Encryption](#page-security-encryption), [MCP Tools Reference](#page-mcp-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [memoraeu_mcp/server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/server.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n \n\n# System Architecture\n\n## Overview\n\nThe **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.\n\nThe 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.\n\n## High-Level Architecture\n\n```mermaid\ngraph TD\n subgraph Client[\"Client Side (Local)\"]\n MCP[\"MCP Client
(Claude Desktop, Cursor, etc.)\"]\n Tools[\"Tool Handlers
remember, recall, forget, etc.\"]\n Crypto[\"Encryption Module
AES-256-GCM + PBKDF2\"]\n Embed[\"Embedding Generator
(Mistral API)\"]\n Compress[\"Local Compression\"]\n Categorize[\"Local Categorization\"]\n end\n\n subgraph External[\"External Services\"]\n Mistral[\"Mistral API
(Embeddings)\"]\n end\n\n subgraph Server[\"MemoraEU Remote API\"]\n API[\"API Endpoint
api.memoraeu.com\"]\n Storage[\"Encrypted Storage\"]\n end\n\n MCP --> Tools\n Tools --> Crypto\n Tools --> Embed\n Tools --> Compress\n Tools --> Categorize\n Embed --> Mistral\n Tools --> API\n API --> Storage\n\n style Client fill:#e1f5fe\n style Server fill:#fff3e0\n style External fill:#f3e5f5\n```\n\n## Component Architecture\n\n### Entry Points\n\nThe project provides multiple entry points for different deployment scenarios:\n\n| Entry Point | Purpose | Use Case |\n|-------------|---------|----------|\n| `memoraeu_mcp/server.py` | Pip/uvx installation entry | Installed via package manager |\n| `server.py` | Development/main server | Direct execution with `python server.py` |\n| SSE Remote | Remote MCP via Server-Sent Events | Web clients without local install |\n\n资料来源：[memoraeu_mcp/server.py:1-9]()\n\n```python\n\"\"\"Entry point pour memoraeu-mcp installé via pip/uvx.\"\"\"\nimport asyncio\n\ndef run():\n from memoraeu_mcp.main import main\n asyncio.run(main())\n```\n\n### Core Server Module\n\nThe `memoraeu_mcp/main.py` file contains the complete MCP server implementation with all tool handlers, resource providers, and prompt managers.\n\n资料来源：[memoraeu_mcp/main.py:1-200]()\n\n## MCP Protocol Implementation\n\n### Tool Registration\n\n```mermaid\ngraph LR\n A[list_tools] --> B[Tool Definitions]\n B --> C[remember]\n B --> D[recall]\n B --> E[forget]\n B --> F[list_memories]\n B --> G[list_categories]\n B --> H[remember_fact]\n B --> I[recall_facts]\n B --> J[invalidate_fact]\n```\n\nAll tools are defined using the MCP SDK `Tool` class with JSON schemas:\n\n```python\nTool(\n name=\"remember\",\n description=\"Mémorise automatiquement une information importante...\",\n inputSchema={\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n)\n```\n\n资料来源：[memoraeu_mcp/main.py:73-106]()\n\n### Available Tools\n\n| Tool | Function | Input Parameters |\n|------|----------|-------------------|\n| `remember` | Stores important information | `content` (required), `category`, `tags` |\n| `recall` | Semantic search across memories | `query` (required), `limit`, `category` |\n| `forget` | Deletes a memory by ID | `memory_id` (required) |\n| `list_memories` | Lists recent memories | `category`, `limit` |\n| `list_categories` | Returns categories sorted by usage | None |\n| `remember_fact` | Stores structured fact | `subject`, `predicate`, `object`, `scope`, `valid_from` |\n| `recall_facts` | Retrieves active facts | `subject`, `predicate`, `scope`, `history` |\n| `invalidate_fact` | Marks fact as expired | `fact_id`, `valid_to` |\n\n### Resources\n\nThe server provides a single resource URI for memory context injection:\n\n| Resource URI | Name | Purpose |\n|--------------|------|---------|\n| `memoraeu://context` | Contexte mémoire MemoraEU | Recent memories injected automatically at session start |\n\n资料来源：[memoraeu_mcp/main.py:148-165]()\n\n```python\n@app.list_resources()\nasync def list_resources() -> list[Resource]:\n return [\n Resource(\n uri=\"memoraeu://context\",\n name=\"Contexte mémoire MemoraEU\",\n description=\"Mémoires récentes injectées automatiquement en début de session\",\n mimeType=\"text/plain\"\n )\n ]\n```\n\n### Prompts\n\nA single system prompt is available for memory behavior injection:\n\n| Prompt Name | Description |\n|-------------|-------------|\n| `memoraeu_system` | Injects automatic memory behavior rules into Claude's context |\n\n资料来源：[memoraeu_mcp/main.py:132-147]()\n\n## Data Flow Architecture\n\n### Memory Storage Flow\n\n```mermaid\ngraph TD\n A[User Input] --> B[remember tool]\n B --> C{API Key Available?}\n C -->|Yes| D[Generate Embedding via Mistral]\n C -->|No| E[Skip Embedding]\n D --> F[Compress Content Locally]\n E --> F\n F --> G[Categorize Locally]\n G --> H[Check Duplicate Similarity]\n H --> I{Similarity >= 94%?}\n I -->|Yes| J[Ignore - Duplicate]\n I -->|No| K[Encrypt Content AES-256-GCM]\n K --> L[API POST /memories]\n L --> M[Server Stores Encrypted Blob]\n```\n\n### Memory Retrieval Flow\n\n```mermaid\ngraph TD\n A[recall tool] --> B[First recall of session?]\n B -->|Yes| C[Load Session Context]\n B -->|No| D[Skip Context]\n C --> E[Inject System Prompt]\n D --> F[API POST /memories/search]\n E --> F\n F --> G[Receive Encrypted Results]\n G --> H[Decrypt Content Locally]\n H --> I[Return Plaintext to Client]\n```\n\n## Security Architecture\n\n### Zero-Knowledge Model\n\n```mermaid\ngraph LR\n subgraph Client[\"Client\"]\n P[Plaintext Content]\n E[Encryption]\n K[Key Derivation]\n end\n\n subgraph Server[\"Server\"]\n C[Encrypted Blob]\n V[Vector Embedding]\n end\n\n P --> E\n E --> C\n P --> K\n K --> E\n C --> Server\n V --> Server\n```\n\nThe security model ensures:\n\n1. **Encryption before transmission** - Content is encrypted locally using AES-256-GCM\n2. **Client-side embedding** - Semantic vectors are generated from plaintext before encryption\n3. **Key derivation** - PBKDF2-HMAC-SHA256 with 100,000 iterations derives encryption keys\n\n### Key Derivation Parameters\n\n| Parameter | Variable | Source |\n|-----------|----------|--------|\n| Secret | `MEMORAEU_SECRET` | User's account password |\n| Salt | `MEMORAEU_SALT` | Server-generated, unique per account |\n| Iterations | 100,000 | Hardcoded in implementation |\n\n资料来源：[memoraeu_mcp/main.py:1-50]()\n\n### API Authentication\n\nTwo authentication modes are supported:\n\n| Mode | Configuration | Transport |\n|------|--------------|-----------|\n| Local stdio | Environment variables | Standard I/O |\n| Remote SSE | Bearer token header | Server-Sent Events |\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n## Configuration Architecture\n\n### Environment Variables\n\n| Variable | Purpose | Required | Source |\n|----------|---------|----------|--------|\n| `MEMORAEU_API_URL` | API endpoint | Yes | Fixed for hosted service |\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Yes | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | Password for key derivation | Yes (local) | User account password |\n| `MEMORAEU_SALT` | KDF salt | Yes (local) | Dashboard → Settings → Encryption Keys |\n| `MISTRAL_API_KEY` | Local embedding generation | Yes (zero-knowledge) | Mistral Console |\n\n资料来源：[README.md:1-50]()\n\n### Configuration File Structure\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n## Dependencies\n\nThe project depends on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | >=1.1.0, <1.2.0 | MCP SDK framework |\n| `httpx` | 0.28.1 | HTTP client for API calls |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | >=0.40.0, <0.42.0 | ASGI framework for SSE |\n| `cryptography` | >=42.0.0 | AES-256-GCM encryption |\n\n资料来源：[requirements.txt:1-5]()\n\n## Auto-Memory Behavior System\n\nThe MCP server implements automatic memory management without manual intervention:\n\n### Automatic Recall\n\nOn the first user message of each session:\n1. `recall` is called automatically with detected topic as query\n2. Recent memories are loaded via `memoraeu://context` resource\n3. Context is injected into the session\n\n### Automatic Remember\n\nWhen Claude detects memorable information:\n- Preferences\n- Decisions\n- Biographical facts\n- Technical configurations\n- Durable constraints\n\nIt calls `remember` autonomously with a single discreet confirmation.\n\n### System Prompt Injection\n\nOn the first `recall` call, the full behavior system prompt is injected:\n\n```\nSYSTEM_PROMPT_TEXT contains:\n- Memory objectives (preferences, decisions, biographical facts)\n- Automatic recall rules\n- Token optimization guidelines\n```\n\n## Deduplication System\n\nBefore storing a memory, the system checks for near-duplicates:\n\n| Similarity Threshold | Action |\n|---------------------|--------|\n| ≥ 94% | Memory ignored (exact duplicate) |\n| < 94% | Memory stored normally |\n\nThis prevents storage of redundant information while allowing similar but distinct memories.\n\n## Error Handling Architecture\n\nAll tool handlers follow a consistent error handling pattern:\n\n```python\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict) -> list[TextContent]:\n if name == \"remember\":\n try:\n # Tool implementation\n return [TextContent(type=\"text\", text=\"✅ Success message\")]\n except Exception as e:\n return [TextContent(type=\"text\", text=f\"❌ Error : {e}\")]\n```\n\nThis ensures all errors return user-friendly messages rather than raw exceptions.\n\n## Module Structure Summary\n\n```\nmemoraeu_mcp/\n├── main.py # Core MCP server implementation\n│ ├── @app decorators (tools, resources, prompts)\n│ ├── Tool handlers (remember, recall, forget, etc.)\n│ ├── Encryption functions\n│ ├── API communication\n│ └── Local processing (compression, categorization)\n└── server.py # Entry point for pip/uvx installation\n\n---\n\n\n\n## Security and Encryption\n\n### 相关页面\n\n相关主题：[System Architecture](#page-architecture), [Configuration Reference](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/crypto.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/crypto.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n \n\n# Security and Encryption\n\n## Overview\n\nMemoraEU 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.\n\nThe system uses industry-standard cryptographic primitives:\n- **AES-256-GCM** for authenticated encryption\n- **PBKDF2-HMAC-SHA256** with 210,000 iterations for key derivation\n\n资料来源：[memoraeu_mcp/crypto.py:1-15]()\n\n---\n\n## Architecture\n\n### Zero-Knowledge Flow\n\n```mermaid\ngraph TD\n A[User Data] -->|Plaintext| B[Client-Side MCP Server]\n B --> C[Mistral Embeddings
Generated from plaintext]\n C --> D[encrypt_content]\n D --> E[AES-256-GCM
Encryption]\n E --> F[ENCv1:... ciphertext]\n F --> G[MemoraEU API]\n F --> H[Stored in DB]\n \n I[API Request] -->|encrypted data only| G\n G -->|cannot decrypt| H\n \n J[MEMORAEU_SECRET
+ MEMORAEU_SALT] -->|derive_key| K[AES-256 Key]\n K -->|in memory only| D\n```\n\nThe embedding generation happens **before** encryption to preserve semantic search capabilities while maintaining zero-knowledge guarantees. The server stores encrypted content and pre-computed embeddings but cannot decrypt the actual memory content.\n\n资料来源：[memoraeu_mcp/crypto.py:1-15]()\n\n---\n\n## Key Derivation\n\n### PBKDF2 Configuration\n\n| Parameter | Value | Notes |\n|-----------|-------|-------|\n| Algorithm | PBKDF2-HMAC-SHA256 | NIST recommended |\n| Iterations | 210,000 | OWASP 2024 recommendation |\n| Key Length | 32 bytes | AES-256 requirement |\n| Salt | User-specific | Server-generated, stored in dashboard |\n\nThe key derivation uses a high iteration count to make brute-force attacks computationally expensive. The salt is unique per user account and generated server-side to prevent rainbow table attacks.\n\n资料来源：[memoraeu_mcp/crypto.py:22-23]()\n\n### Derivation Function\n\n```python\ndef derive_key(password: str, salt: str) -> bytes:\n salt_bytes = salt.encode() if isinstance(salt, str) else salt\n kdf = PBKDF2HMAC(\n algorithm=hashes.SHA256(),\n length=32,\n salt=salt_bytes,\n iterations=PBKDF2_ITERATIONS,\n )\n return kdf.derive(password.encode())\n```\n\nThe function accepts `MEMORAEU_SECRET` (user's account password) and `MEMORAEU_SALT` (server-generated salt) to derive the encryption key.\n\n资料来源：[memoraeu_mcp/crypto.py:28-41]()\n\n---\n\n## Encryption\n\n### AES-256-GCM\n\nThe implementation uses the `cryptography` library's AESGCM implementation for authenticated encryption. GCM mode provides both confidentiality and integrity protection.\n\n| Property | Value |\n|----------|-------|\n| Cipher | AES-256 |\n| Mode | GCM (Galois/Counter Mode) |\n| Nonce | Random per encryption |\n| Authentication | Included in GCM mode |\n\n### Encrypted Value Format\n\nEncrypted values are prefixed with `ENCv1:` to enable detection:\n\n```\nENCv1:\n```\n\nThis prefix allows the decryption function to distinguish between encrypted and plaintext values.\n\n资料来源：[memoraeu_mcp/crypto.py:20-23]()\n\n---\n\n## Key Management\n\n### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant App as MCP Server\n participant Crypto as crypto module\n participant Env as Environment\n \n App->>Env: Read MEMORAEU_SECRET, MEMORAEU_SALT\n App->>App: init_crypto()\n App->>Crypto: derive_key(secret, salt)\n Crypto-->>App: 32-byte AES key\n App->>App: Store in _key global\n \n Note over App: Key held only in memory\n```\n\n### Environment Variables\n\n| Variable | Purpose | Source |\n|----------|---------|--------|\n| `MEMORAEU_SECRET` | User password for key derivation | User's account password |\n| `MEMORAEU_SALT` | KDF salt, unique per account | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Dashboard → Settings → API Keys |\n\n资料来源：[server.py:1-30]()\n\n### Key Storage\n\nThe derived key is stored in the `_key` global variable and is never persisted to disk or transmitted to the server:\n\n```python\n_key: bytes | None = None\n\ndef get_key() -> bytes | None:\n return _key\n```\n\n资料来源：[memoraeu_mcp/main.py:1-30]()\n\n---\n\n## Encryption/Decryption Wrappers\n\n### Content Encryption\n\n```python\ndef encrypt_content(content: str) -> str:\n key = get_key()\n if not key:\n return content # Fallback to plaintext\n from memoraeu_mcp.crypto import encrypt\n return encrypt(content, key)\n```\n\nIf the encryption key is not available (e.g., `MEMORAEU_SECRET` not configured), content is stored in plaintext with a warning message.\n\n资料来源：[server.py:50-60]()\n\n### Content Decryption\n\n```python\ndef decrypt_content(value: str) -> str:\n key = get_key()\n if not key:\n return value\n from memoraeu_mcp.crypto import decrypt, is_encrypted\n if not is_encrypted(value):\n return value\n try:\n return decrypt(value, key)\n except Exception:\n return \"[contenu chiffré — clé incorrecte]\"\n```\n\nDecryption failures (e.g., wrong key) return a placeholder message rather than exposing error details.\n\n资料来源：[memoraeu_mcp/main.py:60-80]()\n\n---\n\n## Dependency Requirements\n\nThe security implementation requires the `cryptography` library:\n\n```\ncryptography>=42.0.0\n```\n\nThis ensures access to the `cryptography.hazmat` primitives used for AES-GCM and PBKDF2.\n\n资料来源：[requirements.txt:1-5]()\n\n---\n\n## Security Properties\n\n### Guarantees\n\n| Property | Implementation |\n|----------|----------------|\n| Confidentiality | AES-256-GCM encryption, key never leaves client |\n| Integrity | GCM authentication tag verification |\n| Authentication | PBKDF2 key derivation from user password |\n| Non-repudiation | User-specific salt ensures key uniqueness |\n\n### Threat Model\n\n| Threat | Mitigation |\n|--------|------------|\n| Server compromise | Server stores only encrypted data |\n| Man-in-middle | HTTPS transport + client-side encryption |\n| Brute force | 210,000 PBKDF2 iterations |\n| Rainbow tables | Unique per-user salt |\n| Replay attacks | Random nonce per encryption operation |\n\n---\n\n## Configuration Examples\n\n### Full Zero-Knowledge Setup\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"server-generated-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n### Remote SSE Mode (Reduced Security)\n\nIn remote SSE mode, content is processed on the server and is **not zero-knowledge encrypted**:\n\n> **Note:** En mode SSE distant, le contenu n'est pas chiffré zero-knowledge (le serveur traite le texte en clair). Utilisez l'installation locale `stdio` pour les garanties zero-knowledge complètes.\n\n资料来源：[README.md:1-30]()\n\n---\n\n## Startup Behavior\n\nOn server initialization:\n\n```\n[memoraeu] ✅ Chiffrement zero-knowledge activé\n```\n\nOr if `MEMORAEU_SECRET` is missing:\n\n```\n[memoraeu] ⚠️ MEMORAEU_SECRET absent — stockage en clair\n```\n\n资料来源：[server.py:45-50]()\n\n---\n\n\n\n## Auto-Memory System\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [Structured Facts System](#page-structured-facts)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation:\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n \n\n# Auto-Memory System\n\nThe 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.\n\n## Overview\n\nThe system operates on a **client-side encryption** model where:\n\n- All memory content is encrypted locally before transmission\n- Embeddings for semantic search are computed from plaintext before encryption\n- The server processes encrypted data without visibility into content\n- A PBKDF2-HMAC-SHA256 key derivation scheme (210,000 iterations) protects the encryption key derived from the user's password\n\n```mermaid\ngraph TD\n A[User Message] --> B{Auto-Recall Trigger}\n B --> C[Extract Topic Query]\n C --> D[Semantic Search
memoraeu://context]\n D --> E[Load Recent Memories]\n E --> F[Inject into Session Context]\n \n G[User Expresses
Preference/Fact] --> H{Auto-Remember Trigger}\n H --> I[Compress Content]\n I --> J[Categorize Locally]\n J --> K[Generate Embedding]\n K --> L{Check Duplicates
Similarity ≥ 94%}\n L -->|No Duplicate| M[Encrypt Content]\n L -->|Duplicate Found| N[Skip Storage]\n M --> O[Store Memory]\n```\n\n## Core Components\n\n### 1. Automatic Recall\n\nOn the first user message of each session, the MCP server automatically triggers a `recall` operation using the detected topic as the search query. 资料来源：[README.md:40-45]()\n\n**Behavior:**\n- Retrieves relevant memories via semantic search\n- Loads recent memories through the `memoraeu://context` resource\n- Injects memories as session context automatically\n- No manual invocation required\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant MCP as MCP Server\n participant API as MemoraEU API\n participant LLM as Claude Model\n \n U->>MCP: First Message\n MCP->>MCP: Detect Topic\n MCP->>API: recall(topic, limit=3)\n API->>MCP: Relevant Memories\n MCP->>LLM: Inject Context\n MCP->>LLM: Inject System Prompt\n```\n\n### 2. Automatic Remember\n\nWhen 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. 资料来源：[README.md:47-52]()\n\n**Triggers for automatic memory:**\n- User expresses a preference\n- User makes a decision\n- User shares biographical information\n- User mentions technical constraints or configurations\n\n**Confirmation:** The system confirms storage with a single discreet line.\n\n### 3. System Prompt Injection\n\nOn 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. 资料来源：[README.md:54-58]()\n\nThe system prompt includes:\n```\n## Ce qu'il faut mémoriser\n- Préférences et configurations utilisateur\n- Décisions et choix récurrents ou contraintes durables\n- Informations techniques propres à l'utilisateur (stack, config, credentials non-sensibles)\n\n## Rappel automatique\nDès le premier message de l'utilisateur, utilise `recall` avec le sujet détecté comme query.\nN'attends pas qu'on te le demande — c'est automatique.\n\n## Règles\n- Ne mémorise pas les informations générales ou éphémères (météo du jour, blagues, calculs ponctuels)\n- Si l'utilisateur dit \"oublie ça\" ou \"ne retiens pas\", utilise `forget`\n- Confirme discrètement les mémorisations : une ligne, pas plus\n- Optimisation tokens : limite recall à 3 résultats par défaut, mémoires compactes\n```\n\n## Available Tools\n\n| Tool | Description | Input Schema |\n|------|-------------|--------------|\n| `remember` | Memorizes important information automatically | `content`, `category`, `tags` |\n| `recall` | Semantic search across stored memories | `query`, `limit` (default: 3), `category` |\n| `forget` | Deletes a memory by ID | `memory_id` |\n| `list_memories` | Lists recent memories with optional category filter | `category`, `limit` (default: 20) |\n| `list_categories` | Returns existing categories sorted by usage | — |\n| `remember_fact` | Stores structured fact with temporal validity | `subject`, `predicate`, `object`, `valid_from`, `valid_to`, `scope` |\n| `recall_facts` | Retrieves active facts for a subject | `subject`, `predicate`, `scope`, `history` |\n| `invalidate_fact` | Marks a fact as expired | `fact_id`, `valid_to` |\n\n### Tool Configuration in MCP\n\nTools are registered via the MCP manifest in `list_tools()`:\n\n```python\nTool(\n name=\"remember\",\n description=(\n \"Mémorise automatiquement une information importante. \"\n \"UTILISE CET OUTIL SANS QU'ON TE LE DEMANDE dès que l'utilisateur exprime \"\n \"une préférence, une décision, un fait biographique, une config technique, \"\n \"ou une contrainte durable. Confirme en une ligne discrète.\"\n ),\n inputSchema={\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n)\n```\n\n资料来源：[memoraeu_mcp/main.py:60-80]()\n\n## Data Processing Pipeline\n\n### Memory Storage Flow\n\n```mermaid\ngraph LR\n A[Content Input] --> B[Compression
via Mistral]\n B --> C[Category Suggestion
via Mistral]\n C --> D[Embedding Generation
via Mistral]\n D --> E{Duplicate Check
Similarity ≥ 0.94?}\n E -->|Similar Found| F[Skip or Warn]\n E -->|No Duplicate| G[AES-256-GCM Encryption]\n G --> H[API POST /memories]\n H --> I[Return Memory ID]\n```\n\n### Pre-Processing Steps (Before Encryption)\n\nThe system performs several operations on plaintext before encryption: 资料来源：[memoraeu_mcp/main.py:140-180]()\n\n| Step | Description | Purpose |\n|------|-------------|---------|\n| 1. Compression | Summarizes text via Mistral if > 500 chars | Token optimization |\n| 2. Categorization | Suggests category using existing categories | Organization |\n| 3. Embedding | Generates vector via Mistral Embed | Semantic search |\n| 4. Deduplication | Checks vector similarity | Avoid storage bloat |\n\n### Local Processing Functions\n\n```python\nasync def compress_locally(content: str) -> str:\n \"\"\"Compression en clair (avant chiffrement).\"\"\"\n if len(content) <= COMPRESSION_THRESHOLD:\n return content\n prompt = (\n \"Résume ce texte en 1-3 phrases concises, en français, en gardant l'essentiel. \"\n \"Réponds uniquement avec le résumé, sans introduction ni conclusion.\\n\\n\"\n f\"{content}\"\n )\n compressed = await _mistral_chat(prompt)\n if compressed and len(compressed) < len(content):\n return compressed\n return content\n```\n\n资料来源：[memoraeu_mcp/main.py:145-160]()\n\n```python\nasync def suggest_category_locally(content: str, existing: list[str]) -> str:\n \"\"\"Suggère une catégorie pour le contenu en clair.\"\"\"\n existing_str = \", \".join(existing) if existing else \"aucune\"\n prompt = (\n f\"Catégories existantes : {existing_str}\\n\\n\"\n f\"Texte : {content[:500]}\\n\\n\"\n \"Quelle catégorie courte (1-2 mots, en français, minuscules) correspond le mieux ? \"\n \"Utilise une existante si pertinent, sinon crée-en une. Réponds uniquement avec la catégorie.\"\n )\n cat = await _mistral_chat(prompt)\n if cat:\n return cat.lower().strip().strip('\"').strip(\"'\")[:30]\n return \"personnel\"\n```\n\n资料来源：[memoraeu_mcp/main.py:162-175]()\n\n## Deduplication & Compression\n\n### Similarity Thresholds\n\nBefore storing a memory, the MCP checks for near-duplicates using vector similarity:\n\n| Similarity Score | Action |\n|------------------|--------|\n| ≥ 94% | Memory ignored — exact duplicate |\n| < 94% | Memory stored (with warning logged) |\n\n资料来源：[README.md:70-76]()\n\n### Duplicate Detection Implementation\n\n```python\nasync def check_duplicate(embedding: list[float]) -> dict | None:\n \"\"\"\n Recherche une mémoire similaire via le vecteur pré-calculé (zero-knowledge).\n Retourne la mémoire existante si similarité ≥ seuil, sinon None.\n \"\"\"\n # Implementation checks against stored embeddings\n # Returns duplicate info if similarity threshold met\n```\n\n资料来源：[memoraeu_mcp/main.py:177-185]()\n\n## Structured Facts System\n\nFor temporal data that changes over time, the system provides structured fact management:\n\n### Fact Data Model\n\n```python\n{\n \"id\": \"uuid-string\",\n \"subject\": \"User/Entity name\",\n \"predicate\": \"property-name\",\n \"object\": \"encrypted-value\",\n \"valid_from\": \"YYYY-MM-DD\",\n \"valid_to\": \"YYYY-MM-DD | null\",\n \"scope\": \"private | org\",\n \"supersedes\": \"previous-fact-id | null\"\n}\n```\n\n### Temporal Validity\n\nFacts support time-bound validity:\n\n- `valid_from`: Start date (defaults to today)\n- `valid_to`: End date (null means currently active)\n- When a new fact replaces an old one, `supersedes` links them\n- `recall_facts` with `history=False` returns only active facts\n\n资料来源：[server.py:35-55]()\n\n## Resource Injection\n\nThe MCP server exposes a resource endpoint for automatic context loading:\n\n```python\n@app.list_resources()\nasync def list_resources() -> list[Resource]:\n return [\n Resource(\n uri=\"memoraeu://context\",\n name=\"Contexte mémoire MemoraEU\",\n description=\"Mémoires récentes injectées automatiquement en début de session\",\n mimeType=\"text/plain\"\n )\n ]\n\n@app.read_resource()\nasync def read_resource(uri: str) -> list[ResourceContents]:\n if uri == \"memoraeu://context\":\n context = await load_session_context()\n text = context if context else \"Aucune mémoire enregistrée.\"\n return [TextResourceContents(uri=uri, mimeType=\"text/plain\", text=text)]\n```\n\n资料来源：[memoraeu_mcp/main.py:90-105]()\n\n## Session Context Loading\n\n```python\nasync def load_session_context() -> str:\n \"\"\"Charge le contexte de session depuis l'API.\"\"\"\n try:\n memories = await api_get(\"/memories\", params={\"limit\": 10, \"scope\": \"private\"})\n if not memories:\n return \"\"\n lines = []\n for m in memories:\n content = decrypt_content(m[\"content\"])\n preview = content[:100] + (\"…\" if len(content) > 100 else \"\")\n lines.append(f\"[{m.get('category') or '—'}] {preview}\")\n return \"\\n\".join(lines)\n except Exception:\n return \"\"\n```\n\n## Recall Flow Implementation\n\n```python\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict) -> list[TextContent]:\n if name == \"recall\":\n global _first_recall\n is_first = _first_recall\n _first_recall = False\n\n # Load session context on first recall\n context = await load_session_context()\n\n response = await api_post(\"/memories/search\", {\n \"query\": arguments[\"query\"],\n \"limit\": arguments.get(\"limit\", 3),\n \"category\": arguments.get(\"category\"),\n \"scope\": \"private\"\n })\n results = response.get(\"results\", [])\n\n lines = []\n\n # Inject system prompt only on first recall\n if is_first:\n lines.append(SYSTEM_PROMPT_TEXT)\n lines.append(\"---\")\n # ... format results\n```\n\n资料来源：[memoraeu_mcp/main.py:220-250]()\n\n## Zero-Knowledge Architecture\n\n```mermaid\ngraph TD\n subgraph Client[\"Client (MCP)\"]\n A[Plaintext Content] --> B[Mistral Embedding]\n A --> C[Compression]\n A --> D[Categorization]\n B --> E[Duplicate Check]\n C --> F[AES-256-GCM Encryption]\n D --> F\n E -->|No Duplicate| F\n end\n \n subgraph Server[\"MemoraEU Server\"]\n G[Encrypted Payload] --> H[Store]\n H --> I[Semantic Search]\n G --> I\n end\n \n F --> G\n I --> J[Return Encrypted Results]\n J --> K[Client Decrypts]\n```\n\n### Encryption Specification\n\n| Parameter | Value |\n|-----------|-------|\n| Algorithm | AES-256-GCM |\n| Key Derivation | PBKDF2-HMAC-SHA256 |\n| Iterations | 210,000 (OWASP 2024) |\n| Ciphertext Prefix | `ENCv1:` |\n| Salt | Per-account, from dashboard |\n\n## Configuration Variables\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Yes |\n| `MEMORAEU_SECRET` | User password for key derivation | Yes |\n| `MEMORAEU_SALT` | KDF salt from dashboard | Yes |\n| `MEMORAEU_API_URL` | API endpoint (default: `https://api.memoraeu.com`) | Yes |\n| `MISTRAL_API_KEY` | Embedding generation | Yes |\n\n资料来源：[README.md:95-115]()\n\n## Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | MCP protocol implementation |\n| `httpx` | 0.28.1 | HTTP client |\n| `python-dotenv` | 1.0.1 | Environment configuration |\n| `starlette` | ≥0.40.0, <0.42.0 | Web framework |\n| `cryptography` | ≥42.0.0 | AES encryption |\n\n资料来源：[requirements.txt:1-5]()\n\n## Version History\n\n| Version | Date | Changes |\n|---------|------|---------|\n| 0.1.9 | 2026-05-12 | Added `remember_fact`, `recall_facts`, `invalidate_fact`; PBKDF2 210k iterations |\n| 0.1.5 | 2026-04-28 | Added `ENCv1:` prefix; deduplication threshold refinement |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n---\n\n\n\n## Deduplication and Compression\n\n### 相关页面\n\n相关主题：[Auto-Memory System](#page-auto-memory), [Security and Encryption](#page-security-encryption)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n \n\n# Deduplication and Compression\n\nThe 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.\n\n## Overview\n\nMemoraEU's optimization pipeline runs entirely on the client side before any data leaves the user's machine. This approach provides several benefits:\n\n- **Token efficiency**: Reduced payload sizes minimize API costs and response times\n- **Bandwidth optimization**: Less data transmitted over the network\n- **Storage savings**: Server-side storage requirements are reduced\n- **Zero-knowledge preservation**: Compression and deduplication occur before encryption, maintaining the security model\n\n## Compression System\n\n### Purpose and Scope\n\nThe 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.\n\n**资料来源：** [memoraeu_mcp/main.py:1-200](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Compression Threshold\n\n| Parameter | Description | Default Value |\n|-----------|-------------|---------------|\n| `COMPRESSION_THRESHOLD` | Minimum content length to trigger compression | Configurable in source |\n\nThe compression logic follows a decision tree:\n\n```mermaid\ngraph TD\n A[New Memory Content] --> B{Content Length > Threshold?}\n B -->|No| C[Return Original Content]\n B -->|Yes| D[Call Mistral Chat API]\n D --> E{Summary Shorter Than Original?}\n E -->|Yes| F[Return Compressed Summary]\n E -->|No| C\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### The `compress_locally` Function\n\nThe compression function `compress_locally()` implements the following workflow:\n\n1. **Threshold Check**: Only processes content exceeding `COMPRESSION_THRESHOLD` characters\n2. **Prompt Engineering**: Sends the content to Mistral Chat with a French-language summarization prompt\n3. **Validation**: Accepts the summary only if it's shorter than the original\n4. **Fallback**: Returns original content if compression doesn't yield improvement\n\n```python\nasync def compress_locally(content: str) -> str:\n \"\"\"Compress content locally before encryption.\"\"\"\n if len(content) <= COMPRESSION_THRESHOLD:\n return content\n prompt = (\n \"Résume ce texte en 1-3 phrases concises, en français, en gardant l'essentiel. \"\n \"Réponds uniquement avec le résumé, sans introduction ni conclusion.\\n\\n\"\n f\"{content}\"\n )\n compressed = await _mistral_chat(prompt)\n if compressed and len(compressed) < len(content):\n print(f\"[mcp] Compression: {len(content)} → {len(compressed)} chars\", file=sys.stderr)\n return compressed\n return content\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Integration with `remember` Tool\n\nCompression is automatically applied during the `remember` tool execution:\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as MCP Server\n participant Mistral as Mistral API\n \n User->>MCP: remember(content)\n MCP->>MCP: compress_locally(content)\n MCP->>Mistral: Summarization Request\n Mistral-->>MCP: Compressed Summary\n MCP->>MCP: encrypt_content()\n MCP->>MCP: api_post(\"/memories\")\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py) and [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n## Deduplication System\n\n### Purpose and Scope\n\nThe 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.\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md) and [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n### Similarity Thresholds\n\n| Similarity Score | Action |\n|------------------|--------|\n| ≥ 94% (0.94) | Memory ignored — exact duplicate |\n| < 94% | Memory stored with warning logged |\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### The `check_duplicate` Function\n\nThe `check_duplicate()` function searches for similar memories using pre-computed vector embeddings:\n\n```python\nasync def check_duplicate(embedding: list[float]) -> dict | None:\n \"\"\"\n Recherche une mémoire similaire via le vecteur pré-calculé (zero-knowledge).\n Retourne la mémoire la plus similaire si le seuil est dépassé.\n \"\"\"\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Zero-Knowledge Embedding Model\n\nEmbeddings 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.\n\n```mermaid\ngraph LR\n A[Plaintext Content] -->|Before Encryption| B[Mistral Embed API]\n B --> C[Embedding Vector]\n C --> D[check_duplicate]\n A -->|After Encryption| E[Encrypted Content]\n E --> F[Server Storage]\n \n style B fill:#90EE90\n style D fill:#FFE4B5\n```\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md) and [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n### Deduplication Workflow\n\n```mermaid\ngraph TD\n A[New Memory] --> B[Generate Embedding]\n B --> C[Call check_duplicate]\n C --> D{Similar Memory Found?}\n D -->|No| E[Store Memory Normally]\n D -->|Yes| F{Score >= 94%?}\n F -->|Yes| G[Skip - Show Duplicate Warning]\n F -->|No| H[Log Warning - Store Anyway]\n \n G --> I[Display Existing Memory ID]\n H --> E\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py) and [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n### Duplicate Detection Response\n\nWhen a duplicate is detected, the system returns a formatted warning message:\n\n```\n⚠️ Doublon détecté (95% similaire) — mémoire non créée.\n→ Existante : [memory preview] (ID: abc12345...)\n```\n\n**资料来源：** [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n\n## Processing Pipeline\n\nThe complete optimization pipeline executes in the following order during the `remember` operation:\n\n```mermaid\nflowchart LR\n subgraph Phase1[\"Phase 1: Pre-Encryption Processing\"]\n A1[Raw Content] --> B1[Compression
compress_locally]\n B1 --> C1[Categorization
suggest_category_locally]\n C1 --> D1[Embedding
embed_locally]\n end\n \n subgraph Phase2[\"Phase 2: Deduplication Check\"]\n D1 --> E1[check_duplicate]\n E1 --> F1{Skip?}\n end\n \n subgraph Phase3[\"Phase 3: Encryption & Storage\"]\n F1 -->|No| G1[encrypt_content]\n G1 --> H1[api_post /memories]\n end\n \n F1 -->|Yes| I1[Return Duplicate Warning]\n```\n\n**资料来源：** [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Dependencies\n\nThe optimization features depend on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `httpx` | 0.28.1 | Async HTTP client for Mistral API calls |\n| `starlette` | ≥0.40.0,<0.42.0 | Web framework components |\n| `cryptography` | ≥42.0.0 | Encryption primitives |\n| `python-dotenv` | 1.0.1 | Environment variable management |\n\n**资料来源：** [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Configuration Variables\n\nThe system uses environment variables for Mistral API integration:\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MISTRAL_API_KEY` | Authentication for Mistral Embed and Chat APIs | Yes (for stdio install) |\n| `MEMORAEU_API_KEY` | MemoraEU API authentication | Yes |\n| `MEMORAEU_SECRET` | Password for key derivation | Yes (stdio) |\n| `MEMORAEU_SALT` | KDF salt for encryption | Yes (stdio) |\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Version History\n\n| Version | Date | Changes |\n|---------|------|---------|\n| 0.1.9 | 2026-05-12 | PBKDF2 updated to 210,000 iterations, `ENCv1:` prefix added |\n| 0.1.5 | 2026-04-28 | PBKDF2 updated to 210k iterations, refactoring |\n| Initial | — | Near-duplicate detection with 0.94 threshold |\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n## Security Considerations\n\n### Zero-Knowledge Guarantee\n\nThe optimization pipeline preserves zero-knowledge encryption by:\n\n1. **Embedding before encryption**: Vector embeddings are computed from plaintext locally\n2. **Compression before encryption**: Summarization occurs on plaintext content\n3. **Local-only processing**: All LLM calls (Mistral) happen client-side\n4. **Server receives encrypted data**: Only encrypted content and pre-computed embeddings travel to the server\n\n### Limitations\n\n- Compression quality depends on Mistral model's summarization capabilities\n- Deduplication threshold (94%) is fixed and not configurable at runtime\n- Similarity search requires pre-computed embeddings, which must be generated during initial storage\n\n---\n\n\n\n## Structured Facts System\n\n### 相关页面\n\n相关主题：[MCP Tools Reference](#page-mcp-tools), [Auto-Memory System](#page-auto-memory)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n \n\n# Structured Facts System\n\nThe 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.\n\n## Overview\n\nTraditional 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:\n\n- **Subject**: The entity being described (e.g., \"Project Alpha\")\n- **Predicate**: The property or relation (e.g., \"status\", \"manager\")\n- **Object**: The value or target (e.g., \"active\", \"John Doe\")\n- **Validity Period**: Time-bounded truth (from/to dates)\n\n资料来源：[CHANGELOG.md:12-14]()\n\n```mermaid\ngraph TD\n subgraph \"Structured Facts Architecture\"\n A[User Query] --> B[recall_facts]\n B --> C[API GET /facts]\n D[New Fact] --> E[remember_fact]\n E --> F[Client Encryption]\n F --> G[API POST /facts]\n G --> H[(Encrypted Storage)]\n C --> I[Decrypt & Filter]\n I --> J[Active Facts Only]\n K[Expired Fact] --> L[invalidate_fact]\n L --> M[API PUT /facts/:id]\n end\n```\n\n## Data Model\n\nEach structured fact follows this schema:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | UUID | Auto | Unique fact identifier |\n| `subject` | string | Yes | Entity being described |\n| `predicate` | string | Yes | Property or relation name |\n| `object` | string | Yes | Encrypted value (E2E) |\n| `scope` | enum | No | `private` (default) or `org` |\n| `valid_from` | date | Auto | When fact became true |\n| `valid_to` | date | No | When fact ceased to be true |\n| `supersedes` | UUID | Auto | Previous fact ID this replaces |\n\n资料来源：[memoraeu_mcp/main.py:60-75]()\n\n### Fact Validity States\n\n```mermaid\nstateDiagram-v2\n [*] --> Active: valid_from <= today\n Active --> Expired: invalidate_fact called\n Active --> Superseded: remember_fact same subject+predicate\n Expired --> [*]\n Superseded --> [*]\n \n state Active {\n [*] --> Current\n }\n```\n\n## MCP Tools\n\n### remember_fact\n\nStores a structured fact with automatic encryption and temporal tracking.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `subject` | string | Yes | Entity name |\n| `predicate` | string | Yes | Property name |\n| `object` | string | Yes | Value (encrypted before storage) |\n| `scope` | string | No | `private` or `org` (default: `private`) |\n| `valid_from` | string | No | Start date YYYY-MM-DD |\n\n**Response Format:**\n```\n✅ Fait mémorisé 🔒 (remplace {id}…)\n {subject} → {predicate}\n Depuis: {valid_from} | ID: {id}…\n```\n\n**Key Behaviors:**\n\n1. **Encryption**: `object` value is encrypted client-side before transmission\n2. **Auto-supersession**: If a fact with the same `subject` + `predicate` exists, the new fact automatically replaces it (old one marked invalid via `supersedes` field)\n3. **Timestamp**: `valid_from` defaults to today if not specified\n\n资料来源：[memoraeu_mcp/main.py:76-106]()\n\n### recall_facts\n\nRetrieves active facts for a specific subject entity.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `subject` | string | Yes | Entity to query |\n| `predicate` | string | No | Filter by specific property |\n| `scope` | string | No | `private` or `org` (default: `private`) |\n| `history` | boolean | No | Include expired facts (default: false) |\n\n**Response Format:**\n```\n📊 {count} fait(s) pour '{subject}' :\n\n• {predicate}: {decrypted_value}\n [{valid_from} → {valid_to}] | ID: {id}…\n```\n\n资料来源：[memoraeu_mcp/main.py:107-136]()\n\n### invalidate_fact\n\nMarks a fact as expired, indicating the information is no longer true.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fact_id` | string | Yes | UUID of fact to expire |\n| `valid_to` | string | No | End date YYYY-MM-DD (default: today) |\n\n**Behavior:**\n- Sets `valid_to` to specified date or current date\n- Expired facts are excluded from default `recall_facts` queries\n- Use `history=true` in `recall_facts` to see expired facts\n\n资料来源：[memoraeu_mcp/main.py:137-152]()\n\n## Workflows\n\n### Creating a New Fact\n\n```mermaid\nsequenceDiagram\n participant U as User/Claude\n participant M as MCP Server\n participant C as Crypto Layer\n participant A as MemoraEU API\n \n U->>M: remember_fact(subject, predicate, object)\n M->>C: encrypt_content(object)\n C-->>M: encrypted_blob\n M->>M: Check for existing fact (same subject+predicate)\n M->>A: POST /facts {subject, predicate, encrypted_blob, scope}\n A->>A: Set valid_from=today\n A->>A: Mark old fact as superseded\n A-->>M: {id, supersedes, valid_from}\n M-->>U: Confirmation with ID\n```\n\n### Querying Facts\n\n```mermaid\nsequenceDiagram\n participant U as User/Claude\n participant M as MCP Server\n participant A as MemoraEU API\n participant C as Crypto Layer\n \n U->>M: recall_facts(subject, history=false)\n M->>A: GET /facts?subject={subject}\n A-->>M: [facts with valid_to=null]\n M->>C: decrypt_content(facts[].object)\n C-->>M: decrypted_values\n M-->>U: Active facts only\n```\n\n## Security Model\n\nAll structured facts leverage the same zero-knowledge encryption as regular memories:\n\n| Layer | Implementation |\n|-------|----------------|\n| Key Derivation | PBKDF2-HMAC-SHA256, 210,000 iterations (OWASP 2024) |\n| Symmetric Cipher | AES-256-GCM |\n| Ciphertext Format | `ENCv1:{base64_ciphertext}` |\n\n资料来源：[CHANGELOG.md:18-19]()\n\n**Encryption Flow for Facts:**\n\n1. `object` value encrypted client-side before API transmission\n2. `subject` and `predicate` transmitted in plaintext (used for routing/indexing)\n3. Server never sees decrypted values\n\n```python\n# From memoraeu_mcp/main.py:78-79\nencrypted_object = encrypt_content(arguments[\"object\"])\npayload = {\n \"subject\": arguments[\"subject\"],\n \"predicate\": arguments[\"predicate\"],\n \"object\": encrypted_object,\n ...\n}\n```\n\n## Use Cases\n\n### Preference Tracking\n\n```\nremember_fact(subject=\"Alice\", predicate=\"preferred_language\", object=\"French\")\n```\n\n### Status Changes\n\n```\nremember_fact(subject=\"Project X\", predicate=\"status\", object=\"completed\", valid_from=\"2024-01-15\")\n```\n\n### Configuration State\n\n```\nremember_fact(subject=\"dev-environment\", predicate=\"python_version\", object=\"3.12.1\")\n```\n\n### Relationship Management\n\n```\nremember_fact(subject=\"Team Alpha\", predicate=\"lead\", object=\"bob@example.com\")\n```\n\n## Comparison with Regular Memories\n\n| Aspect | Regular Memory | Structured Facts |\n|--------|----------------|-------------------|\n| Content | Free-form text | Subject-predicate-object |\n| Query | Semantic search | Entity-based retrieval |\n| Deduplication | Vector similarity ≥94% | Auto-supersession by predicate |\n| Temporal | Implicit | Explicit valid_from/valid_to |\n| Use Case | Context, preferences, notes | Entity state, relationships |\n\n资料来源：[README.md:34-45]()\n\n## Configuration\n\nStructured Facts require no additional configuration beyond the base MCP server setup:\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MEMORAEU_API_KEY` | Bearer token authentication | Yes |\n| `MEMORAEU_SECRET` | Password for PBKDF2 key derivation | Yes (for encryption) |\n| `MEMORAEU_SALT` | KDF salt from server | Yes (for encryption) |\n| `MEMORAEU_API_URL` | API endpoint | Yes |\n| `MISTRAL_API_KEY` | Embedding generation | Yes (stdio mode) |\n\n资料来源：[README.md:60-74]()\n\n## Implementation Notes\n\n### Duplicate Detection Strategy\n\nUnlike regular memories which use vector similarity thresholds, structured facts handle duplicates through **predicate-based supersession**:\n\n```\nSame subject + Same predicate = Automatic supersession\nSame subject + Different predicate = Distinct facts (no conflict)\n```\n\n### API Endpoints Used\n\n| Tool | Endpoint | Method |\n|------|----------|--------|\n| `remember_fact` | `/facts` | POST |\n| `recall_facts` | `/facts` | GET |\n| `invalidate_fact` | `/facts/{id}` | PUT |\n\n### Response Formatting\n\nThe system uses emoji indicators in responses:\n- 🔒 — Indicates content is encrypted\n- 📝 — Indicates content is unencrypted (no key configured)\n- 📊 — Prefixed fact list headers\n\n资料来源：[memoraeu_mcp/main.py:93-98]()\n\n## Version History\n\n| Version | Date | Changes |\n|---------|------|---------|\n| 0.1.9 | 2026-05-12 | Initial structured facts release: `remember_fact`, `recall_facts`, `invalidate_fact` |\n\n资料来源：[CHANGELOG.md:10-15]()\n\n---\n\n\n\n## MCP Tools Reference\n\n### 相关页面\n\n相关主题：[Auto-Memory System](#page-auto-memory), [Structured Facts System](#page-structured-facts)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [memoraeu_mcp/server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/moraeu_mcp/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# MCP Tools Reference\n\n## Overview\n\nThe `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.\n\n**资料来源：** [requirements.txt:1]()\n\n**Key Capabilities:**\n\n- Semantic memory storage with automatic categorization\n- Structured fact management with temporal validity\n- Client-side encryption using AES-256-GCM\n- Near-duplicate detection before storage\n- Automatic context injection on session start\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n---\n\n## Architecture\n\n### System Components\n\n```mermaid\ngraph TD\n A[\"Claude Desktop / AI Client\"] -->|MCP Protocol| B[\"memoraeu-mcp Server\"]\n B -->|API Calls| C[\"MemoraEU Cloud API\"]\n \n B --> D[\"Local Pre-processing\"]\n D --> E[\"Mistral API
(Embeddings + Categorization)\"]\n \n B --> F[\"Encryption Layer
(PBKDF2 + AES-256-GCM)\"]\n F --> C\n \n style E fill:#f9f,stroke:#333\n style F fill:#ff9,stroke:#333\n```\n\n### Memory Storage Flow\n\n```mermaid\nsequenceDiagram\n participant Client as AI Client\n participant MCP as memoraeu-mcp\n participant Mistral as Mistral API\n participant Crypto as Encryption Layer\n participant API as MemoraEU API\n \n Client->>MCP: remember(content, category?)\n MCP->>Mistral: compress_locally(content)\n Mistral-->>MCP: compressed_content\n MCP->>Mistral: suggest_category(content, existing)\n Mistral-->>MCP: category\n MCP->>Mistral: generate_embedding(content)\n Mistral-->>MCP: embedding\n MCP->>MCP: check_duplicates(embedding)\n MCP->>Crypto: encrypt(compressed_content)\n Crypto-->>MCP: encrypted_blob\n MCP->>API: POST /memories
(encrypted + embedding)\n API-->>MCP: memory_id\n MCP-->>Client: ✅ Memorized\n```\n\n**资料来源：** [memoraeu_mcp/main.py:60-100](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Core Memory Tools\n\n### `remember`\n\nStores a memory with automatic compression, categorization, and duplicate detection.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"remember\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | The memory content to store |\n| `category` | string | No | Category name; auto-suggested if omitted |\n| `tags` | array[string] | No | Custom tags for the memory |\n\n**Workflow:**\n\n1. Compress content locally via Mistral API\n2. Suggest or use provided category\n3. Generate embedding from plaintext (before encryption)\n4. Check for near-duplicates using vector similarity (threshold: 0.94)\n5. Encrypt content with AES-256-GCM\n6. Send to `/memories` endpoint with `pre_processed: true`\n\n**Duplicate Detection Behavior:**\n\n| Similarity Score | Action |\n|------------------|--------|\n| ≥ 94% | Skip storage, return existing memory ID |\n| < 94% | Store anyway with warning logged |\n\n**资料来源：** [memoraeu_mcp/main.py:90-130](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n**Response Format:**\n\n```\n✅ Memorized 🔒 (ID: abc12345…, catégorie: preferences)\n```\n\nThe 🔒 lock icon indicates encryption is active (key available).\n\n---\n\n### `recall`\n\nPerforms semantic search across stored memories.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"recall\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 3},\n \"category\": {\"type\": \"string\"}\n },\n \"required\": [\"query\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `query` | string | Yes | — | Semantic search query |\n| `limit` | integer | No | 3 | Maximum results to return |\n| `category` | string | No | — | Filter by category |\n\n**Auto-Recall Behavior:**\n\nThe MCP server is designed to automatically invoke `recall` on the first user message of each session using the detected topic as the query. This behavior is encoded in the tool description and reinforced via system prompt injection.\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n**Special Behavior on First Recall:**\n\n1. Loads session context from `memoraeu://context` resource\n2. Injects the full system prompt into Claude's context\n3. Returns results merged with existing context\n\n---\n\n### `forget`\n\nDeletes a memory by its ID.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"forget\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"memory_id\": {\"type\": \"string\"}\n },\n \"required\": [\"memory_id\"]\n }\n}\n```\n\n**Response:**\n\n```\n🗑️ Supprimée.\n```\n\nOr `Introuvable.` if the memory does not exist.\n\n**资料来源：** [memoraeu_mcp/main.py:145-150](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n### `list_memories`\n\nLists recent memories with optional category filtering.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"list_memories\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"category\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 20}\n }\n }\n}\n```\n\n**Response Format:**\n\n```\n📋 5 mémoire(s) :\n\n• [preferences] User prefers dark mode... (ID: abc12345…)\n• [config] Python 3.11 installed... (ID: def67890…)\n```\n\n---\n\n### `list_categories`\n\nReturns existing categories sorted by usage frequency.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"list_categories\",\n \"inputSchema\": {\"type\": \"object\", \"properties\": {}}\n}\n```\n\n**Response Format:**\n\n```\n📂 Catégories :\n\n• preferences (42 usages)\n• config (18 usages)\n• projects (7 usages)\n```\n\n**资料来源：** [memoraeu_mcp/main.py:160-175](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Structured Fact Tools\n\n### `remember_fact`\n\nStores a structured fact with subject/predicate/object pattern and temporal validity.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"remember_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"object\": {\"type\": \"string\"},\n \"valid_from\": {\"type\": \"string\"},\n \"valid_to\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"], \"default\": \"private\"}\n },\n \"required\": [\"subject\", \"predicate\", \"object\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `subject` | string | Yes | Entity being described |\n| `predicate` | string | Yes | Property/relationship name |\n| `object` | string | Yes | Value of the property |\n| `valid_from` | string | No | Start date (YYYY-MM-DD) |\n| `valid_to` | string | No | End date (YYYY-MM-DD) |\n| `scope` | string | No | `private` (default) or `org` |\n\n**Key Features:**\n\n- **Auto-invalidation**: Automatically invalidates previous fact with same subject+predicate\n- **Temporal validity**: Supports date ranges for time-sensitive facts\n- **Encryption**: Object value is encrypted before transmission\n\n**Response Format:**\n\n```\n✅ Fait mémorisé 🔒\n User → prefers_color\n Depuis: 2026-01-15 | ID: abc12345…\n```\n\nOr if superseded:\n\n```\n✅ Fait mémorisé 🔒 (remplace abc12345…)\n User → prefers_color\n Depuis: 2026-01-20 | ID: def67890…\n```\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n### `recall_facts`\n\nRetrieves active (non-expired) facts for a given subject.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"recall_facts\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"], \"default\": \"private\"},\n \"history\": {\"type\": \"boolean\", \"default\": False}\n },\n \"required\": [\"subject\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `subject` | string | Yes | — | Entity to query |\n| `predicate` | string | No | — | Filter by specific property |\n| `scope` | string | No | private | `private` or `org` |\n| `history` | boolean | No | false | Include expired facts |\n\n**Response Format:**\n\n```\n📊 2 fait(s) pour 'User' :\n\n• prefers_color: blue\n [2026-01-15 → aujourd'hui] | ID: abc12345…\n\n• works_at: Acme Corp\n [2025-03-01 → 2026-02-28 (expiré)] | ID: def67890…\n```\n\n**资料来源：** [memoraeu_mcp/main.py:180-210](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n### `invalidate_fact`\n\nMarks a fact as expired, indicating it is no longer true.\n\n**Tool Definition:**\n\n```json\n{\n \"name\": \"invalidate_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"fact_id\": {\"type\": \"string\"},\n \"valid_to\": {\"type\": \"string\"}\n },\n \"required\": [\"fact_id\"]\n }\n}\n```\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `fact_id` | string | Yes | ID of fact to invalidate |\n| `valid_to` | string | No | End date (default: today) |\n\n**资料来源：** [memoraeu_mcp/main.py:212-220](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## MCP Resources\n\n### `memoraeu://context`\n\nA read-only resource that provides session context with recent memories.\n\n**Resource Definition:**\n\n```python\nResource(\n uri=\"memoraeu://context\",\n name=\"Contexte mémoire MemoraEU\",\n description=\"Mémoires récentes injectées automatiquement en début de session\",\n mimeType=\"text/plain\"\n)\n```\n\n**Usage in Tool Calls:**\n\nOn the first `recall` invocation, the MCP server automatically:\n\n1. Reads from `memoraeu://context` resource\n2. Injects session context into the response\n3. Loads relevant memories via `/memories/recent` endpoint\n\n**资料来源：** [memoraeu_mcp/main.py:45-60](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## MCP Prompts\n\n### `memoraeu_system`\n\nA system prompt that reinforces automatic memory behavior rules for Claude.\n\n**Prompt Content:**\n\n```\n## Rôle\nTu es un assistant qui mémorise automatiquement les informations importantes pour l'utilisateur.\n\n## Ce qu'il faut retenir\n- Préférences et choix de l'utilisateur\n- Décisions prises au cours de la conversation\n- Faits biographiques ou informations récurrentes ou contraintes durables\n- Informations techniques propres à l'utilisateur (stack, config, credentials non-sensibles)\n\n## Rappel automatique\nDès le premier message de l'utilisateur, utilise `recall` avec le sujet détecté comme query.\nN'attends pas qu'on te le demande — c'est automatique.\n\n## Règles\n- Ne mémorise pas les informations générales ou éphémères (météo du jour, blagues, calculs ponctuels)\n- Si l'utilisateur dit \"oublie ça\" ou \"ne retiens pas\", utilise `forget`\n- Confirme discrètement les mémorisations : une ligne, pas plus\n- Optimisation tokens : limite recall à 3 résultats par défaut, mémoires compactes\n```\n\n**资料来源：** [memoraeu_mcp/main.py:25-45](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Security Model\n\n### Zero-Knowledge Architecture\n\n```mermaid\ngraph LR\n subgraph Client[\"Client Side (Encrypted)\"]\n P[\"Plaintext\"] -->|PBKDF2
100k iterations| K[\"Key\"]\n P -->|AES-256-GCM| E[\"Encrypted\"]\n K --> E\n end\n \n subgraph Server[\"Server Side\"]\n E -->|\"ENCv1:...\"| DB[\"Encrypted Blob Storage\"]\n end\n \n style P fill:#9f6\n style K fill:#f96\n style DB fill:#99f\n```\n\n**Encryption Details:**\n\n| Component | Specification |\n|-----------|---------------|\n| Key Derivation | PBKDF2-HMAC-SHA256 |\n| Iterations | 100,000 (OWASP 2024 recommendation: 210,000) |\n| Cipher | AES-256-GCM |\n| Ciphertext Format | `ENCv1:` |\n| Salt | Unique per user, stored server-side |\n\n**资料来源：** [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n### Local Pre-processing\n\nTo maintain zero-knowledge guarantees, the following operations occur **before** encryption:\n\n1. **Compression** — Content is compressed via Mistral API\n2. **Categorization** — Category is suggested using existing categories\n3. **Embedding Generation** — Vector embeddings computed from plaintext\n\nOnly the **content** is encrypted. Embeddings, categories, and metadata are stored in cleartext for search functionality.\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n---\n\n## API Endpoints\n\n| Endpoint | Method | Tool | Purpose |\n|----------|--------|------|---------|\n| `/memories` | POST | `remember` | Create encrypted memory |\n| `/memories/search` | POST | `recall` | Semantic search |\n| `/memories/{id}` | DELETE | `forget` | Delete memory |\n| `/memories` | GET | `list_memories` | List recent memories |\n| `/memories/categories` | GET | `list_categories` | List categories |\n| `/facts` | POST | `remember_fact` | Create structured fact |\n| `/facts` | GET | `recall_facts` | Query facts |\n| `/facts/{id}` | PUT | `invalidate_fact` | Expire fact |\n\n**资料来源：** [memoraeu_mcp/main.py:130-220](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n---\n\n## Environment Configuration\n\n| Variable | Purpose | Required |\n|----------|---------|----------|\n| `MEMORAEU_API_URL` | API endpoint | Yes |\n| `MEMORAEU_API_KEY` | Bearer token authentication | Yes |\n| `MEMORAEU_SECRET` | Password for PBKDF2 key derivation | For local/stdio |\n| `MEMORAEU_SALT` | KDF salt (unique per account) | For local/stdio |\n| `MISTRAL_API_KEY` | Embedding generation | For local/stdio |\n\n**资料来源：** [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n---\n\n## Tool Summary Table\n\n| Tool | Category | Auto-Inject | Encryption |\n|------|----------|-------------|------------|\n| `remember` | Memory | No | Yes |\n| `recall` | Memory | Yes (first call) | Decrypted output |\n| `forget` | Memory | No | N/A |\n| `list_memories` | Memory | No | Decrypted output |\n| `list_categories` | Memory | No | No |\n| `remember_fact` | Facts | No | Object only |\n| `recall_facts` | Facts | No | Decrypted output |\n| `invalidate_fact` | Facts | No | N/A |\n\n---\n\n\n\n## Configuration Reference\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [Security and Encryption](#page-security-encryption)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n \n\n# Configuration Reference\n\nThis 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.\n\n---\n\n## Overview\n\nThe MemoraEU MCP server acts as an intermediary between AI assistants (such as Claude) and the MemoraEU memory API. It enables automatic memory management with end-to-end encryption where the server never sees plaintext content. Configuration involves setting up environment variables for authentication, encryption, and API access, as well as defining the MCP server connection in your AI client's configuration file.\n\n资料来源：[README.md:1-45]()\n\n---\n\n## Environment Variables\n\n### Required Variables\n\nThe following environment variables are mandatory for MCP server operation. They are **not interchangeable** and serve distinct purposes in the authentication and encryption pipeline.\n\n| Variable | Purpose | Source |\n|----------|---------|--------|\n| `MEMORAEU_API_KEY` | HTTP Bearer token sent with every request for API authentication | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | User's MemoraEU login password; used as PBKDF2 input to derive the encryption key locally | Your account password |\n| `MEMORAEU_SALT` | KDF salt generated by the server, unique to your account; combined with `MEMORAEU_SECRET` to produce the encryption key | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint for the hosted service | Use `https://api.memoraeu.com` |\n| `MISTRAL_API_KEY` | Required for generating embeddings locally before encryption; enables zero-knowledge semantic search | [console.mistral.ai](https://console.mistral.ai) |\n\n资料来源：[README.md:60-85]()\n\n### Variable Dependency Graph\n\n```mermaid\ngraph TD\n A[User Password] --> B[PBKDF2 Key Derivation]\n C[MEMORAEU_SALT] --> B\n B --> D[ AES-256-GCM Encryption]\n \n E[Plaintext Content] --> F[Mistral Embed API]\n F --> G[Embedding Vector]\n G --> D\n D --> H[Encrypted Blob]\n \n I[API Request] --> J[MEMORAEU_API_KEY]\n J --> K[Bearer Header]\n K --> I\n```\n\n### Optional Behavior Without `MISTRAL_API_KEY`\n\nIf `MISTRAL_API_KEY` is not provided, the MCP server continues to function with degraded semantic search capabilities:\n\n- `remember` and `recall` tools remain operational\n- Semantic search falls back to **keyword-based search on the server side**\n- Zero-knowledge encryption is **not affected**\n\n资料来源：[README.md:88-92]()\n\n---\n\n## MCP Client Configuration\n\n### stdio Mode (Local Installation)\n\nFor full zero-knowledge guarantees, use the stdio transport mode with local installation. Add the following configuration to your `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:38-52]()\n\n### SSE Mode (Remote Connection)\n\nFor remote connections without local installation, use Server-Sent Events (SSE) transport. This mode works with Claude.ai web, Cursor, Windsurf, or any MCP-compatible remote client.\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:5-14]()\n\n### Security Warning for SSE Mode\n\n> **Note:** In remote SSE mode, content is **not** zero-knowledge encrypted because the server processes plaintext. Use the local `stdio` installation for full zero-knowledge guarantees.\n\n资料来源：[README.md:15-17]()\n\n---\n\n## Zero-Knowledge Encryption Configuration\n\n### Encryption Architecture\n\nThe zero-knowledge architecture ensures the server never sees plaintext content. Embeddings are generated locally before encryption:\n\n```mermaid\nsequenceDiagram\n participant User as User/AI\n participant MCP as MCP Server\n participant Mistral as Mistral API\n participant Server as MemoraEU API\n participant DB as Encrypted DB\n\n User->>MCP: Raw memory content\n MCP->>Mistral: Plaintext for embedding\n Mistral-->>MCP: Embedding vector\n MCP->>MCP: AES-256-GCM encryption\n MCP->>Server: Encrypted blob + embedding vector\n Server->>DB: Store opaque data\n```\n\n资料来源：[README.md:80-84]()\n\n### PBKDF2 Configuration\n\nThe encryption key derivation uses PBKDF2-HMAC-SHA256 with the following parameters:\n\n| Parameter | Value | Source |\n|-----------|-------|--------|\n| Iterations | 210,000 | CHANGELOG.md:20 |\n| Hash Algorithm | SHA256 | CHANGELOG.md:20 |\n| Cipher | AES-256-GCM | CHANGELOG.md:4 |\n| Ciphertext Prefix | `ENCv1:` | CHANGELOG.md:20 |\n\n资料来源：[CHANGELOG.md:17-21]()\n\n---\n\n## Tool Input Schemas\n\n### Core Memory Tools\n\n#### `remember`\n\nMemorizes important information automatically. The AI assistant should call this tool without being asked when the user expresses preferences, decisions, biographical facts, technical configurations, or durable constraints.\n\n```json\n{\n \"name\": \"remember\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"content\": {\"type\": \"string\"},\n \"category\": {\"type\": \"string\"},\n \"tags\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}}\n },\n \"required\": [\"content\"]\n }\n}\n```\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | Yes | The memory content to store |\n| `category` | string | No | Category for organization; auto-suggested if omitted |\n| `tags` | array | No | Array of string tags for filtering |\n\n资料来源：[memoraeu_mcp/main.py:180-200]()\n\n#### `recall`\n\nSemantic search across stored memories. Called automatically on the first user message of each session.\n\n```json\n{\n \"name\": \"recall\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"query\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 3},\n \"category\": {\"type\": \"string\"}\n },\n \"required\": [\"query\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `query` | string | — | Semantic search query |\n| `limit` | integer | 3 | Maximum number of results (token optimization) |\n| `category` | string | — | Filter by category name |\n\n资料来源：[memoraeu_mcp/main.py:202-220]()\n\n#### `forget`\n\nDeletes a memory by its ID.\n\n```json\n{\n \"name\": \"forget\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"memory_id\": {\"type\": \"string\"}\n },\n \"required\": [\"memory_id\"]\n }\n}\n```\n\n资料来源：[memoraeu_mcp/main.py:222-230]()\n\n#### `list_memories`\n\nLists recent memories with optional category filter.\n\n```json\n{\n \"name\": \"list_memories\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"category\": {\"type\": \"string\"},\n \"limit\": {\"type\": \"integer\", \"default\": 20}\n }\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `category` | string | — | Filter by category name |\n| `limit` | integer | 20 | Maximum number of results |\n\n资料来源：[memoraeu_mcp/main.py:244-252]()\n\n#### `list_categories`\n\nReturns existing categories sorted by usage frequency.\n\n```json\n{\n \"name\": \"list_categories\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {}\n }\n}\n```\n\n资料来源：[memoraeu_mcp/main.py:254-258]()\n\n### Structured Fact Tools\n\n#### `remember_fact`\n\nStores a structured fact with temporal validity (subject/predicate/object model).\n\n```json\n{\n \"name\": \"remember_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"object\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"]},\n \"valid_from\": {\"type\": \"string\"}\n },\n \"required\": [\"subject\", \"predicate\", \"object\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `subject` | string | — | Entity being described |\n| `predicate` | string | — | Property or relationship |\n| `object` | string | — | Value of the property |\n| `scope` | string | \"private\" | Access scope (private or org) |\n| `valid_from` | string | — | Start date in YYYY-MM-DD format |\n\n资料来源：[server.py:60-80]()\n\n#### `recall_facts`\n\nRetrieves active facts for a given subject.\n\n```json\n{\n \"name\": \"recall_facts\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"subject\": {\"type\": \"string\"},\n \"predicate\": {\"type\": \"string\"},\n \"scope\": {\"type\": \"string\", \"enum\": [\"private\", \"org\"]},\n \"history\": {\"type\": \"boolean\", \"default\": false}\n },\n \"required\": [\"subject\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `subject` | string | — | Entity to query |\n| `predicate` | string | — | Specific property to retrieve |\n| `scope` | string | \"private\" | Access scope |\n| `history` | boolean | false | Include expired facts |\n\n资料来源：[server.py:82-105]()\n\n#### `invalidate_fact`\n\nMarks a fact as expired.\n\n```json\n{\n \"name\": \"invalidate_fact\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"fact_id\": {\"type\": \"string\"},\n \"valid_to\": {\"type\": \"string\"}\n },\n \"required\": [\"fact_id\"]\n }\n}\n```\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `fact_id` | string | — | ID of the fact to invalidate |\n| `valid_to` | string | today | End date in YYYY-MM-DD format |\n\n资料来源：[server.py:107-120]()\n\n---\n\n## Deduplication Configuration\n\nBefore storing a memory, the MCP checks for near-duplicates using vector similarity:\n\n| Similarity Threshold | Action |\n|---------------------|--------|\n| ≥ 94% | Memory ignored — exact duplicate |\n| < 94% | Memory stored as new |\n\n资料来源：[README.md:110-115]()\n\n---\n\n## Dependencies\n\nThe following Python packages are required for the MCP server:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `mcp` | ≥1.1.0, <1.2.0 | Model Context Protocol framework |\n| `httpx` | 0.28.1 | HTTP client for API requests |\n| `python-dotenv` | 1.0.1 | Environment variable loading |\n| `starlette` | ≥0.40.0, <0.42.0 | ASGI framework |\n| `cryptography` | ≥42.0.0 | Encryption utilities |\n\n资料来源：[requirements.txt:1-5]()\n\n---\n\n## API Endpoints\n\nThe MCP server communicates with the MemoraEU API using the following endpoints:\n\n| Method | Endpoint | Purpose |\n|--------|----------|---------|\n| `POST` | `/memories/search` | Semantic search for memories |\n| `POST` | `/facts` | Store structured facts |\n| `GET` | `/facts` | Retrieve facts for a subject |\n| `PUT` | `/facts/{id}/invalidate` | Mark fact as expired |\n| `GET` | `/memories` | List recent memories |\n| `DELETE` | `/memories/{id}` | Delete a memory |\n| `GET` | `/memories/categories` | Get existing categories |\n\n资料来源：[memoraeu_mcp/main.py:280-310]()\n\n---\n\n## Quick Setup Checklist\n\n1. Create an account at [app.memoraeu.com](https://app.memoraeu.com)\n2. Navigate to **Settings → Encryption Keys** → copy `MEMORAEU_SALT`\n3. Set `MEMORAEU_SECRET` to your MemoraEU login password\n4. Navigate to **Settings → API Keys** → create a key → copy `MEMORAEU_API_KEY`\n5. Obtain a Mistral API key from [console.mistral.ai](https://console.mistral.ai)\n6. Add the MCP server configuration to your client's config file\n7. Set all five environment variables in your configuration\n\n资料来源：[README.md:93-99]()\n\n---\n\n## Security Considerations\n\n| Concern | Mitigation |\n|---------|------------|\n| Server sees plaintext | Use local `stdio` mode; SSE sends plaintext |\n| API key exposure | Store in environment variables, not in config files |\n| Encryption key derivation | PBKDF2 with 210k iterations per OWASP 2024 |\n| Near-duplicate leakage | 94% similarity threshold prevents similar content storage |\n\n---\n\n\n\n## Deployment Guide\n\n### 相关页面\n\n相关主题：[Installation Guide](#page-installation), [Configuration Reference](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n \n\n# Deployment Guide\n\nThis 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.\n\n## Overview\n\nmemoraeu-mcp is an MCP server that enables semantic memory management with client-side AES-256-GCM encryption. The server supports two deployment modes:\n\n| Deployment Mode | Use Case | Encryption | Setup Complexity |\n|-----------------|----------|------------|------------------|\n| **Local (stdio)** | Full zero-knowledge guarantees | Client-side, server never sees plaintext | Higher |\n| **Remote (SSE)** | Quick testing, no install | Server processes plaintext | Minimal |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Prerequisites\n\nBefore deploying, ensure you have:\n\n- **Python 3.10+** with `uvx` or pip access\n- **API Keys**: MemoraEU account, Mistral API key for embeddings\n- **MCP-compatible client**: Claude Desktop, Cursor, Windsurf, or any MCP client\n\n### Python Dependencies\n\n```text\nmcp>=1.1.0,<1.2.0\nhttpx==0.28.1\npython-dotenv==1.0.1\nstarlette>=0.40.0,<0.42.0\ncryptography>=42.0.0\n```\n\n资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)\n\n## Local Deployment (stdio)\n\nThe stdio mode provides complete zero-knowledge encryption. All content is encrypted on the client before transmission.\n\n### Architecture\n\n```mermaid\ngraph TD\n subgraph \"Client Machine\"\n A[MCP Client] -->|stdio| B[memoraeu-mcp]\n B --> C[Mistral API]\n B -->|Encrypt| D[Encrypted Payload]\n end\n D -->|AES-256-GCM| E[MemoraEU API]\n C -->|Embedding| B\n \n style A fill:#e1f5fe\n style E fill:#fff3e0\n style D fill:#f3e5f5\n```\n\n### Configuration Steps\n\n#### 1. Create Claude Desktop Configuration\n\nEdit your Claude Desktop config file:\n\n| OS | Config Location |\n|----|-----------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n#### 2. Add Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"command\": \"uvx\",\n \"args\": [\"memoraeu-mcp\"],\n \"env\": {\n \"MEMORAEU_API_URL\": \"https://api.memoraeu.com\",\n \"MEMORAEU_API_KEY\": \"meu-sk-...\",\n \"MEMORAEU_SECRET\": \"your-memoraeu-password\",\n \"MEMORAEU_SALT\": \"your-kdf-salt\",\n \"MISTRAL_API_KEY\": \"your-mistral-key\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Environment Variables Reference\n\n| Variable | Purpose | Required | Source |\n|----------|---------|----------|--------|\n| `MEMORAEU_API_KEY` | HTTP Bearer authentication | Yes | Dashboard → Settings → API Keys |\n| `MEMORAEU_SECRET` | PBKDF2 password input for key derivation | Yes | Your MemoraEU login password |\n| `MEMORAEU_SALT` | KDF salt unique to your account | Yes | Dashboard → Settings → Encryption Keys |\n| `MEMORAEU_API_URL` | API endpoint | Yes | Use `https://api.memoraeu.com` for hosted |\n| `MISTRAL_API_KEY` | Local embedding generation | Yes* | Mistral Console |\n\n*Without `MISTRAL_API_KEY`, semantic search falls back to server-side keyword matching.\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### Why Local Embeddings?\n\nThe zero-knowledge architecture requires embeddings to be computed **before encryption**:\n\n```mermaid\nsequenceDiagram\n participant User\n participant MCP as memoraeu-mcp\n participant Mistral\n participant Server\n \n User->>MCP: remember(\"I prefer dark mode\")\n MCP->>Mistral: Generate embedding\n Mistral-->>MCP: Embedding vector\n MCP->>MCP: AES-256-GCM encrypt content\n MCP->>Server: Encrypted content + embedding\n Note over Server: Never sees plaintext\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Remote Deployment (SSE)\n\nSSE mode connects directly to the hosted MemoraEU MCP endpoint without local installation.\n\n### Configuration for Cursor/Windsurf\n\n```json\n{\n \"mcpServers\": {\n \"memoraeu\": {\n \"type\": \"sse\",\n \"url\": \"https://api.memoraeu.com/mcp/sse\",\n \"headers\": {\n \"Authorization\": \"Bearer meu-sk-...\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n### SSE Endpoint Details\n\n| Property | Value |\n|----------|-------|\n| Protocol | Server-Sent Events (SSE) |\n| Endpoint | `https://api.memoraeu.com/mcp/sse` |\n| Authentication | Bearer token in header |\n| Encryption | Not zero-knowledge* |\n\n> **Warning**: In remote SSE mode, content is processed as plaintext by the server. Use local stdio installation for zero-knowledge guarantees.\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Obtaining Credentials\n\nFollow these steps to obtain all required credentials:\n\n### Step 1: MemoraEU Account\n\n1. Create account at [app.memoraeu.com](https://app.memoraeu.com)\n\n### Step 2: Get Encryption Salt\n\n1. Go to **Settings → Encryption Keys**\n2. Copy the `MEMORAEU_SALT` value\n\n### Step 3: Set Secret\n\n1. `MEMORAEU_SECRET` is your MemoraEU login password\n2. Used as PBKDF2 input to derive encryption key\n\n### Step 4: Get API Key\n\n1. Go to **Settings → API Keys**\n2. Create a new key\n3. Copy the `MEMORAEU_API_KEY` (format: `meu-sk-xxx`)\n\n### Step 5: Get Mistral API Key\n\n1. Obtain key at [console.mistral.ai](https://console.mistral.ai)\n2. Required for local embedding generation\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Security Considerations\n\n### Encryption Implementation\n\n| Aspect | Detail |\n|--------|--------|\n| Algorithm | AES-256-GCM |\n| Key Derivation | PBKDF2-HMAC-SHA256 |\n| Iterations | 210,000 (OWASP 2024 recommendation) |\n| Ciphertext Prefix | `ENCv1:` |\n| Salt | Server-generated, unique per account |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n### Security Comparison\n\n| Feature | stdio (Local) | SSE (Remote) |\n|---------|---------------|--------------|\n| Zero-knowledge | ✅ Yes | ❌ No |\n| Embeddings | Local (via Mistral) | Server-processed |\n| Content encryption | Client-side | Server-side |\n| PBKDF2 iterations | 210,000 | 210,000 |\n\n资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)\n\n## Available MCP Tools\n\nOnce deployed, the following tools are available:\n\n| Tool | Description |\n|------|-------------|\n| `remember` | Automatically memorize important information |\n| `recall` | Semantic search across stored memories |\n| `forget` | Delete a memory by ID |\n| `list_memories` | List recent memories with optional category filter |\n| `list_categories` | Return existing categories sorted by usage |\n| `remember_fact` | Store structured fact with temporal validity |\n| `recall_facts` | Retrieve active facts for a subject |\n| `invalidate_fact` | Mark a fact as expired |\n\n资料来源：[memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `MISTRAL_API_KEY` missing | MCP continues working but semantic search falls back to keyword matching |\n| Authentication failed | Verify `MEMORAEU_API_KEY` format is `meu-sk-xxx` |\n| Encryption errors | Ensure `MEMORAEU_SECRET` and `MEMORAEU_SALT` are correct |\n| stdio connection refused | Restart Claude Desktop after config changes |\n\n### Verification Steps\n\n1. Check config file syntax is valid JSON\n2. Verify all required environment variables are set\n3. Confirm API keys are active in MemoraEU dashboard\n4. Restart the MCP client after configuration changes\n\n## Version History\n\n| Version | Date | Key Changes |\n|---------|------|-------------|\n| 0.1.9 | 2026-05-12 | Added fact tools, PBKDF2 210k iterations, ENCv1 prefix |\n| 0.1.5 | 2026-04-28 | Initial fact support, PBKDF2 updates |\n\n资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: pquattro/memoraeu-mcp\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | host_targets=mcp_host, claude\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: pquattro/memoraeu-mcp\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | host_targets=mcp_host, claude\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | last_activity_observed missing\n\n## 4. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# memoraeu-mcp - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for pquattro/memoraeu-mcp.\n\nProject:\n- Name: memoraeu-mcp\n- Repository: https://github.com/pquattro/memoraeu-mcp\n- Summary: Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.\n- Host target: mcp_host, claude\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Zero-knowledge persistent memory layer for Claude — AES-256-GCM encrypted, semantic search, EU hosted. MCP server for Claude Desktop.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-home: Home. Produce one small intermediate artifact and wait for confirmation.\n2. page-installation: Installation Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. page-security-encryption: Security and Encryption. Produce one small intermediate artifact and wait for confirmation.\n5. page-auto-memory: Auto-Memory System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/pquattro/memoraeu-mcp\n- https://github.com/pquattro/memoraeu-mcp#readme\n- README.md\n- memoraeu_mcp/__init__.py\n- server.json\n- pyproject.toml\n- memoraeu_mcp/main.py\n- memoraeu_mcp/server.py\n- server.py\n- memoraeu_mcp/crypto.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: pquattro/memoraeu-mcp\n\n## Official Entry Points\n\n### Python / pip · 官方安装入口\n\n```bash\npip install memoraeu-mcp\n```\n\nSource：https://github.com/pquattro/memoraeu-mcp#readme\n\n## Sources\n\n- repo: https://github.com/pquattro/memoraeu-mcp\n- docs: https://github.com/pquattro/memoraeu-mcp#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_017644bf19ad4842aff2692e2be4439b"
}