- tenant-scoped memories stored for a specific tenant plus
external_user_id - universal memories stored for a Memory Passport user and shared only with agents that were granted access
Memory data model
Stored memory objects expose these fields in the public API:| Field | Type | Meaning |
|---|---|---|
id | string | Memory id |
content | string | Canonicalized memory text |
category | preference | fact | goal | procedure | relationship | expertise | Memory type |
importance_score | float | Relative importance |
original_importance_score | float | null | Extraction-time importance before boosts or decay |
confidence_score | float | Extraction confidence |
created_at | datetime | null | Creation timestamp |
updated_at | datetime | null | Last update timestamp |
last_accessed_at | datetime | null | Last retrieval access time |
access_count | int | Retrieval count |
is_archived | bool | Whether the memory is archived |
is_hot | bool | Whether the memory is currently promoted to the hot tier |
system_archived | bool | Whether lifecycle manager auto-archived the memory |
agent_id | string | null | Optional agent ownership |
previous_version_id | string | null | Prior version link |
source_conversation_id | string | null | Source conversation link |
source_job_id | string | null | Extraction job that created the memory |
metadata | object | Custom metadata |
Tenant memory vs universal memory
| Dimension | Tenant-scoped memory | Universal memory |
|---|---|---|
| Owner | A tenant workspace | A Memory Passport user |
| User identity | external_user_id | uui_... |
| Access model | Tenant API key | Agent API key + UUI grant |
| Primary use case | App personalization inside one product | Cross-agent memory sharing with user consent |
| Isolation boundary | Tenant | User plus granted categories |
The six memory categories
| Category | Example |
|---|---|
preference | ”User prefers concise technical explanations.” |
fact | ”User works at Acme Robotics.” |
goal | ”User is preparing for a cloud certification.” |
procedure | ”User wants weekly summaries sent on Fridays.” |
relationship | ”User reports to Priya on the data platform team.” |
expertise | ”User is experienced with FastAPI and PostgreSQL.” |
Importance scoring
importance_score is stored as a numeric value and influences ranking at retrieval time. Higher-importance memories are more likely to survive ranking and remain useful in cold-start retrieval.
Memory lifecycle
- Extracted Conversation content is analyzed from an ingestion job.
- Stored Valid extracted memories are written to the database and vector index.
- Retrieved Matching memories are ranked and returned to your app.
- Boosted or decayed Usage can increase live importance, while inactivity can reduce it.
- Hot promoted Frequently accessed, high-value memories can be cached in Redis.
- Archived Low-value inactive memories can be removed from search while remaining in PostgreSQL.
- Versioned Meaningful changes are recorded in append-only version history.
Universal memory lifecycle
Universal memories follow the same extraction and ranking ideas, but with one extra rule:- the user creates a Memory Passport
- an agent requests access to one or more categories
- the user grants or revokes access
- only then can that agent write or retrieve universal memories for that user
- revocation removes future access without exposing what other agents can see