mcp-memory-graph

mcp-memory-graph

A context-aware memory MCP server for Claude Code and any MCP-compatible AI agent.

Goes beyond basic vector search by adding authority weighting, conflict detection, and typed relationship edges between memories — so your agent always retrieves the right answer when sources disagree.

Inspired by the context engine architecture described in Unblocked's "How a Context Engine Actually Works".

---

Why this exists

Standard memory MCP servers store and retrieve memories by semantic similarity. That works until you have conflicting memories — an old instruction saying one thing and a new one saying another. Without authority weighting, the agent retrieves whichever is semantically closer to the query, not whichever is more trustworthy.

mcp-memory-graph solves this with three mechanisms:

Problem	Solution
All memories treated equally	Priority tiers: high / medium / low → authority scores 1.0 / 0.6 / 0.3
Stale memories persist silently	Supersession tracking: old memories marked status=superseded with typed edges
Duplicates accumulate over time	Conflict detection before every store; auto-resolve by authority

---

Installation

pip install mcp-memory-graph

Or run directly:

git clone https://github.com/RetroRobAI/mcp-memory-graph
cd mcp-memory-graph
pip install -r requirements.txt
python server.py

---

Claude Code setup

Add to ~/.claude.json under mcpServers:

"mcp-memory-graph": {
  "type": "stdio",
  "command": "mcp-memory-graph",
  "env": {
    "MEMORY_GRAPH_DB_PATH": "/path/to/memories.db"
  }
}

Or with the raw script:

"mcp-memory-graph": {
  "type": "stdio",
  "command": "python",
  "args": ["/path/to/mcp-memory-graph/server.py"],
  "env": {
    "MEMORY_GRAPH_DB_PATH": "/path/to/memories.db"
  }
}

---

Migrating from an existing memory service

If you have an existing memory service (mcp-memory-service, Mem0, or a markdown-based memory system), you can import your memories into mcp-memory-graph using the included migration script.

Migration is manual and opt-in — it never runs automatically. Nothing is written until you explicitly confirm.

Run the migration script

python -m mcp_memory_graph.migrate

The script will:

1. Auto-detect any existing mcp-memory-service SQLite database
2. Ask if you have a markdown memory directory to import
3. Show you how many memories it found
4. Present three choices:
   • [1] Migrate — import everything into mcp-memory-graph
   • [2] Run in parallel — start mcp-memory-graph fresh, keep your old service running
   • [3] Skip — do nothing
5. Ask for a final confirmation before writing anything

Your existing memory service is never modified — the script only reads from it.

---

Configuration

All settings via environment variables:

Variable	Default	Description
MEMORY_GRAPH_DB_PATH	~/.mcp-memory-graph/memories.db	SQLite database path
MEMORY_GRAPH_MODEL	all-MiniLM-L6-v2	sentence-transformers model
MEMORY_GRAPH_DIM	384	Embedding dimensions
MEMORY_GRAPH_CONFLICT_THRESHOLD	0.85	Cosine similarity above which memories are flagged as conflicting
MEMORY_GRAPH_DEFAULT_RESULTS	10	Default retrieval limit

---

Tools

Tool	Description
store_memory	Store with conflict detection and optional auto-resolve
retrieve_memories	Semantic search ranked by similarity × authority
check_conflicts	Preview conflicts before storing
update_memory	Update content/priority with supersession tracking
delete_memory	Soft delete (preserves history)
add_memory_edge	Manually add typed relationship
get_related_memories	Traverse relationship graph for a memory
list_memories	List with filters (status, type, priority)

---

Priority system

priority="high"    # authority_score=1.0  — explicit instructions, confirmed preferences
priority="medium"  # authority_score=0.6  — inferred preferences, reference data
priority="low"     # authority_score=0.3  — session summaries, historical context

Retrieval ranking: weighted_score = 1 - (distance / (authority_score + 0.001) / 10)

A high-authority memory will rank above a semantically closer low-authority one when their similarity scores are within ~3x of each other.

---

Edge types

• supersedes — this memory replaces another
• relates_to — connected but not conflicting
• contradicts — explicitly conflicting, unresolved
• referenced_by — another memory cites this one

---

Stack

• sqlite-vec — vector similarity search
• sentence-transformers — local embeddings, no API key needed
• FastMCP — MCP server framework

---

License

MIT