Persistent, encrypted memory for AI agents with 25 tools spanning episodic recall, knowledge graphs, hybrid search, session management, and operational controls.
Memory Management – Remember, recall, and forget facts (L4 CoreMemory) with importance scoring; separate user/agent layers.
Sessions & Episodes – Start/end sessions (L2), save/recall emotional episodes (L3) with tags and weight.
Knowledge Graphs – Epistemic and temporal graphs: add/query nodes (facts, decisions, errors) and edges.
Hybrid Search – FTS5, semantic (MIB), or combined search across RAG and Wiki entries, with ITS novelty scoring.
Context & Stats – Compressed context summaries for prompt injection, plus memory statistics.
Wiki System – Manage user/agent wiki pages stored as markdown, indexed with FTS5.
Administration – API key management, automated backups/restores, data import/export, sagas with rollback, deduplication/cleanup, emergency purge, and replica sync.
Security & Transport – Envelope encryption, authentication, rate limiting, Prometheus metrics, real‑time dashboard; stdio and HTTP transports; installable via npm, pip, or Docker.
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.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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.
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.
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]Feature | mcp-ariel-memory | Typical Memory |
Memory hierarchy | L1→L2→L3→L4 (4 layers) | Flat key-value store |
Adaptive Threshold | Dynamic EMA-based noise filtering | Static threshold |
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 |
Auto-Compaction | Periodic archiving of low-importance items | None |
Encryption | libsodium secretbox (keychain-first) | Usually none |
Metrics | Real-time Prometheus exporter (port 9120) | None |
Tests | 250 (79 property-based/logic/chaos) | — |
Dashboard | Real-time HTML dashboard | — |
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
npx mcp-ariel-memory --transport stdioRequires Python 3.10+ on the system. The npm wrapper automatically installs the Python package.
pip install git+https://github.com/Cipher208/mcp-ariel-memory.git
python -m mcp_server --transport stdiodocker build -t ariel-memory .
docker run -p 8000:8000 ariel-memorygit clone https://github.com/Cipher208/mcp-ariel-memory.git
cd mcp-ariel-memory
pip install -e ".[all]"
python -m mcp_server.server --transport stdiomcp-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.
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"]
}
}
}Add to Hermes config (YAML format):
mcpServers:
ariel-memory:
command: npx
args:
- mcp-ariel-memory
- --transport
- stdio# 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 8000docker-compose upPlatform | 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 |
Single memory.db file — no external database required.
Table | Module | Purpose |
| core/memory.py | L4 key-value facts |
| core/session.py | L2 session history |
| core/episodic.py | L3 episodic memories |
| shared/dream_buffer.py | Temporary staging |
| shared/archived_memories.py | Archived memories |
| features/audit_trail.py | Audit trail |
`rate_limits" | features/rate_limiting.py | Rate limiting |
| shared/embeddings.py | Cached embeddings |
| rag/engine.py | RAG document pages |
| rag/engine.py | RAG document chunks |
| rag/engine.py | RAG relations |
| graph/epistemic.py | Epistemic graph nodes |
| graph/epistemic.py | Epistemic graph edges |
| graph/temporal.py | Temporal events |
| graph/temporal.py | Temporal links |
| wiki/models.py | User wiki entries |
| wiki/models.py | Agent wiki entries |
| wiki/index.py | Wiki FTS5 index |
| rag/conflict.py | Memory conflicts |
| shared/migrations.py | Migration history |
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 |
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) |
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)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)Strategy | Description | When to Use |
| Full-text search via FTS5 with LIKE fallback | Short queries (<3 words), keyword-heavy |
| Binary embedding similarity (Hamming distance) | Semantic similarity, concept-based |
| Combines FTS5 + MIB with Scorer ranking | General-purpose, best recall |
| Automatically selects | Default for most use cases |
Full documentation with API reference, architecture diagrams, and guides:
Topic | Link |
Architecture | |
MCP Tools | |
Configuration | |
API Reference |
# 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_perfOperation | Speed | Notes |
| 1533 ops/s | SQLite + encryption |
| 6739 q/s | FTS5 search |
| 402 ops/s | argon2id KDF |
| 1817 ops/s | FTS5 full-text search |
| 215 ops/s | Binary embedding search (batched) |
| 178 ops/s | FTS5 + MIB combined |
| 1850 ops/s | Tag lookup via epi_tags table |
| 3537 ops/s | rag_chunks + rag_pages JOIN |
# 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"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')"# 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=30MIT License - see LICENSE for details.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
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