name: memory-mcp
description: >
Persistent memory for Claude Code with two-tier architecture: hot cache for instant
recall (0ms) and semantic search for everything else (~50ms). Automatically learns
what you use and promotes it.
allowed-tools: "mcp__memory__*"
version: "0.6.0"
author: "Michael Denyer https://github.com/michael-denyer"
license: "MIT"
Memory MCP - Persistent Memory for Claude Code
Give your AI assistant a second brain that persists across sessions.
Two-Tier Architecture
| Tier |
Latency |
How it works |
| Hot Cache |
0ms |
Auto-injected into context before Claude thinks |
| Cold Storage |
~50ms |
Semantic search via recall() tool call |
The system learns what you use and automatically promotes frequently-accessed memories to the hot cache.
Quick Start
Store a Memory
remember("FastAPI with async endpoints for all APIs", memory_type="project", tags=["tech-stack"])
Recall by Meaning
recall("what framework for backend") # Finds FastAPI memory
Check What's Hot
hot_cache_status() # See what's instantly available
Core Tools
Storage
| Tool |
Purpose |
remember(content, memory_type, tags) |
Store new memory |
recall(query, mode, limit) |
Semantic search |
recall_by_tag(tag) |
Find by tag |
forget(memory_id) |
Delete memory |
list_memories(limit, offset) |
Browse all |
Memory types: project, pattern, reference, episodic, conversation
Recall modes: precision (few, high-confidence), balanced (default), exploratory (many results)
Hot Cache
| Tool |
Purpose |
promote(memory_id) |
Add to hot cache |
demote(memory_id) |
Remove from hot cache |
pin(memory_id) |
Prevent auto-eviction |
unpin(memory_id) |
Allow auto-eviction |
hot_cache_status() |
View hot cache contents |
Knowledge Graph
| Tool |
Purpose |
link_memories(from_id, to_id, relation) |
Connect memories |
unlink_memories(from_id, to_id) |
Remove connection |
get_related_memories(memory_id) |
Find connected |
relationship_stats() |
Graph overview |
Relation types: relates_to, depends_on, supersedes, refines, contradicts, elaborates
Trust Management
| Tool |
Purpose |
validate_memory(id, reason) |
Increase trust |
invalidate_memory(id, reason) |
Decrease trust |
get_trust_history(memory_id) |
View changes |
Sessions
| Tool |
Purpose |
get_sessions() |
List sessions |
summarize_session(session_id) |
Structured summary |
end_session(session_id) |
Promote top memories |
Pattern Mining
| Tool |
Purpose |
mining_status() |
View mining stats |
review_candidates() |
See patterns found |
approve_candidate(id) |
Promote to memory |
reject_candidate(id) |
Discard pattern |
Maintenance
| Tool |
Purpose |
memory_stats() |
Overview stats |
db_info() |
Database details |
run_cleanup() |
Clean stale data |
preview_consolidation() |
Find duplicates |
MCP Resources
These are auto-injected into Claude's context:
| Resource |
Contents |
memory://hot-cache |
All promoted memories |
memory://working-set |
Session-aware context (~10 items) |
memory://project-context |
Current project memories |
Auto-Promotion Rules
Memories are auto-promoted to hot cache when:
- Salience score ≥ 0.5 AND access count ≥ 3
- Salience = importance + trust + access_count + recency
Memories are auto-demoted after 14 days without access.
Common Workflows
Project Setup
# Bootstrap from project docs (CLAUDE.md, README.md, etc.)
bootstrap_project(promote_to_hot=true)
Daily Work
# Store decisions and patterns as you work
remember("Decided to use PostgreSQL for main DB", memory_type="project", tags=["decision", "database"])
# Recall when needed
recall("database decision")
Session End
# Review what you learned
summarize_session(session_id)
# Promote valuable memories to long-term storage
end_session(session_id, promote_top=true)
Knowledge Linking
# Connect related concepts
link_memories(postgres_id, pgvector_id, "depends_on")
# Recall with graph expansion
recall("PostgreSQL", expand_relations=true)
Tips
- Tag consistently - Use tags like
decision, convention, tech-stack, gotcha
- Use episodic for session context - Short-term memories that may get promoted
- Link related memories - Build a knowledge graph for better recall
- Trust the auto-promotion - Don't over-promote manually
- Check hot cache periodically -
hot_cache_status() shows what's instantly available
By