Custom Instructions

What are Custom Instructions?

Custom instructions are natural language guidelines that let you define exactly what Mem0 should include or exclude when creating memories from conversations. This gives you precise control over what information is extracted, acting as smart filters so your AI application only remembers what matters for your use case.

# Simple example: Health app focusing on wellness
prompt = """
Extract only health and wellness information:
- Symptoms, medications, and treatments
- Exercise routines and dietary habits
- Doctor appointments and health goals

Exclude: Personal identifiers, financial data
"""

client.project.update(custom_instructions=prompt)

// Simple example: Health app focusing on wellness
const prompt = `
Extract only health and wellness information:
- Symptoms, medications, and treatments
- Exercise routines and dietary habits
- Doctor appointments and health goals

Exclude: Personal identifiers, financial data
`;

await client.project.update({ customInstructions: prompt });

Why Use Custom Instructions?

Focus on What Matters: Only capture information relevant to your application
Maintain Privacy: Explicitly exclude sensitive data like passwords or personal identifiers
Ensure Consistency: All memories follow the same extraction rules across your project
Improve Quality: Filter out noise and irrelevant conversations

How to Set Custom Instructions

Basic Setup

# Set instructions for your project
client.project.update(custom_instructions="Your guidelines here...")

# Retrieve current instructions
response = client.project.get(fields=["custom_instructions"])
print(response["custom_instructions"])

// Set instructions for your project
await client.project.update({ customInstructions: "Your guidelines here..." });

// Retrieve current instructions
const response = await client.project.get({ fields: ["customInstructions"] });
console.log(response.customInstructions);

project.get() always returns the full project object. The fields parameter is accepted but has no filtering effect server-side, so response["custom_instructions"] above is a key on the full response, not a pre-filtered payload.

Best Practice Template

Structure your instructions using this proven template:

Your Task: [Brief description of what to extract]

Information to Extract:
1. [Category 1]:
   - [Specific details]
   - [What to look for]

2. [Category 2]:
   - [Specific details]
   - [What to look for]

Guidelines:
- [Processing rules]
- [Quality requirements]

Exclude:
- [Sensitive data to avoid]
- [Irrelevant information]

Agent Custom Instructions

custom_instructions applies to every memory your project extracts, no matter whose it is. But what is worth remembering about an agent is rarely what is worth remembering about a user: an agent’s useful memories are things like which tools fail, which retry strategies work, and how a given environment behaves, not personal preferences. agent_custom_instructions is an optional second set of extraction rules that applies only to agent-scoped memories. Available from Python SDK v2.0.17 and TypeScript SDK v3.1.5. Upgrade first if you are on an earlier release. Set it on the project alongside custom_instructions:

client.project.update(
    custom_instructions="Extract the user's preferences, goals, and constraints.",
    agent_custom_instructions=(
        "Extract operational lessons for the agent:\n"
        "- Tools that failed and the error returned\n"
        "- Retry or fallback strategies that worked\n"
        "- Environment quirks worth recalling on the next run\n\n"
        "Exclude: user preferences, personal details."
    ),
)

await client.updateProject({
  customInstructions: "Extract the user's preferences, goals, and constraints.",
  agentCustomInstructions: `Extract operational lessons for the agent:
- Tools that failed and the error returned
- Retry or fallback strategies that worked
- Environment quirks worth recalling on the next run

Exclude: user preferences, personal details.`,
});

Which instructions apply

Which set governs an add() call depends on the entity IDs you pass with it:

The add call passes	Instructions applied
`user_id` only	`custom_instructions`
`agent_id` only	`agent_custom_instructions`
`user_id` and `agent_id`	`agent_custom_instructions` govern the memories attributed to the assistant; `custom_instructions` govern the rest

agent_custom_instructions is unset by default. While it is unset, custom_instructions applies to every memory, so projects that don’t set it behave exactly as they did before.

Overriding for a single call

Both fields are also accepted per request, overriding the project setting for that add() only:

client.add(
    messages,
    filters={"agent_id": "support-agent"},
    agent_custom_instructions="Only remember which tools errored and why.",
)

await client.add(messages, {
  agentId: "support-agent",
  agentCustomInstructions: "Only remember which tools errored and why.",
});

Reading and clearing

# Read the current value
response = client.project.get(fields=["agent_custom_instructions"])
print(response["agent_custom_instructions"])

# Clear it; agent memories fall back to custom_instructions
client.project.update(agent_custom_instructions="")

// Read the current value
const response = await client.getProject({
  fields: ["agentCustomInstructions"],
});
console.log(response.agentCustomInstructions);

// Clear it; agent memories fall back to customInstructions
await client.updateProject({ agentCustomInstructions: "" });

Real-World Examples

E-commerce Customer Support
Personalized Learning Platform
AI Financial Advisor

instructions = """
Extract customer service information for better support:

1. Product Issues:
   - Product names, SKUs, defects
   - Return/exchange requests
   - Quality complaints

2. Customer Preferences:
   - Preferred brands, sizes, colors
   - Shopping frequency and habits
   - Price sensitivity

3. Service Experience:
   - Satisfaction with support
   - Resolution time expectations
   - Communication preferences

Exclude: Payment card numbers, passwords, personal identifiers.
"""

client.project.update(custom_instructions=instructions)

