Graphiti MCP

# Graphiti MCP Server - Example Usage This document provides comprehensive examples of how to use the Graphiti MCP Server tools in real-world scenarios. ## Table of Contents 1. [Basic Memory Operations](#basic-memory-operations) 2. [Context Retrieval](#context-retrieval) 3. [Building Knowledge Graphs](#building-knowledge-graphs) 4. [Real-World Scenarios](#real-world-scenarios) 5. [Advanced Graph Queries](#advanced-graph-queries) --- ## Basic Memory Operations ### Example 1: Storing a Simple Memory **Use Case**: Remember a user preference or fact **Tool**: `store_memory` **Example Request**: ```json { "content": "I prefer Python for data science projects because of its rich ecosystem of libraries like pandas, numpy, and scikit-learn.", "tags": ["preferences", "programming", "data-science"], "metadata": { "category": "user_preference", "importance": "high" } } ``` **Expected Response**: ```json { "success": true, "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "content": "I prefer Python for data science projects because of its rich ecosystem of libraries like pandas, numpy, and scikit-learn.", "created_at": "2024-01-15T10:30:00Z" } ``` ### Example 2: Storing Multiple Related Memories **Use Case**: Store information about a project you're working on **Memory 1 - Project Overview**: ```json { "content": "Working on a machine learning project to predict customer churn using historical transaction data. The project uses XGBoost and is scheduled for completion in Q2 2024.", "tags": ["project", "machine-learning", "churn-prediction"], "metadata": { "project_name": "Customer Churn Prediction", "status": "in-progress", "deadline": "2024-06-30" } } ``` **Memory 2 - Technical Details**: ```json { "content": "The churn prediction model uses features like transaction frequency, average order value, customer lifetime value, and support ticket history. We're achieving 87% accuracy with the current model.", "tags": ["project", "machine-learning", "technical"], "metadata": { "project_name": "Customer Churn Prediction", "model_accuracy": "87%", "algorithm": "XGBoost" } } ``` **Memory 3 - Team Information**: ```json { "content": "The project team consists of Sarah (data scientist), Mike (ML engineer), and myself. We have weekly standups every Monday at 10 AM.", "tags": ["project", "team", "meetings"], "metadata": { "project_name": "Customer Churn Prediction", "team_size": 3, "meeting_schedule": "Monday 10 AM" } } ``` --- ## Context Retrieval ### Example 3: Retrieving Relevant Memories **Use Case**: Find all memories related to a specific topic **Tool**: `retrieve_memories` **Example Request**: ```json { "query": "What do you know about my machine learning projects?", "limit": 5 } ``` **Expected Response**: ```json { "query": "What do you know about my machine learning projects?", "count": 2, "memories": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "content": "Working on a machine learning project to predict customer churn using historical transaction data. The project uses XGBoost and is scheduled for completion in Q2 2024.", "metadata": { "project_name": "Customer Churn Prediction", "status": "in-progress" }, "tags": ["project", "machine-learning", "churn-prediction"], "created_at": "2024-01-15T10:30:00Z", "similarity": 0.89 }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "content": "The churn prediction model uses features like transaction frequency, average order value, customer lifetime value, and support ticket history. We're achieving 87% accuracy with the current model.", "metadata": { "project_name": "Customer Churn Prediction", "model_accuracy": "87%" }, "tags": ["project", "machine-learning", "technical"], "created_at": "2024-01-15T11:00:00Z", "similarity": 0.85 } ] } ``` ### Example 4: Getting Synthesized Context **Use Case**: Get a comprehensive summary of related information **Tool**: `get_context` **Example Request**: ```json { "query": "Tell me about the customer churn prediction project", "max_memories": 10 } ``` **Expected Response**: ```json { "query": "Tell me about the customer churn prediction project", "context": "The customer churn prediction project is a machine learning initiative currently in progress, scheduled for completion in Q2 2024. The project uses XGBoost algorithm to predict customer churn based on historical transaction data. Key features include transaction frequency, average order value, customer lifetime value, and support ticket history. The current model achieves 87% accuracy. The project team consists of Sarah (data scientist), Mike (ML engineer), and yourself, with weekly standups every Monday at 10 AM.", "memories_used": 3, "source_memories": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "content": "Working on a machine learning project to predict customer churn..." }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "content": "The churn prediction model uses features like transaction frequency..." }, { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "content": "The project team consists of Sarah (data scientist), Mike (ML engineer)..." } ] } ``` --- ## Building Knowledge Graphs ### Example 5: Creating Relationships Between Memories **Use Case**: Link related concepts or events **Tool**: `create_relationship` **Scenario**: After storing the three project-related memories, create relationships between them. **Step 1**: Link project overview to technical details ```json { "source_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "target_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "relationship_type": "has_details", "properties": { "relationship_strength": "strong", "category": "technical" } } ``` **Step 2**: Link project overview to team information ```json { "source_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "target_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "relationship_type": "has_team", "properties": { "relationship_strength": "strong", "category": "organizational" } } ``` **Expected Response**: ```json { "success": true, "source_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "target_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "relationship_type": "has_details" } ``` ### Example 6: Building a Learning Path Graph **Use Case**: Track learning progress and connect related concepts **Memory 1 - Learning Goal**: ```json { "content": "I want to learn deep learning and neural networks to advance my machine learning skills.", "tags": ["learning", "deep-learning", "goal"], "metadata": { "learning_area": "deep-learning", "priority": "high" } } ``` **Memory 2 - Resource**: ```json { "content": "Started reading 'Deep Learning' by Ian Goodfellow. It covers neural networks, backpropagation, and convolutional networks.", "tags": ["learning", "resource", "book"], "metadata": { "resource_type": "book", "author": "Ian Goodfellow", "status": "reading" } } ``` **Memory 3 - Practice**: ```json { "content": "Built my first neural network using TensorFlow to classify handwritten digits from MNIST dataset. Achieved 95% accuracy.", "tags": ["learning", "practice", "project"], "metadata": { "framework": "TensorFlow", "dataset": "MNIST", "accuracy": "95%" } } ``` **Create Relationships**: ```json // Goal -> Resource { "source_id": "goal_memory_id", "target_id": "resource_memory_id", "relationship_type": "uses_resource" } // Goal -> Practice { "source_id": "goal_memory_id", "target_id": "practice_memory_id", "relationship_type": "practices_with" } // Resource -> Practice { "source_id": "resource_memory_id", "target_id": "practice_memory_id", "relationship_type": "applied_in" } ``` --- ## Real-World Scenarios ### Scenario 1: Personal Knowledge Base **Use Case**: Build a personal knowledge base about your interests, projects, and learnings. **Example Workflow**: 1. **Store Interest**: ```json { "content": "I'm interested in quantum computing and have been following developments in quantum algorithms and quantum machine learning.", "tags": ["interest", "quantum-computing"], "metadata": { "interest_level": "high", "started": "2024-01-01" } } ``` 2. **Store Learning Resource**: ```json { "content": "Completed an online course on quantum computing basics from MIT. Learned about qubits, superposition, and quantum gates.", "tags": ["learning", "quantum-computing", "course"], "metadata": { "provider": "MIT", "completion_date": "2024-01-20", "certificate": true } } ``` 3. **Store Project Idea**: ```json { "content": "Planning to build a quantum algorithm simulator to visualize quantum circuits and test quantum algorithms.", "tags": ["project", "quantum-computing", "idea"], "metadata": { "status": "planning", "priority": "medium" } } ``` 4. **Create Relationships**: ```json // Interest -> Course { "source_id": "interest_id", "target_id": "course_id", "relationship_type": "pursued_through" } // Course -> Project { "source_id": "course_id", "target_id": "project_id", "relationship_type": "inspired" } ``` 5. **Retrieve Context**: ```json { "query": "What have I learned about quantum computing and what projects am I planning?", "max_memories": 10 } ``` ### Scenario 2: Meeting Notes and Follow-ups **Use Case**: Store meeting notes and track action items. **Memory 1 - Meeting Summary**: ```json { "content": "Weekly team meeting on January 15, 2024. Discussed Q1 goals, reviewed sprint progress, and assigned new tasks. Key decisions: prioritize API refactoring, schedule code review session for next week.", "tags": ["meeting", "team", "q1-2024"], "metadata": { "date": "2024-01-15", "meeting_type": "weekly_standup", "participants": ["Alice", "Bob", "Charlie", "You"] } } ``` **Memory 2 - Action Item**: ```json { "content": "Action item: Refactor the user authentication API to use OAuth2. Deadline: January 22, 2024. Assigned to: You.", "tags": ["action-item", "api", "oauth2"], "metadata": { "assigned_to": "You", "deadline": "2024-01-22", "priority": "high", "status": "pending" } } ``` **Memory 3 - Decision**: ```json { "content": "Decision: Schedule code review session for January 18, 2024 at 2 PM. All team members should review the pull requests before the session.", "tags": ["decision", "code-review", "meeting"], "metadata": { "date": "2024-01-18", "time": "14:00", "type": "code-review" } } ``` **Create Relationships**: ```json // Meeting -> Action Item { "source_id": "meeting_id", "target_id": "action_item_id", "relationship_type": "generated" } // Meeting -> Decision { "source_id": "meeting_id", "target_id": "decision_id", "relationship_type": "resulted_in" } ``` **Query Later**: ```json { "query": "What are my action items from recent meetings?", "limit": 10 } ``` ### Scenario 3: Research and Documentation **Use Case**: Store research findings and build connections between concepts. **Memory 1 - Research Finding**: ```json { "content": "Recent study shows that transformer architectures outperform traditional RNNs for sequence-to-sequence tasks, especially in machine translation. Key advantage: parallel processing of sequences.", "tags": ["research", "nlp", "transformers"], "metadata": { "topic": "neural-architectures", "finding_type": "comparison", "date": "2024-01-10" } } ``` **Memory 2 - Related Concept**: ```json { "content": "Attention mechanism allows models to focus on relevant parts of input sequences. Self-attention in transformers enables understanding of relationships between all positions in a sequence.", "tags": ["research", "nlp", "attention"], "metadata": { "topic": "neural-architectures", "concept_type": "mechanism" } } ``` **Memory 3 - Application**: ```json { "content": "Used BERT (Bidirectional Encoder Representations from Transformers) for sentiment analysis task. Achieved 92% accuracy on customer review dataset.", "tags": ["application", "nlp", "bert"], "metadata": { "task": "sentiment-analysis", "model": "BERT", "accuracy": "92%" } } ``` **Create Relationships**: ```json // Finding -> Concept { "source_id": "finding_id", "target_id": "concept_id", "relationship_type": "relies_on" } // Concept -> Application { "source_id": "concept_id", "target_id": "application_id", "relationship_type": "enables" } ``` --- ## Advanced Graph Queries ### Example 7: Custom Cypher Queries **Use Case**: Perform complex graph traversals and analytics **Tool**: `search_graph` **Query 1 - Find All Memories with Relationships**: ```json { "cypher_query": "MATCH (m:Memory)-[r]->(n:Memory) RETURN m.content as source, type(r) as relationship, n.content as target, m.tags as source_tags, n.tags as target_tags LIMIT 20" } ``` **Query 2 - Find Memories by Tag**: ```json { "cypher_query": "MATCH (m:Memory) WHERE 'project' IN m.tags RETURN m.id as id, m.content as content, m.tags as tags, m.created_at as created_at ORDER BY m.created_at DESC" } ``` **Query 3 - Find Related Memories (2 hops)**: ```json { "cypher_query": "MATCH path = (start:Memory {id: $memory_id})-[*1..2]-(related:Memory) RETURN DISTINCT related.id as id, related.content as content, length(path) as distance ORDER BY distance", "parameters": { "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } ``` **Query 4 - Find Most Connected Memories**: ```json { "cypher_query": "MATCH (m:Memory)-[r]-() RETURN m.id as id, m.content as content, count(r) as connection_count ORDER BY connection_count DESC LIMIT 10" } ``` **Query 5 - Find Memories by Date Range**: ```json { "cypher_query": "MATCH (m:Memory) WHERE m.created_at >= datetime($start_date) AND m.created_at <= datetime($end_date) RETURN m.id as id, m.content as content, m.created_at as created_at ORDER BY m.created_at", "parameters": { "start_date": "2024-01-01T00:00:00Z", "end_date": "2024-01-31T23:59:59Z" } } ``` **Query 6 - Find Memories by Metadata**: ```json { "cypher_query": "MATCH (m:Memory) WHERE m.metadata CONTAINS $project_name RETURN m.id as id, m.content as content, m.metadata as metadata", "parameters": { "project_name": "Customer Churn Prediction" } } ``` **Note**: Since metadata is stored as a JSON string in Neo4j, use `CONTAINS` for simple text matching. For complex metadata queries, consider using the `retrieve_memories` tool which handles JSON parsing automatically. If you have APOC procedures installed, you can use `apoc.convert.fromJsonMap(m.metadata)` to parse and query nested properties. --- ## Integration Examples ### Using with Cursor AI Once the MCP server is running and configured in Cursor, you can interact with it naturally: **Example Conversation**: ``` You: "Remember that I'm working on a customer churn prediction project using XGBoost" AI: [Uses store_memory tool] "I've stored that information. Your memory has been saved with ID: a1b2c3d4..." You: "What projects am I currently working on?" AI: [Uses retrieve_memories tool] "Based on your stored memories, you're currently working on: 1. Customer Churn Prediction - using XGBoost, scheduled for Q2 2024 2. API Refactoring - OAuth2 implementation, deadline January 22" ``` ### Using with Claude Desktop Similar to Cursor, Claude can use the MCP tools: **Example Conversation**: ``` You: "Give me context about my machine learning projects" Claude: [Uses get_context tool] "Based on your stored memories, here's what I know about your ML projects: You're working on a customer churn prediction project using XGBoost... [synthesized context from multiple memories]" ``` --- ## Best Practices 1. **Use Descriptive Tags**: Tags help with quick categorization and retrieval ```json "tags": ["project", "machine-learning", "churn-prediction", "in-progress"] ``` 2. **Add Rich Metadata**: Metadata enables powerful queries and filtering ```json "metadata": { "project_name": "Customer Churn Prediction", "status": "in-progress", "deadline": "2024-06-30", "team_size": 3 } ``` **Note**: Metadata is automatically stored as JSON in Neo4j. The tools handle JSON serialization/deserialization automatically, so you can use nested dictionaries without worrying about the storage format. 3. **Create Relationships**: Build a knowledge graph by linking related memories ```json { "relationship_type": "relates_to", // or "follows", "references", "part_of", etc. "properties": { "strength": "strong", "category": "technical" } } ``` 4. **Regular Context Retrieval**: Use `get_context` to synthesize information from multiple memories 5. **Use Cypher for Complex Queries**: When simple retrieval isn't enough, use `search_graph` with custom Cypher queries --- ## Tips and Tricks - **Memory Chunking**: Store related but distinct information as separate memories, then link them with relationships - **Version Control**: Use metadata to track versions or updates to information - **Temporal Queries**: Use date-based metadata and Cypher queries to find memories from specific time periods - **Graph Traversal**: Use relationship types to create semantic paths through your knowledge graph - **Tag Hierarchies**: Use consistent tag naming (e.g., "project/ml", "project/api") for better organization --- ## Next Steps - Explore the [README.md](README.md) for setup instructions - Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if you encounter issues - Start building your own knowledge graph!