Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openmem.blog/llms.txt

Use this file to discover all available pages before exploring further.

All types returned by the OMP Python SDK are Pydantic v2 models. You can import them directly from the top-level openmem package for use in type hints, serialization, or validation. The models mirror the schemas defined in the OMP OpenAPI spec and are the single source of truth for all field names and types. 
from openmem import (
    MemoryRecord,
    MemorySource,
    SearchResult,
    MemoryPage,
    ContextBlock,
    Capabilities,
    CapabilityFeatures,
    CapabilityLimits,
    AuditEntry,
)
All models extend a shared base that sets extra="allow". Unknown fields from future spec versions and provider-specific x-<provider> extension fields are preserved on the model instance without raising a validation error.

​
MemoryRecord

MemoryRecord is the alias for openmem.types.Memory. It is returned by add(), get(), update(), and in paginated lists from list().
​
id
string
required
Provider-assigned unique identifier for this memory, e.g. "mem_abc123".
​
content
string
required
The text content of the memory.
​
user_id
string
required
The user this memory belongs to.
​
created_at
datetime
required
ISO 8601 timestamp of when the memory was created.
​
scope
string | None
Slash-delimited namespace, e.g. "coding/preferences". None if not set.
​
tags
string[] | None
Free-form labels associated with this memory.
​
source
MemorySource | None
Origin information. See MemorySource.
​
confidence
number | None
Confidence score between 0 and 1. Higher values indicate greater certainty.
​
valid_from
datetime | None
Datetime at which this memory becomes valid. None means immediately.
​
valid_to
datetime | None
Datetime at which this memory expires. None means no expiry.
​
supersedes
string[] | None
IDs of memories that this memory replaces.
​
embedding_model
string | None
The model used to generate the memory’s embedding, e.g. "text-embedding-3-small". Set by the provider.
​
updated_at
datetime | None
ISO 8601 timestamp of the last update to this memory.
​
status
"queued" | "indexing" | "done" | "failed" | None
Ingestion status. Relevant for async-ingestion providers (mem0, supermemory) where memories may be queued before being searchable. None on providers with synchronous ingestion.

​
MemorySource

Describes the origin of a memory. All fields are optional.
​
app
string | None
Name of the application that created the memory, e.g. "cursor" or "chatbot".
​
type
"extracted" | "explicit" | "imported" | None
How the memory was created:
  • "extracted" — inferred from a conversation or document
  • "explicit" — provided directly by the user
  • "imported" — migrated from another system
​
ref
string | None
An opaque pointer back to the source artifact, such as a session ID or document ID.

​
SearchResult

Returned as an element in the list from search().
​
memory
MemoryRecord
required
The matched memory record.
​
score
number
required
Cosine similarity score between 0 and 1. Higher values indicate greater similarity to the query.

​
MemoryPage

Returned by list(). Carries a page of records and a cursor for continuation.
​
items
MemoryRecord[]
required
The memories in this page.
​
next_cursor
string | None
An opaque pagination cursor. Pass this as cursor= to the next list() call to retrieve the following page. None means you have reached the last page.
Pagination example: 
cursor = None
while True:
    page = mem.list(user_id="u1", limit=50, cursor=cursor)
    for m in page.items:
        process(m)
    if page.next_cursor is None:
        break
    cursor = page.next_cursor

​
ContextBlock

Returned by context(). Contains a ranked text string ready to inject directly into an LLM prompt.
​
text
string
required
Pre-ranked text assembled from the most relevant memories, formatted for direct inclusion in a system or user prompt.
​
citations
object[]
required
A list of citation objects, each with:
  • memory_id (string) — the ID of the source memory
  • score (float) — its relevance score
​
token_count
number | None
The approximate token count of text, if the provider reports it. None when not available.
Usage in a prompt: 
ctx = mem.context(query="set up a new Node project", user_id="u1", token_budget=400)

messages = [
    {
        "role": "system",
        "content": f"Relevant user memory:\n{ctx.text}",
    },
    {"role": "user", "content": user_message},
]

​
Capabilities

Returned by capabilities(). Describes what the provider supports so your application can degrade gracefully.
​
omp_version
string
required
The OMP specification version this provider implements, e.g. "0.1".
​
provider
string
required
The provider’s own identifier string, e.g. "postgres" or "mem0".
​
verbs
string[]
required
List of supported verb names: add, search, get, update, delete, list, context, audit.
​
features
CapabilityFeatures
required
Feature flags. See CapabilityFeatures.
​
limits
CapabilityLimits | None
Rate and size limits. See CapabilityLimits.

​
CapabilityFeatures

Nested inside Capabilities.features.
​
vector_search
boolean | None
Whether the provider supports semantic (vector) search.
​
keyword_search
boolean | None
Whether the provider supports keyword (BM25 / full-text) search.
​
graph_queries
boolean | None
Whether the provider supports graph-based queries.
​
temporal
boolean | None
Whether the provider supports time-range filtering.
​
scopes
"native" | "tags" | "none" | None
How the provider implements scopes:
  • "native" — first-class scope support
  • "tags" — scopes emulated via tags
  • "none" — no scope support
​
max_content_length
number | None
Maximum number of characters allowed in content. None means no declared limit.
​
supports_e2e
boolean | None
Whether the provider supports end-to-end encryption.
​
supports_audit
boolean | None
Whether the provider supports the audit() verb.
​
supports_supersession
boolean | None
Whether the provider supports the supersedes field on memories.

​
CapabilityLimits

Nested inside Capabilities.limits. None when the provider does not declare limits.
​
rate_limit_per_minute
number | None
Maximum number of API calls allowed per minute. None means not declared.
​
max_search_results
number | None
Maximum value accepted for the limit parameter on search(). None means not declared.

​
AuditEntry

Each element in the list returned by audit().
​
timestamp
datetime | None
When the operation occurred.
​
app
string | None
The app that performed the operation.
​
action
"add" | "search" | "get" | "update" | "delete" | "list" | "context" | None
The OMP verb that was invoked.
​
memory_id
string | None
The ID of the memory involved, if applicable.
​
scope
string | None
The scope active at the time of the operation.
​
request_id
string | None
The provider-assigned request ID for tracing.

​
Extension fields

Every model uses extra="allow", which means provider-specific x-<provider> fields are silently preserved when the SDK receives them from the provider. For example, a memory returned by the mem0 adapter may include an x-mem0 key with graph metadata; that field round-trips transparently on the MemoryRecord instance without breaking validation. 
record = mem.get("mem_abc123")

# Standard fields
print(record.content)

# Provider extension (if present)
print(record.model_extra.get("x-mem0"))