Core Concepts
Metadata & Semantic Fields
metadata_json is the open-ended JSON column on every memory. It mixes user-supplied keys with platform-computed keys. This page lists what the platform writes into it, what you can safely write into it, and what you should avoid.
Two layers in one column
| Layer | Owner | Examples |
|---|---|---|
| User-supplied | You | Free-form keys passed via the request metadata object. |
| Echoed | Server | Selected request fields copied in for downstream consumers (source, event_type, tags, ttl_minutes). |
| Computed | Server | Pipeline outputs (semantic_summary, processing_time_ms). |
What you write
- Anything JSON-serializable. The platform does not validate the schema.
- Stable, lower-cased keys make filtering easier later.
- Reference ids back to your own systems (
ticket_id,order_id) — these are exactly what trace-back queries rely on.
Keys the server echoes from the request
| Key | Source |
|---|---|
source | Request source field (also the source column). |
event_type | Request event_type field. |
tags | Request tags array (also the tags column). |
ttl_minutes | Request ttl_minutes (also drives expires_at). |
Keys the platform writes
| Key | Meaning |
|---|---|
semantic_summary | Short description produced by the semantic engine. |
semantic_processing | Boolean flag — whether the semantic engine ran. |
preprocessing_timestamp | When preprocessing finished. |
token_count | Tokens consumed by the embedding step. |
processing_time_ms | Total wall time of the semantic enrichment. |
Keys you read back through <code>MemoryResponse</code>
The semantic enrichment also surfaces these on the response model — they originate inside metadata_json:
key_pointsinsightsentitiestopicscontext
Filtering on metadata at query time
POST /memory/query accepts a metadata-filter object. Filters apply after vector recall — they are evaluated in the primary store, not inside the vector index. Use them for narrow business filters (specific ticket_id, customer_id); use tags for coarse filters that must run at vector-search time.
What not to put in metadata
- PII you would not store in plain text elsewhere —
metadata_jsonis not encrypted at the column level. - Large blobs — keep payloads small; the column is stored inline with the row.
- Reserved keys — do not set
semantic_summary,semantic_processing,preprocessing_timestamp,token_count, orprocessing_time_msyourself; the server overwrites them.