chore: import upstream snapshot with attribution

apps/sim/tools/zep/add_messages.ts

@@ -0,0 +1,113 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+import { THREAD_OUTPUT_PROPERTIES } from '@/tools/zep/types'
+
+export const zepAddMessagesTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_add_messages',
+  name: 'Add Messages',
+  description: 'Add messages to an existing thread',
+  version: '1.0.0',
+
+  params: {
+    threadId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Thread ID to add messages to (e.g., "thread_abc123")',
+    },
+    messages: {
+      type: 'json',
+      required: true,
+      visibility: 'user-or-llm',
+      description:
+        'Array of message objects with role and content (e.g., [{"role": "user", "content": "Hello"}])',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: (params) => `https://api.getzep.com/api/v2/threads/${params.threadId}/messages`,
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => {
+      let messagesArray = params.messages
+      if (typeof messagesArray === 'string') {
+        try {
+          messagesArray = JSON.parse(messagesArray)
+        } catch (_e) {
+          throw new Error('Messages must be a valid JSON array')
+        }
+      }
+
+      if (!Array.isArray(messagesArray) || messagesArray.length === 0) {
+        throw new Error('Messages must be a non-empty array')
+      }
+
+      for (const msg of messagesArray) {
+        if (!msg.role || !msg.content) {
+          throw new Error('Each message must have role and content properties')
+        }
+      }
+
+      return {
+        messages: messagesArray,
+      }
+    },
+  },
+
+  transformResponse: async (response, params) => {
+    const threadId = params.threadId
+
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const text = await response.text()
+    if (!text || text.trim() === '') {
+      return {
+        success: true,
+        output: {
+          threadId,
+          added: true,
+          messageIds: [],
+        },
+      }
+    }
+
+    const data = JSON.parse(text)
+
+    return {
+      success: true,
+      output: {
+        threadId,
+        added: true,
+        messageIds: data.message_uuids || [],
+      },
+    }
+  },
+
+  outputs: {
+    threadId: THREAD_OUTPUT_PROPERTIES.threadId,
+    added: {
+      type: 'boolean',
+      description: 'Whether messages were added successfully',
+    },
+    messageIds: {
+      type: 'array',
+      description: 'Array of added message UUIDs',
+      items: {
+        type: 'string',
+        description: 'Message UUID',
+      },
+    },
+  },
+}

apps/sim/tools/zep/add_user.ts

@@ -0,0 +1,121 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+import { USER_OUTPUT_PROPERTIES } from '@/tools/zep/types'
+
+export const zepAddUserTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_add_user',
+  name: 'Add User',
+  description: 'Create a new user in Zep',
+  version: '1.0.0',
+
+  params: {
+    userId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Unique identifier for the user (e.g., "user_123")',
+    },
+    email: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'User email address',
+    },
+    firstName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'User first name',
+    },
+    lastName: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'User last name',
+    },
+    metadata: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Additional metadata as JSON object (e.g., {"key": "value"})',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: 'https://api.getzep.com/api/v2/users',
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => {
+      const body: Record<string, any> = {
+        user_id: params.userId,
+      }
+
+      if (params.email) body.email = params.email
+      if (params.firstName) body.first_name = params.firstName
+      if (params.lastName) body.last_name = params.lastName
+
+      if (params.metadata) {
+        let metadataObj = params.metadata
+        if (typeof metadataObj === 'string') {
+          try {
+            metadataObj = JSON.parse(metadataObj)
+          } catch (_e) {
+            throw new Error('Metadata must be a valid JSON object')
+          }
+        }
+        body.metadata = metadataObj
+      }
+
+      return body
+    },
+  },
+
+  transformResponse: async (response) => {
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const text = await response.text()
+    if (!text || text.trim() === '') {
+      return {
+        success: true,
+        output: {},
+      }
+    }
+
+    const data = JSON.parse(text)
+
+    return {
+      success: true,
+      output: {
+        userId: data.user_id,
+        email: data.email,
+        firstName: data.first_name,
+        lastName: data.last_name,
+        uuid: data.uuid,
+        createdAt: data.created_at,
+        metadata: data.metadata,
+      },
+    }
+  },
+
+  outputs: {
+    userId: USER_OUTPUT_PROPERTIES.userId,
+    email: USER_OUTPUT_PROPERTIES.email,
+    firstName: USER_OUTPUT_PROPERTIES.firstName,
+    lastName: USER_OUTPUT_PROPERTIES.lastName,
+    uuid: USER_OUTPUT_PROPERTIES.uuid,
+    createdAt: USER_OUTPUT_PROPERTIES.createdAt,
+    metadata: USER_OUTPUT_PROPERTIES.metadata,
+  },
+}

