mcp-ariel-memory¶

Universal Two-Layer Memory MCP Server for AI agents

What is it?¶

mcp-ariel-memory is a production-ready MCP server providing persistent, searchable memory for AI agents. It implements a two-layer architecture:

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

Feature	Description
25 MCP tools	Unified layer-based API (`user`/`agent` parameter)
4-layer memory	L1 ReflexBuffer → L2 Episodic → L3 Session → L4 Core
Typed memory	13 categories with per-type retention, decay, and boost
RAG search	FTS5 + binary embeddings + hybrid scoring
Knowledge graphs	Epistemic (facts/decisions) + Temporal (timeline)
Wiki system	.md files as source of truth, 14 content types
Saga pattern	Multi-step ops with retry, idempotency, compensation
Envelope encryption	libsodium secretbox, keychain-first key resolution
Platform-aware async	aiosqlite on Linux/macOS, asyncio.to_thread on Windows
SHA-256 dedup	Prevents duplicate observations within 5-minute window
Circuit breaker	Prevents cascading LLM/embedding failures
Token budget	Limits context injection to 2000 tokens
Privacy filter	Strips API keys, secrets, and private tags

npm (recommended)pipDocker

npx mcp-ariel-memory --transport stdio

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

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

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

Section	Description
Architecture	Two-layer model, L1-L4, consolidation, 22 DB tables
MCP Tools	All 19 tools with parameters and examples
RAG & Search	Unified search, BM25 conflict similarity, type-aware boost
Hooks	24 hooks (12 user + 12 agent), type-aware gating
Operations	Transports, health, auth, configuration
API Reference	Auto-generated from docstrings