---
title: "Step 10: Official Graphiti MCP Server Breakdown - Understanding Before Building (Discussion + Project)"
source: Panaversity Learn Agentic AI
source_url: https://github.com/panaversity/learn-agentic-ai
licence: Apache-2.0
domain: agentic-ai
subdomain: panaversity-agentic
date_added: 2026-04-25
---

# Step 10: Official Graphiti MCP Server Breakdown - Understanding Before Building (Discussion + Project)

> For implementation see the last step 05_temporal_kg_mcp_server before graphiti learning path.

Before diving into building custom educational systems, let's understand how the **official Graphiti MCP server** works. This step breaks down the existing server so you understand the foundations before creating specialized implementations.

## 🎯 **Why This Matters**

You've learned all the Graphiti fundamentals (Steps 01-08), but the **official MCP server** is your first look at how these concepts work together in a production system. Understanding this architecture will help you:

- **Recognize patterns** used in real-world Graphiti applications
- **Understand best practices** for MCP server development
- **Learn from proven architecture** before building custom solutions
- **Appreciate the complexity** that Graphiti abstracts for you

## 📁 **Official MCP Server Structure**

The official server lives in `@05_mcp_temporal_memory/graphiti_mcp_server/` and follows this structure:

```
graphiti_mcp_server/
├── mcp_server.py          # Main server with all tools (981 lines!)
├── python_client.py       # Demo client for testing
├── postman.json          # Postman collection for API testing
├── README.md             # Setup and usage instructions
└── .env                  # Environment configuration
```

## 🔧 **Server Architecture Breakdown**

### **1. Core Imports and Setup**

```python
# Essential MCP and Graphiti imports
from mcp.server.fastmcp import FastMCP
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType, EpisodicNode
from graphiti_core.edges import EntityEdge

# Gemini LLM integration (not OpenAI!)
from graphiti_core.llm_client.gemini_client import GeminiClient
from graphiti_core.embedder.gemini import GeminiEmbedder
```

**Key Insight**: The official server uses **Gemini** (Google) instead of OpenAI, showing Graphiti's LLM flexibility.

### **2. Configuration Management**

```python
# Environment-based configuration
DEFAULT_LLM_MODEL = os.getenv('MODEL_NAME', 'gemini-2.5-flash')
SMALL_LLM_MODEL = os.getenv('SMALL_LLM_MODEL', 'gemini-2.5-flash')
DEFAULT_EMBEDDER_MODEL = os.getenv('DEFAULT_EMBEDDER_MODEL', 'embedding-001')

# Rate limiting for production
SEMAPHORE_LIMIT = int(os.getenv('SEMAPHORE_LIMIT', 10))
```

**Key Insight**: Production servers need **rate limiting** and **environment-based configuration** for different deployment scenarios.

### **3. Custom Domain Types**

The server includes **business-focused** custom types:

```python
class Requirement(BaseModel):
    """Requirements for projects and products"""
    project_name: str
    description: str

class Preference(BaseModel):
    """User preferences and likes/dislikes"""
    category: str  # 'Brands', 'Food', 'Music'
    description: str

class Procedure(BaseModel):
    """Step-by-step procedures and workflows"""
    # ... detailed procedure modeling
```

**Key Insight**: The official server targets **business and enterprise use cases**, not education. This shows how custom types should match your domain.

### **4. MCP Server Instructions**

```python
GRAPHITI_MCP_INSTRUCTIONS = """
Graphiti is a memory service for AI agents built on a knowledge graph. 
Graphiti performs well with dynamic data such as user interactions, 
changing enterprise data, and external information.

Key capabilities:
1. Add episodes (text, messages, or JSON) to the knowledge graph
2. Search for nodes (entities) using natural language queries
3. Find relevant facts (relationships between entities)
4. Retrieve specific entity edges or episodes by UUID
5. Manage the knowledge graph with maintenance tools
"""
```

**Key Insight**: Clear **server instructions** help AI assistants understand how to use the tools effectively.

## 🛠️ **Official MCP Tools Analysis**

The official server provides **8 core tools**. Let's break down each one:

### **1. `add_memory` - The Primary Ingestion Tool**

```python
@mcp.tool()
async def add_memory(
    name: str,
    episode_body: str,
    group_id: str | None = None,
    source: str = 'text',  # 'text', 'json', 'message'
    source_description: str = '',
    uuid: str | None = None,
) -> SuccessResponse | ErrorResponse:
```

**What it does:**
- **Primary way** to add information to the knowledge graph
- Supports **multiple data formats**: text, JSON, messages
- Uses **background processing** with queues for scalability
- Handles **group-based isolation** for multi-user scenarios

