Zep MCP Server - API Reference

Complete API documentation for all 10 MCP tools with examples, parameters, and response formats.

Version: 0.1.0

Last Updated: October 2025

1. memory_add_messages

2. memory_get_context

3. memory_search

4. memory_add_data

5. memory_add_data_batch

6. memory_get_user_summary

7. memory_create_thread

8. memory_list_threads

9. memory_get_messages

10. memory_check_status

1. memory_add_messages

⭐ Call this tool every turn to build the knowledge graph

Store conversation messages in Zep. Threads auto-create on first use - just provide messages and reuse the returned threadId on subsequent turns.

Parameters


{
  threadId?: string,        // Thread ID from previous turn (omit on first turn to auto-generate)
  messages: Array<{
    role: "user" | "assistant" | "system" | "function" | "tool",
    content: string,
    name?: string,          // Optional: speaker name for better entity association
    createdAt?: string      // Optional: RFC3339 timestamp
  }>,
  returnContext?: boolean,  // Return context block immediately (adds ~200ms latency)
  ignoreRoles?: string[]    // Roles to exclude from graph (e.g., ["assistant"])
}

Response


{
  success: true,
  threadId: string,         // Use this ID for subsequent calls
  messageUuids: string[],   // UUIDs of stored messages
  context?: string          // Only present if returnContext was true
}

Examples

First Turn (Auto-Create Thread)


{
  "name": "memory_add_messages",
  "arguments": {
    "messages": [
      {
        "role": "user",
        "content": "My name is Alex and I live in Ho Chi Minh City"
      },
      {
        "role": "assistant",
        "content": "Nice to meet you, Alex! Ho Chi Minh City is a vibrant place."
      }
    ]
  }
}

Response


{
  "success": true,
  "threadId": "thread_1729263000_abc123",
  "messageUuids": ["uuid-1", "uuid-2"]
}

Subsequent Turn (Reuse Thread)


{
  "name": "memory_add_messages",
  "arguments": {
    "threadId": "thread_1729263000_abc123",
    "messages": [
      {
        "role": "user",
        "content": "I work as a software engineer"
      },
      {
        "role": "assistant",
        "content": "That's great! What kind of software do you work on?"
      }
    ]
  }
}

2. memory_get_context

Retrieve relevant context and facts for the current conversation.

Parameters


{
  threadId: string,
  mode?: "summary" | "basic"  // summary=concise (default), basic=fast (<200ms)
}

Response


{
  success: true,
  context: string,           // Formatted context string with facts
  messages: Message[],       // Recent conversation messages
  facts: Fact[]             // Extracted facts (currently empty array)
}

Example


{
  "name": "memory_get_context",
  "arguments": {
    "threadId": "thread_1729263000_abc123",
    "mode": "summary"
  }
}

Response


{
  "success": true,
  "context": "Alex lives in Ho Chi Minh City. Alex works as a software engineer.",
  "messages": [
    {
      "role": "user",
      "content": "My name is Alex...",
      "createdAt": "2025-10-18T10:00:00Z"
    }
  ],
  "facts": []
}

3. memory_search 🔥 (Enhanced in Phase 2)

Search the knowledge graph with advanced filtering and reranking. Now supports entity/edge type filtering, fact quality filtering, and 5 reranking algorithms.

⚠️ IMPORTANT: scope is mutually exclusive. You get ONE type per search:

scope="edges" (default) → Returns only facts

scope="nodes" → Returns only entities

scope="episodes" → Returns only messages

To retrieve multiple types, make separate API calls.

Parameters


{
  query: string,
  scope?: "edges" | "nodes" | "episodes",  // Default: "edges" (mutually exclusive)
  limit?: number,                          // Default: 5, Max: 100


  // Phase 2: Advanced Filters
  searchFilters?: {
    entityTypes?: string[],      // e.g., ["User", "Preference", "Location"]
    edgeTypes?: string[],        // e.g., ["LOCATED_AT", "PREFERS"]
    minFactRating?: number       // 0.0-1.0, filter by fact quality
  },


  // Phase 2: Advanced Search Parameters
  reranker?: "rrf" | "mmr" | "cross_encoder" | "node_distance" | "episode_mentions",
  mmrLambda?: number,            // 0.0-1.0, diversity control (only for MMR)
  minScore?: number,             // Minimum relevance threshold
  centerNodeUuid?: string        // Required for node_distance reranker
}