apps/sim/tools/zep/create_thread.ts

@@ -0,0 +1,80 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+import { THREAD_OUTPUT_PROPERTIES } from '@/tools/zep/types'
+
+export const zepCreateThreadTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_create_thread',
+  name: 'Create Thread',
+  description: 'Start a new conversation thread in Zep',
+  version: '1.0.0',
+
+  params: {
+    threadId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Unique identifier for the thread (e.g., "thread_abc123")',
+    },
+    userId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'User ID associated with the thread (e.g., "user_123")',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: 'https://api.getzep.com/api/v2/threads',
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => ({
+      thread_id: params.threadId,
+      user_id: params.userId,
+    }),
+  },
+
+  transformResponse: async (response) => {
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const text = await response.text()
+    if (!text || text.trim() === '') {
+      return {
+        success: true,
+        output: {},
+      }
+    }
+
+    const data = JSON.parse(text)
+
+    return {
+      success: true,
+      output: {
+        threadId: data.thread_id,
+        userId: data.user_id,
+        uuid: data.uuid,
+        createdAt: data.created_at,
+        projectUuid: data.project_uuid,
+      },
+    }
+  },
+
+  outputs: {
+    threadId: THREAD_OUTPUT_PROPERTIES.threadId,
+    userId: THREAD_OUTPUT_PROPERTIES.userId,
+    uuid: THREAD_OUTPUT_PROPERTIES.uuid,
+    createdAt: THREAD_OUTPUT_PROPERTIES.createdAt,
+    projectUuid: THREAD_OUTPUT_PROPERTIES.projectUuid,
+  },
+}

apps/sim/tools/zep/delete_thread.ts

@@ -0,0 +1,55 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+
+export const zepDeleteThreadTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_delete_thread',
+  name: 'Delete Thread',
+  description: 'Delete a conversation thread from Zep',
+  version: '1.0.0',
+
+  params: {
+    threadId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Thread ID to delete (e.g., "thread_abc123")',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: (params) => `https://api.getzep.com/api/v2/threads/${params.threadId}`,
+    method: 'DELETE',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response) => {
+    const text = await response.text()
+
+    if (!response.ok) {
+      throw new Error(`Zep API error (${response.status}): ${text || response.statusText}`)
+    }
+
+    return {
+      success: true,
+      output: {
+        deleted: true,
+      },
+    }
+  },
+
+  outputs: {
+    deleted: {
+      type: 'boolean',
+      description: 'Whether the thread was deleted',
+    },
+  },
+}

apps/sim/tools/zep/get_context.ts