**Key Features:**
- **Asynchronous processing**: Returns immediately, processes in background
- **Sequential processing**: Episodes for same group_id processed in order
- **Flexible input**: Handles unstructured text and structured JSON
- **Enterprise focus**: Built for business data ingestion

### **2. `search_memory_nodes` - Entity Search**

```python
@mcp.tool()
async def search_memory_nodes(
    query: str,
    group_id: str | None = None,
    limit: int = 20
) -> list[NodeSearchResult]:
```

**What it does:**
- Searches for **entity summaries** using natural language
- Returns **node information** with relevance scores
- Filters by **group_id** for multi-tenant isolation

**Key Features:**
- **Semantic search**: Uses embeddings for meaning-based matching
- **Relevance scoring**: Returns confidence scores with results
- **Flexible limits**: Configurable result count

### **3. `search_memory_facts` - Relationship Search**

```python
@mcp.tool()
async def search_memory_facts(
    query: str,
    group_id: str | None = None,
    limit: int = 20
) -> list[FactSearchResult]:
```

**What it does:**
- Searches for **relationships between entities**
- Returns **fact triples** with context
- Essential for understanding **entity connections**

**Key Features:**
- **Relationship-focused**: Finds connections, not just entities
- **Contextual results**: Returns facts with supporting evidence
- **Temporal awareness**: Includes creation and validity timestamps

### **4. `get_episodes` - Recent Memory Retrieval**

```python
@mcp.tool()
async def get_episodes(
    group_id: str | None = None,
    last_n: int = 10
) -> list[Episode]:
```

**What it does:**
- Retrieves **most recent episodes** for a group
- Useful for **conversation context** and recent activity
- Supports **temporal memory** patterns

**Key Features:**
- **Recency-based**: Gets latest information first
- **Group isolation**: Respects multi-user boundaries
- **Configurable count**: Flexible episode limits

### **5. `delete_episode` - Content Management**

```python
@mcp.tool()
async def delete_episode(
    episode_uuid: str
) -> SuccessResponse | ErrorResponse:
```

**What it does:**
- **Removes episodes** from the knowledge graph
- Essential for **data management** and privacy compliance
- **Permanent deletion** - use carefully!

### **6. `delete_entity_edge` - Relationship Management**

```python
@mcp.tool()
async def delete_entity_edge(
    edge_uuid: str
) -> SuccessResponse | ErrorResponse:
```

**What it does:**
- **Removes relationships** between entities
- Allows **fine-grained graph editing**
- Useful for **correcting wrong connections**

### **7. `get_entity_edge` - Relationship Inspection**

```python
@mcp.tool()
async def get_entity_edge(
    edge_uuid: str
) -> EntityEdge | None:
```

**What it does:**
- **Retrieves specific relationships** by UUID
- Enables **detailed relationship inspection**
- Supports **debugging and verification**

### **8. `clear_graph` - Complete Reset**

```python
@mcp.tool()
async def clear_graph() -> SuccessResponse | ErrorResponse:
```

**What it does:**
- **Completely clears** the knowledge graph
- **Rebuilds indices** for fresh start
- **Development and testing** tool - dangerous in production!

## 🏗️ **Architecture Patterns**

### **1. Background Processing with Queues**

```python
# Episode processing queue per group_id
episode_queues: dict[str, asyncio.Queue] = {}
queue_workers: dict[str, bool] = {}

async def process_episode_queue(group_id: str):
    """Process episodes sequentially for each group"""
    while queue_workers.get(group_id, True):
        episode_data = await episode_queues[group_id].get()
        # Process episode...
```

**Why this matters:**
- **Scalability**: Handles multiple users simultaneously
- **Consistency**: Sequential processing prevents race conditions
- **Performance**: Non-blocking API responses

### **2. Error Handling Pattern**

```python
class SuccessResponse(BaseModel):
    success: bool = True
    message: str

class ErrorResponse(BaseModel):
    success: bool = False
    error: str

# Usage in tools
try:
    # ... operation
    return SuccessResponse(message="Operation completed")
except Exception as e:
    return ErrorResponse(error=str(e))
```

**Key Benefits:**
- **Consistent responses**: All tools return similar structure
- **Error transparency**: Clear error messages for debugging
- **Type safety**: Pydantic models ensure structure

### **3. Multi-Tenant Isolation**

```python
# Every operation respects group_id
async def add_memory(group_id: str | None = None, ...):
    if group_id is None:
        group_id = config.default_group_id
    # ... use group_id for isolation
```

**Architecture benefit:**
- **Data separation**: Multiple users/projects isolated
- **Scalable design**: Single server, multiple tenants
- **Privacy protection**: Users can't access others' data