Response

Returns one of the following based on scope:


// scope="edges" (default)
{
  success: true,
  edges: Array<{
    uuid: string,
    name: string,           // Edge type (e.g., "LOCATED_AT", "PREFERS")
    fact: string,           // Human-readable fact
    sourceNodeUuid: string,
    targetNodeUuid: string,
    validAt?: string,
    invalidAt?: string,
    createdAt: string,
    episodes: string[],     // Episode UUIDs only (not full content)
    score?: number          // Relevance score from reranker
  }>
}


// scope="nodes"
{
  success: true,
  nodes: Array<{
    uuid: string,
    name: string,           // Entity name
    summary?: string,
    createdAt: string,
    score?: number
  }>
}


// scope="episodes"
{
  success: true,
  episodes: Array<{
    uuid: string,
    content: string,        // Full message/data content
    createdAt: string,
    type?: string,          // "message", "json", "text"
    role?: string,          // "user", "assistant", etc.
    score?: number,
    sessionId?: string      // Thread/session ID
  }>
}

Examples

Search for Facts (scope="edges", default)


{
  "name": "memory_search",
  "arguments": {
    "query": "where does Alex live",
    "scope": "edges",
    "limit": 5
  }
}

Response:


{
  "success": true,
  "edges": [
    {
      "uuid": "edge-uuid-1",
      "name": "LOCATED_AT",
      "fact": "Alex lives in Ho Chi Minh City",
      "score": 0.95,
      "episodes": ["ep-uuid-1", "ep-uuid-2"]
    }
  ]
}

Search for Entities (scope="nodes")


{
  "name": "memory_search",
  "arguments": {
    "query": "Alex",
    "scope": "nodes",
    "limit": 5
  }
}

Response:


{
  "success": true,
  "nodes": [
    {
      "uuid": "node-alex",
      "name": "Alex",
      "summary": "Software engineer living in Ho Chi Minh City",
      "score": 0.98
    }
  ]
}

Search for Messages (scope="episodes")


{
  "name": "memory_search",
  "arguments": {
    "query": "what did I say about my location",
    "scope": "episodes",
    "limit": 5
  }
}

Response:


{
  "success": true,
  "episodes": [
    {
      "uuid": "ep-uuid-1",
      "content": "I live in Ho Chi Minh City",
      "role": "user",
      "score": 0.92,
      "sessionId": "thread_123",
      "createdAt": "2025-10-18T10:00:00Z"
    }
  ]
}

Advanced: Filter by Entity Type


{
  "name": "memory_search",
  "arguments": {
    "query": "user preferences",
    "scope": "edges",
    "searchFilters": {
      "entityTypes": ["Preference"],
      "minFactRating": 0.8
    }
  }
}

Advanced: High-Accuracy Search


{
  "name": "memory_search",
  "arguments": {
    "query": "important information",
    "reranker": "cross_encoder",
    "minScore": 0.7
  }
}

Advanced: Diverse Results


{
  "name": "memory_search",
  "arguments": {
    "query": "user interests",
    "scope": "edges",
    "reranker": "mmr",
    "mmrLambda": 0.6,
    "limit": 10
  }
}

4. memory_add_data

Add structured business data or documents to the knowledge graph. For non-conversational data.

Parameters


{
  data: string,         // JSON string or plain text
  type: "json" | "text"
}

Response


{
  success: true,
  episodeId: string     // UUID of created episode
}

Example

JSON Data


{
  "name": "memory_add_data",
  "arguments": {
    "data": "{\"product\": \"Coffee Maker\", \"price\": 89.99, \"inStock\": true}",
    "type": "json"
  }
}

Text Data


{
  "name": "memory_add_data",
  "arguments": {
    "data": "The user's favorite color is blue and they prefer dark mode interfaces.",
    "type": "text"
  }
}

5. memory_add_data_batch

🆕 Phase 1

Add multiple data episodes concurrently (up to 20). Ideal for bulk imports and historical data backfills. 10-20x faster than individual calls.

