# Ember MCP

> Persistent memory server for AI with Shadow-Decay to prevent hallucinations from stale data.

Ember MCP is a Model Context Protocol (MCP) server that provides LLMs with long-term memory. It runs locally on your machine with zero cloud dependencies. Unlike standard vector stores, Ember actively manages knowledge freshness using the Shadow-Decay framework — newer memories automatically shadow older, semantically-similar ones, preventing retrieval of obsolete information.

## Installation

```
pip install git+https://github.com/Arkya-AI/ember-mcp.git
ember-mcp init
```

The `init` command auto-detects Claude Desktop, Claude Code, Cursor, and Windsurf, and registers Ember with each one.

## Key Features

- Cross-session memory across all MCP clients
- 100% local — no API keys, no cloud, ~500MB disk, ~200MB RAM
- Shadow-Decay framework with HESTIA scoring for intelligent retrieval
- Temporal intelligence with exponential decay and access frequency boosting
- Drift detection that auto-flags stale memories when knowledge regions shift
- Knowledge graph with semantic edges and BFS traversal
- Source linking for traceable decisions
- Zero configuration — two commands to install

## How It Works

1. Local embeddings via all-MiniLM-L6-v2 (384-dim, CPU)
2. Voronoi partitioning with 16 frozen centroids for topic clustering
3. FAISS similarity search with custom ID mapping
4. Shadow-Decay: newer memories shadow older similar ones via φ(mᵢ|mⱼ), HESTIA scoring ranks by S = cos_sim · (1-Φ)^γ · vitality_factor
5. Knowledge graph: semantic edges connect related memories, BFS traversal discovers correlated context
6. Drift detection pipeline: per-cell statistics, Welford's algorithm, Laplacian smoothing, adaptive thresholds

## 16 MCP Tools

### Store & Recall
- `ember_store` — Save a named memory with importance level and tags
- `ember_recall` — Semantic search ranked by HESTIA score
- `ember_deep_recall` — Recall + read source files for full context
- `ember_learn` — Auto-capture facts, preferences, decisions from conversation

### Management
- `ember_list` — List all stored memories, filter by tag
- `ember_delete` — Remove a memory by ID
- `ember_contradict` — Mark outdated memory stale, store corrected version
- `ember_read` — Read full content of a specific memory by ID

### Intelligence
- `ember_auto` — Auto-retrieve relevant context at conversation start
- `ember_inspect` — View Voronoi cell distribution and conflict density
- `ember_save_session` — Save session summary with source linking
- `ember_drift_check` — Run drift detection to flag stale memories

### Advanced Analysis
- `ember_graph_search` — Vector search + BFS traversal via knowledge graph edges
- `ember_health` — Hallucination risk score with trend tracking
- `ember_recompute_shadows` — Full recalculation of shadow loads after migration
- `ember_explain` — HESTIA score breakdown for a specific memory

## Storage

All data stored locally at `~/.ember/` (JSON + SQLite + FAISS index).

## Requirements

- Python 3.10+
- macOS, Linux, Windows (WSL)

## Links

- GitHub: https://github.com/Arkya-AI/ember-mcp
- Website: https://embermcp.arkya.ai
- License: MIT
- Author: Arkya AI (https://github.com/Arkya-AI)