orca-sdk 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

orca_sdk/memoryset.py

@@ -1,9 +1,10 @@
 from __future__ import annotations
 
 import logging
+from abc import ABC
 from datetime import datetime, timedelta
 from os import PathLike
-from typing import Any, Iterable, Literal, cast, overload
+from typing import Any, Generic, Iterable, Literal, Self, TypeVar, cast, overload
 
 import pandas as pd
 import pyarrow as pa
@@ -11,62 +12,62 @@ from datasets import Dataset
 from torch.utils.data import DataLoader as TorchDataLoader
 from torch.utils.data import Dataset as TorchDataset
 
-from ._generated_api_client.api import (
-    clone_memoryset,
-    create_analysis,
-    create_memoryset,
-    delete_memories,
-    delete_memoryset,
-    get_analysis,
-    get_memories,
-    get_memory,
-    get_memoryset,
-    insert_memories_gpu,
-    list_memorysets,
-    memoryset_lookup_gpu,
-    query_memoryset,
-    update_memories_gpu,
-    update_memory_gpu,
-)
-from ._generated_api_client.models import (
-    AnalyzeNeighborLabelsResult,
-    CloneLabeledMemorysetRequest,
-    CreateLabeledMemorysetRequest,
-    DeleteMemoriesRequest,
+from ._utils.common import UNSET, CreateMode, DropMode
+from .async_client import OrcaAsyncClient
+from .client import (
+    CascadingEditSuggestion,
+    CloneMemorysetRequest,
+    CreateMemorysetRequest,
     FilterItem,
-    FilterItemOp,
-    FindDuplicatesAnalysisResult,
-    GetMemoriesRequest,
 )
-from ._generated_api_client.models import LabeledMemory as LabeledMemoryResponse
-from ._generated_api_client.models import (
+from .client import LabeledMemory as LabeledMemoryResponse
+from .client import (
     LabeledMemoryInsert,
-    LabeledMemoryInsertMetadata,
 )
-from ._generated_api_client.models import (
-    LabeledMemoryLookup as LabeledMemoryLookupResponse,
-)
-from ._generated_api_client.models import (
-    LabeledMemoryMetrics,
-    LabeledMemorysetMetadata,
+from .client import LabeledMemoryLookup as LabeledMemoryLookupResponse
+from .client import (
     LabeledMemoryUpdate,
-    LabeledMemoryUpdateMetadataType0,
+    LabeledMemoryWithFeedbackMetrics,
     LabelPredictionMemoryLookup,
-    ListMemoriesRequest,
-    LookupRequest,
-    MemorysetAnalysisRequest,
-    MemorysetAnalysisRequestType,
-    TaskStatus,
+    MemoryMetrics,
+    MemorysetAnalysisConfigs,
+    MemorysetMetadata,
+    MemorysetMetrics,
+    MemorysetUpdate,
+    MemoryType,
+    OrcaClient,
+)
+from .client import ScoredMemory as ScoredMemoryResponse
+from .client import (
+    ScoredMemoryInsert,
+)
+from .client import ScoredMemoryLookup as ScoredMemoryLookupResponse
+from .client import (
+    ScoredMemoryUpdate,
+    ScoredMemoryWithFeedbackMetrics,
+    ScorePredictionMemoryLookup,
+    TelemetryFilterItem,
+    TelemetrySortOptions,
 )
-from ._generated_api_client.types import UNSET as CLIENT_UNSET
-from ._utils.common import UNSET, CreateMode, DropMode
-from ._utils.task import wait_for_task
 from .datasource import Datasource
 from .embedding_model import (
+    EmbeddingModelBase,
     FinetunedEmbeddingModel,
     PretrainedEmbeddingModel,
-    _EmbeddingModel,
 )
+from .job import Job, Status
+
+TelemetrySortItem = tuple[str, Literal["asc", "desc"]]
+"""
+Sort expression for telemetry data consisting of a field and a direction.
+
+* **`field`**: The field to sort on.
+* **`direction`**: The direction to sort in.
+
+Examples:
+    >>> ("feedback_metrics.accuracy.avg", "asc")
+    >>> ("lookup.count", "desc")
+"""
 
 FilterOperation = Literal["==", "!=", ">", ">=", "<", "<=", "in", "not in", "like"]
 """
@@ -90,62 +91,250 @@ Examples:
     >>> ("label", "==", 0)
     >>> ("metadata.author", "like", "John")
     >>> ("source_id", "in", ["123", "456"])
+    >>> ("feedback_metrics.accuracy.avg", ">", 0.95)
 """
 
+IndexType = Literal["FLAT", "IVF_FLAT", "IVF_SQ8", "IVF_PQ", "HNSW", "DISKANN"]
 
-DEFAULT_COLUMN_NAMES = {"value", "label", "source_id"}
-FORBIDDEN_METADATA_COLUMN_NAMES = {"memory_id", "memory_version", "embedding", "created_at", "updated_at", "metrics"}
+DEFAULT_COLUMN_NAMES = {"value", "source_id"}
+TYPE_SPECIFIC_COLUMN_NAMES = {"label", "score"}
+FORBIDDEN_METADATA_COLUMN_NAMES = {
+    "memory_id",
+    "memory_version",
+    "embedding",
+    "created_at",
+    "updated_at",
+    "metrics",
+    "feedback_metrics",
+    "lookup",
+}
 
 
-def _parse_filter_item_from_tuple(input: FilterItemTuple) -> FilterItem:
+def _is_metric_column(column: str):
+    return column in ["feedback_metrics", "lookup"]
+
+
+def _parse_filter_item_from_tuple(input: FilterItemTuple) -> FilterItem | TelemetryFilterItem:
     field = input[0].split(".")
-    if len(field) == 1 and field[0] not in DEFAULT_COLUMN_NAMES | FORBIDDEN_METADATA_COLUMN_NAMES:
+    if (
+        len(field) == 1
+        and field[0] not in DEFAULT_COLUMN_NAMES | TYPE_SPECIFIC_COLUMN_NAMES | FORBIDDEN_METADATA_COLUMN_NAMES
+    ):
         field = ["metadata", field[0]]
-    op = FilterItemOp(input[1])
+    op = input[1]
     value = input[2]
+    if isinstance(value, datetime):
+        value = value.isoformat()
+    if _is_metric_column(field[0]):
+        if not (
+            (isinstance(value, list) and all(isinstance(v, float) or isinstance(v, int) for v in value))
+            or isinstance(value, float)
+            or isinstance(value, int)
+        ):
+            raise ValueError(f"Invalid value for {field[0]} filter: {value}")
+        if field[0] == "feedback_metrics" and (len(field) != 3 or field[2] not in ["avg", "count"]):
+            raise ValueError(
+                "Feedback metrics filters must follow the format `feedback_metrics.<feedback_category_name>.<avg | count>`"
+            )
+        elif field[0] == "lookup" and (len(field) != 2 or field[1] != "count"):
+            raise ValueError("Lookup filters must follow the format `lookup.count`")
+        if op == "like":
+            raise ValueError("Like filters are not supported on metric columns")
+        op = cast(Literal["==", "!=", ">", ">=", "<", "<=", "in", "not in"], op)
+        value = cast(float | int | list[float] | list[int], value)
+        return TelemetryFilterItem(field=field, op=op, value=value)
+
     return FilterItem(field=field, op=op, value=value)
 
 
-def _parse_memory_insert(memory: dict[str, Any]) -> LabeledMemoryInsert:
+def _parse_sort_item_from_tuple(
+    input: TelemetrySortItem,
+) -> TelemetrySortOptions:
+    field = input[0].split(".")
+
+    if len(field) == 1:
+        raise ValueError("Sort field must be a telemetry field with an aggregate function name value")
+    if field[0] not in ["feedback_metrics", "lookup"]:
+        raise ValueError("Sort field must be one of telemetry fields: feedback_metrics or lookup")
+    if field[0] == "feedback_metrics":
+        if len(field) != 3:
+            raise ValueError(
+                "Feedback metrics must follow the format `feedback_metrics.<feedback_category_name>.<avg | count>`"
+            )
+        if field[2] not in ["avg", "count"]:
+            raise ValueError("Feedback metrics can only be sorted on avg or count")
+    if field[0] == "lookup":
+        if len(field) != 2:
+            raise ValueError("Lookup must follow the format `lookup.count`")
+        if field[1] != "count":
+            raise ValueError("Lookup can only be sorted on count")
+    return TelemetrySortOptions(field=field, direction=input[1])
+
+
+def _parse_memory_insert(memory: dict[str, Any], type: MemoryType) -> LabeledMemoryInsert | ScoredMemoryInsert:
     value = memory.get("value")
     if not isinstance(value, str):
         raise ValueError("Memory value must be a string")
-    label = memory.get("label")
-    if not isinstance(label, int):
-        raise ValueError("Memory label must be an integer")
     source_id = memory.get("source_id")
     if source_id and not isinstance(source_id, str):
         raise ValueError("Memory source_id must be a string")
-    metadata = LabeledMemoryInsertMetadata.from_dict({k: v for k, v in memory.items() if k not in DEFAULT_COLUMN_NAMES})
-    if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
-        raise ValueError(f"The following column names are reserved: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}")
-    return LabeledMemoryInsert(value=value, label=label, source_id=source_id, metadata=metadata)
-
-
-def _parse_memory_update(update: dict[str, Any]) -> LabeledMemoryUpdate:
+    match type:
+        case "LABELED":
+            label = memory.get("label")
+            if label is not None and not isinstance(label, int):
+                raise ValueError("Memory label must be an integer")
+            metadata = {k: v for k, v in memory.items() if k not in DEFAULT_COLUMN_NAMES | {"label"}}
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"The following column names are reserved: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            return {"value": value, "label": label, "source_id": source_id, "metadata": metadata}
+        case "SCORED":
+            score = memory.get("score")
+            if score is not None and not isinstance(score, (int, float)):
+                raise ValueError("Memory score must be a number")
+            metadata = {k: v for k, v in memory.items() if k not in DEFAULT_COLUMN_NAMES | {"score"}}
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"The following column names are reserved: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            return {"value": value, "score": score, "source_id": source_id, "metadata": metadata}
+
+
+def _parse_memory_update(update: dict[str, Any], type: MemoryType) -> LabeledMemoryUpdate | ScoredMemoryUpdate:
     if "memory_id" not in update:
         raise ValueError("memory_id must be specified in the update dictionary")
     memory_id = update["memory_id"]
     if not isinstance(memory_id, str):
         raise ValueError("memory_id must be a string")
-    value = update.get("value", CLIENT_UNSET)
-    if value is not CLIENT_UNSET and not isinstance(value, str):
-        raise ValueError("value must be a string or unset")
-    label = update.get("label", CLIENT_UNSET)
-    if label is not CLIENT_UNSET and not isinstance(label, int):
-        raise ValueError("label must be an integer or unset")
-    source_id = update.get("source_id", CLIENT_UNSET)
-    if source_id is not CLIENT_UNSET and not isinstance(source_id, str):
-        raise ValueError("source_id must be a string or unset")
-    metadata = LabeledMemoryUpdateMetadataType0.from_dict(
-        {k: v for k, v in update.items() if k not in DEFAULT_COLUMN_NAMES | {"memory_id"}}
-    )
-    if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
-        raise ValueError(f"Cannot update the following metadata keys: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}")
-    return LabeledMemoryUpdate(memory_id=memory_id, value=value, label=label, source_id=source_id, metadata=metadata)
-
-
-class LabeledMemory:
+    payload: LabeledMemoryUpdate | ScoredMemoryUpdate = {"memory_id": memory_id}
+    if "value" in update:
+        if not isinstance(update["value"], str):
+            raise ValueError("value must be a string or unset")
+        payload["value"] = update["value"]
+    if "source_id" in update:
+        if not isinstance(update["source_id"], str):
+            raise ValueError("source_id must be a string or unset")
+        payload["source_id"] = update["source_id"]
+    match type:
+        case "LABELED":
+            payload = cast(LabeledMemoryUpdate, payload)
+            if "label" in update:
+                if not isinstance(update["label"], int):
+                    raise ValueError("label must be an integer or unset")
+                payload["label"] = update["label"]
+            metadata = {k: v for k, v in update.items() if k not in DEFAULT_COLUMN_NAMES | {"memory_id", "label"}}
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"Cannot update the following metadata keys: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            payload["metadata"] = metadata
+            return payload
+        case "SCORED":
+            payload = cast(ScoredMemoryUpdate, payload)
+            if "score" in update:
+                if not isinstance(update["score"], (int, float)):
+                    raise ValueError("score must be a number or unset")
+                payload["score"] = update["score"]
+            metadata = {k: v for k, v in update.items() if k not in DEFAULT_COLUMN_NAMES | {"memory_id", "score"}}
+            if any(k in metadata for k in FORBIDDEN_METADATA_COLUMN_NAMES):
+                raise ValueError(
+                    f"Cannot update the following metadata keys: {', '.join(FORBIDDEN_METADATA_COLUMN_NAMES)}"
+                )
+            payload["metadata"] = metadata
+            return cast(ScoredMemoryUpdate, payload)
+
+
+class MemoryBase(ABC):
+    value: str
+    embedding: list[float]
+    source_id: str | None
+    created_at: datetime
+    updated_at: datetime
+    metadata: dict[str, str | float | int | bool | None]
+    metrics: MemoryMetrics
+    memory_id: str
+    memory_version: int
+    feedback_metrics: dict[str, Any]
+    lookup_count: int
+    memory_type: MemoryType  # defined by subclasses
+
+    def __init__(
+        self,
+        memoryset_id: str,
+        memory: (
+            LabeledMemoryResponse
+            | LabeledMemoryLookupResponse
+            | LabeledMemoryWithFeedbackMetrics
+            | LabelPredictionMemoryLookup
+            | ScoredMemoryResponse
+            | ScoredMemoryLookupResponse
+            | ScoredMemoryWithFeedbackMetrics
+            | ScorePredictionMemoryLookup
+        ),
+    ):
+        # for internal use only, do not document
+        self.memoryset_id = memoryset_id
+        self.memory_id = memory["memory_id"]
+        self.memory_version = memory["memory_version"]
+        self.value = cast(str, memory["value"])
+        self.embedding = memory["embedding"]
+        self.source_id = memory["source_id"]
+        self.created_at = datetime.fromisoformat(memory["created_at"])
+        self.updated_at = datetime.fromisoformat(memory["updated_at"])
+        self.metadata = memory["metadata"]
+        self.metrics = memory["metrics"] if "metrics" in memory else {}
+        self.feedback_metrics = memory.get("feedback_metrics", {}) or {}
+        self.lookup_count = memory.get("lookup_count", 0)
+
+    def __getattr__(self, key: str) -> Any:
+        if key.startswith("__") or key not in self.metadata:
+            raise AttributeError(f"{key} is not a valid attribute")
+        return self.metadata[key]
+
+    def _update(
+        self,
+        *,
+        value: str = UNSET,
+        source_id: str | None = UNSET,
+        **metadata: None | bool | float | int | str,
+    ) -> Self:
+        client = OrcaClient._resolve_client()
+        response = client.PATCH(
+            "/gpu/memoryset/{name_or_id}/memory",
+            params={"name_or_id": self.memoryset_id},
+            json=_parse_memory_update(
+                {"memory_id": self.memory_id}
+                | ({"value": value} if value is not UNSET else {})
+                | ({"source_id": source_id} if source_id is not UNSET else {})
+                | {k: v for k, v in metadata.items() if v is not UNSET},
+                type=self.memory_type,
+            ),
+        )
+        self.__dict__.update(self.__class__(self.memoryset_id, response).__dict__)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the memory to a dictionary
+        """
+        return {
+            "value": self.value,
+            "embedding": self.embedding,
+            "source_id": self.source_id,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "metadata": self.metadata,
+            "metrics": self.metrics,
+            "memory_id": self.memory_id,
+            "memory_version": self.memory_version,
+            "feedback_metrics": self.feedback_metrics,
+            "lookup_count": self.lookup_count,
+            "memory_type": self.memory_type,
+        }
+
+
+class LabeledMemory(MemoryBase):
     """
     A row of the [`LabeledMemoryset`][orca_sdk.LabeledMemoryset]
 
@@ -170,47 +359,30 @@ class LabeledMemory:
     * **`...`** (<code>[str][str] | [float][float] | [int][int] | [bool][bool] | None</code>): All metadata properties can be accessed as attributes
     """
 
-    value: str
-    embedding: list[float]
-    label: int
+    label: int | None
     label_name: str | None
-    source_id: str | None
-    created_at: datetime
-    updated_at: datetime
-    metadata: dict[str, str | float | int | bool | None]
-    metrics: LabeledMemoryMetrics | None
-    memory_id: str
-    memory_version: int
+    memory_type = "LABELED"
 
     def __init__(
         self,
         memoryset_id: str,
-        memory: LabeledMemoryResponse | LabeledMemoryLookupResponse | LabelPredictionMemoryLookup,
+        memory: (
+            LabeledMemoryResponse
+            | LabeledMemoryLookupResponse
+            | LabelPredictionMemoryLookup
+            | LabeledMemoryWithFeedbackMetrics
+        ),
     ):
         # for internal use only, do not document
-        self.memoryset_id = memoryset_id
-        self.memory_id = memory.memory_id
-        self.memory_version = memory.memory_version
-        self.value = memory.value
-        self.embedding = memory.embedding
-        self.label = memory.label
-        self.label_name = memory.label_name
-        self.source_id = memory.source_id
-        self.created_at = memory.created_at
-        self.updated_at = memory.updated_at
-        self.metadata = memory.metadata.to_dict()
-        self.metrics = memory.metrics
-
-    def __getattr__(self, key: str) -> Any:
-        if key.startswith("__") or key not in self.metadata:
-            raise AttributeError(f"{key} is not a valid attribute")
-        return self.metadata[key]
+        super().__init__(memoryset_id, memory)
+        self.label = memory["label"]
+        self.label_name = memory["label_name"]
 
     def __repr__(self) -> str:
         return (
             "LabeledMemory({ "
             + f"label: {('<' + self.label_name + ': ' + str(self.label) + '>') if self.label_name else str(self.label)}"
-            + f", value: '{self.value[:100] + '...' if len(self.value) > 100 else self.value}'"
+            + f", value: '{self.value[:100] + '...' if isinstance(self.value, str) and len(self.value) > 100 else self.value}'"
             + (f", source_id: '{self.source_id}'" if self.source_id is not None else "")
             + " })"
         )
@@ -222,7 +394,7 @@ class LabeledMemory:
         self,
         *,
         value: str = UNSET,
-        label: int = UNSET,
+        label: int | None = UNSET,
         source_id: str | None = UNSET,
         **metadata: None | bool | float | int | str,
     ) -> LabeledMemory:
@@ -241,19 +413,18 @@ class LabeledMemory:
         Returns:
             The updated memory
         """
-        response = update_memory_gpu(
-            self.memoryset_id,
-            body=_parse_memory_update(
-                {"memory_id": self.memory_id}
-                | ({"value": value} if value is not UNSET else {})
-                | ({"label": label} if label is not UNSET else {})
-                | ({"source_id": source_id} if source_id is not UNSET else {})
-                | metadata
-            ),
-        )
-        self.__dict__.update(LabeledMemory(self.memoryset_id, response).__dict__)
+        self._update(value=value, label=label, source_id=source_id, **metadata)
         return self
 
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the memory to a dictionary
+        """
+        super_dict = super().to_dict()
+        super_dict["label"] = self.label
+        super_dict["label_name"] = self.label_name
+        return super_dict
+
 
 class LabeledMemoryLookup(LabeledMemory):
     """
@@ -289,10 +460,8 @@ class LabeledMemoryLookup(LabeledMemory):
     def __init__(self, memoryset_id: str, memory_lookup: LabeledMemoryLookupResponse | LabelPredictionMemoryLookup):
         # for internal use only, do not document
         super().__init__(memoryset_id, memory_lookup)
-        self.lookup_score = memory_lookup.lookup_score
-        self.attention_weight = (
-            memory_lookup.attention_weight if isinstance(memory_lookup, LabelPredictionMemoryLookup) else None
-        )
+        self.lookup_score = memory_lookup["lookup_score"]
+        self.attention_weight = memory_lookup["attention_weight"] if "attention_weight" in memory_lookup else None
 
     def __repr__(self) -> str:
         return (
@@ -300,20 +469,155 @@ class LabeledMemoryLookup(LabeledMemory):
             + f"label: {('<' + self.label_name + ': ' + str(self.label) + '>') if self.label_name else str(self.label)}"
             + f", lookup_score: {self.lookup_score:.2f}"
             + (f", attention_weight: {self.attention_weight:.2f}" if self.attention_weight is not None else "")
-            + f", value: '{self.value[:100] + '...' if len(self.value) > 100 else self.value}'"
+            + f", value: '{self.value[:100] + '...' if isinstance(self.value, str) and len(self.value) > 100 else self.value}'"
+            + (f", source_id: '{self.source_id}'" if self.source_id is not None else "")
+            + " })"
+        )
+
+
+class ScoredMemory(MemoryBase):
+    """
+    A row of the [`ScoredMemoryset`][orca_sdk.ScoredMemoryset]
+
+    Attributes:
+        value: Value represented by the row
+        embedding: Embedding of the value of the memory for semantic search, automatically generated
+            with the [`ScoredMemoryset.embedding_model`][orca_sdk.ScoredMemoryset]
+        score: Score of the memory
+        source_id: Optional unique identifier of the memory in a system of reference
+        metrics: Metrics about the memory, generated when running an analysis on the
+            [`ScoredMemoryset`][orca_sdk.ScoredMemoryset]
+        metadata: Metadata associated with the memory that is not used in the model. Metadata
+            properties are also accessible as individual attributes on the instance.
+        memory_id: Unique identifier for the memory, automatically generated on insert
+        memory_version: Version of the memory, automatically updated when the score or value changes
+        created_at: When the memory was created, automatically generated on insert
+        updated_at: When the memory was last updated, automatically updated on update
+
+    ## Other Attributes:
+    * **`...`** (<code>[str][str] | [float][float] | [int][int] | [bool][bool] | None</code>): All metadata properties can be accessed as attributes
+    """
+
+    score: float | None
+    memory_type = "SCORED"
+
+    def __init__(
+        self,
+        memoryset_id: str,
+        memory: (
+            ScoredMemoryResponse
+            | ScoredMemoryLookupResponse
+            | ScorePredictionMemoryLookup
+            | ScoredMemoryWithFeedbackMetrics
+        ),
+    ):
+        # for internal use only, do not document
+        super().__init__(memoryset_id, memory)
+        self.score = memory["score"]
+
+    def __repr__(self) -> str:
+        return (
+            "ScoredMemory({ "
+            + f"score: {self.score:.2f}"
+            + f", value: '{self.value[:100] + '...' if isinstance(self.value, str) and len(self.value) > 100 else self.value}'"
+            + (f", source_id: '{self.source_id}'" if self.source_id is not None else "")
+            + " })"
+        )
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, ScoredMemory) and self.memory_id == other.memory_id
+
+    def update(
+        self,
+        *,
+        value: str = UNSET,
+        score: float | None = UNSET,
+        source_id: str | None = UNSET,
+        **metadata: None | bool | float | int | str,
+    ) -> ScoredMemory:
+        """
+        Update the memory with new values
+
+        Note:
+            If a field is not provided, it will default to [UNSET][orca_sdk.UNSET] and not be updated.
+
+        Params:
+            value: New value of the memory
+            score: New score of the memory
+            source_id: New source ID of the memory
+            **metadata: New values for metadata properties
+
+        Returns:
+            The updated memory
+        """
+        self._update(value=value, score=score, source_id=source_id, **metadata)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert the memory to a dictionary
+        """
+        super_dict = super().to_dict()
+        super_dict["score"] = self.score
+        return super_dict
+
+
+class ScoredMemoryLookup(ScoredMemory):
+    """
+    Lookup result for a memory in a memoryset
+
+    Attributes:
+        lookup_score: Similarity between the memory embedding and search query embedding
+        attention_weight: Weight the model assigned to the memory during prediction if this lookup
+            happened as part of a prediction
+        value: Value represented by the row
+        embedding: Embedding of the value of the memory for semantic search, automatically generated
+            with the [`ScoredMemoryset.embedding_model`][orca_sdk.ScoredMemoryset]
+        score: Score of the memory
+        source_id: Optional unique identifier of the memory in a system of reference
+        metrics: Metrics about the memory, generated when running an analysis on the
+            [`ScoredMemoryset`][orca_sdk.ScoredMemoryset]
+        memory_id: The unique identifier for the memory, automatically generated on insert
+        memory_version: The version of the memory, automatically updated when the score or value changes
+        created_at: When the memory was created, automatically generated on insert
+        updated_at: When the memory was last updated, automatically updated on update
+
+    ## Other Attributes:
+    * **`...`** (<code>[str][str] | [float][float] | [int][int] | [bool][bool] | None</code>): All metadata properties can be accessed as attributes
+    """
+
+    lookup_score: float
+    attention_weight: float | None
+
+    def __init__(self, memoryset_id: str, memory_lookup: ScoredMemoryLookupResponse | ScorePredictionMemoryLookup):
+        # for internal use only, do not document
+        super().__init__(memoryset_id, memory_lookup)
+        self.lookup_score = memory_lookup["lookup_score"]
+        self.attention_weight = memory_lookup["attention_weight"] if "attention_weight" in memory_lookup else None
+
+    def __repr__(self) -> str:
+        return (
+            "ScoredMemoryLookup({ "
+            + f"score: {self.score:.2f}"
+            + f", lookup_score: {self.lookup_score:.2f}"
+            + f", value: '{self.value[:100] + '...' if isinstance(self.value, str) and len(self.value) > 100 else self.value}'"
             + (f", source_id: '{self.source_id}'" if self.source_id is not None else "")
             + " })"
         )
 
 
-class LabeledMemoryset:
+MemoryT = TypeVar("MemoryT", bound=MemoryBase)
+MemoryLookupT = TypeVar("MemoryLookupT", bound=MemoryBase)
+
+
+class MemorysetBase(Generic[MemoryT, MemoryLookupT], ABC):
     """
     A Handle to a collection of memories with labels in the OrcaCloud
 
     Attributes:
         id: Unique identifier for the memoryset
         name: Unique name of the memoryset
-        label_names: Names for the class labels in the memoryset
+        description: Description of the memoryset
         length: Number of memories in the memoryset
         embedding_model: Embedding model used to embed the memory values for semantic search
         created_at: When the memoryset was created, automatically generated on create
@@ -322,43 +626,96 @@ class LabeledMemoryset:
 
     id: str
     name: str
-    label_names: list[str]
+    description: str | None
+    memory_type: MemoryType  # defined by subclasses
+
     length: int
     created_at: datetime
     updated_at: datetime
-    insertion_status: TaskStatus
-    embedding_model: _EmbeddingModel
+    insertion_status: Status
+    embedding_model: EmbeddingModelBase
+    index_type: IndexType
+    index_params: dict[str, Any]
+    hidden: bool
 
-    def __init__(self, metadata: LabeledMemorysetMetadata):
+    _batch_size = 32  # max number of memories to insert/update/delete in a single API call
+
+    def __init__(self, metadata: MemorysetMetadata):
         # for internal use only, do not document
-        if metadata.pretrained_embedding_model_name:
-            self.embedding_model = PretrainedEmbeddingModel._get(metadata.pretrained_embedding_model_name)
-        elif metadata.finetuned_embedding_model_id:
-            self.embedding_model = FinetunedEmbeddingModel.open(metadata.finetuned_embedding_model_id)
+        if metadata["pretrained_embedding_model_name"]:
+            self.embedding_model = PretrainedEmbeddingModel._get(metadata["pretrained_embedding_model_name"])
+        elif metadata["finetuned_embedding_model_id"]:
+            self.embedding_model = FinetunedEmbeddingModel.open(metadata["finetuned_embedding_model_id"])
         else:
             raise ValueError("Either pretrained_embedding_model_name or finetuned_embedding_model_id must be provided")
-        self.id = metadata.id
-        self.name = metadata.name
-        self.label_names = metadata.label_names
-        self.length = metadata.length
-        self.created_at = metadata.created_at
-        self.updated_at = metadata.updated_at
-        self.insertion_status = metadata.insertion_status
+        self.id = metadata["id"]
+        self.name = metadata["name"]
+        self.description = metadata["description"]
+        self.length = metadata["length"]
+        self.created_at = datetime.fromisoformat(metadata["created_at"])
+        self.updated_at = datetime.fromisoformat(metadata["updated_at"])
+        self.insertion_status = Status(metadata["insertion_status"])
         self._last_refresh = datetime.now()
+        self.index_type = metadata["index_type"]
+        self.index_params = metadata["index_params"]
+        self.memory_type = metadata["memory_type"]
+        self.hidden = metadata["hidden"]
 
     def __eq__(self, other) -> bool:
-        return isinstance(other, LabeledMemoryset) and self.id == other.id
+        return isinstance(other, MemorysetBase) and self.id == other.id
 
     def __repr__(self) -> str:
         return (
-            "LabeledMemoryset({\n"
+            "Memoryset({\n"
             f"    name: '{self.name}',\n"
             f"    length: {self.length},\n"
-            f"    label_names: {self.label_names},\n"
             f"    embedding_model: {self.embedding_model},\n"
             "})"
         )
 
+    @classmethod
+    def _handle_if_exists(
+        cls,
+        name: str,
+        *,
+        if_exists: CreateMode,
+        label_names: list[str] | None,
+        embedding_model: PretrainedEmbeddingModel | FinetunedEmbeddingModel | None,
+    ) -> Self | None:
+        """
+        Handle common `if_exists` logic shared by all creator-style helpers.
+
+        Returns the already-existing memoryset when `if_exists == "open"`, raises for `"error"`,
+        and returns `None` when the memoryset does not yet exist.
+        """
+        if not cls.exists(name):
+            return None
+        if if_exists == "error":
+            raise ValueError(f"Memoryset with name {name} already exists")
+
+        existing = cls.open(name)
+
+        if label_names is not None and hasattr(existing, "label_names"):
+            existing_label_names = getattr(existing, "label_names")
+            if label_names != existing_label_names:
+                requested = ", ".join(label_names)
+                existing_joined = ", ".join(existing_label_names)
+                raise ValueError(
+                    f"Memoryset {name} already exists with label names [{existing_joined}] "
+                    f"(requested: [{requested}])."
+                )
+
+        if embedding_model is not None and embedding_model != existing.embedding_model:
+            existing_model = existing.embedding_model
+            existing_model_name = getattr(existing_model, "name", getattr(existing_model, "path", str(existing_model)))
+            requested_name = getattr(embedding_model, "name", getattr(embedding_model, "path", str(embedding_model)))
+            raise ValueError(
+                f"Memoryset {name} already exists with embedding_model {existing_model_name} "
+                f"(requested: {requested_name})."
+            )
+
+        return existing
+
     @classmethod
     def create(
         cls,
@@ -367,12 +724,20 @@ class LabeledMemoryset:
         *,
         embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
         value_column: str = "value",
-        label_column: str = "label",
+        label_column: str | None = None,
+        score_column: str | None = None,
         source_id_column: str | None = None,
+        description: str | None = None,
         label_names: list[str] | None = None,
         max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
         if_exists: CreateMode = "error",
-    ) -> LabeledMemoryset:
+        background: bool = False,
+        hidden: bool = False,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset in the OrcaCloud
 
@@ -387,8 +752,12 @@ class LabeledMemoryset:
             value_column: Name of the column in the datasource that contains the memory values
             label_column: Name of the column in the datasource that contains the memory labels,
                 these must be contiguous integers starting from 0
+            score_column: Name of the column in the datasource that contains the memory scores
             source_id_column: Optional name of the column in the datasource that contains the ids in
                 the system of reference
+            description: Optional description for the memoryset, this will be used in agentic flows,
+                so make sure it is concise and describes the contents of your memoryset not the
+                datasource or the embedding model.
             label_names: List of human-readable names for the labels in the memoryset, must match
                 the number of labels in the `label_column`. Will be automatically inferred if a
                 [Dataset][datasets.Dataset] with a [`ClassLabel`][datasets.ClassLabel] feature for
@@ -396,8 +765,16 @@ class LabeledMemoryset:
             max_seq_length_override: Maximum sequence length of values in the memoryset, if the
                 value is longer than this it will be truncated, will default to the model's max
                 sequence length if not provided
+            prompt: Optional prompt to use when embedding documents/memories for storage
+            remove_duplicates: Whether to remove duplicates from the datasource before inserting
+                into the memoryset
+            index_type: Type of vector index to use for the memoryset, defaults to `"FLAT"`. Valid
+                values are `"FLAT"`, `"IVF_FLAT"`, `"IVF_SQ8"`, `"IVF_PQ"`, `"HNSW"`, and `"DISKANN"`.
+            index_params: Parameters for the vector index, defaults to `{}`
             if_exists: What to do if a memoryset with the same name already exists, defaults to
                 `"error"`. Other option is `"open"` to open the existing memoryset.
+            background: Whether to run the operation none blocking and return a job handle
+            hidden: Whether the memoryset should be hidden
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
@@ -407,42 +784,62 @@ class LabeledMemoryset:
                 `"open"` and the params do not match those of the existing memoryset.
         """
         if embedding_model is None:
-            embedding_model = PretrainedEmbeddingModel.CDE_SMALL
+            embedding_model = PretrainedEmbeddingModel.GTE_BASE
 
-        logging.info(f"Checking if memoryset with name: {name} exists")
-        if cls.exists(name):
-            if if_exists == "error":
-                raise ValueError(f"Memoryset with name {name} already exists")
-            elif if_exists == "open":
-                existing = cls.open(name)
-                for attribute in {"label_names", "embedding_model"}:
-                    if locals()[attribute] is not None and locals()[attribute] != getattr(existing, attribute):
-                        raise ValueError(f"Memoryset with name {name} already exists with a different {attribute}.")
-                return existing
+        if label_column is None and score_column is None:
+            raise ValueError("label_column or score_column must be provided")
 
-        logging.info(f"Creating memoryset with name: {name} from datasource: {datasource}")
-        response = create_memoryset(
-            body=CreateLabeledMemorysetRequest(
-                name=name,
-                datasource_id=datasource.id,
-                datasource_label_column=label_column,
-                datasource_value_column=value_column,
-                datasource_source_id_column=source_id_column,
-                pretrained_embedding_model_name=(
-                    embedding_model._model_name if isinstance(embedding_model, PretrainedEmbeddingModel) else None
-                ),
-                finetuned_embedding_model_id=(
-                    embedding_model.id if isinstance(embedding_model, FinetunedEmbeddingModel) else None
-                ),
-                label_names=label_names or [],
-                max_seq_length_override=max_seq_length_override,
-            ),
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=label_names,
+            embedding_model=embedding_model,
         )
-        wait_for_task(response.insertion_task_id, description="Inserting datasource")
-        return cls.open(response.id)
+        if existing is not None:
+            return existing
+
+        payload: CreateMemorysetRequest = {
+            "name": name,
+            "description": description,
+            "datasource_name_or_id": datasource.id,
+            "datasource_label_column": label_column,
+            "datasource_score_column": score_column,
+            "datasource_value_column": value_column,
+            "datasource_source_id_column": source_id_column,
+            "label_names": label_names,
+            "max_seq_length_override": max_seq_length_override,
+            "remove_duplicates": remove_duplicates,
+            "index_type": index_type,
+            "index_params": index_params,
+            "hidden": hidden,
+        }
+        if prompt is not None:
+            payload["prompt"] = prompt
+        if isinstance(embedding_model, PretrainedEmbeddingModel):
+            payload["pretrained_embedding_model_name"] = embedding_model.name
+        elif isinstance(embedding_model, FinetunedEmbeddingModel):
+            payload["finetuned_embedding_model_name_or_id"] = embedding_model.id
+        else:
+            raise ValueError("Invalid embedding model")
+        client = OrcaClient._resolve_client()
+        response = client.POST("/memoryset", json=payload)
+        job = Job(response["insertion_task_id"], lambda: cls.open(response["id"]))
+        return job if background else job.result()
+
+    @overload
+    @classmethod
+    def from_hf_dataset(cls, name: str, hf_dataset: Dataset, background: Literal[True], **kwargs: Any) -> Self:
+        pass
+
+    @overload
+    @classmethod
+    def from_hf_dataset(cls, name: str, hf_dataset: Dataset, background: Literal[False] = False, **kwargs: Any) -> Self:
+        pass
 
     @classmethod
-    def from_hf_dataset(cls, name: str, hf_dataset: Dataset, **kwargs: Any) -> LabeledMemoryset:
+    def from_hf_dataset(
+        cls, name: str, hf_dataset: Dataset, background: bool = False, **kwargs: Any
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a Hugging Face [`Dataset`][datasets.Dataset] in the OrcaCloud
 
@@ -456,18 +853,53 @@ class LabeledMemoryset:
             name: Name for the new memoryset (must be unique)
             hf_dataset: Hugging Face dataset to create the memoryset from
             kwargs: Additional parameters for creating the memoryset. See
-                [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
-
+                [`create`][orca_sdk.memoryset.MemorysetBase.create] attributes for details.
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
         """
+        if_exists = kwargs.get("if_exists", "error")
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=kwargs.get("label_names"),
+            embedding_model=kwargs.get("embedding_model"),
+        )
+        if existing is not None:
+            return existing
+
         datasource = Datasource.from_hf_dataset(
             f"{name}_datasource", hf_dataset, if_exists=kwargs.get("if_exists", "error")
         )
-        logging.info(f"Datasource: {datasource}")
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_pytorch(
+        cls,
+        name: str,
+        torch_data: TorchDataLoader | TorchDataset,
+        *,
+        column_names: list[str] | None = None,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_pytorch(
+        cls,
+        name: str,
+        torch_data: TorchDataLoader | TorchDataset,
+        *,
+        column_names: list[str] | None = None,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
     def from_pytorch(
         cls,
@@ -475,8 +907,9 @@ class LabeledMemoryset:
         torch_data: TorchDataLoader | TorchDataset,
         *,
         column_names: list[str] | None = None,
+        background: bool = False,
         **kwargs: Any,
-    ) -> LabeledMemoryset:
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a PyTorch [`DataLoader`][torch.utils.data.DataLoader] or
         [`Dataset`][torch.utils.data.Dataset] in the OrcaCloud
@@ -492,34 +925,77 @@ class LabeledMemoryset:
             torch_data: PyTorch data loader or dataset to create the memoryset from
             column_names: If the provided dataset or data loader returns unnamed tuples, this
                 argument must be provided to specify the names of the columns.
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
-                [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
-
+                [`create`][orca_sdk.memoryset.MemorysetBase.create] attributes for details.
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
         """
+        if_exists = kwargs.get("if_exists", "error")
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=kwargs.get("label_names"),
+            embedding_model=kwargs.get("embedding_model"),
+        )
+        if existing is not None:
+            return existing
+
         datasource = Datasource.from_pytorch(
             f"{name}_datasource", torch_data, column_names=column_names, if_exists=kwargs.get("if_exists", "error")
         )
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
     @classmethod
-    def from_list(cls, name: str, data: list[dict], **kwargs: Any) -> LabeledMemoryset:
-        """
-        Create a new memoryset from a list of dictionaries in the OrcaCloud
+    def from_list(
+        cls,
+        name: str,
+        data: list[dict],
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
 
-        This will automatically create a [`Datasource`][orca_sdk.Datasource] with the same name
-        appended with `_datasource` and use that as the datasource for the memoryset.
+    @overload
+    @classmethod
+    def from_list(
+        cls,
+        name: str,
+        data: list[dict],
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
 
-        All properties that are not specified to be used as `value_column`, `label_column`, or
-        `source_id_column` will be stored as metadata in the memoryset.
+    @classmethod
+    def from_list(
+        cls,
+        name: str,
+        data: list[dict],
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
+        """
+        Create a new memoryset from a list of dictionaries in the OrcaCloud
+
+        This will automatically create a [`Datasource`][orca_sdk.Datasource] with the same name
+        appended with `_datasource` and use that as the datasource for the memoryset.
+
+        All properties that are not specified to be used as `value_column`, `label_column`, or
+        `source_id_column` will be stored as metadata in the memoryset.
 
         Params:
             name: Name for the new memoryset (must be unique)
             data: List of dictionaries to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
-                [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
+                [`create`][orca_sdk.memoryset.MemorysetBase.create] attributes for details.
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
@@ -530,11 +1006,53 @@ class LabeledMemoryset:
             ...     {"value": "world", "label": 1, "tag": "tag2"},
             ... ])
         """
+        if_exists = kwargs.get("if_exists", "error")
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=kwargs.get("label_names"),
+            embedding_model=kwargs.get("embedding_model"),
+        )
+        if existing is not None:
+            return existing
+
         datasource = Datasource.from_list(f"{name}_datasource", data, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
     @classmethod
-    def from_dict(cls, name: str, data: dict, **kwargs: Any) -> LabeledMemoryset:
+    def from_dict(
+        cls,
+        name: str,
+        data: dict,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_dict(
+        cls,
+        name: str,
+        data: dict,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
+    @classmethod
+    def from_dict(
+        cls,
+        name: str,
+        data: dict,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a dictionary of columns in the OrcaCloud
 
@@ -547,8 +1065,9 @@ class LabeledMemoryset:
         Params:
             name: Name for the new memoryset (must be unique)
             data: Dictionary of columns to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
-                [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
+                [`create`][orca_sdk.memoryset.MemorysetBase.create] attributes for details.
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
@@ -560,11 +1079,53 @@ class LabeledMemoryset:
             ...     "tag": ["tag1", "tag2"],
             ... })
         """
+        if_exists = kwargs.get("if_exists", "error")
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=kwargs.get("label_names"),
+            embedding_model=kwargs.get("embedding_model"),
+        )
+        if existing is not None:
+            return existing
+
         datasource = Datasource.from_dict(f"{name}_datasource", data, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
     @classmethod
-    def from_pandas(cls, name: str, dataframe: pd.DataFrame, **kwargs: Any) -> LabeledMemoryset:
+    def from_pandas(
+        cls,
+        name: str,
+        dataframe: pd.DataFrame,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_pandas(
+        cls,
+        name: str,
+        dataframe: pd.DataFrame,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
+    @classmethod
+    def from_pandas(
+        cls,
+        name: str,
+        dataframe: pd.DataFrame,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a pandas [`DataFrame`][pandas.DataFrame] in the OrcaCloud
 
@@ -577,17 +1138,60 @@ class LabeledMemoryset:
         Params:
             name: Name for the new memoryset (must be unique)
             dataframe: Dataframe to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
-                [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
+                [`create`][orca_sdk.memoryset.MemorysetBase.create] attributes for details.
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
         """
+        if_exists = kwargs.get("if_exists", "error")
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=kwargs.get("label_names"),
+            embedding_model=kwargs.get("embedding_model"),
+        )
+        if existing is not None:
+            return existing
+
         datasource = Datasource.from_pandas(f"{name}_datasource", dataframe, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
+    @classmethod
+    def from_arrow(
+        cls,
+        name: str,
+        pyarrow_table: pa.Table,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_arrow(
+        cls,
+        name: str,
+        pyarrow_table: pa.Table,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
     @classmethod
-    def from_arrow(cls, name: str, pyarrow_table: pa.Table, **kwargs: Any) -> LabeledMemoryset:
+    def from_arrow(
+        cls,
+        name: str,
+        pyarrow_table: pa.Table,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a PyArrow [`Table`][pyarrow.Table] in the OrcaCloud
 
@@ -600,19 +1204,62 @@ class LabeledMemoryset:
         Params:
             name: Name for the new memoryset (must be unique)
             pyarrow_table: PyArrow table to create the memoryset from
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
-                [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
+                [`create`][orca_sdk.memoryset.MemorysetBase.create] attributes for details.
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
         """
+        if_exists = kwargs.get("if_exists", "error")
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=kwargs.get("label_names"),
+            embedding_model=kwargs.get("embedding_model"),
+        )
+        if existing is not None:
+            return existing
+
         datasource = Datasource.from_arrow(
             f"{name}_datasource", pyarrow_table, if_exists=kwargs.get("if_exists", "error")
         )
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
+    @overload
     @classmethod
-    def from_disk(cls, name: str, file_path: str | PathLike, **kwargs: Any) -> LabeledMemoryset:
+    def from_disk(
+        cls,
+        name: str,
+        file_path: str | PathLike,
+        *,
+        background: Literal[True],
+        **kwargs: Any,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def from_disk(
+        cls,
+        name: str,
+        file_path: str | PathLike,
+        *,
+        background: Literal[False] = False,
+        **kwargs: Any,
+    ) -> Self:
+        pass
+
+    @classmethod
+    def from_disk(
+        cls,
+        name: str,
+        file_path: str | PathLike,
+        *,
+        background: bool = False,
+        **kwargs: Any,
+    ) -> Self | Job[Self]:
         """
         Create a new memoryset from a file on disk in the OrcaCloud
 
@@ -632,17 +1279,29 @@ class LabeledMemoryset:
                 - .csv: [`CSV`][csv] files
                 - .parquet: [`Parquet`][pyarrow.parquet.ParquetFile] files
                 - dataset directory: Directory containing a saved HuggingFace [`Dataset`][datasets.Dataset]
+            background: Whether to run the operation in the background
             kwargs: Additional parameters for creating the memoryset. See
-                [`create`][orca_sdk.LabeledMemoryset.create] attributes for details.
+                [`create`][orca_sdk.memoryset.MemorysetBase.create] attributes for details.
 
         Returns:
             Handle to the new memoryset in the OrcaCloud
         """
+        if_exists = kwargs.get("if_exists", "error")
+        existing = cls._handle_if_exists(
+            name,
+            if_exists=if_exists,
+            label_names=kwargs.get("label_names"),
+            embedding_model=kwargs.get("embedding_model"),
+        )
+        if existing is not None:
+            return existing
+
         datasource = Datasource.from_disk(f"{name}_datasource", file_path, if_exists=kwargs.get("if_exists", "error"))
+        kwargs["background"] = background
         return cls.create(name, datasource, **kwargs)
 
     @classmethod
-    def open(cls, name: str) -> LabeledMemoryset:
+    def open(cls, name: str) -> Self:
         """
         Get a handle to a memoryset in the OrcaCloud
 
@@ -655,7 +1314,26 @@ class LabeledMemoryset:
         Raises:
             LookupError: If the memoryset does not exist
         """
-        metadata = get_memoryset(name)
+        client = OrcaClient._resolve_client()
+        metadata = client.GET("/memoryset/{name_or_id}", params={"name_or_id": name})
+        return cls(metadata)
+
+    @classmethod
+    async def aopen(cls, name: str) -> Self:
+        """
+        Asynchronously get a handle to a memoryset in the OrcaCloud
+
+        Params:
+            name: Name or unique identifier of the memoryset
+
+        Returns:
+            Handle to the existing memoryset in the OrcaCloud
+
+        Raises:
+            LookupError: If the memoryset does not exist
+        """
+        client = OrcaAsyncClient._resolve_client()
+        metadata = await client.GET("/memoryset/{name_or_id}", params={"name_or_id": name})
         return cls(metadata)
 
     @classmethod
@@ -676,14 +1354,21 @@ class LabeledMemoryset:
             return False
 
     @classmethod
-    def all(cls) -> list[LabeledMemoryset]:
+    def all(cls, show_hidden: bool = False) -> list[Self]:
         """
         Get a list of handles to all memorysets in the OrcaCloud
 
+        Params:
+            show_hidden: Whether to include hidden memorysets in results, defaults to `False`
+
         Returns:
             List of handles to all memorysets in the OrcaCloud
         """
-        return [cls(metadata) for metadata in list_memorysets()]
+        client = OrcaClient._resolve_client()
+        return [
+            cls(metadata)
+            for metadata in client.GET("/memoryset", params={"type": cls.memory_type, "show_hidden": show_hidden})
+        ]
 
     @classmethod
     def drop(cls, name_or_id: str, if_not_exists: DropMode = "error"):
@@ -699,29 +1384,94 @@ class LabeledMemoryset:
             LookupError: If the memoryset does not exist and if_not_exists is `"error"`
         """
         try:
-            delete_memoryset(name_or_id)
+            client = OrcaClient._resolve_client()
+            client.DELETE("/memoryset/{name_or_id}", params={"name_or_id": name_or_id})
             logging.info(f"Deleted memoryset {name_or_id}")
         except LookupError:
             if if_not_exists == "error":
                 raise
 
+    def set(
+        self,
+        *,
+        name: str = UNSET,
+        description: str | None = UNSET,
+        label_names: list[str] = UNSET,
+        hidden: bool = UNSET,
+    ):
+        """
+        Update editable attributes of the memoryset
+
+        Note:
+            If a field is not provided, it will default to [UNSET][orca_sdk.UNSET] and not be updated.
+
+        Params:
+            description: Value to set for the description
+            name: Value to set for the name
+            label_names: Value to replace existing label names with
+        """
+        payload: MemorysetUpdate = {}
+        if name is not UNSET:
+            payload["name"] = name
+        if description is not UNSET:
+            payload["description"] = description
+        if label_names is not UNSET:
+            payload["label_names"] = label_names
+        if hidden is not UNSET:
+            payload["hidden"] = hidden
+
+        client = OrcaClient._resolve_client()
+        client.PATCH("/memoryset/{name_or_id}", params={"name_or_id": self.id}, json=payload)
+        self.refresh()
+
+    @overload
     def clone(
         self,
         name: str,
         *,
         embedding_model: PretrainedEmbeddingModel | FinetunedEmbeddingModel | None = None,
         max_seq_length_override: int | None = None,
+        prompt: str | None = None,
         if_exists: CreateMode = "error",
-    ) -> LabeledMemoryset:
+        background: Literal[True],
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    def clone(
+        self,
+        name: str,
+        *,
+        embedding_model: PretrainedEmbeddingModel | FinetunedEmbeddingModel | None = None,
+        max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        if_exists: CreateMode = "error",
+        background: Literal[False] = False,
+    ) -> Self:
+        pass
+
+    def clone(
+        self,
+        name: str,
+        *,
+        embedding_model: PretrainedEmbeddingModel | FinetunedEmbeddingModel | None = None,
+        max_seq_length_override: int | None = UNSET,
+        prompt: str | None = None,
+        if_exists: CreateMode = "error",
+        background: bool = False,
+    ) -> Self | Job[Self]:
         """
         Create a clone of the memoryset with a new name
 
         Params:
             name: Name for the new memoryset (must be unique)
             embedding_model: Optional new embedding model to use for re-embedding the memory values
-            max_seq_length_override: Maximum sequence length of values in the memoryset, if the
                 value is longer than this it will be truncated, will default to the model's max
                 sequence length if not provided
+            max_seq_length_override: Optional custom max sequence length to use for the cloned memoryset.
+                If not provided, will use the source memoryset's max sequence length.
+            prompt: Optional custom prompt to use for the cloned memoryset.
+                If not provided, will use the source memoryset's prompt.
             if_exists: What to do if a memoryset with the same name already exists, defaults to
                 `"error"`. Other option is `"open"` to open the existing memoryset.
 
@@ -736,6 +1486,13 @@ class LabeledMemoryset:
             >>> new_memoryset = memoryset.clone(
             ...     "my_memoryset_finetuned", embedding_model=finetuned_embedding_model,
             ... )
+
+            >>> # Clone with custom prompts
+            >>> new_memoryset = memoryset.clone(
+            ...     "my_memoryset_with_prompts",
+            ...     document_prompt_override="Represent this document for retrieval:",
+            ...     query_prompt_override="Represent this query for retrieval:",
+            ... )
         """
         if self.exists(name):
             if if_exists == "error":
@@ -746,22 +1503,23 @@ class LabeledMemoryset:
                     if locals()[attribute] is not None and locals()[attribute] != getattr(existing, attribute):
                         raise ValueError(f"Memoryset with name {name} already exists with a different {attribute}.")
                 return existing
-
-        metadata = clone_memoryset(
-            self.id,
-            body=CloneLabeledMemorysetRequest(
-                name=name,
-                pretrained_embedding_model_name=(
-                    embedding_model._model_name if isinstance(embedding_model, PretrainedEmbeddingModel) else None
-                ),
-                finetuned_embedding_model_id=(
-                    embedding_model.id if isinstance(embedding_model, FinetunedEmbeddingModel) else None
-                ),
-                max_seq_length_override=max_seq_length_override,
-            ),
+        payload: CloneMemorysetRequest = {"name": name}
+        if max_seq_length_override is not UNSET:
+            payload["max_seq_length_override"] = max_seq_length_override
+        if prompt is not None:
+            payload["prompt"] = prompt
+        if isinstance(embedding_model, PretrainedEmbeddingModel):
+            payload["pretrained_embedding_model_name"] = embedding_model.name
+        elif isinstance(embedding_model, FinetunedEmbeddingModel):
+            payload["finetuned_embedding_model_name_or_id"] = embedding_model.id
+
+        client = OrcaClient._resolve_client()
+        metadata = client.POST("/memoryset/{name_or_id}/clone", params={"name_or_id": self.id}, json=payload)
+        job = Job(
+            metadata["insertion_task_id"],
+            lambda: self.open(metadata["id"]),
         )
-        wait_for_task(metadata.insertion_task_id, description="Cloning memoryset")
-        return LabeledMemoryset.open(metadata.id)
+        return job if background else job.result()
 
     def refresh(self, throttle: float = 0):
         """
@@ -775,7 +1533,7 @@ class LabeledMemoryset:
         if (current_time - self._last_refresh) < timedelta(seconds=throttle):
             return
 
-        self.__dict__.update(LabeledMemoryset.open(self.id).__dict__)
+        self.__dict__.update(self.open(self.id).__dict__)
         self._last_refresh = current_time
 
     def __len__(self) -> int:
@@ -784,14 +1542,14 @@ class LabeledMemoryset:
         return self.length
 
     @overload
-    def __getitem__(self, index: int | str) -> LabeledMemory:
+    def __getitem__(self, index: int | str) -> MemoryT:
         pass
 
     @overload
-    def __getitem__(self, index: slice) -> list[LabeledMemory]:
+    def __getitem__(self, index: slice) -> list[MemoryT]:
         pass
 
-    def __getitem__(self, index: int | slice | str) -> LabeledMemory | list[LabeledMemory]:
+    def __getitem__(self, index: int | slice | str) -> MemoryT | list[MemoryT]:
         """
         Get memories from the memoryset by index or memory id
 
@@ -837,22 +1595,24 @@ class LabeledMemoryset:
             raise ValueError(f"Invalid index type: {type(index)}")
 
     @overload
-    def search(self, query: str, *, count: int = 1) -> list[LabeledMemoryLookup]:
+    def search(self, query: str, *, count: int = 1, prompt: str | None = None) -> list[MemoryLookupT]:
         pass
 
     @overload
-    def search(self, query: list[str], *, count: int = 1) -> list[list[LabeledMemoryLookup]]:
+    def search(self, query: list[str], *, count: int = 1, prompt: str | None = None) -> list[list[MemoryLookupT]]:
         pass
 
     def search(
-        self, query: str | list[str], *, count: int = 1
-    ) -> list[LabeledMemoryLookup] | list[list[LabeledMemoryLookup]]:
+        self, query: str | list[str], *, count: int = 1, prompt: str | None = None
+    ) -> list[MemoryLookupT] | list[list[MemoryLookupT]]:
         """
         Search for memories that are semantically similar to the query
 
         Params:
             query: Query to lookup memories in the memoryset, can be a single query or a list
             count: Number of memories to return for each query
+            prompt: Optional prompt for query embedding during search.
+                If not provided, the memoryset's default query prompt will be used if available.
 
         Returns:
             List of memories from the memoryset that match the query. If a single query is provided,
@@ -867,6 +1627,13 @@ class LabeledMemoryset:
                 LabeledMemoryLookup({ label: <positive: 1>, value: 'I am content' }),
             ]
 
+            Search with custom query prompt for instruction-following models:
+            >>> memoryset.search("I am happy", count=2, query_prompt="Represent this query for sentiment retrieval:")
+            [
+                LabeledMemoryLookup({ label: <positive: 1>, value: 'I am happy' }),
+                LabeledMemoryLookup({ label: <positive: 1>, value: 'I am content' }),
+            ]
+
             Search for similar memories for multiple queries:
             >>> memoryset.search(["I am happy", "I am sad"], count=1)
             [
@@ -878,14 +1645,30 @@ class LabeledMemoryset:
                 ],
             ]
         """
-        response = memoryset_lookup_gpu(
-            name_or_id=self.id,
-            body=LookupRequest(
-                query=query if isinstance(query, list) else [query],
-                count=count,
-            ),
+        client = OrcaClient._resolve_client()
+        response = client.POST(
+            "/gpu/memoryset/{name_or_id}/lookup",
+            params={"name_or_id": self.id},
+            json={
+                "query": query if isinstance(query, list) else [query],
+                "count": count,
+                "prompt": prompt,
+            },
         )
-        lookups = [[LabeledMemoryLookup(self.id, lookup_response) for lookup_response in batch] for batch in response]
+        lookups = [
+            [
+                cast(
+                    MemoryLookupT,
+                    (
+                        LabeledMemoryLookup(self.id, lookup_response)
+                        if "label" in lookup_response
+                        else ScoredMemoryLookup(self.id, lookup_response)
+                    ),
+                )
+                for lookup_response in batch
+            ]
+            for batch in response
+        ]
         return lookups if isinstance(query, list) else lookups[0]
 
     def query(
@@ -893,7 +1676,9 @@ class LabeledMemoryset:
         offset: int = 0,
         limit: int = 100,
         filters: list[FilterItemTuple] = [],
-    ) -> list[LabeledMemory]:
+        with_feedback_metrics: bool = False,
+        sort: list[TelemetrySortItem] | None = None,
+    ) -> list[MemoryT]:
         """
         Query the memoryset for memories that match the filters
 
@@ -901,6 +1686,7 @@ class LabeledMemoryset:
             offset: The offset of the first memory to return
             limit: The maximum number of memories to return
             filters: List of filters to apply to the query.
+            with_feedback_metrics: Whether to include feedback metrics in the response
 
         Returns:
             List of memories from the memoryset that match the filters
@@ -912,21 +1698,78 @@ class LabeledMemoryset:
                 LabeledMemory({ label: <negative: 0>, value: "I am sad" }),
             ]
         """
+        parsed_filters = [
+            _parse_filter_item_from_tuple(filter) if isinstance(filter, tuple) else filter for filter in filters
+        ]
+
+        if with_feedback_metrics:
+            client = OrcaClient._resolve_client()
+            response = client.POST(
+                "/telemetry/memories",
+                json={
+                    "memoryset_id": self.id,
+                    "offset": offset,
+                    "limit": limit,
+                    "filters": parsed_filters,
+                    "sort": [_parse_sort_item_from_tuple(item) for item in sort] if sort else None,
+                },
+            )
+            return [
+                cast(
+                    MemoryT,
+                    (LabeledMemory(self.id, memory) if "label" in memory else ScoredMemory(self.id, memory)),
+                )
+                for memory in response["items"]
+            ]
+
+        if any(_is_metric_column(filter[0]) for filter in filters):
+            raise ValueError("Feedback metrics are only supported when the with_feedback_metrics flag is set to True")
+
+        if sort:
+            logging.warning("Sorting is not supported when with_feedback_metrics is False. Sort value will be ignored.")
+
+        client = OrcaClient._resolve_client()
+        response = client.POST(
+            "/memoryset/{name_or_id}/memories",
+            params={"name_or_id": self.id},
+            json={
+                "offset": offset,
+                "limit": limit,
+                "filters": cast(list[FilterItem], parsed_filters),
+            },
+        )
         return [
-            LabeledMemory(self.id, memory)
-            for memory in query_memoryset(
-                self.id,
-                body=ListMemoriesRequest(
-                    offset=offset,
-                    limit=limit,
-                    filters=[
-                        _parse_filter_item_from_tuple(filter) if isinstance(filter, tuple) else filter
-                        for filter in filters
-                    ],
-                ),
+            cast(
+                MemoryT,
+                (LabeledMemory(self.id, memory) if "label" in memory else ScoredMemory(self.id, memory)),
             )
+            for memory in response
         ]
 
+    def to_pandas(
+        self,
+        offset: int = 0,
+        limit: int = 100,
+        filters: list[FilterItemTuple] = [],
+        with_feedback_metrics: bool = False,
+        sort: list[TelemetrySortItem] | None = None,
+    ) -> pd.DataFrame:
+        """
+        Convert the memoryset to a pandas DataFrame
+        """
+        return pd.DataFrame(
+            [
+                memory.to_dict()
+                for memory in self.query(
+                    offset=offset,
+                    limit=limit,
+                    filters=filters,
+                    with_feedback_metrics=with_feedback_metrics,
+                    sort=sort,
+                )
+            ]
+        )
+
     def insert(self, items: Iterable[dict[str, Any]] | dict[str, Any]) -> None:
         """
         Insert memories into the memoryset
@@ -937,6 +1780,7 @@ class LabeledMemoryset:
 
                 - `value`: Value of the memory
                 - `label`: Label of the memory
+                - `score`: Score of the memory
                 - `source_id`: Optional unique ID of the memory in a system of reference
                 - `...`: Any other metadata to store for the memory
 
@@ -946,26 +1790,83 @@ class LabeledMemoryset:
             ...     {"value": "I am sad", "label": 0, "source_id": "user_124", "tag": "sad"},
             ... ])
         """
-        insert_memories_gpu(
-            self.id,
-            body=(
-                [
-                    _parse_memory_insert(memory)
-                    for memory in (cast(list[dict[str, Any]], [items]) if isinstance(items, dict) else items)
-                ]
-            ),
-        )
+        client = OrcaClient._resolve_client()
+        items = cast(list[dict[str, Any]], [items]) if isinstance(items, dict) else list(items)
+        # insert memories in batches to avoid API timeouts
+        for i in range(0, len(items), self._batch_size):
+            batch = items[i : i + self._batch_size]
+            client.POST(
+                "/gpu/memoryset/{name_or_id}/memory",
+                params={"name_or_id": self.id},
+                json=cast(
+                    list[LabeledMemoryInsert] | list[ScoredMemoryInsert],
+                    [_parse_memory_insert(item, type=self.memory_type) for item in batch],
+                ),
+            )
+
         self.refresh()
 
+    async def ainsert(self, items: Iterable[dict[str, Any]] | dict[str, Any]) -> None:
+        """
+        Asynchronously insert memories into the memoryset
+
+        Params:
+            items: List of memories to insert into the memoryset. This should be a list of
+                dictionaries with the following keys:
+
+                - `value`: Value of the memory
+                - `label`: Label of the memory
+                - `score`: Score of the memory
+                - `source_id`: Optional unique ID of the memory in a system of reference
+                - `...`: Any other metadata to store for the memory
+
+        Examples:
+            >>> await memoryset.ainsert([
+            ...     {"value": "I am happy", "label": 1, "source_id": "user_123", "tag": "happy"},
+            ...     {"value": "I am sad", "label": 0, "source_id": "user_124", "tag": "sad"},
+            ... ])
+        """
+        client = OrcaAsyncClient._resolve_client()
+        items = cast(list[dict[str, Any]], [items]) if isinstance(items, dict) else list(items)
+        # insert memories in batches to avoid API timeouts
+        for i in range(0, len(items), self._batch_size):
+            batch = items[i : i + self._batch_size]
+            await client.POST(
+                "/gpu/memoryset/{name_or_id}/memory",
+                params={"name_or_id": self.id},
+                json=cast(
+                    list[LabeledMemoryInsert] | list[ScoredMemoryInsert],
+                    [_parse_memory_insert(item, type=self.memory_type) for item in batch],
+                ),
+            )
+
+        await self.arefresh()
+
+    async def arefresh(self, throttle: float = 0):
+        """
+        Asynchronously refresh the information about the memoryset from the OrcaCloud
+
+        Params:
+            throttle: Minimum time in seconds between refreshes
+        """
+        current_time = datetime.now()
+        # Skip refresh if last refresh was too recent
+        if (current_time - self._last_refresh) < timedelta(seconds=throttle):
+            return
+
+        refreshed_memoryset = await type(self).aopen(self.id)
+        self.__dict__.update(refreshed_memoryset.__dict__)
+        self._last_refresh = current_time
+
     @overload
-    def get(self, memory_id: str) -> LabeledMemory:  # type: ignore -- this takes precedence
+    def get(self, memory_id: str) -> MemoryT:  # type: ignore -- this takes precedence
         pass
 
     @overload
-    def get(self, memory_id: Iterable[str]) -> list[LabeledMemory]:
+    def get(self, memory_id: Iterable[str]) -> list[MemoryT]:
         pass
 
-    def get(self, memory_id: str | Iterable[str]) -> LabeledMemory | list[LabeledMemory]:
+    def get(self, memory_id: str | Iterable[str]) -> MemoryT | list[MemoryT]:
         """
         Fetch a memory or memories from the memoryset
 
@@ -994,22 +1895,38 @@ class LabeledMemoryset:
             ]
         """
         if isinstance(memory_id, str):
-            return LabeledMemory(self.id, get_memory(self.id, memory_id))
+            client = OrcaClient._resolve_client()
+            response = client.GET(
+                "/memoryset/{name_or_id}/memory/{memory_id}", params={"name_or_id": self.id, "memory_id": memory_id}
+            )
+            return cast(
+                MemoryT,
+                (LabeledMemory(self.id, response) if "label" in response else ScoredMemory(self.id, response)),
+            )
         else:
+            client = OrcaClient._resolve_client()
+            response = client.POST(
+                "/memoryset/{name_or_id}/memories/get",
+                params={"name_or_id": self.id},
+                json={"memory_ids": list(memory_id)},
+            )
             return [
-                LabeledMemory(self.id, memory)
-                for memory in get_memories(self.id, body=GetMemoriesRequest(memory_ids=list(memory_id)))
+                cast(
+                    MemoryT,
+                    (LabeledMemory(self.id, memory) if "label" in memory else ScoredMemory(self.id, memory)),
+                )
+                for memory in response
             ]
 
     @overload
-    def update(self, updates: dict[str, Any]) -> LabeledMemory:
+    def update(self, updates: dict[str, Any]) -> MemoryT:
         pass
 
     @overload
-    def update(self, updates: Iterable[dict[str, Any]]) -> list[LabeledMemory]:
+    def update(self, updates: Iterable[dict[str, Any]]) -> list[MemoryT]:
         pass
 
-    def update(self, updates: dict[str, Any] | Iterable[dict[str, Any]]) -> LabeledMemory | list[LabeledMemory]:
+    def update(self, updates: dict[str, Any] | Iterable[dict[str, Any]]) -> MemoryT | list[MemoryT]:
         """
         Update one or multiple memories in the memoryset
 
@@ -1041,16 +1958,87 @@ class LabeledMemoryset:
             ...     for m in memoryset.query(filters=[("tag", "==", "happy")])
             ... )
         """
-        response = update_memories_gpu(
-            self.id,
-            body=[
-                _parse_memory_update(update)
-                for update in (cast(list[dict[str, Any]], [updates]) if isinstance(updates, dict) else updates)
-            ],
-        )
-        updated_memories = [LabeledMemory(self.id, memory) for memory in response]
+        client = OrcaClient._resolve_client()
+        updates_list = cast(list[dict[str, Any]], [updates]) if isinstance(updates, dict) else list(updates)
+        # update memories in batches to avoid API timeouts
+        updated_memories: list[MemoryT] = []
+        for i in range(0, len(updates_list), self._batch_size):
+            batch = updates_list[i : i + self._batch_size]
+            response = client.PATCH(
+                "/gpu/memoryset/{name_or_id}/memories",
+                params={"name_or_id": self.id},
+                json=cast(
+                    list[LabeledMemoryUpdate] | list[ScoredMemoryUpdate],
+                    [_parse_memory_update(update, type=self.memory_type) for update in batch],
+                ),
+            )
+            updated_memories.extend(
+                cast(
+                    MemoryT,
+                    (LabeledMemory(self.id, memory) if "label" in memory else ScoredMemory(self.id, memory)),
+                )
+                for memory in response
+            )
+
         return updated_memories[0] if isinstance(updates, dict) else updated_memories
 
+    def get_cascading_edits_suggestions(
+        self,
+        memory: MemoryT,
+        *,
+        old_label: int,
+        new_label: int,
+        max_neighbors: int = 50,
+        max_validation_neighbors: int = 10,
+        similarity_threshold: float | None = None,
+        only_if_has_old_label: bool = True,
+        exclude_if_new_label: bool = True,
+        suggestion_cooldown_time: float = 3600.0 * 24.0,  # 1 day
+        label_confirmation_cooldown_time: float = 3600.0 * 24.0 * 7,  # 1 week
+    ) -> list[CascadingEditSuggestion]:
+        """
+        Suggests cascading edits for a given memory based on nearby points with similar labels.
+
+        This function is triggered after a user changes a memory's label. It looks for nearby
+        candidates in embedding space that may be subject to similar relabeling and returns them
+        as suggestions. The system uses scoring heuristics, label filters, and cooldown tracking
+        to reduce noise and improve usability.
+
+        Params:
+            memory: The memory whose label was just changed.
+            old_label: The label this memory used to have.
+            new_label: The label it was changed to.
+            max_neighbors: Maximum number of neighbors to consider.
+            max_validation_neighbors: Maximum number of neighbors to use for label suggestion.
+            similarity_threshold: If set, only include neighbors with a lookup score above this threshold.
+            only_if_has_old_label: If True, only consider neighbors that have the old label.
+            exclude_if_new_label: If True, exclude neighbors that already have the new label.
+            suggestion_cooldown_time: Minimum time (in seconds) since the last suggestion for a neighbor
+                to be considered again.
+            label_confirmation_cooldown_time: Minimum time (in seconds) since a neighbor's label was confirmed
+                to be considered for suggestions.
+
+        Returns:
+            A list of CascadingEditSuggestion objects, each containing a neighbor and the suggested new label.
+        """
+        # TODO: properly integrate this with memory edits and return something that can be applied
+        client = OrcaClient._resolve_client()
+        return client.POST(
+            "/memoryset/{name_or_id}/memory/{memory_id}/cascading_edits",
+            params={"name_or_id": self.id, "memory_id": memory.memory_id},
+            json={
+                "old_label": old_label,
+                "new_label": new_label,
+                "max_neighbors": max_neighbors,
+                "max_validation_neighbors": max_validation_neighbors,
+                "similarity_threshold": similarity_threshold,
+                "only_if_has_old_label": only_if_has_old_label,
+                "exclude_if_new_label": exclude_if_new_label,
+                "suggestion_cooldown_time": suggestion_cooldown_time,
+                "label_confirmation_cooldown_time": label_confirmation_cooldown_time,
+            },
+        )
+
     def delete(self, memory_id: str | Iterable[str]) -> None:
         """
         Delete memories from the memoryset
@@ -1069,57 +2057,75 @@ class LabeledMemoryset:
             ... )
 
         """
+        client = OrcaClient._resolve_client()
         memory_ids = [memory_id] if isinstance(memory_id, str) else list(memory_id)
-        delete_memories(self.id, body=DeleteMemoriesRequest(memory_ids=memory_ids))
+        # delete memories in batches to avoid API timeouts
+        for i in range(0, len(memory_ids), self._batch_size):
+            batch = memory_ids[i : i + self._batch_size]
+            client.POST(
+                "/memoryset/{name_or_id}/memories/delete", params={"name_or_id": self.id}, json={"memory_ids": batch}
+            )
         logging.info(f"Deleted {len(memory_ids)} memories from memoryset.")
         self.refresh()
 
-    def find_duplicates(self) -> dict:
+    @overload
+    def analyze(
+        self,
+        *analyses: dict[str, Any] | str,
+        lookup_count: int = 15,
+        clear_metrics: bool = False,
+        background: Literal[True],
+    ) -> Job[MemorysetMetrics]:
+        pass
+
+    @overload
+    def analyze(
+        self,
+        *analyses: dict[str, Any] | str,
+        lookup_count: int = 15,
+        clear_metrics: bool = False,
+        background: Literal[False] = False,
+    ) -> MemorysetMetrics:
+        pass
+
+    def analyze(
+        self,
+        *analyses: dict[str, Any] | str,
+        lookup_count: int = 15,
+        clear_metrics: bool = False,
+        background: bool = False,
+    ) -> Job[MemorysetMetrics] | MemorysetMetrics:
         """
-        Run an analysis to find duplicate memories in the memoryset
+        Run analyses on the memoryset to find duplicates, clusters, mislabelings, and more
 
         The results of the analysis will be stored in the [`LabeledMemory.metrics`][orca_sdk.LabeledMemory]
-        attribute of each memory in the memoryset.
+        attribute of each memory in the memoryset. Overall memoryset metrics will be returned as a dictionary.
 
-        Returns:
-            Summary of analysis with number of duplicate memories found
-
-        Examples:
-            >>> memoryset.find_duplicate_memories()
-            { "num_duplicates": 10 }
-            >>> memoryset.delete(
-            ...     m.memory_id
-            ...     for m in memoryset.query(
-            ...         filters=[("metrics.is_duplicate", "==", True)]
-            ...     )
-            ... )
-        """
-        analysis = create_analysis(
-            self.id,
-            body=MemorysetAnalysisRequest(
-                type=MemorysetAnalysisRequestType.ANALYZE_DUPLICATE_MEMORIES,
-            ),
-        )
-        wait_for_task(analysis.task_id, description="Analyzing duplicates")
-        analysis = get_analysis(self.id, analysis.task_id)
-        assert isinstance(analysis.result, FindDuplicatesAnalysisResult)
-        # TODO: return a custom duplicate analysis class instance with helper methods
-        return analysis.result.to_dict()
+        Params:
+            analyses: List of analysis to run on the memoryset, can either be just the name of an
+                analysis or a dictionary with a name property and additional config. The available
+                analyses are:
 
-    def analyze_labels(self, neighbor_count: int = 10) -> dict:
-        """
-        Run an analysis to access if the labels in the memoryset are consistent to detect possibly
-        mislabeled memories.
+                - **`"duplicate"`**: Find potentially duplicate memories in the memoryset
+                - **`"cluster"`**: Cluster the memories in the memoryset
+                - **`"label"`**: Analyze the labels to find potential mislabelings
+                - **`"distribution"`**: Analyze the embedding distribution to populate
+                - **`"projection"`**: Create a 2D projection of the embeddings for visualization
 
-        The results of the analysis will be stored in the [`LabeledMemory.metrics`][orca_sdk.LabeledMemory]
-        attribute of each memory in the memoryset.
+            lookup_count: Number of memories to lookup for each memory in the memoryset
+            clear_metrics: Whether to clear any existing metrics from the memories before running the analysis
 
         Returns:
-            Summary of analysis with aggregate metrics for each label class
+            dictionary with aggregate metrics for each analysis that was run
+
+        Raises:
+            ValueError: If an invalid analysis name is provided
 
         Examples:
-            >>> memoryset.analyze_labels()
-            {
+            Run label and duplicate analysis:
+            >>> memoryset.analyze("label", {"name": "duplicate", "possible_duplicate_threshold": 0.99})
+            { "duplicate": { "num_duplicates": 10 },
+              "label": {
                 "label_metrics": [{
                     "label": 0,
                     "label_name": "negative",
@@ -1131,24 +2137,384 @@ class LabeledMemoryset:
                     "average_lookup_score": 0.90,
                     "memory_count": 100,
                 }]
+                "neighbor_prediction_accuracy": 0.95,
+                "mean_neighbor_label_confidence": 0.95,
+                "mean_neighbor_label_entropy": 0.95,
+                "mean_neighbor_predicted_label_ambiguity": 0.95,
+              }
             }
+
+            Remove all exact duplicates:
+            >>> memoryset.delete(
+            ...     m.memory_id
+            ...     for m in memoryset.query(
+            ...         filters=[("metrics.is_duplicate", "==", True)]
+            ...     )
+            ... )
+
+            Display label analysis to review potential mislabelings:
             >>> memoryset.display_label_analysis()
         """
-        analysis = create_analysis(
-            self.id,
-            body=MemorysetAnalysisRequest(
-                type=MemorysetAnalysisRequestType.ANALYZE_MEMORY_NEIGHBOR_LABELS,
-                neighbor_count=neighbor_count,
-            ),
+
+        # Get valid analysis names from MemorysetAnalysisConfigs
+        valid_analysis_names = set(MemorysetAnalysisConfigs.__annotations__)
+
+        configs: MemorysetAnalysisConfigs = {}
+        for analysis in analyses:
+            if isinstance(analysis, str):
+                error_msg = (
+                    f"Invalid analysis name: {analysis}. Valid names are: {', '.join(sorted(valid_analysis_names))}"
+                )
+                if analysis not in valid_analysis_names:
+                    raise ValueError(error_msg)
+                configs[analysis] = {}
+            else:
+                name = analysis.pop("name")
+                error_msg = f"Invalid analysis name: {name}. Valid names are: {', '.join(sorted(valid_analysis_names))}"
+                if name not in valid_analysis_names:
+                    raise ValueError(error_msg)
+                configs[name] = analysis
+
+        client = OrcaClient._resolve_client()
+        analysis = client.POST(
+            "/memoryset/{name_or_id}/analysis",
+            params={"name_or_id": self.id},
+            json={
+                "configs": configs,
+                "lookup_count": lookup_count,
+                "clear_metrics": clear_metrics,
+            },
+        )
+
+        def get_analysis_result():
+            client = OrcaClient._resolve_client()
+            return client.GET(
+                "/memoryset/{name_or_id}/analysis/{analysis_task_id}",
+                params={"name_or_id": self.id, "analysis_task_id": analysis["task_id"]},
+            )["results"]
+
+        job = Job(analysis["task_id"], get_analysis_result)
+        return job if background else job.result()
+
+    def get_potential_duplicate_groups(self) -> list[list[MemoryT]]:
+        """Group potential duplicates in the memoryset"""
+        client = OrcaClient._resolve_client()
+        response = client.GET("/memoryset/{name_or_id}/potential_duplicate_groups", params={"name_or_id": self.id})
+        return [
+            [cast(MemoryT, LabeledMemory(self.id, m) if "label" in m else ScoredMemory(self.id, m)) for m in ms]
+            for ms in response
+        ]
+
+
+class LabeledMemoryset(MemorysetBase[LabeledMemory, LabeledMemoryLookup]):
+    """
+    A Handle to a collection of memories with labels in the OrcaCloud
+
+    Attributes:
+        id: Unique identifier for the memoryset
+        name: Unique name of the memoryset
+        description: Description of the memoryset
+        label_names: Names for the class labels in the memoryset
+        length: Number of memories in the memoryset
+        embedding_model: Embedding model used to embed the memory values for semantic search
+        created_at: When the memoryset was created, automatically generated on create
+        updated_at: When the memoryset was last updated, automatically updated on updates
+    """
+
+    label_names: list[str]
+    memory_type: MemoryType = "LABELED"
+
+    def __init__(self, metadata: MemorysetMetadata):
+        super().__init__(metadata)
+        assert metadata["label_names"] is not None
+        self.label_names = metadata["label_names"]
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, LabeledMemoryset) and self.id == other.id
+
+    @overload
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        value_column: str = "value",
+        label_column: str = "label",
+        source_id_column: str | None = None,
+        description: str | None = None,
+        label_names: list[str] | None = None,
+        max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: Literal[True],
+        hidden: bool = False,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        value_column: str = "value",
+        label_column: str = "label",
+        source_id_column: str | None = None,
+        description: str | None = None,
+        label_names: list[str] | None = None,
+        max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: Literal[False] = False,
+        hidden: bool = False,
+    ) -> Self:
+        pass
+
+    @classmethod
+    def create(  # type: ignore[override]
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        value_column: str = "value",
+        label_column: str = "label",
+        source_id_column: str | None = None,
+        description: str | None = None,
+        label_names: list[str] | None = None,
+        max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: bool = False,
+        hidden: bool = False,
+    ) -> Self | Job[Self]:
+        """
+        Create a new labeled memoryset in the OrcaCloud
+
+        All columns from the datasource that are not specified in the `value_column`,
+        `label_column`, or `source_id_column` will be stored as metadata in the memoryset.
+
+        Params:
+            name: Name for the new memoryset (must be unique)
+            datasource: Source data to populate the memories in the memoryset
+            embedding_model: Embedding model to use for embedding memory values for semantic search.
+                If not provided, a default embedding model for the memoryset will be used.
+            value_column: Name of the column in the datasource that contains the memory values
+            label_column: Name of the column in the datasource that contains the memory labels,
+                these must be contiguous integers starting from 0
+            source_id_column: Optional name of the column in the datasource that contains the ids in
+                the system of reference
+            description: Optional description for the memoryset, this will be used in agentic flows,
+                so make sure it is concise and describes the contents of your memoryset not the
+                datasource or the embedding model.
+            label_names: List of human-readable names for the labels in the memoryset, must match
+                the number of labels in the `label_column`. Will be automatically inferred if a
+                [Dataset][datasets.Dataset] with a [`ClassLabel`][datasets.ClassLabel] feature for
+                labels is used as the datasource
+            max_seq_length_override: Maximum sequence length of values in the memoryset, if the
+                value is longer than this it will be truncated, will default to the model's max
+                sequence length if not provided
+            prompt: Optional prompt to use when embedding documents/memories for storage
+            remove_duplicates: Whether to remove duplicates from the datasource before inserting
+                into the memoryset
+            index_type: Type of vector index to use for the memoryset, defaults to `"FLAT"`. Valid
+                values are `"FLAT"`, `"IVF_FLAT"`, `"IVF_SQ8"`, `"IVF_PQ"`, `"HNSW"`, and `"DISKANN"`.
+            index_params: Parameters for the vector index, defaults to `{}`
+            if_exists: What to do if a memoryset with the same name already exists, defaults to
+                `"error"`. Other option is `"open"` to open the existing memoryset.
+            background: Whether to run the operation none blocking and return a job handle
+            hidden: Whether the memoryset should be hidden
+
+        Returns:
+            Handle to the new memoryset in the OrcaCloud
+
+        Raises:
+            ValueError: If the memoryset already exists and if_exists is `"error"` or if it is
+                `"open"` and the params do not match those of the existing memoryset.
+        """
+        return super().create(
+            name,
+            datasource,
+            label_column=label_column,
+            score_column=None,
+            embedding_model=embedding_model,
+            value_column=value_column,
+            source_id_column=source_id_column,
+            description=description,
+            label_names=label_names,
+            max_seq_length_override=max_seq_length_override,
+            prompt=prompt,
+            remove_duplicates=remove_duplicates,
+            index_type=index_type,
+            index_params=index_params,
+            if_exists=if_exists,
+            background=background,
+            hidden=hidden,
         )
-        wait_for_task(analysis.task_id, description="Analyzing labels")
-        analysis = get_analysis(self.id, analysis.task_id)
-        assert isinstance(analysis.result, AnalyzeNeighborLabelsResult)
-        # TODO: return a custom label analysis class instance with helper methods
-        return analysis.result.to_dict()
 
     def display_label_analysis(self):
-        """Display a UI to review and act upon the label analysis results"""
+        """
+        Display an interactive UI to review and act upon the label analysis results
+
+        Note:
+            This method is only available in Jupyter notebooks.
+        """
         from ._utils.analysis_ui import display_suggested_memory_relabels
 
         display_suggested_memory_relabels(self)
+
+
+class ScoredMemoryset(MemorysetBase[ScoredMemory, ScoredMemoryLookup]):
+    """
+    A Handle to a collection of memories with scores in the OrcaCloud
+
+    Attributes:
+        id: Unique identifier for the memoryset
+        name: Unique name of the memoryset
+        description: Description of the memoryset
+        length: Number of memories in the memoryset
+        embedding_model: Embedding model used to embed the memory values for semantic search
+        created_at: When the memoryset was created, automatically generated on create
+        updated_at: When the memoryset was last updated, automatically updated on updates
+    """
+
+    memory_type: MemoryType = "SCORED"
+
+    def __eq__(self, other) -> bool:
+        return isinstance(other, ScoredMemoryset) and self.id == other.id
+
+    @overload
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        value_column: str = "value",
+        score_column: str = "score",
+        source_id_column: str | None = None,
+        description: str | None = None,
+        max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: Literal[True],
+        hidden: bool = False,
+    ) -> Job[Self]:
+        pass
+
+    @overload
+    @classmethod
+    def create(
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        score_column: str = "score",
+        value_column: str = "value",
+        source_id_column: str | None = None,
+        description: str | None = None,
+        max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: Literal[False] = False,
+        hidden: bool = False,
+    ) -> Self:
+        pass
+
+    @classmethod
+    def create(  # type: ignore[override]
+        cls,
+        name: str,
+        datasource: Datasource,
+        *,
+        embedding_model: FinetunedEmbeddingModel | PretrainedEmbeddingModel | None = None,
+        value_column: str = "value",
+        score_column: str = "score",
+        source_id_column: str | None = None,
+        description: str | None = None,
+        max_seq_length_override: int | None = None,
+        prompt: str | None = None,
+        remove_duplicates: bool = True,
+        index_type: IndexType = "FLAT",
+        index_params: dict[str, Any] = {},
+        if_exists: CreateMode = "error",
+        background: bool = False,
+        hidden: bool = False,
+    ) -> Self | Job[Self]:
+        """
+        Create a new scored memoryset in the OrcaCloud
+
+        All columns from the datasource that are not specified in the `value_column`,
+        `score_column`, or `source_id_column` will be stored as metadata in the memoryset.
+
+        Params:
+            name: Name for the new memoryset (must be unique)
+            datasource: Source data to populate the memories in the memoryset
+            embedding_model: Embedding model to use for embedding memory values for semantic search.
+                If not provided, a default embedding model for the memoryset will be used.
+            value_column: Name of the column in the datasource that contains the memory values
+            score_column: Name of the column in the datasource that contains the memory scores
+            source_id_column: Optional name of the column in the datasource that contains the ids in
+                the system of reference
+            description: Optional description for the memoryset, this will be used in agentic flows,
+                so make sure it is concise and describes the contents of your memoryset not the
+                datasource or the embedding model.
+            max_seq_length_override: Maximum sequence length of values in the memoryset, if the
+                value is longer than this it will be truncated, will default to the model's max
+                sequence length if not provided
+            prompt: Optional prompt to use when embedding documents/memories for storage
+            remove_duplicates: Whether to remove duplicates from the datasource before inserting
+                into the memoryset
+            index_type: Type of vector index to use for the memoryset, defaults to `"FLAT"`. Valid
+                values are `"FLAT"`, `"IVF_FLAT"`, `"IVF_SQ8"`, `"IVF_PQ"`, `"HNSW"`, and `"DISKANN"`.
+            index_params: Parameters for the vector index, defaults to `{}`
+            if_exists: What to do if a memoryset with the same name already exists, defaults to
+                `"error"`. Other option is `"open"` to open the existing memoryset.
+            background: Whether to run the operation none blocking and return a job handle
+            hidden: Whether the memoryset should be hidden
+
+        Returns:
+            Handle to the new memoryset in the OrcaCloud
+
+        Raises:
+            ValueError: If the memoryset already exists and if_exists is `"error"` or if it is
+                `"open"` and the params do not match those of the existing memoryset.
+        """
+        return super().create(
+            name,
+            datasource,
+            embedding_model=embedding_model,
+            value_column=value_column,
+            score_column=score_column,
+            source_id_column=source_id_column,
+            description=description,
+            max_seq_length_override=max_seq_length_override,
+            prompt=prompt,
+            remove_duplicates=remove_duplicates,
+            index_type=index_type,
+            index_params=index_params,
+            if_exists=if_exists,
+            background=background,
+            hidden=hidden,
+        )