const instructions = `
Extract customer service information for better support:

1. Product Issues:
   - Product names, SKUs, defects
   - Return/exchange requests
   - Quality complaints

2. Customer Preferences:
   - Preferred brands, sizes, colors
   - Shopping frequency and habits
   - Price sensitivity

3. Service Experience:
   - Satisfaction with support
   - Resolution time expectations
   - Communication preferences

Exclude: Payment card numbers, passwords, personal identifiers.
`;

await client.project.update({ customInstructions: instructions });

education_prompt = """
Extract learning-related information for personalized education:

1. Learning Progress:
   - Course completions and current modules
   - Skills acquired and improvement areas
   - Learning goals and objectives

2. Student Preferences:
   - Learning styles (visual, audio, hands-on)
   - Time availability and scheduling
   - Subject interests and career goals

3. Performance Data:
   - Assignment feedback and patterns
   - Areas of struggle or strength
   - Study habits and engagement

Exclude: Specific grades, personal identifiers, financial information.
"""

client.project.update(custom_instructions=education_prompt)

const educationPrompt = `
Extract learning-related information for personalized education:

1. Learning Progress:
   - Course completions and current modules
   - Skills acquired and improvement areas
   - Learning goals and objectives

2. Student Preferences:
   - Learning styles (visual, audio, hands-on)
   - Time availability and scheduling
   - Subject interests and career goals

3. Performance Data:
   - Assignment feedback and patterns
   - Areas of struggle or strength
   - Study habits and engagement

Exclude: Specific grades, personal identifiers, financial information.
`;

await client.project.update({ customInstructions: educationPrompt });

finance_prompt = """
Extract financial planning information for advisory services:

1. Financial Goals:
   - Retirement and investment objectives
   - Risk tolerance and preferences
   - Short-term and long-term goals

2. Life Events:
   - Career and income changes
   - Family changes (marriage, children)
   - Major planned purchases

3. Investment Interests:
   - Asset allocation preferences
   - ESG or ethical investment interests
   - Previous investment experience

Exclude: Account numbers, SSNs, passwords, specific financial amounts.
"""

client.project.update(custom_instructions=finance_prompt)

const financePrompt = `
Extract financial planning information for advisory services:

1. Financial Goals:
   - Retirement and investment objectives
   - Risk tolerance and preferences
   - Short-term and long-term goals

2. Life Events:
   - Career and income changes
   - Family changes (marriage, children)
   - Major planned purchases

3. Investment Interests:
   - Asset allocation preferences
   - ESG or ethical investment interests
   - Previous investment experience

Exclude: Account numbers, SSNs, passwords, specific financial amounts.
`;

await client.project.update({ customInstructions: financePrompt });

Advanced Techniques

Conditional Processing

Handle different conversation types with conditional logic:

advanced_prompt = """
Extract information based on conversation context:

IF customer support conversation:
- Issue type, severity, resolution status
- Customer satisfaction indicators

IF sales conversation:
- Product interests, budget range
- Decision timeline and influencers

IF onboarding conversation:
- User experience level
- Feature interests and priorities

Always exclude personal identifiers and maintain professional context.
"""

client.project.update(custom_instructions=advanced_prompt)

Testing Your Instructions

Always test your custom instructions with real message examples:

# Test with sample messages
messages = [
    {"role": "user", "content": "I'm having billing issues with my subscription"},
    {"role": "assistant", "content": "I can help with that. What's the specific problem?"},
    {"role": "user", "content": "I'm being charged twice each month"}
]

# Add the messages and check extracted memories
result = client.add(messages, user_id="test_user")
memories = client.get_all(filters={"AND": [{"user_id": "test_user"}]})

# Review if the right information was extracted
for memory in memories:
    print(f"Extracted: {memory['memory']}")

Best Practices

✅ Do

Be specific about what information to extract
Use clear categories to organize your instructions
Test with real conversations before deploying
Explicitly state exclusions for privacy and compliance
Start simple and iterate based on results

❌ Don’t

Make instructions too long or complex
Create conflicting rules within your guidelines
Be overly restrictive (balance specificity with flexibility)
Forget to exclude sensitive information
Skip testing with diverse conversation examples

Common Issues and Solutions

Issue	Solution
Instructions too long	Break into focused categories, keep concise
Missing important data	Add specific examples of what to capture
Capturing irrelevant info	Strengthen exclusion rules and be more specific
Inconsistent results	Clarify guidelines and test with more examples

Getting Started

Core Concepts

Features

Support

Migration

Custom Instructions

What are Custom Instructions?

Why Use Custom Instructions?

How to Set Custom Instructions

Basic Setup

Best Practice Template

Agent Custom Instructions

Which instructions apply

Overriding for a single call

Reading and clearing

Real-World Examples

Advanced Techniques

Conditional Processing

Testing Your Instructions

Best Practices

✅ Do

❌ Don’t

Common Issues and Solutions

​What are Custom Instructions?

​Why Use Custom Instructions?

​How to Set Custom Instructions

​Basic Setup

​Best Practice Template

​Agent Custom Instructions

​Which instructions apply

​Overriding for a single call

​Reading and clearing

​Real-World Examples

​Advanced Techniques

​Conditional Processing

​Testing Your Instructions

​Best Practices

​✅ Do

​❌ Don’t

​Common Issues and Solutions

What are Custom Instructions?

Why Use Custom Instructions?

How to Set Custom Instructions

Basic Setup

Best Practice Template

Agent Custom Instructions

Which instructions apply

Overriding for a single call

Reading and clearing

Real-World Examples

Advanced Techniques

Conditional Processing

Testing Your Instructions

Best Practices

✅ Do

❌ Don’t

Common Issues and Solutions