Parameters


{
  episodes: Array<{
    data: string; // JSON string, plain text, or message
    type: 'json' | 'text' | 'message';
  }>; // Min: 1, Max: 20 episodes
}

Response


{
  success: true,
  episodeIds: string[],  // UUIDs of all created episodes
  count: number          // Number of episodes created
}

Example


{
  "name": "memory_add_data_batch",
  "arguments": {
    "episodes": [
      {
        "data": "User prefers dark mode",
        "type": "text"
      },
      {
        "data": "{\"theme\": \"dark\", \"fontSize\": 14}",
        "type": "json"
      },
      {
        "data": "User: I like minimalist designs",
        "type": "message"
      }
    ]
  }
}

Response


{
  "success": true,
  "episodeIds": ["ep-uuid-1", "ep-uuid-2", "ep-uuid-3"],
  "count": 3
}

6. memory_get_user_summary

🆕 Phase 2

Get a comprehensive summary of all facts known about the user. Perfect for "What do you know about me?" queries.

Parameters


{
  minFactRating?: number,   // 0.0-1.0, filter by fact quality (optional)
  limit?: number,           // Max facts to return (default: 50)
  includeStats?: boolean    // Include statistics (default: true)
}

Response


{
  success: true,
  facts: GraphEdge[],      // All user facts with scores
  stats?: {
    totalFacts: number,
    totalThreads: number,
    factsByType: {
      [edgeType: string]: number  // Count per edge type
    }
  }
}

Example


{
  "name": "memory_get_user_summary",
  "arguments": {
    "minFactRating": 0.7,
    "limit": 50,
    "includeStats": true
  }
}

Response


{
  "success": true,
  "facts": [
    {
      "uuid": "edge-1",
      "name": "LOCATED_AT",
      "fact": "Alex lives in Ho Chi Minh City",
      "score": 0.95,
      "createdAt": "2025-10-18T10:00:00Z"
    },
    {
      "uuid": "edge-2",
      "name": "WORKS_AS",
      "fact": "Alex works as a software engineer",
      "score": 0.92,
      "createdAt": "2025-10-18T10:05:00Z"
    }
  ],
  "stats": {
    "totalFacts": 47,
    "totalThreads": 12,
    "factsByType": {
      "LOCATED_AT": 5,
      "PREFERS": 15,
      "WORKS_AS": 3,
      "HAS_FAMILY": 8,
      "INTERESTED_IN": 16
    }
  }
}

7. memory_create_thread

Explicitly create a new conversation thread. Optional - threads auto-create in memory_add_messages when omitted.

Parameters


{
  threadId?: string  // Custom thread ID (auto-generated if omitted)
}

Response


{
  success: true,
  threadId: string
}

Example


{
  "name": "memory_create_thread",
  "arguments": {}
}

Response


{
  "success": true,
  "threadId": "thread_1729263000_xyz789"
}

8. memory_list_threads

List all conversation threads for the user.

Parameters


{
  limit?: number,   // Max threads to return (default: 50)
  cursor?: string   // Pagination cursor
}

Response


{
  success: true,
  threads: Array<{
    threadId: string,
    userId: string,
    createdAt: string,
    updatedAt?: string,
    metadata?: Record
  }>,
  nextCursor?: string  // For pagination
}

Example


{
  "name": "memory_list_threads",
  "arguments": {
    "limit": 10
  }
}

9. memory_get_messages

Get raw message history from a thread.

Parameters


{
  threadId: string,
  limit?: number,   // Max messages (default: 50)
  before?: string   // Message UUID for pagination
}

Response


{
  success: true,
  messages: Array<{
    role: "user" | "assistant" | "system" | "function" | "tool",
    content: string,
    name?: string,
    createdAt?: string
  }>
}

Example


{
  "name": "memory_get_messages",
  "arguments": {
    "threadId": "thread_1729263000_abc123",
    "limit": 20
  }
}

10. memory_check_status

Check ingestion status of messages or data. Use to verify data is processed.

Parameters


{
  messageUuids?: string[],  // Message UUIDs from add_messages
  episodeIds?: string[]     // Episode IDs from add_data
}

Response


