Ariel Memory MCP Server

mcp-ariel-memory

Give your AI agents real memory — episodic recall, knowledge graphs, hybrid search, and envelope encryption in a single MCP server. 19 tools. 4-layer hierarchy. 250+ tests.

---

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.

Architecture

graph TD
    A[LLM Agent] -->|MCP Protocol| B[mcp_server]
    B --> C{ImportanceGate}
    C -->|score > 0.3| D[L1: ReflexBuffer]
    C -->|score ≤ 0.3| E[Filtered Out]
    D --> F[L2: SessionStore]
    F --> G{EmotionTrigger?}
    G -->|high emotion| H[L3: EpisodicMemory]
    G -->|normal| I[Consolidation]
    H --> J[L4: CoreMemory]
    I --> J

    B --> K[RAG Engine]
    K --> L[FTS5 Search]
    K --> M[MIB Binary Search]
    K --> N[Hybrid Scoring]

    B --> O[Wiki System]
    O --> P[.md Files]
    O --> Q[SQLite Index]

    B --> R[Knowledge Graphs]
    R --> S[Epistemic Graph]
    R --> T[Temporal Graph]

Why mcp-ariel-memory?

Who needs this?

• AI agent developers — give your agent memory that persists across sessions
• Multi-agent systems — one database, isolated tables, shared memory on demand
• Anyone tired of "forget context every request" — mcp-ariel-memory remembers for you
• Data-conscious teams — everything local, no cloud dependency

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

Monitoring & Maintenance

mcp-ariel-memory includes built-in tools for keeping the system healthy:

• Prometheus Metrics — The server exports real-time metrics on port 9120. Monitor search latency, operation counts, and memory growth.
• Memory Auto-Compaction — Automatically archives old memories with low importance scores to keep the context window efficient.
• Adaptive Threshold (EMA) — The importance filter dynamically adjusts to your conversation style, ensuring only high-signal data reaches long-term storage.
• Alembic Migrations — Versioned database schema management for reliable updates.

---

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

---

Platform Support

---

Database Schema (21 tables)

Single memory.db file — no external database required.

---

Features

---

Architecture

Memory Hierarchy

Message → L1 (ReflexBuffer, ring buffer, 50 items)
         → ImportanceGate (noise filter, threshold 0.3)
         → L2 (SessionStore, SQLite, 100 sessions)
         → EmotionTrigger (emotional analysis)
         → L3 (EpisodicMemory, SQLite, 1000 episodes)
         → L4 (CoreMemory, key-value, 5000 facts)

Secret Resolution Order

1. OS keychain (keyring library) — recommended for production
2. .env file (MCP_MASTER_KEY=...)
3. config.yaml (crypto.master_key_hex)
4. Environment variable (MCP_MASTER_KEY)

Search Strategies

---

Documentation

Full documentation with API reference, architecture diagrams, and guides:

Read the Docs →

---

Testing

# Run all tests (250 passed, 39 property-based)
pytest tests/ -v

# Run with parallel execution
pytest tests/ -v -n auto

# Run only integration tests
pytest tests/test_integration.py -v

# Run with coverage
pytest tests/ --cov=. --cov-report=term-missing

# Run performance benchmark
python -m tests.benchmark_perf

Benchmark

---

Configuration

# config.yaml (optional, mounted as volume)
layers: { user: { enabled: true }, agent: { enabled: true } }
limits: { l1_buffer_size: 50, l4_core_limit: 5000 }
hooks: { user: { message_received: true }, agent: { error_occurred: true } }
forgetting: { decay_rate: 0.01, archive_threshold_days: 90 }
rag: { fts_enabled: true, vec_enabled: true }
embeddings: { model: "BAAI/bge-small-en-v1.5" }
wiki:
  user: { diary: true, external_dirs: ["/path/to/notes"] }
  agent: { decision_log: true, external_dirs: ["/path/to/lore"] }
auth: { api_keys_enabled: true, bearer_token_enabled: true }
backup: { auto_backup: true, backup_interval_hours: 24 }

# Security: master key (add config.yaml to .gitignore!)
# crypto:
#   master_key_hex: "your-32-byte-hex-key"

Secrets Management

On first run without a master key, the server auto-generates a key and saves it to .env for development convenience.

# Check if .env was created
cat .env

# For production, set explicitly:
export MCP_MASTER_KEY="your-32-byte-hex-key"

# Or use OS keychain (recommended)
pip install keyring
python -c "from features.secrets import install_master_key_to_keychain; install_master_key_to_keychain('your-key')"

---

Development

# Install dev dependencies
pip install -e ".[dev,binary]"

# Run linter
ruff check .

# Format code
ruff format .

# Type check
mypy --config-file pyproject.toml features/ shared/ mcp_server/ rag/ hooks/ wiki/ lifecycle/ graph/ core/

# Run tests
pytest tests/ -v --timeout=30

---

Community

• Contributing Guide
• Security Policy
• Code of Conduct
• Discussions
• Changelog

---

License

MIT License - see LICENSE for details.

---