@@ -0,0 +1,76 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+
+export const zepGetContextTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_get_context',
+  name: 'Get User Context',
+  description: 'Retrieve user context from a thread with summary or basic mode',
+  version: '1.0.0',
+
+  params: {
+    threadId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Thread ID to get context from (e.g., "thread_abc123")',
+    },
+    mode: {
+      type: 'string',
+      required: false,
+      default: 'summary',
+      visibility: 'user-only',
+      description: 'Context mode: "summary" (natural language) or "basic" (raw facts)',
+    },
+    minRating: {
+      type: 'number',
+      required: false,
+      visibility: 'user-only',
+      description: 'Minimum rating by which to filter relevant facts',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const queryParams = new URLSearchParams()
+      const mode = params.mode || 'summary'
+      queryParams.append('mode', mode)
+      if (params.minRating !== undefined)
+        queryParams.append('minRating', String(Number(params.minRating)))
+      return `https://api.getzep.com/api/v2/threads/${params.threadId}/context?${queryParams.toString()}`
+    },
+    method: 'GET',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response) => {
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const data = await response.json()
+
+    return {
+      success: true,
+      output: {
+        context: data.context,
+      },
+    }
+  },
+
+  outputs: {
+    context: {
+      type: 'string',
+      description: 'The context string (summary or basic mode)',
+    },
+  },
+}

apps/sim/tools/zep/get_messages.ts

@@ -0,0 +1,84 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+import { MESSAGES_ARRAY_OUTPUT, PAGINATION_OUTPUT_PROPERTIES } from '@/tools/zep/types'
+
+export const zepGetMessagesTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_get_messages',
+  name: 'Get Messages',
+  description: 'Retrieve messages from a thread',
+  version: '1.0.0',
+
+  params: {
+    threadId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Thread ID to get messages from (e.g., "thread_abc123")',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of messages to return (e.g., 10, 50, 100)',
+    },
+    cursor: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Cursor for pagination',
+    },
+    lastn: {
+      type: 'number',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Number of most recent messages to return (overrides limit and cursor)',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const queryParams = new URLSearchParams()
+      if (params.limit) queryParams.append('limit', String(Number(params.limit)))
+      if (params.cursor) queryParams.append('cursor', params.cursor)
+      if (params.lastn) queryParams.append('lastn', String(Number(params.lastn)))
+
+      const queryString = queryParams.toString()
+      return `https://api.getzep.com/api/v2/threads/${params.threadId}/messages${queryString ? `?${queryString}` : ''}`
+    },
+    method: 'GET',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response) => {
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const data = await response.json()
+
+    return {
+      success: true,
+      output: {
+        messages: data.messages || [],
+        rowCount: data.row_count,
+        totalCount: data.total_count,
+      },
+    }
+  },
+
+  outputs: {
+    messages: MESSAGES_ARRAY_OUTPUT,
+    rowCount: PAGINATION_OUTPUT_PROPERTIES.rowCount,
+    totalCount: PAGINATION_OUTPUT_PROPERTIES.totalCount,
+  },
+}

apps/sim/tools/zep/get_threads.ts

@@ -0,0 +1,86 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+import { PAGINATION_OUTPUT_PROPERTIES, THREADS_ARRAY_OUTPUT } from '@/tools/zep/types'
+
+export const zepGetThreadsTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_get_threads',
+  name: 'Get Threads',
+  description: 'List all conversation threads',
+  version: '1.0.0',
+
+  params: {
+    pageSize: {
+      type: 'number',
+      required: false,
+      default: 10,
+      visibility: 'user-or-llm',
+      description: 'Number of threads to retrieve per page (e.g., 10, 25, 50)',
+    },
+    pageNumber: {
+      type: 'number',
+      required: false,
+      default: 1,
+      visibility: 'user-or-llm',
+      description: 'Page number for pagination (e.g., 1, 2, 3)',
+    },
+    orderBy: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description: 'Field to order results by (created_at, updated_at, user_id, thread_id)',
+    },
+    asc: {
+      type: 'boolean',
+      required: false,
+      default: false,
+      visibility: 'user-only',
+      description: 'Order direction: true for ascending, false for descending',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const queryParams = new URLSearchParams()
+      queryParams.append('page_size', String(Number(params.pageSize || 10)))
+      queryParams.append('page_number', String(Number(params.pageNumber || 1)))
+      if (params.orderBy) queryParams.append('order_by', params.orderBy)
+      if (params.asc !== undefined) queryParams.append('asc', String(params.asc))
+      return `https://api.getzep.com/api/v2/threads?${queryParams.toString()}`
+    },
+    method: 'GET',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response) => {
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const data = await response.json()
+
+    return {
+      success: true,
+      output: {
+        threads: data.threads || [],
+        responseCount: data.response_count,
+        totalCount: data.total_count,
+      },
+    }
+  },
+
+  outputs: {
+    threads: THREADS_ARRAY_OUTPUT,
+    responseCount: PAGINATION_OUTPUT_PROPERTIES.responseCount,
+    totalCount: PAGINATION_OUTPUT_PROPERTIES.totalCount,
+  },
+}