## 🎓 **What We Learn from the Official Server**

### **1. Production Patterns**

- **Background processing** for scalability
- **Rate limiting** to prevent API abuse
- **Environment configuration** for different deployments
- **Comprehensive error handling** for reliability

### **2. Business Focus**

- **Enterprise data types** (Requirements, Procedures, Preferences)
- **JSON data ingestion** for structured business data
- **Multi-tenant architecture** for SaaS applications
- **Maintenance tools** for production management

### **3. MCP Best Practices**

- **Clear tool descriptions** with examples
- **Consistent response patterns** across all tools
- **Flexible parameters** with sensible defaults
- **Comprehensive documentation** in server instructions

## 🆚 **Official vs. Educational Comparison**

| Aspect | Official Server | Educational Server (Step 09) |
|--------|----------------|-------------------------------|
| **Domain** | Business/Enterprise | Education/Learning |
| **Custom Types** | Requirements, Preferences | Students, Courses, Mastery |
| **Use Cases** | CRM, Project Management | AI Tutoring, Learning Analytics |
| **Tools Focus** | General memory operations | Educational workflows |
| **Complexity** | Single file (981 lines) | Modular architecture |

## 🚀 **Key Takeaways**

### **1. Architecture Insights**

- **Single-file approach** works for general-purpose servers
- **Background processing** essential for production scalability
- **Multi-tenant design** enables SaaS applications
- **Comprehensive toolset** covers full CRUD lifecycle

### **2. Development Patterns**

- **Environment-driven configuration** for flexibility
- **Consistent error handling** across all operations
- **Clear documentation** helps AI assistants use tools
- **Type safety** with Pydantic models prevents errors

### **3. Production Considerations**

- **Rate limiting** prevents LLM provider issues
- **Queue management** ensures data consistency
- **Maintenance tools** support operational needs
- **Telemetry collection** helps improve the system

## 🎯 **Preparing for Custom Development**

Understanding this official server prepares you to:

1. **Recognize proven patterns** in production Graphiti applications
2. **Adapt architecture** for your specific domain needs
3. **Implement best practices** from the start
4. **Build on solid foundations** rather than starting from scratch

The official server shows **what's possible** with Graphiti MCP servers. Your educational server (Step 09) shows **what's optimal** for specific domains.

## 🧠 **Extending to Complete Agentic Memory System**

The official MCP server provides the **foundation** for implementing all memory types from cognitive science. Here's how it could be extended to create a **comprehensive multi-user agentic memory system**:

### **Current Implementation Mapping**

The official server already implements several memory types:

| Memory Type | Current Implementation | How It Works |
|-------------|----------------------|--------------|
| **Long-Term Memory** | `add_memory` + persistent storage | Episodes stored in Neo4j, persist across sessions |
| **Episodic Memory** | Episodes with timestamps | Each episode is a specific event with temporal context |
| **Semantic Memory** | Entity extraction + fact triples | LLM extracts structured knowledge from episodes |

### **Missing Memory Types & Extensions**

To create a **complete agentic memory system**, we could extend the official server:

#### **1. Short-Term Memory (STM) Extension**

```python
@mcp.tool()
async def manage_working_memory(
    user_id: str,
    operation: str,  # "add", "get", "clear", "summarize"
    content: str = "",
    context_window: int = 10
) -> WorkingMemoryResponse:
    """Manage agent's working memory/scratchpad for current session
    
    STM serves as the agent's 'conscious mind' - a dynamic workspace for:
    - Planning and reasoning traces
    - Current task state management  
    - Multi-step problem solving
    - Error correction and adaptation
    """
    
    # Implementation would use in-memory storage with TTL
    # Could integrate with agent's current reasoning trace
```

#### **2. Procedural Memory Extension**

```python
@mcp.tool()
async def manage_procedures(
    user_id: str,
    operation: str,  # "learn", "execute", "update", "list"
    procedure_name: str = "",
    steps: List[str] = [],
    success_rate: float = 0.0
) -> ProceduralMemoryResponse:
    """Manage learned procedures and skill sequences
    
    Procedural memory stores 'how to' knowledge:
    - Learned task sequences (e.g., "how to debug code")
    - Skill patterns (e.g., "how to write tests")  
    - Tool usage workflows (e.g., "how to deploy apps")
    - Decision rules (e.g., "when to use which approach")
    """
    
    # Could store as structured workflows in knowledge graph
    # Track success rates and optimize over time
```

#### **3. Reflection Memory Extension**

