TL;DR - Memory MCP Quick Start
Give your AI assistant a persistent local knowledge graph using the official @modelcontextprotocol/server-memory package (npx -y @modelcontextprotocol/server-memory). Whether you are working with Claude Opus 4.6, GPT-5.4, or Gemini 3.1 Pro (compare long-context recall on our LLM Benchmarks hub), Memory MCP stores structured entities, active-voice relations, and atomic observations across sessions. For a foundational overview of the protocol, see the MCP Introduction guide.
Key Takeaways
- 3 Core Knowledge Graph Primitives: Structures long-term memory into Entities (typed nodes like
AliceorProject_Alpha), Relations (directed active-voice edges likeworks_onordepends_on), and Observations (discrete factual strings attached to entities). - 9 Verified Graph Tools & Sub-5ms Latency: Exposes 9 CRUD and traversal tools (
create_entities,create_relations,add_observations,delete_entities,delete_observations,delete_relations,read_graph,search_nodes,open_nodes) operating on a local JSON/JSONL file with 2ms to 5ms read/write latency and ~1,100 tokens of tool schema overhead. - Custom Storage via
MEMORY_FILE_PATH: Configure theMEMORY_FILE_PATHenvironment variable in your MCP client config (modelcontextprotocol/servers) to isolate work, personal, and repository-specific knowledge graphs on disk. - Cross-Pillar Developer Workflow: Validate your
claude_desktop_config.jsonand JSON graph files in our JSON Formatter & Validator and craft memory-extraction system prompts with our AI Prompt Generator.
Verified Configuration: Setting Custom MEMORY_FILE_PATH (Click to Expand)
Always set an explicit MEMORY_FILE_PATH in your env block so your knowledge graph persists in a known, backed-up directory rather than inside a temporary npx package cache folder:
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"],
"env": {
"MEMORY_FILE_PATH": "/Users/yourname/.mcp-memories/work-graph.jsonl"
}
}
}
}Quick Setup:
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}What you can do:
- Remember: Store entities (people, projects, concepts)
- Connect: Create relationships between entities
- Recall: Search and retrieve stored knowledge
- Update: Modify existing memories
- Forget: Delete specific memories
Example conversation:
You: Remember that Alice is a senior developer on my team
who specializes in React and works remotely from Seattle.
Claude: I've stored that information:
- Entity: Alice
- Type: Person
- Relations: team member, React specialist, Seattle-based
I'll remember this in future conversations.
--- Next Day ---
You: What do you know about my team?
Claude: Based on my memory:
- Alice: Senior developer, React specialist, remote (Seattle)
- [Any other stored team members...]True persistence - Memory survives across conversations, restarts, and even machine reboots.
2025 Context: ChatGPT, Gemini, Grok, Copilot, and Claude all have memory features now. Memory MCP gives you full control over your data.
Why AI Memory Matters
Without memory, every conversation starts fresh:
| Without Memory | With Memory MCP |
|---|---|
| Re-explain project context | AI remembers your projects |
| Re-introduce team members | AI knows who’s who |
| Repeat preferences | AI recalls your style |
| Lose conversation insights | AI builds on past learning |
The Knowledge Graph Model
Memory MCP uses a structured knowledge graph model composed of nodes (Entities), directed edges (Relations), and atomic facts (Observations):
| Graph Primitive | Structural Role | Example Instances in Graph |
|---|---|---|
| Entities (Nodes) | Named domain objects with an entityType classification | Alice (Person), Bob (Person), Project X (Project), React (Technology) |
| Relations (Directed Edges) | Active-voice predicates connecting a from entity to a to entity | Alice -> works_on -> Project X, Alice -> knows -> Bob, Project X -> uses -> React |
| Observations (Node Attributes) | Array of discrete, timestamped or atomic fact strings attached to an entity | Alice: ["Senior developer", "React specialist", "Works remotely from Seattle"] |
Entities are things: people, projects, concepts, places.
Relations connect entities: works_on, knows, uses, located_in.
For more on knowledge graphs and RAG, see the RAG, Embeddings & Vector Databases guide.
2025: Temporal Knowledge Graphs
Advanced memory now tracks when things change:
| Feature | Standard | Temporal (2025) |
|---|---|---|
| Store facts | ✓ | ✓ |
| Track relationships | ✓ | ✓ |
| Know when things changed | ✗ | ✓ |
| Reason about past/present | ✗ | ✓ |
| Build timelines | ✗ | ✓ |
Installation & Configuration
Prerequisites
- Node.js v18+ (check with
node --version) - MCP-compatible client (Claude Desktop, Cursor, etc.)
Basic Setup
Add to claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}This uses the default memory location.
Custom Memory Location
Specify where to store the memory file:
{
"mcpServers": {
"memory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-memory",
"--memory-path",
"/Users/yourname/memories/main.json"
]
}
}
}Multiple Memory Contexts
Create separate memories for different contexts:
{
"mcpServers": {
"memory-work": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory",
"--memory-path", "/memories/work.json"]
},
"memory-personal": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory",
"--memory-path", "/memories/personal.json"]
},
"memory-project-x": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory",
"--memory-path", "/memories/project-x.json"]
}
}
}Verify Installation
Restart your AI client and test:
You: What do you remember about me?
Claude: I don't have any stored memories yet.
Would you like me to remember something about you?
You: Remember that my name is Alex and I'm a software engineer
Claude: I've stored that information:
- Entity: Alex (You)
- Type: Person
- Observation: Software engineer
I'll remember this in our future conversations!Available Tools
Memory MCP provides these capabilities:
Creating Knowledge
| Tool | Description | Example Prompt |
|---|---|---|
create_entities | Store new entities | ”Remember Alice is a developer” |
create_relations | Connect entities | ”Remember Alice works on Project X” |
add_observations | Add facts to entities | ”Note that Alice prefers TypeScript” |
Reading Knowledge
| Tool | Description | Example Prompt |
|---|---|---|
read_graph | Get all stored knowledge | ”What do you remember?” |
search_nodes | Find specific entities | ”What do you know about Alice?” |
open_nodes | Get details of entities | ”Tell me everything about Project X” |
Modifying Knowledge
| Tool | Description | Example Prompt |
|---|---|---|
delete_entities | Remove entities | ”Forget about old Project Y” |
delete_observations | Remove specific facts | ”Remove the note about Alice’s location” |
delete_relations | Remove connections | ”Remove Alice from Project X” |
Building Your Knowledge Graph
Constructing a high-signal knowledge graph follows a three-stage lifecycle: creating canonical entities (create_entities), linking entities with active-voice relations (create_relations), and appending granular observations (add_observations) as facts evolve. Rather than dumping raw, unstructured paragraphs into a single entity, encourage your AI assistant to keep entity names canonical (e.g., "Project_Alpha" rather than "the alpha project") and break attributes into atomic observation strings so search_nodes and open_nodes can retrieve targeted subgraphs in under 5ms without loading the entire graph into your prompt context.
Step 1: Create Entities
Start by teaching AI about important things:
You: Remember these team members:
- Alice: Senior developer, React expert
- Bob: Backend developer, Python specialist
- Carol: Designer, Figma expert
- Dave: DevOps, AWS certified
Claude: I've created 4 entities:
👤 Alice
- Type: Person
- Role: Senior developer
- Expertise: React
👤 Bob
- Type: Person
- Role: Backend developer
- Expertise: Python
👤 Carol
- Type: Person
- Role: Designer
- Expertise: Figma
👤 Dave
- Type: Person
- Role: DevOps
- Expertise: AWS
All stored in memory!Step 2: Create Relations
Connect entities together:
You: Remember these project assignments:
- Project Alpha: Alice and Bob
- Project Beta: Carol and Dave
Claude: I've created relationships:
📋 Project Alpha
- Alice → works_on → Project Alpha
- Bob → works_on → Project Alpha
📋 Project Beta
- Carol → works_on → Project Beta
- Dave → works_on → Project Beta
I can now answer questions about project teams!
You: Who works on Project Alpha?
Claude: Based on my memory:
Project Alpha team:
- Alice (Senior developer, React)
- Bob (Backend developer, Python)Step 3: Add Observations
Enrich entities with more details:
You: Add these details:
- Alice works remotely from Seattle
- Bob is in the New York office
- Project Alpha uses PostgreSQL and Redis
Claude: Updated my memory:
👤 Alice
+ Location: Seattle (remote)
👤 Bob
+ Location: New York (office)
📋 Project Alpha
+ Tech stack: PostgreSQL, Redis
Knowledge graph enriched!Practical Workflows
Workflow 1: Team Context
Build AI knowledge about your team:
You: I want you to remember my team for future conversations.
Our team is called "Platform Team" and we work on the
company's core infrastructure.
Claude: I'll create the team context:
Created Entity: Platform Team
- Type: Team
- Focus: Core infrastructure
What team members should I remember?
You: We have Sarah (lead), Mike (senior), and Jen (junior)
Claude: Added team members:
👤 Sarah → leads → Platform Team
👤 Mike → member_of → Platform Team
👤 Jen → member_of → Platform Team
I'll remember your Platform Team context!
--- Later ---
You: I need to assign a complex task on the Platform Team
Claude: Based on my memory of the Platform Team:
- Sarah is the lead - should be involved in planning
- Mike is senior - suitable for complex implementation
- Jen is junior - good for learning opportunity with support
Recommendation: Have Mike lead implementation with
Sarah overseeing and Jen paired for learning.Workflow 2: Project Knowledge Base
Persist project context across sessions:
You: Remember details about my e-commerce project:
- Name: ShopFast
- Stack: Next.js, Prisma, PostgreSQL
- Hosting: Vercel + AWS RDS
- Current focus: Performance optimization
Claude: Stored project knowledge:
📋 ShopFast
- Type: Project
- Frontend: Next.js
- ORM: Prisma
- Database: PostgreSQL
- Hosting: Vercel (frontend), AWS RDS (database)
- Current focus: Performance optimization
--- Weeks Later ---
You: What should I consider when adding a new feature to my project?
Claude: Based on my knowledge of ShopFast:
Consider:
1. **Performance** (current focus) - profile impact
2. **Stack compatibility** - Next.js patterns
3. **Database** - Prisma migrations for PostgreSQL
4. **Deployment** - Vercel preview deployments
Want me to suggest a specific approach based on
your tech stack?Workflow 3: Personal Preferences
Let AI learn your style:
You: Remember my coding preferences:
- I prefer TypeScript over JavaScript
- I like functional programming patterns
- I prefer descriptive variable names
- I don't like comments that just repeat code
Claude: Stored your preferences:
🎨 Coding Style (You)
- Language: TypeScript preferred
- Paradigm: Functional programming
- Naming: Descriptive variable names
- Comments: Meaningful only (no code repetition)
--- Later ---
You: Refactor this function for me
Claude: Here's the refactor following your preferences:
- Converted to TypeScript with proper types
- Used functional approach with map/filter
- Used descriptive names: `calculateTotalPrice`
instead of `calc`
- Added comment only for complex logicFor tips on effective AI communication, see the Prompt Engineering Fundamentals guide.
Workflow 4: Meeting Context
Remember discussion outcomes:
You: Remember from today's planning meeting:
- Sprint goals: Complete auth module, start API v2
- Alice owns auth, Bob owns API v2
- Blockers: Need design review from Carol
- Next meeting: Thursday 2pm
Claude: Stored meeting outcomes:
📅 Sprint Planning (Dec 24)
Goals:
- Complete auth module → assigned to Alice
- Start API v2 → assigned to Bob
Blockers:
- Design review needed → waiting on Carol
Follow-up:
- Next meeting: Thursday 2pm
--- Thursday ---
You: What was discussed in our last planning meeting?
Claude: From the Sprint Planning (Dec 24):
**Sprint Goals:**
- Auth module (Alice) - should be completed
- API v2 (Bob) - should be started
**Blocker Status:**
- Did Carol complete the design review?
**Action Items:**
- Follow up on auth module progress
- Check API v2 kickoff statusWorkflow 5: Learning & Research
Track what you’re learning:
You: I'm learning about MCP. Remember that:
- MCP = Model Context Protocol by Anthropic
- It connects AI to external tools
- I've read the intro docs, need to try building a server
Claude: Stored learning progress:
📚 Learning: MCP
- Full name: Model Context Protocol
- Created by: Anthropic
- Purpose: Connect AI to external tools
Progress:
- ✅ Read intro docs
- 🔲 Build a server (next step)
--- Later ---
You: What was I learning about recently?
Claude: Based on my memory, you're learning MCP:
**Model Context Protocol**
- You've read the intro documentation
- Next step: Try building a server
Want me to help you get started with building
your first MCP server?For more on AI-assisted learning workflows, see the AI for Everyday Productivity guide.
Example Prompts
Storing Information
# People
"Remember that John is my manager"
"Store that Sarah specializes in security"
"Remember Alice works remotely from Seattle"
# Projects
"Remember I'm working on ProjectX using React and Node"
"Store that the API uses REST, not GraphQL"
"Remember we deploy to AWS using Terraform"
# Preferences
"Remember I prefer dark mode in all applications"
"Store that I like detailed code comments"
"Remember I'm a morning person for meetings"
# Relationships
"Remember Sarah and John work together on the platform team"
"Store that ProjectX depends on the auth service"
"Remember Alice mentors the junior developers"Retrieving Information
# Full knowledge
"What do you remember?"
"Show me all stored memories"
"List everything in your knowledge graph"
# Specific queries
"What do you know about Alice?"
"Tell me about ProjectX"
"What are my preferences?"
# Relationship queries
"Who works on the platform team?"
"What projects is Bob involved in?"
"What technologies does ProjectX use?"Updating Information
# Adding details
"Add that Alice is now a tech lead"
"Note that ProjectX launched on Dec 15"
"Remember that we switched from MySQL to PostgreSQL"
# Removing information
"Forget about old Project Y"
"Remove the note about Bob's location"
"Delete the outdated team structure"
# Correcting information
"Actually, Alice works from Portland, not Seattle"
"Update ProjectX status to 'completed'"
"Change Sarah's role to 'Director'"Context Building
# Team context
"Remember our team for future conversations"
"Store our project structure"
"Build a knowledge base of our tools"
# Learning tracking
"Remember what I'm learning about"
"Track my progress on this tutorial"
"Store book recommendations"
# Meeting outcomes
"Remember decisions from this meeting"
"Store action items and owners"
"Track project milestones"Memory File Structure
Understanding how memory is stored helps with advanced use:
Location
| Client | Default Location |
|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/memory.json |
| Claude Desktop (Windows) | %APPDATA%/Claude/memory.json |
| Custom | Specified via --memory-path |
Format
The memory file is JSON:
{
"entities": [
{
"name": "Alice",
"entityType": "person",
"observations": [
"Senior developer",
"React specialist",
"Works remotely from Seattle"
]
},
{
"name": "ProjectX",
"entityType": "project",
"observations": [
"E-commerce platform",
"Uses Next.js and PostgreSQL"
]
}
],
"relations": [
{
"from": "Alice",
"to": "ProjectX",
"relationType": "works_on"
}
]
}Manual Editing
You can edit the file directly:
# Stop the AI client first
# Then edit:
vim ~/Library/Application\ Support/Claude/memory.json
# Restart client to load changesBackup
# Create backup
cp memory.json memory.backup.json
# Restore
cp memory.backup.json memory.jsonAdvanced Patterns
Once your baseline knowledge graph is running, you can model complex organizational hierarchies, project timelines, and conditional workflow rules using standardized entity types and relation naming conventions. By prefixing temporal observations with ISO-8601 dates ("[2026-11-01] Promoted to Staff Engineer") and modeling parent-child org structures (Team -> part_of -> Department), your AI assistant can reason over multi-hop dependency chains and historical state transitions without requiring an external graph database cluster.
Hierarchical Knowledge
Build structured understanding across teams and departments:
You: Remember our company structure:
- Company: TechCorp
- Team: Platform (Sarah leads)
- Alice, Bob
- Team: Product (Tom leads)
- Carol, Dave
Claude: Created hierarchical structure:
🏢 TechCorp (Company)
- Platform Team (Sarah leads): Alice (member), Bob (member)
- Product Team (Tom leads): Carol (member), Dave (member)Temporal Knowledge
Track changes over time:
You: Remember that ProjectX:
- Started: January 2024
- MVP launch: March 2024
- Current phase: Scaling (December 2024)
Claude: Stored project timeline:
📋 ProjectX Timeline
- Started: January 2024
- MVP Launch: March 2024
- Current Phase: Scaling (Dec 2024)
I can track how this project evolves!Conditional Knowledge
Store context-dependent information:
You: Remember that for standup meetings we use Zoom,
but for planning meetings we use Gather
Claude: Stored meeting preferences:
📅 Meeting Tools
- Standup → Zoom
- Planning → Gather
I'll suggest the right tool based on meeting type!Combining with Other MCPs
Memory MCP acts as the persistent state layer across your entire MCP server stack. Because most MCP servers (such as Filesystem, GitHub, Notion, and PostgreSQL) are stateless connectors that query live data on demand, pairing them with Memory MCP allows your AI assistant to cache architectural summaries, repository branch conventions, database schema relationships, and Notion database IDs in its local knowledge graph. On subsequent sessions, the AI calls search_nodes first (under 5ms local read) instead of re-crawling dozens of files or API endpoints, cutting multi-turn token consumption by 40% to 65%.
Memory + Filesystem
Create documented memories:
You: Read my project README and remember the key details
Claude: [Uses Filesystem to read README]
[Uses Memory to store key points]
Stored from README:
- Project: TaskManager
- Stack: Vue.js, Express, MongoDB
- Key features: Real-time sync, offline supportMemory + GitHub
Remember project conventions:
You: Learn this repository's patterns and remember them
Claude: [Uses GitHub/Git to analyze repo]
[Uses Memory to store patterns]
Stored patterns:
- Branch naming: feature/, bugfix/, hotfix/
- Commit style: Conventional commits
- PR review: 2 approvals requiredMemory + Notion
Persist workspace understanding:
You: Learn my Notion database structure and remember it
Claude: [Uses Notion to explore workspace]
[Uses Memory to store structure]
Stored your Notion structure:
- Tasks database: Status, Priority, Assignee
- Projects database: Stage, Team, Launch date
- Meeting Notes: linked to Tasks via action itemsTroubleshooting
Issue: “Memory not persisting”
Symptoms: AI forgets between sessions
Solutions:
| Cause | Solution |
|---|---|
| Server not running | Check MCP is configured |
| Wrong memory path | Verify path in config |
| File permissions | Check write access |
| Client not restarted | Restart after config change |
Issue: “Memory file corrupted”
Symptoms: Server fails to start, JSON errors
Solutions:
-
Check JSON syntax:
python -m json.tool < memory.json -
Restore from backup:
cp memory.backup.json memory.json -
Start fresh:
rm memory.json # Server will create new file
Issue: “Too much memory slowing down”
Symptoms: Slow responses with large knowledge graph
Solutions:
- Archive old/unused memories
- Split into multiple context files
- Clean up redundant entities
- Be more selective about what to store
Security Considerations
Because @modelcontextprotocol/server-memory persists entities, relations, and observations as unencrypted plain-text JSON/JSONL on your local disk (MEMORY_FILE_PATH), you must apply strict data-hygiene and filesystem permission controls (chmod 600). Never instruct or permit your AI assistant to store API keys, database passwords, OAuth bearer tokens, or regulated customer PII inside the knowledge graph. Furthermore, when working across multiple clients or sensitive enterprise repositories, isolate your graphs into separate MEMORY_FILE_PATH files (work-graph.jsonl vs. personal-graph.jsonl) so confidential project architecture from one workspace cannot be recalled via read_graph in an unrelated chat session. For broader guidance on securing agentic AI workflows, see the Understanding AI Safety, Ethics, and Limitations guide and our MCP Security Best Practices.
What’s Stored
| Stored | Not Stored |
|---|---|
| Entities and relations you create | Conversation history |
| Observations about entities | API keys or secrets |
| Your specified knowledge | Anything you don’t explicitly save |
Privacy Best Practices
| ✓ Do | ✗ Don’t |
|---|---|
| Store work info in work memory | Mix personal/work contexts |
| Use separate files for projects | Store passwords or secrets |
| Regularly review stored data | Store sensitive personal data |
| Backup before experiments | Share memory files |
Memory Location Security
# Check permissions (macOS/Linux)
ls -la ~/Library/Application\ Support/Claude/memory.json
# Should be readable only by you:
# -rw------- 1 youruser staff 12345 Dec 24 12:00 memory.jsonRelated MCP Servers
| Server | Complements Memory By… |
|---|---|
| Filesystem MCP | Reading files to inform memory |
| GitHub MCP | Storing repo conventions |
| Notion MCP | Remembering workspace structure |
| PostgreSQL MCP | Remembering database schemas |
Summary
The Memory MCP Server gives AI persistent knowledge:
- ✓ Knowledge graph for entities and relations
- ✓ Local storage - your data stays on your machine
- ✓ Cross-session persistence
- ✓ Multiple contexts for work/personal/projects
- ✓ Full control over what’s remembered
- ✓ Temporal support (2025) - track when things change
2025 AI Memory Ecosystem:
- Memory MCP - Local, fully controllable knowledge graph
- ChatGPT Memory - Cloud-based, integrated in OpenAI
- Gemini Memory - Google’s conversation memory
- Graphiti - Open-source temporal knowledge graphs
- Neo4j - Graph database for persistent memory
Best use cases:
- Team and project context
- Personal preferences and style
- Meeting outcomes and action items
- Learning progress tracking
- Project knowledge bases
Getting started checklist:
- ☐ Add Memory MCP to your config
- ☐ Teach AI about your team/projects
- ☐ Store your preferences
- ☐ Build relationships between entities
- ☐ Review and curate stored knowledge
Pro tip: Start with one focused area (like your current project) and gradually expand what you teach AI.
Phase 2 Complete! Continue to Phase 3 for productivity and communication tools.
By modeling atomic observations and explicit relationships in the knowledge graph, you achieve durable AI context retention across hundreds of agent sessions.
Questions about Memory MCP? Check the source code on GitHub or explore Graphiti for temporal knowledge graphs.