apps/sim/tools/zep/get_user.ts

@@ -0,0 +1,68 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+import { USER_OUTPUT_PROPERTIES } from '@/tools/zep/types'
+
+export const zepGetUserTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_get_user',
+  name: 'Get User',
+  description: 'Retrieve user information from Zep',
+  version: '1.0.0',
+
+  params: {
+    userId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'User ID to retrieve (e.g., "user_123")',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: (params) => `https://api.getzep.com/api/v2/users/${params.userId}`,
+    method: 'GET',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response) => {
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const data = await response.json()
+
+    return {
+      success: true,
+      output: {
+        userId: data.user_id,
+        email: data.email,
+        firstName: data.first_name,
+        lastName: data.last_name,
+        uuid: data.uuid,
+        createdAt: data.created_at,
+        updatedAt: data.updated_at,
+        metadata: data.metadata,
+      },
+    }
+  },
+
+  outputs: {
+    userId: USER_OUTPUT_PROPERTIES.userId,
+    email: USER_OUTPUT_PROPERTIES.email,
+    firstName: USER_OUTPUT_PROPERTIES.firstName,
+    lastName: USER_OUTPUT_PROPERTIES.lastName,
+    uuid: USER_OUTPUT_PROPERTIES.uuid,
+    createdAt: USER_OUTPUT_PROPERTIES.createdAt,
+    updatedAt: USER_OUTPUT_PROPERTIES.updatedAt,
+    metadata: USER_OUTPUT_PROPERTIES.metadata,
+  },
+}

apps/sim/tools/zep/get_user_threads.ts