```python
@mcp.tool()
async def manage_reflections(
    user_id: str,
    operation: str,  # "reflect", "get_insights", "track_patterns"
    task_outcome: str = "",
    reflection_type: str = "performance",  # "performance", "learning", "error"
    insights: List[str] = []
) -> ReflectionResponse:
    """Manage agent's self-reflection and meta-learning
    
    Reflection enables agents to:
    - Analyze their own performance patterns
    - Learn from mistakes and successes
    - Identify improvement opportunities
    - Adapt strategies based on outcomes
    """
    
    # Could analyze episode patterns to generate insights
    # Track performance trends over time
```

#### **4. Enhanced Multi-User Memory Management**

```python
@mcp.tool()
async def manage_user_memory_profile(
    user_id: str,
    operation: str,  # "create", "get", "update", "analyze"
    memory_preferences: Dict[str, Any] = {},
    learning_patterns: Dict[str, Any] = {}
) -> UserMemoryProfile:
    """Manage individual user memory profiles and preferences
    
    Each user gets personalized memory management:
    - Memory retention preferences (what to remember/forget)
    - Learning style adaptations
    - Context switching patterns
    - Memory consolidation schedules
    """
    
    # Sophisticated user modeling for memory optimization
```

### **Complete Agentic Memory Architecture**

```python
class ComprehensiveMemorySystem:
    """Extended official MCP server with full memory capabilities"""
    
    # Existing official tools (enhanced)
    add_memory()           # Episodes → Long-term & Episodic memory
    search_memory_nodes()  # Semantic memory retrieval
    search_memory_facts()  # Relationship memory
    get_episodes()         # Recent episodic memory
    
    # New memory type extensions
    manage_working_memory()    # Short-term memory & reasoning traces
    manage_procedures()        # Procedural memory & learned skills
    manage_reflections()       # Meta-learning & self-improvement
    manage_user_profiles()     # Personalized memory management
    
    # Advanced memory operations
    consolidate_memories()     # Move STM → LTM, strengthen important memories
    forget_memories()          # Selective forgetting & memory cleanup
    transfer_learning()        # Apply learned patterns to new domains
    memory_visualization()     # Understand memory structure & patterns
```

### **Real-World Applications**

This **comprehensive memory system** would enable:

#### **1. Advanced Personal AI Assistants**
```python
# AI assistant with complete memory
assistant_memory = {
    "STM": "Currently helping user debug Python code, context: Flask app",
    "Episodic": "Last week user struggled with similar database connection issue",
    "Semantic": "User prefers detailed explanations with examples",
    "Procedural": "Learned debugging workflow: logs → error trace → fix → test",
    "Reflection": "User learns faster with visual diagrams than text"
}
```

#### **2. Adaptive Learning Systems**
```python
# Educational AI with memory-driven adaptation
learning_memory = {
    "STM": "Student currently working on Python loops, showing confusion",
    "Episodic": "Student mastered variables last week after visual examples",
    "Semantic": "Loops require understanding of variables and conditionals",
    "Procedural": "Teaching workflow: concept → example → practice → assessment",
    "Reflection": "Visual learners need diagrams before abstract concepts"
}
```

#### **3. Enterprise Knowledge Workers**
```python
# Business AI with organizational memory
enterprise_memory = {
    "STM": "Currently analyzing Q3 sales data, looking for trends",
    "Episodic": "Similar analysis in Q1 revealed seasonal patterns",
    "Semantic": "Company policy: quarterly reviews include regional breakdown",
    "Procedural": "Analysis workflow: data → trends → insights → recommendations",
    "Reflection": "Management prefers executive summaries over detailed reports"
}
```

### **Implementation Strategy**

To extend the official server into a complete memory system:

1. **Phase 1**: Add STM management for session-based reasoning
2. **Phase 2**: Implement procedural memory for learned workflows  
3. **Phase 3**: Add reflection capabilities for meta-learning
4. **Phase 4**: Enhanced multi-user profiles with memory preferences
5. **Phase 5**: Memory consolidation and optimization algorithms

### **Benefits of Complete Memory System**

- **Truly Adaptive Agents**: Learn and improve from every interaction
- **Personalized Experiences**: Each user gets tailored AI behavior
- **Efficient Learning**: Agents don't repeat solved problems
- **Meta-Cognitive Abilities**: Agents understand their own learning
- **Scalable Intelligence**: Memory systems that grow with usage

---

**Key Insight**: The official Graphiti MCP server provides the **foundation** for comprehensive agentic memory. By extending it with STM, procedural memory, and reflection capabilities, it could become a **complete multi-user cognitive architecture** that rivals human memory systems in sophistication.

*"The official server shows what's possible - extending it with complete memory types shows what's revolutionary for AI agents."* 🧠
