mcp-ariel-memory

Universal Two-Layer Memory MCP Server

A two-layer universal memory system for AI agents. Real MCP Python SDK, async, 19 unified tools, stdio + HTTP transports, dashboard, metrics, authentication, envelope encryption, automatic backups, external wiki folders, read-only replica.

About

mcp-ariel-memory is a production-ready MCP (Model Context Protocol) server that provides persistent, searchable memory for AI agents. It implements a two-layer architecture:

• Layer 1 (User) — stores facts about users: preferences, conversation history, emotional context, relationships
• Layer 2 (Agent) — stores agent identity: decisions, errors, personality evolution, learning patterns

The server is built with the official MCP Python SDK (FastMCP), supports both stdio and HTTP transports, and includes enterprise features like authentication, rate limiting, automatic backups, and a real-time dashboard.

Key Capabilities

• 19 unified MCP tools with layer parameter (user/agent) instead of 37 separate tools
• Envelope encryption — all sensitive data (API keys, tokens, saga state) encrypted at rest with libsodium secretbox
• .env support — set MCP_MASTER_KEY in .env file for easy local development
• Unified Search API — single search() method with 4 strategies: fts, mib, hybrid, auto
• MultiSourceRAG — unified search across RAG + Wiki with deduplication and reranking
• ITS-inspired scoring — novelty component using document frequency as prior for better ranking
• Supervised thresholds — per-dimension MIB thresholds trained on labeled data (+10-15% recall)
• Knowledge graphs for epistemic (facts/decisions) and temporal (timeline) relationships
• Wiki system with 14 content types, .md files as source of truth, and external folder sync
• 24 hooks for intercepting memory operations at every stage
• Saga pattern for multi-step operations with compensation and watchdog
• Platform-aware async — aiosqlite on Linux/macOS, sync fallback on Windows
• Python 3.10–3.13 tested in CI matrix

Installation

Option 1: npm (recommended for MCP clients)

npx mcp-ariel-memory --transport stdio

Requires Python 3.10+ on the system. The npm wrapper automatically installs the Python package.

Option 2: pip

pip install git+https://github.com/Cipher208/mcp-ariel-memory.git
python -m mcp_server --transport stdio

Option 3: Docker

docker build -t ariel-memory .
docker run -p 8000:8000 ariel-memory

Option 4: From source

git clone https://github.com/Cipher208/mcp-ariel-memory.git
cd mcp-ariel-memory
pip install -e ".[all]"
python -m mcp_server.server --transport stdio

Quick Start

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ariel-memory": {
      "command": "npx",
      "args": ["mcp-ariel-memory", "--transport", "stdio"]
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "ariel-memory": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ariel-memory", "--transport", "stdio"]
    }
  }
}

Hermes Agent

Add to Hermes config (YAML format):

mcpServers:
  ariel-memory:
    command: npx
    args:
      - mcp-ariel-memory
      - --transport
      - stdio

HTTP Server

# Start HTTP server (no auth required for MCP endpoint)
python -m mcp_server.server --transport http --port 8000

# With dashboard (disabled by default)
python -m mcp_server.server --transport http --port 8000 --dashboard

# Development mode (no auth at all)
python -m mcp_server.server --transport http --port 8000 --no-auth

# Or with Docker
docker run -p 8000:8000 ariel-memory --transport http --port 8000

docker-compose

docker-compose up


... [View full README on GitHub](https://github.com/cipher208/mcp-ariel-memory#readme)