mem0ai--mem0/docs/open-source/features/custom-instructions.mdx

---
title: Custom Instructions
description: Tailor fact extraction so Mem0 stores only the details you care about.
icon: "wand-magic-sparkles"
---

Custom instructions let you decide exactly which facts Mem0 records from a conversation. Define a focused prompt, give a few examples, and Mem0 will add only the memories that match your use case.

<Info>
  **You'll use this when...**
  - A project needs domain-specific facts (order numbers, customer info) without storing casual chatter.
  - You already have a clear schema for memories and want the LLM to follow it.
  - You must prevent irrelevant details from entering long-term storage.
</Info>

<Warning>
  Prompts that are too broad cause unrelated facts to slip through. Keep instructions tight and test them with real transcripts.
</Warning>

<Note>
  The `custom_fact_extraction_prompt` parameter has been renamed to `custom_instructions`. If you are upgrading from an older version, update your configuration accordingly.
</Note>

---

## Feature anatomy

- **Prompt instructions:** Describe which entities or phrases to keep. Specific guidance keeps the extractor focused.
- **Few-shot examples:** Show positive and negative cases so the model copies the right format.
- **Structured output:** Responses return JSON with a `facts` array that Mem0 converts into individual memories.
- **LLM configuration:** `custom_instructions` (Python) or `customInstructions` (TypeScript) lives alongside your model settings.

<AccordionGroup>
  <Accordion title="Prompt blueprint">
    1. State the allowed fact types.
    2. Include short examples that mirror production messages.
    3. Show both empty (`[]`) and populated outputs.
    4. Remind the model to return JSON with a `facts` key only.
  </Accordion>
</AccordionGroup>

---

## Configure it

### Write the custom prompt

<CodeGroup>
```python Python
custom_instructions = """
Please only extract entities containing customer support information, order details, and user information.
Here are some few shot examples:

Input: Hi.
Output: {"facts" : []}

Input: The weather is nice today.
Output: {"facts" : []}

Input: My order #12345 hasn't arrived yet.
Output: {"facts" : ["Order #12345 not received"]}

Input: I'm John Doe, and I'd like to return the shoes I bought last week.
Output: {"facts" : ["Customer name: John Doe", "Wants to return shoes", "Purchase made last week"]}

Input: I ordered a red shirt, size medium, but received a blue one instead.
Output: {"facts" : ["Ordered red shirt, size medium", "Received blue shirt instead"]}

Return the facts and customer information in a json format as shown above.
"""
```

```ts TypeScript
const customInstructions = `
Please only extract entities containing customer support information, order details, and user information.
Here are some few shot examples:

Input: Hi.
Output: {"facts" : []}

Input: The weather is nice today.
Output: {"facts" : []}

Input: My order #12345 hasn't arrived yet.
Output: {"facts" : ["Order #12345 not received"]}

Input: I am John Doe, and I would like to return the shoes I bought last week.
Output: {"facts" : ["Customer name: John Doe", "Wants to return shoes", "Purchase made last week"]}

Input: I ordered a red shirt, size medium, but received a blue one instead.
Output: {"facts" : ["Ordered red shirt, size medium", "Received blue shirt instead"]}

Return the facts and customer information in a json format as shown above.
`;
```
</CodeGroup>

<Tip>
  Keep example pairs short and mirror the capitalization, punctuation, and tone you see in real user messages.
</Tip>

### Load the prompt in configuration

<CodeGroup>
```python Python
from mem0 import Memory

config = {
    "llm": {
        "provider": "openai",
        "config": {
            "model": "gpt-5-mini",
            "temperature": 0.2,
            "max_tokens": 2000,
        }
    },
    "custom_instructions": custom_instructions,
}

m = Memory.from_config(config)
```

```ts TypeScript
import { Memory } from "mem0ai/oss";

const config = {
  llm: {
    provider: "openai",
    config: {
      apiKey: process.env.OPENAI_API_KEY ?? "",
      model: "gpt-4-turbo-preview",
      temperature: 0.2,
      maxTokens: 1500,
    },
  },
  customInstructions: customInstructions,
};

const memory = new Memory(config);
```
</CodeGroup>

<Info icon="check">
  After initialization, run a quick `add` call with a known example and confirm the response splits into separate facts.
</Info>

---

## See it in action

### Example: Order support memory

<CodeGroup>
```python Python
m.add("Yesterday, I ordered a laptop, the order id is 12345", user_id="alice")
```

```ts TypeScript
await memory.add("Yesterday, I ordered a laptop, the order id is 12345", { userId: "user123" });
```

```json Output
{
  "results": [
    {"memory": "Ordered a laptop", "event": "ADD"},
    {"memory": "Order ID: 12345", "event": "ADD"},
    {"memory": "Order placed yesterday", "event": "ADD"}
  ]
}
```
</CodeGroup>

<Info icon="check">
  The output contains only the facts described in your prompt, each stored as a separate memory entry.
</Info>

### Example: Irrelevant message filtered out

<CodeGroup>
```python Python
m.add("I like going to hikes", user_id="alice")
```

```ts TypeScript
await memory.add("I like going to hikes", { userId: "user123" });
```

```json Output
{
  "results": []
}
```
</CodeGroup>

<Tip>
  Empty `results` show the prompt successfully ignored content outside your target domain.
</Tip>

---

## Verify the feature is working

- Log every call during rollout and confirm the `facts` array matches your schema.
- Check that unrelated messages return an empty `results` array.
- Run regression samples whenever you edit the prompt to ensure previously accepted facts still pass.

---

## Best practices

1. **Be precise:** Call out the exact categories or fields you want to capture.
2. **Show negative cases:** Include examples that should produce `[]` so the model learns to skip them.
3. **Keep JSON strict:** Avoid extra keys; only return `facts` to simplify downstream parsing.
4. **Version prompts:** Track prompt changes with a version number so you can roll back quickly.
5. **Review outputs regularly:** Spot-check stored memories to catch drift early.

---

<CardGroup cols={2}>
  <Card title="Review Add Operations" icon="list" href="/core-concepts/memory-operations/add">
    Refresh how Mem0 stores memories and how prompts influence fact creation.
  </Card>
  <Card title="Automate Support Triage" icon="inbox" href="/cookbooks/operations/support-inbox">
    Apply custom extraction to route customer requests in a full workflow.
  </Card>
</CardGroup>