@@ -0,0 +1,67 @@
+import type { ToolConfig } from '@/tools/types'
+import type { ZepResponse } from '@/tools/zep/types'
+import { PAGINATION_OUTPUT_PROPERTIES, THREADS_ARRAY_OUTPUT } from '@/tools/zep/types'
+
+export const zepGetUserThreadsTool: ToolConfig<any, ZepResponse> = {
+  id: 'zep_get_user_threads',
+  name: 'Get User Threads',
+  description: 'List all conversation threads for a specific user',
+  version: '1.0.0',
+
+  params: {
+    userId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'User ID to get threads for (e.g., "user_123")',
+    },
+    limit: {
+      type: 'number',
+      required: false,
+      default: 10,
+      visibility: 'user-or-llm',
+      description: 'Maximum number of threads to return (e.g., 10, 25, 50)',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Your Zep API key',
+    },
+  },
+
+  request: {
+    url: (params) => {
+      const limit = Number(params.limit || 10)
+      return `https://api.getzep.com/api/v2/users/${params.userId}/threads?limit=${limit}`
+    },
+    method: 'GET',
+    headers: (params) => ({
+      Authorization: `Api-Key ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response) => {
+    if (!response.ok) {
+      const error = await response.text()
+      throw new Error(`Zep API error (${response.status}): ${error || response.statusText}`)
+    }
+
+    const data = await response.json()
+    const threads = data.threads || data || []
+
+    return {
+      success: true,
+      output: {
+        threads,
+        totalCount: threads.length,
+      },
+    }
+  },
+
+  outputs: {
+    threads: THREADS_ARRAY_OUTPUT,
+    totalCount: PAGINATION_OUTPUT_PROPERTIES.totalCount,
+  },
+}

apps/sim/tools/zep/index.ts

@@ -0,0 +1,21 @@
+import { zepAddMessagesTool } from '@/tools/zep/add_messages'
+import { zepAddUserTool } from '@/tools/zep/add_user'
+import { zepCreateThreadTool } from '@/tools/zep/create_thread'
+import { zepDeleteThreadTool } from '@/tools/zep/delete_thread'
+import { zepGetContextTool } from '@/tools/zep/get_context'
+import { zepGetMessagesTool } from '@/tools/zep/get_messages'
+import { zepGetThreadsTool } from '@/tools/zep/get_threads'
+import { zepGetUserTool } from '@/tools/zep/get_user'
+import { zepGetUserThreadsTool } from '@/tools/zep/get_user_threads'
+
+export {
+  zepCreateThreadTool,
+  zepGetThreadsTool,
+  zepDeleteThreadTool,
+  zepGetContextTool,
+  zepGetMessagesTool,
+  zepAddMessagesTool,
+  zepAddUserTool,
+  zepGetUserTool,
+  zepGetUserThreadsTool,
+}

apps/sim/tools/zep/types.ts

@@ -0,0 +1,211 @@
+import type { OutputProperty, ToolResponse } from '@/tools/types'
+
+/**
+ * Shared output property definitions for Zep API responses.
+ * Based on Zep Cloud API v2 documentation.
+ * @see https://help.getzep.com/sdk-reference/thread/list-all
+ * @see https://help.getzep.com/sdk-reference/user/add
+ * @see https://help.getzep.com/adding-messages
+ */
+
+/**
+ * Output definition for thread objects returned by Zep API.
+ * @see https://help.getzep.com/threads
+ * @see https://help.getzep.com/sdk-reference/thread/list-all
+ */
+export const THREAD_OUTPUT_PROPERTIES = {
+  threadId: { type: 'string', description: 'Thread identifier' },
+  userId: { type: 'string', description: 'Associated user ID' },
+  uuid: { type: 'string', description: 'Internal UUID' },
+  createdAt: { type: 'string', description: 'Creation timestamp (ISO 8601)' },
+  updatedAt: { type: 'string', description: 'Last update timestamp (ISO 8601)' },
+  projectUuid: { type: 'string', description: 'Project UUID' },
+  metadata: {
+    type: 'object',
+    description: 'Custom metadata (dynamic key-value pairs)',
+    optional: true,
+  },
+} as const satisfies Record<string, OutputProperty>
+
+/**
+ * Complete thread object output definition.
+ */
+export const THREAD_OUTPUT: OutputProperty = {
+  type: 'object',
+  description: 'Zep thread object',
+  properties: THREAD_OUTPUT_PROPERTIES,
+}
+
+/**
+ * Threads array output definition for list endpoints.
+ * @see https://help.getzep.com/sdk-reference/thread/list-all
+ */
+export const THREADS_ARRAY_OUTPUT: OutputProperty = {
+  type: 'array',
+  description: 'Array of thread objects',
+  items: {
+    type: 'object',
+    properties: THREAD_OUTPUT_PROPERTIES,
+  },
+}
+
+/**
+ * Output definition for user objects returned by Zep API.
+ * @see https://help.getzep.com/users
+ * @see https://help.getzep.com/sdk-reference/user/add
+ * @see https://help.getzep.com/sdk-reference/user/get
+ */
+export const USER_OUTPUT_PROPERTIES = {
+  userId: { type: 'string', description: 'User identifier' },
+  email: { type: 'string', description: 'User email address', optional: true },
+  firstName: { type: 'string', description: 'User first name', optional: true },
+  lastName: { type: 'string', description: 'User last name', optional: true },
+  uuid: { type: 'string', description: 'Internal UUID' },
+  createdAt: { type: 'string', description: 'Creation timestamp (ISO 8601)' },
+  updatedAt: { type: 'string', description: 'Last update timestamp (ISO 8601)', optional: true },
+  metadata: {
+    type: 'object',
+    description: 'User metadata (dynamic key-value pairs)',
+    optional: true,
+  },
+} as const satisfies Record<string, OutputProperty>
+
+/**
+ * Complete user object output definition.
+ */
+export const USER_OUTPUT: OutputProperty = {
+  type: 'object',
+  description: 'Zep user object',
+  properties: USER_OUTPUT_PROPERTIES,
+}
+
+/**
+ * Output definition for message objects returned by Zep API.
+ * @see https://help.getzep.com/adding-messages
+ * @see https://help.getzep.com/sdk-reference/thread/message/update
+ */
+export const MESSAGE_OUTPUT_PROPERTIES = {
+  uuid: { type: 'string', description: 'Message UUID' },
+  role: { type: 'string', description: 'Message role (user, assistant, system, tool)' },
+  roleType: { type: 'string', description: 'Role type (AI, human, tool)', optional: true },
+  content: { type: 'string', description: 'Message content' },
+  name: { type: 'string', description: 'Sender name', optional: true },
+  createdAt: { type: 'string', description: 'Timestamp (RFC3339 format)' },
+  metadata: {
+    type: 'object',
+    description: 'Message metadata (dynamic key-value pairs)',
+    optional: true,
+  },
+  processed: { type: 'boolean', description: 'Whether message has been processed', optional: true },
+} as const satisfies Record<string, OutputProperty>
+
+/**
+ * Complete message object output definition.
+ */
+export const MESSAGE_OUTPUT: OutputProperty = {
+  type: 'object',
+  description: 'Zep message object',
+  properties: MESSAGE_OUTPUT_PROPERTIES,
+}
+
+/**
+ * Messages array output definition for list endpoints.
+ * @see https://help.getzep.com/sdk-reference/thread/message/get-messages
+ */
+export const MESSAGES_ARRAY_OUTPUT: OutputProperty = {
+  type: 'array',
+  description: 'Array of message objects',
+  items: {
+    type: 'object',
+    properties: MESSAGE_OUTPUT_PROPERTIES,
+  },
+}
+
+/**
+ * Pagination output properties for list endpoints.
+ * @see https://help.getzep.com/sdk-reference/thread/list-all
+ */
+export const PAGINATION_OUTPUT_PROPERTIES = {
+  responseCount: {
+    type: 'number',
+    description: 'Number of items in this response',
+    optional: true,
+  },
+  totalCount: { type: 'number', description: 'Total number of items available', optional: true },
+  rowCount: { type: 'number', description: 'Number of rows returned', optional: true },
+} as const satisfies Record<string, OutputProperty>
+
+// Zep v3 Response Type
+export interface ZepResponse extends ToolResponse {
+  output: {
+    // Thread operations
+    threadId?: string
+    uuid?: string
+    createdAt?: string
+    updatedAt?: string
+    projectUuid?: string
+    threads?: ZepThread[]
+    deleted?: boolean
+
+    // Message operations
+    messages?: ZepMessage[]
+    messageIds?: string[]
+    added?: boolean
+
+    // Context operations
+    context?: string
+
+    // User operations
+    userId?: string
+    email?: string
+    firstName?: string
+    lastName?: string
+    metadata?: Record<string, unknown>
+
+    // Counts
+    totalCount?: number
+    responseCount?: number
+    rowCount?: number
+  }
+}
+
+/**
+ * Thread object interface for type safety.
+ */
+interface ZepThread {
+  threadId: string
+  userId: string
+  uuid?: string
+  createdAt?: string
+  updatedAt?: string
+  projectUuid?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * User object interface for type safety.
+ */
+interface ZepUser {
+  userId: string
+  email?: string
+  firstName?: string
+  lastName?: string
+  uuid?: string
+  createdAt?: string
+  updatedAt?: string
+  metadata?: Record<string, unknown>
+}
+
+/**
+ * Message object interface for type safety.
+ */
+interface ZepMessage {
+  uuid: string
+  role: string
+  roleType?: string
+  content: string
+  name?: string
+  createdAt: string
+  metadata?: Record<string, unknown>
+  processed?: boolean
+}