Which integrations are available for this server?

Integrates with Hermes Agent to offer memory capabilities including episodic recall, knowledge graphs, and hybrid search for agent identity and learning. Exposes a Prometheus-compatible metrics endpoint for monitoring server performance, memory usage, and request rates.

How do I use mcp-ariel-memory?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-ariel-memory remember that my favorite color is blue" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-ariel-memory

by Cipher208

Overview Schema Related Servers Score Discussions

Python

Remote

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.

codecov License: MIT Python 3.10+ Ruff MCP Compatible Docs Release

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?

Feature	mcp-ariel-memory	Typical Memory
Memory hierarchy	L1→L2→L3→L4 (4 layers)	Flat key-value store
Hybrid search	FTS5 + binary embeddings + RRF	FTS or vector only
ITS scoring	Novelty + relevance via document frequency	None
Knowledge graphs	Epistemic + Temporal	None
Typed memory	13 categories with per-type retention	None
Two layers	User (about people) + Agent (self-knowledge)	User only
Wiki	14 types, .md files as source of truth, FTS5	None
24 hooks	Intercept operations at every stage	0
Lost-in-the-Middle prevention	L4 CoreMemory at start/end of prompt	None
Encryption	libsodium secretbox (keychain-first)	Usually none
Tests	250 (79 property-based/logic/chaos)	—
Dashboard	Real-time HTML dashboard	—

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

Related MCP server: ContextStream MCP Server

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

Platform Support

Platform	Method	Notes
Windows	npm / pip / Docker	aiosqlite fallback (sync sqlite3 + to_thread)
Linux	npm / pip / Docker	aiosqlite (native async)
macOS	npm / pip / Docker	aiosqlite (native async)
Docker	Any	Works on all platforms with Docker

Database Schema (21 tables)

Single memory.db file — no external database required.

Table	Module	Purpose
`core_memory`	core/memory.py	L4 key-value facts
`sessions`	core/session.py	L2 session history
`episodes`	core/episodic.py	L3 episodic memories
`staging_memories`	shared/dream_buffer.py	Temporary staging
`archived_memories`	shared/archived_memories.py	Archived memories
`audit_log`	features/audit_trail.py	Audit trail
`rate_limits`	features/rate_limiting.py	Rate limiting
`embedding_cache`	shared/embeddings.py	Cached embeddings
`rag_pages`	rag/engine.py	RAG document pages
`rag_chunks`	rag/engine.py	RAG document chunks
`rag_relations`	rag/engine.py	RAG relations
`epi_nodes`	graph/epistemic.py	Epistemic graph nodes
`epi_edges`	graph/epistemic.py	Epistemic graph edges
`temporal_events`	graph/temporal.py	Temporal events
`temporal_links`	graph/temporal.py	Temporal links
`user_wiki`	wiki/user_wiki.py	User wiki entries
`agent_wiki`	wiki/agent_wiki.py	Agent wiki entries
`wiki_index`	wiki/file_wiki.py	Wiki FTS5 index
`memory_conflicts`	rag/conflict.py	Memory conflicts
`migration_log`	shared/migrations.py	Migration history

Features

Feature	Description
19 MCP Tools	Layer tools (11): remember, recall, forget, session, episode, graph, stats, context. Ops tools (8): api_key, backup, saga, data, replica, cleanup, purge, search
Two-Layer Memory	L1 ReflexBuffer → L2 SessionStore → L3 EpisodicMemory → L4 CoreMemory
Envelope Encryption	libsodium secretbox (AES-256-GCM) for API keys, tokens, saga state
Unified Search API	Single `search()` method with 4 strategies: `fts`, `mib`, `hybrid`, `auto`
MultiSourceRAG	Unified search across RAG + Wiki with deduplication and reranking
ITS 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 Graph	Epistemic graph (facts, decisions) + Temporal graph (timeline)
Wiki System	14 types (7 user + 7 agent), .md files as source of truth, FTS5 index
24 Hooks	12 user hooks + 12 agent hooks, integrated into tool pipeline
Saga Pattern	Multi-step operations with compensation, timeout, watchdog
Dashboard	HTML dashboard with stats, facts, episodes, audit log
Auth	API keys + Bearer tokens, encrypted at rest
Rate Limiting	Per-user limits on write operations (100 req/min default)
Backup	Auto-backups with jitter, restore, cleanup
Metrics	Prometheus-compatible metrics endpoint
Read-Only Replica	SQLite read-only replica for queries
Embeddings	Multilingual (100+ languages including Russian)

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

Strategy	Description	When to Use
`fts`	Full-text search via FTS5 with LIKE fallback	Short queries (<3 words), keyword-heavy
`mib`	Binary embedding similarity (Hamming distance)	Semantic similarity, concept-based
`hybrid`	Combines FTS5 + MIB with Scorer ranking	General-purpose, best recall
`auto`	Automatically selects `fts` for short queries, `hybrid` for longer	Default for most use cases

Documentation

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

Read the Docs →

Topic	Link
Architecture	Overview
MCP Tools	Reference
Configuration	Guide
API Reference	Secrets, Importance

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

Operation	Speed	Notes
`memory_remember`	1533 ops/s	SQLite + encryption
`memory_recall`	6739 q/s	FTS5 search
`encrypt+decrypt`	402 ops/s	argon2id KDF
`fts_search`	1817 ops/s	FTS5 full-text search
`mib_search`	215 ops/s	Binary embedding search (batched)
`hybrid_search`	178 ops/s	FTS5 + MIB combined
`epi_tags_join`	1850 ops/s	Tag lookup via epi_tags table
`rag_chunks_join`	3537 ops/s	rag_chunks + rag_pages JOIN

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

License

MIT License - see LICENSE for details.

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

0dRelease cycle

2Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Cipher208/mcp-ariel-memory'

If you have feedback or need assistance with the MCP directory API, please join our Discord server