JDSS/mem0
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(sdk, docs): expose agent_custom_instructions for agent-scoped extraction (#6809)

Browse Source
This commit is contained in:
Saket Aryan
2026-08-05 22:12:10 +05:30
committed by GitHub
parent 3f717e5459
commit 12c47f5249
14 changed files with 375 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-reference/organizations-projects.mdx
+6
View File
@@ -95,6 +95,12 @@ client.project.update(
custom_instructions="..."
)
# Separate extraction instructions for agent-scoped memories
# (see /platform/features/custom-instructions)
client.project.update(
agent_custom_instructions="..."
)
# Use the input language for memory storage and retrieval
client.project.update(multilingual=True)
docs/changelog/sdk.mdx
+14
View File
@@ -7,6 +7,13 @@ mode: "wide"
<Tabs>
<Tab title="Python">
<Update label="2026-08-05" description="v2.0.17">
**New Features:**
- **Client:** Add `agent_custom_instructions` to `project.update()`/`update_project()` (sync and async) and to the `ProjectUpdateOptions` and `AddMemoryOptions` typed models. It sets a second extraction instruction set that applies only to agent-scoped memories: an add passing `agent_id` without `user_id` uses it, one passing both splits by attribution, and while it is unset `custom_instructions` continues to apply to every memory ([#6809](https://github.com/mem0ai/mem0/pull/6809))
</Update>
<Update label="2026-08-04" description="v2.0.16">
**New Features:**
@@ -1189,6 +1196,13 @@ See the [OSS v2 to v3 migration guide](https://docs.mem0.ai/migration/oss-v2-to-
<Tab title="TypeScript">
<Update label="2026-08-05" description="v3.1.5">
**New Features:**
- **Client:** Add `agentCustomInstructions` to `PromptUpdatePayload`, `AddMemoryOptions`, and `ProjectResponse`. It sets a second extraction instruction set that applies only to agent-scoped memories: an add passing `agentId` without `userId` uses it, one passing both splits by attribution, and while it is unset `customInstructions` continues to apply to every memory ([#6809](https://github.com/mem0ai/mem0/pull/6809))
</Update>
<Update label="2026-08-04" description="v3.1.4">
**New Features:**
docs/openapi.json
+15
View File
@@ -2784,6 +2784,10 @@
"type": "string",
"description": "Project-level instructions that guide extraction for this call."
},
"agent_custom_instructions": {
"type": "string",
"description": "Extraction instructions for agent-scoped memories, overriding the project-level setting for this call. Applied when `agent_id` is sent without `user_id`; when both are sent it governs the assistant-attributed memories while `custom_instructions` governs the rest."
},
"custom_categories": {
"type": "array",
"description": "Category catalog for this call. Replaces the project-level list rather than merging with it. Omit to fall back to the project list, then the default catalog.",
@@ -5805,6 +5809,11 @@
},
"description": "Custom instructions for memory processing in this project"
},
"agent_custom_instructions": {
"type": "string",
"nullable": true,
"description": "Extraction instructions for agent-scoped memories. Falls back to `custom_instructions` when unset. Send an empty string to clear it."
},
"custom_categories": {
"type": "array",
"items": {
@@ -7431,6 +7440,12 @@
"type": "string",
"nullable": true
},
"agent_custom_instructions": {
"description": "Extraction instructions that apply only to agent-scoped memories. Used when `agent_id` is sent without `user_id`; when both are sent it governs the assistant-attributed memories while `custom_instructions` governs the rest. Falls back to `custom_instructions` when unset.",
"title": "Agent custom instructions",
"type": "string",
"nullable": true
},
"immutable": {
"description": "Whether the memory is immutable.",
"title": "Immutable",
docs/platform/features/custom-instructions.mdx
+94
View File
@@ -95,6 +95,100 @@ Exclude:
- [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`:
<CodeGroup>
```python Python
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."
),
)
```
```javascript JavaScript
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.`,
});
```
</CodeGroup>
### 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:
<CodeGroup>
```python Python
client.add(
messages,
filters={"agent_id": "support-agent"},
agent_custom_instructions="Only remember which tools errored and why.",
)
```
```javascript JavaScript
await client.add(messages, {
agentId: "support-agent",
agentCustomInstructions: "Only remember which tools errored and why.",
});
```
</CodeGroup>
### Reading and clearing
<CodeGroup>
```python Python
# 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="")
```
```javascript JavaScript
// 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: "" });
```
</CodeGroup>
## Real-World Examples
<Tabs>