Skip to content

PARAMETER_GUIDE.md

Latest commit

 

History

History
138 lines (111 loc) · 4.6 KB

PARAMETER_GUIDE.md

File metadata and controls

138 lines (111 loc) · 4.6 KB

Mem0 MCP Parameter Guide

This guide explains the different parameters available in the Mem0 MCP server and how they relate to Mem0's organization structure.

Parameter Types

User Identification

  • userId: Required. Identifies the user whose memories to store/search.
    • Fallback: DEFAULT_USER_ID environment variable
    • Example: "user123"

Session/Conversation Tracking

  • sessionId: Optional. Groups memories by conversation/session.
    • Maps to run_id in Mem0 API
    • Example: "conversation_abc123"

Agent/Assistant Identification

  • agentId: Optional. Identifies which LLM/agent is making the request.
    • Fallback: DEFAULT_AGENT_ID environment variable
    • Example: "Claude", "GPT-4"
    • Note: This should appear as "agent_id" in search results, not "actor_id"

Project/Organization Structure

appId (Legacy Parameter)

  • Optional application identifier
  • Fallback: DEFAULT_APP_ID environment variable
  • Creates an "app" entry in Mem0 dashboard
  • Example: "my-chatbot-v1"

projectId (Recommended for Pro Plans)

  • Optional project identifier for Mem0 Pro plan project organization
  • Fallback: DEFAULT_PROJECT_ID environment variable
  • Should use format: proj_ABC123...
  • Purpose: Organizes memories within specific project buckets in Mem0 dashboard
  • Example: "proj_ABC123456789"

orgId (Organization Level)

  • Optional organization identifier for organization-level management
  • Fallback: DEFAULT_ORG_ID environment variable
  • Purpose: Manages memories at the organization level
  • Example: "org_XYZ789012345"

Common Issues & Solutions

Issue: agentId shows as "actor_id": null instead of "agent_id": "Claude"

Possible Causes:

  1. Parameter not being passed correctly to API
  2. API response format differences between SDK and direct REST calls
  3. Mem0 API version differences

Debug Steps:

  1. Check the console logs for parameter resolution details
  2. Verify the agentId parameter is being passed
  3. Try using both SDK and direct REST API methods

Issue: projectId doesn't organize memories in correct project bucket

Solution:

  • Ensure you're using the correct proj_ format ID from your Mem0 dashboard
  • The projectId should match exactly what appears in your Mem0 Pro account
  • appId and projectId serve different purposes - use projectId for project organization

Issue: "Missing required argument: userId" even with DEFAULT_USER_ID set

Solution:

  • Verify the DEFAULT_USER_ID environment variable is properly set
  • Check that the environment variable is loaded before the MCP server starts
  • Explicitly pass userId parameter if environment variable approach isn't working

Environment Variables

Set these in your environment to provide fallback values:

# Required (one of these approaches)
DEFAULT_USER_ID="your-default-user-id"

# Optional fallbacks
DEFAULT_AGENT_ID="Claude"  # or "GPT-4", etc.
DEFAULT_APP_ID="my-app"
DEFAULT_PROJECT_ID="proj_ABC123456789"  # From your Mem0 dashboard
DEFAULT_ORG_ID="org_XYZ789012345"      # From your Mem0 dashboard

API Parameter Mapping

The MCP server automatically converts camelCase parameters to snake_case for the Mem0 API:

MCP Parameter Mem0 API Parameter Purpose
userId user_id User identification
sessionId run_id Session/conversation tracking
agentId agent_id Agent/LLM identification
appId app_id Application identification (legacy)
projectId project_id Project organization (Pro plans)
orgId org_id Organization management

Recommended Usage Patterns

For Individual Users

{
  "content": "User prefers dark mode",
  "userId": "user123",
  "agentId": "Claude"
}

For Project Organization (Pro Plans)

{
  "content": "Customer feedback about product feature",
  "userId": "user123", 
  "projectId": "proj_ABC123456789",
  "agentId": "Claude",
  "metadata": {
    "category": "feedback",
    "product": "main-app"
  }
}

For Organization Management

{
  "content": "Company policy update",
  "userId": "admin123",
  "orgId": "org_XYZ789012345", 
  "projectId": "proj_ABC123456789",
  "agentId": "Claude"
}

Debugging Tips

  1. Enable Debug Logging: Check console output for parameter resolution details
  2. Test Parameters Individually: Try each parameter one at a time to isolate issues
  3. Verify API Responses: Look for the expected field names in search results
  4. Check Mem0 Dashboard: Verify that memories appear in the expected project/organization buckets