save_memory
Persist user preferences, facts, episodes, or skills so agents recall them in future sessions. Near-duplicate saves are merged or skipped automatically, and embeddings are generated for semantic search.
Instructions
Save a new memory. Memories are persistent user preferences, facts, episodes, or skills that should be recalled in future conversations. Embeddings are generated automatically for semantic search. Delta-write is on by default: near-duplicate saves are skipped and similar existing memories absorb the new content instead of a new row being created (status in the response: saved | merged | skipped). Pass force_insert=true to bypass. Writes persist immediately; requires agent auth when the agent has a registered key.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"content": "<content>"
},
"name": "save_memory"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags for categorization | |
| type | No | Memory type: preference, fact, episode, entity, or skill | fact |
| layer | No | Memory layer: L0 (raw), L1 (atom), L2 (scenario), L3 (persona). Auto-assigned if omitted. | |
| api_key | No | API key for agent authentication (required if agent has a registered key) | |
| content | Yes | The content of the memory to save | |
| agent_id | No | ID of the agent saving this memory | unknown |
| priority | No | Priority level: MUST, REFERENCE, or BACKGROUND | REFERENCE |
| namespace | No | Namespace for the memory (default: global) | global |
| agent_type | No | Type of the agent (e.g., coding-assistant) | general-assistant |
| confidence | No | Confidence score (0.0 to 1.0) | |
| expires_at | No | Valid-time bound (RFC3339): when this fact stops being true, e.g. `2026-12-31T00:00:00Z`. Once past, the memory leaves retrieval and injection but stays inspectable and restorable — expiry retires a fact, only `forget_memory` erases one. Use for inherently temporary facts ("the deploy freeze runs until Friday") so they retire themselves instead of decaying slowly and being re-injected as stale truth. Omit for anything not time-bounded. | |
| fact_write | No | preserve (default) or resolve (atomic, requires a verified keyed producer). force_insert=true takes precedence and leaves the new row unmanaged. | |
| visibility | No | Sharing scope: "scoped" (default, namespace rules) or "shared" (team pool). | |
| instruction | No | Optional instruction format for the memory | |
| occurred_at | No | When the remembered fact actually happened in the source conversation/document (RFC 3339) — **event-time**, a separate axis from `created_at` (ingest-time) and from `expires_at` (valid-time). Set this when saving something that happened earlier than now, e.g. backfilling a dated transcript; without it a batch import stamps every row "now" and all event timing is lost. Invalid input is an error, never a silent drop. | |
| skill_steps | No | Skill execution steps (only for type=skill) | |
| force_insert | No | Force insert, skipping delta-write dedup/merge. By default a save is checked against similar memories in the same namespace: near-duplicates are skipped, similar memories absorb the new content's residual (docs/DESIGN.md §9.1.1). | |
| skill_trigger | No | Skill trigger pattern (only for type=skill) | |
| fact_assertion | No | Explicit caller-supplied fact identity/value/source metadata; never inferred from text. | |
| skill_verification | No | Skill verification criteria (only for type=skill) |