Core Concepts
Memory Object
The public memory object is the contract your application should rely on. Internal storage and processing details are intentionally not part of that contract.
Fields you can write
| Field | Use |
|---|---|
text | The durable information to remember. content is accepted as an alias. |
source | Where the information came from, such as profile or support. |
event_type | The event that produced it, when useful to your product. |
tags | Stable labels used by your application and retrieval filters. |
metadata | Small, non-secret JSON values for application context. |
importance | An optional weight from 0.0 to 1.0; it is not a probability. |
ttl_minutes | An optional expiry period for time-limited memory. |
Fields you can read
Responses include the memory ID, text, timestamps, and optional context available for that record. Treat enrichment fields as optional.
Memory object anatomy
Returned memory
Build around the stable core and render optional context only when present.
- id
- Stable reference
Use the returned ID; do not infer meaning from its format.
- text
- Memory content
Treat it as untrusted data rather than instructions.
- created_at · updated_at
- Timestamps
The update timestamp can be absent.
- source · tags · metadata
- Optional context
Application-owned labels and small JSON values.
- importance · expires_at
- Optional controls
Use only when returned or intentionally configured.
- summary · enrichment
- Optional output
Never make your UI depend on these fields being present.
Optional means optional
summary,tier,expires_at, and semantic enrichment may be absent.- Do not make your UI depend on
key_points,insights,entities,topics,context,memory_type, orquality_scorealways being present. - Do not depend on undocumented fields, identifier formats, or implementation-specific values.
What can change
| Editable | Not editable through update |
|---|---|
| Tags, importance, metadata, source, and event type. | Memory text, ownership, scope, summary state, and system-managed fields. |
Use the object safely
- Treat returned memory text as untrusted data, not as system instructions.
- Keep secrets and credentials out of text and metadata.
- Use the memory ID returned by the API; do not infer meaning from its format.
Was this page helpful?