OMP Python SDK type reference

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().

string

required

Provider-assigned unique identifier for this memory, e.g. "mem_abc123".

string

required

The text content of the memory.

string

required

The user this memory belongs to.

datetime

required

ISO 8601 timestamp of when the memory was created.

string | None

Slash-delimited namespace, e.g. "coding/preferences". None if not set.

string[] | None

Free-form labels associated with this memory.

MemorySource | None

Origin information. See MemorySource.

number | None

Confidence score between 0 and 1. Higher values indicate greater certainty.

datetime | None

Datetime at which this memory becomes valid. None means immediately.

datetime | None

Datetime at which this memory expires. None means no expiry.

string[] | None

IDs of memories that this memory replaces.

string | None

The model used to generate the memory’s embedding, e.g. "text-embedding-3-small". Set by the provider.

datetime | None

ISO 8601 timestamp of the last update to this memory.

"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.

string | None

Name of the application that created the memory, e.g. "cursor" or "chatbot".

"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

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().

MemoryRecord

required

The matched memory record.

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.

MemoryRecord[]

required

The memories in this page.

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.

string

required

Pre-ranked text assembled from the most relevant memories, formatted for direct inclusion in a system or user prompt.

object[]

required

A list of citation objects, each with:

memory_id (string) — the ID of the source memory
score (float) — its relevance score

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.

string

required

The OMP specification version this provider implements, e.g. "0.1".

string

required

The provider’s own identifier string, e.g. "postgres" or "mem0".

string[]

required

List of supported verb names: add, search, get, update, delete, list, context, audit.

CapabilityFeatures

required

Feature flags. See CapabilityFeatures.

CapabilityLimits | None

Rate and size limits. See CapabilityLimits.

CapabilityFeatures

Nested inside Capabilities.features.

boolean | None

Whether the provider supports semantic (vector) search.

boolean | None

Whether the provider supports keyword (BM25 / full-text) search.

boolean | None

Whether the provider supports graph-based queries.

boolean | None

Whether the provider supports time-range filtering.

"native" | "tags" | "none" | None

How the provider implements scopes:

"native" — first-class scope support
"tags" — scopes emulated via tags
"none" — no scope support

number | None

Maximum number of characters allowed in content. None means no declared limit.

boolean | None

Whether the provider supports end-to-end encryption.

boolean | None

Whether the provider supports the audit() verb.

boolean | None

Whether the provider supports the supersedes field on memories.

CapabilityLimits

Nested inside Capabilities.limits. None when the provider does not declare limits.

number | None

Maximum number of API calls allowed per minute. None means not declared.

number | None

Maximum value accepted for the limit parameter on search(). None means not declared.

AuditEntry

Each element in the list returned by audit().

datetime | None

When the operation occurred.

string | None

The app that performed the operation.

The OMP verb that was invoked.

string | None

The ID of the memory involved, if applicable.

string | None

The scope active at the time of the operation.

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"))

Get Started

Core Concepts

Guides

SDK Reference

MemoryRecord

MemorySource

SearchResult

MemoryPage

ContextBlock

Capabilities

CapabilityFeatures

CapabilityLimits

AuditEntry

Extension fields

​MemoryRecord

​MemorySource

​SearchResult

​MemoryPage

​ContextBlock

​Capabilities

​CapabilityFeatures

​CapabilityLimits

​AuditEntry

​Extension fields

MemoryRecord

MemorySource

SearchResult

MemoryPage

ContextBlock

Capabilities

CapabilityFeatures

CapabilityLimits

AuditEntry

Extension fields