mcp-ariel-memory

Universal Two-Layer Memory MCP Server

A two-layer universal memory system for AI agents. Real MCP Python SDK, async, 37 tools, stdio + HTTP transports, dashboard, metrics, authentication, 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

• 37 MCP tools covering memory CRUD, search, graph operations, and system management
• Hybrid search combining FTS5 full-text with vector similarity via Reciprocal Rank Fusion
• 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

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 --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"]
    }
  }
}

HTTP Server

# Start HTTP server
python -m mcp_server --transport http --port 8000

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

# Or with dashboard + metrics
docker run -p 8000:8000 ariel-memory --transport http --port 8000 --dashboard

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

---

Features

Feature	Description
37 MCP Tools	User layer (10), Agent layer (10), Auth (3), Backup (4), Saga (2), Replica (1), Import/Export (3), Maintenance (1), Emergency (1), Search (1), Context (1)
Two-Layer Memory	L1 ReflexBuffer → L2 SessionStore → L3 EpisodicMemory → L4 CoreMemory
Hybrid Search	FTS5 + vector similarity via Reciprocal Rank Fusion (RRF)
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, persistent storage
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)

Database Tables (21)

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
api_keys	features/auth.py	API keys

---

Documentation

#	Document	Description
01	Architecture	Stack, two-layer model, L1-L4, consolidation
02	MCP Tools	All 37 tools with parameters and examples
03	Core Memory	ReflexBuffer, SessionStore, EpisodicMemory, CoreMemory
04	Search (RAG)	FTS5 + fallback, RRF, RetrievalRouter, ConflictResolver
05	Knowledge Graph	EpistemicGraph, TemporalGraph
06	Lifecycle	Forgetting, EmotionTrigger, Consolidation
07	Hooks	24 hooks (12 user + 12 agent)
08	Wiki	FileWiki (.md files + FTS5)
09	Features	Auth, Backup, Dashboard, Audit, RateLimit
10	Shared	Cache, Saga+Watchdog, Middleware, Embeddings, Metrics
11	Operations	Transports, Dashboard, Auth, Backup, Configuration
12	Testing	pytest, project structure

---

Testing

# Run all tests (104 passed)
pytest tests/ -v

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

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

---

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 }

---

Development

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

# Run linter
ruff check .

# Format code
ruff format .

# Run tests
pytest tests/ -v

---

License

MIT License - see LICENSE for details.