Search Documentation
Search across all documentation pages
write_memory
Create or upsert a durable memory entry. Supports multiple memory types, importance/confidence scoring, entity extraction, and automatic semantic deduplication.
Memory types: fact (durable knowledge, importance 3-5), skill (procedures/how-tos, 3-5), preference (user style/choices, 2-4), constraint (hard rules/limits, 4-5), task (active work items, 2-4), episodic (session summaries, 1-3), correction (superseded knowledge — always set supersededById, 3-5).
Importance scale: 5=critical, 4=important, 3=standard (default), 2=supplementary, 1=low-value. Confidence scale: 5=verified, 4=observed multiple times, 3=reasonable inference (default), 2=uncertain, 1=speculative.
Server dedup (dedup: true): >92% similarity = skip, >80% = supersede old, <80% = create new.
Parameters#
| Parameter | Type | Required | Description |
|---|---|---|---|
| content | string (1-1,000,000 chars) | required | Memory content in plain text |
| memoryType | string | optional | Type: fact, skill, preference, constraint, task, episodic, correction |
| summary | string (max 500) | optional | Optional short summary |
| vaultId | string (UUID) | optional | Vault/project scope. Required unless defaultVaultId is configured. |
| importance | integer (1-5) | optional | Importance from 1 to 5 |
| confidence | integer (1-5) | optional | Confidence from 1 to 5 |
| agentId | string | optional | Agent identifier |
| agentType | string | optional | Agent type |
| modelId | string | optional | Model used to create this memory |
| agentRunId | string | optional | Agent run identifier |
| sourceMessageId | string (UUID) | optional | Source message UUID |
| writeReason | string | optional | Why this memory should be stored |
| externalWriteId | string | optional | Idempotency key for upsert behavior |
| relatedMemoryIds | array | optional | Links to related memories with relation type. Each object: { memoryId: uuid, relationType: "derived_from" | "contradicts" | "refines" | "part_of" | "supersedes" } |
| sourceNoteIds | string[] (UUIDs) | optional | Note UUIDs this memory was extracted from |
| supersededById | string (UUID) | optional | Memory ID that supersedes this one (for corrections) |
| entities | string[] | optional | Extracted entity names (people, projects, tools, concepts) for cross-linking |
| dedup | boolean | optional | Run semantic dedup before writing. >92% match = skip, >80% = supersede old. |
Returns#
An object containing the created or matched memory ID, and a status indicating whether the memory was created, skipped (duplicate), or superseded an existing memory.
Example#
{
"tool": "write_memory",
"arguments": {
"content": "The organization always uses PostgreSQL instead of MySQL for all database needs.",
"memoryType": "constraint",
"importance": 5,
"confidence": 5,
"entities": ["PostgreSQL", "MySQL", "database"],
"writeReason": "Critical infrastructure decision that affects all projects",
"dedup": true
}
}