{
  success: true,
  statuses: Array<{
    id: string,
    status: "processing" | "completed" | "failed"
  }>
}

Example


{
  "name": "memory_check_status",
  "arguments": {
    "messageUuids": ["uuid-1", "uuid-2"],
    "episodeIds": ["ep-uuid-1"]
  }
}

Response


{
  "success": true,
  "statuses": [
    { "id": "uuid-1", "status": "completed" },
    { "id": "uuid-2", "status": "completed" },
    { "id": "ep-uuid-1", "status": "processing" }
  ]
}

Error Responses

All tools return errors in a consistent format:


{
  success: false,
  error: {
    code: string,        // Machine-readable error code
    message: string,     // Human-readable message
    context?: object     // Additional error context
  }
}

Common Error Codes

CONFIG_ERROR - Missing or invalid configuration

USER_CREATE_FAILED - Failed to create/verify user

THREAD_CREATE_FAILED - Failed to create thread

ADD_MESSAGES_FAILED - Failed to add messages

SEARCH_MEMORY_FAILED - Failed to search

INTERNAL_ERROR - Unexpected error

Example Error Response


{
  "success": false,
  "error": {
    "code": "THREAD_CREATE_FAILED",
    "message": "Failed to create thread: Invalid API key",
    "context": {
      "threadId": "thread_123"
    }
  }
}

Advanced Features

Reranker Comparison

RerankerSpeedAccuracyUse Case rrf⚡⚡⚡ Fast⭐⭐⭐ GoodDefault, balanced mmr⚡⚡ Medium⭐⭐⭐ GoodDiverse results cross_encoder⚡ Slow⭐⭐⭐⭐⭐ ExcellentMaximum accuracy node_distance⚡⚡ Medium⭐⭐⭐⭐ Very GoodRelated information episode_mentions⚡⚡⚡ Fast⭐⭐⭐ GoodFrequently mentioned

Entity Types

Default entity types in Zep's ontology:

User - The user (singleton)

Assistant - The AI assistant (singleton)

Preference - User preferences, choices, opinions

Location - Physical or virtual places

Event - Time-bound activities or occurrences

Object - Physical items, tools, devices

Topic - Subjects of conversation or interest

Organization - Companies, institutions, groups

Document - Information content

Edge Types

Default edge types:

LOCATED_AT - Entity exists at a location

OCCURRED_AT - Event happened at time/location

Custom types created based on data

Best Practices

1. Always call memory_add_messages every turn - Builds complete knowledge graph

2. Save and reuse threadId - First call returns it, use for all subsequent turns

3. Use search filters for precision - Filter by entity types and ratings

4. Check relevance scores - Prioritize high-scoring results

5. Batch for performance - Use memory_add_data_batch for bulk operations

6. Choose appropriate reranker - Balance speed vs accuracy needs

7. Filter by fact rating - Use minFactRating for high-confidence data only

Version History

v0.1.0 (October 2025)

✅ Phase 1: Relevance scores, episode enhancements, batch operations

✅ Phase 2: Advanced search filters, 5 rerankers, user summary tool

✅ 10 total tools (8 core + 2 new)

✅ Full backward compatibility maintained

Additional Resources

README.md - Quick start guide

PHASE-1-IMPLEMENTATION.md - Phase 1 details

PHASE-2-IMPLEMENTATION.md - Phase 2 details

Zep Documentation - Official Zep docs

Zep MCP Server - API Reference

Table of Contents

1. memory_add_messages

Parameters

Response

Examples

2. memory_get_context

Parameters

Response

Example

3. memory_search 🔥 (Enhanced in Phase 2)

Parameters

Response

Examples

4. memory_add_data

Parameters

Response

Example

5. memory_add_data_batch

Parameters

Response

Example

6. memory_get_user_summary

Parameters

Response

Example

7. memory_create_thread

Parameters

Response

Example

8. memory_list_threads

Parameters

Response

Example

9. memory_get_messages

Parameters

Response

Example

10. memory_check_status

Parameters

Response

Example

Error Responses

Common Error Codes

Example Error Response

Advanced Features

Reranker Comparison

Entity Types

Edge Types

Best Practices

Version History

v0.1.0 (October 2025)

Additional Resources