atomicmemory 1.0.0__py3-none-any.whl

atomicmemory/providers/atomicmemory/provider.py

@@ -0,0 +1,300 @@
+"""Sync AtomicMemoryProvider — V3 core methods + Packager + TemporalSearch + Versioner + Health.
+
+Port of `atomicmemory-sdk/src/memory/atomicmemory-provider/atomicmemory-provider.ts`.
+The handle namespace (lifecycle/audit/lessons/config/agents) is wired in
+Phase 3 via :mod:`atomicmemory.providers.atomicmemory.handle_impl`.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from atomicmemory.core.errors import ProviderError
+from atomicmemory.memory.provider import BaseMemoryProvider
+from atomicmemory.memory.types import (
+    Capabilities,
+    CapabilitiesExtensions,
+    CapabilitiesRequiredScope,
+    ContextPackage,
+    CustomExtensionMeta,
+    HealthStatus,
+    IngestInput,
+    IngestResult,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    MemoryVersion,
+    PackageFormat,
+    PackageRequest,
+    SearchRequest,
+    SearchResult,
+    SearchResultPage,
+)
+from atomicmemory.providers.atomicmemory.config import AtomicMemoryProviderConfig
+from atomicmemory.providers.atomicmemory.handle import ATOMICMEMORY_EXTENSION_NAMES
+from atomicmemory.providers.atomicmemory.handle_impl import AtomicMemoryHandle
+from atomicmemory.providers.atomicmemory.http import (
+    HttpOptions,
+    delete_ignore_404,
+    fetch_json,
+    fetch_json_or_none,
+)
+from atomicmemory.providers.atomicmemory.mappers import (
+    to_ingest_result,
+    to_memory,
+    to_memory_version,
+    to_search_result,
+)
+from atomicmemory.providers.atomicmemory.path import normalize_api_version
+
+_ATOMICMEMORY_CUSTOM_EXTENSIONS: dict[str, CustomExtensionMeta] = {
+    name: CustomExtensionMeta(version="1.0.0") for name in ATOMICMEMORY_EXTENSION_NAMES
+}
+
+
+class AtomicMemoryProvider(BaseMemoryProvider):
+    """Sync HTTP-backed V3 provider for atomicmemory-core."""
+
+    name = "atomicmemory"
+
+    def __init__(self, config: AtomicMemoryProviderConfig) -> None:
+        self._config = config
+        self._http_options = HttpOptions(
+            api_url=config.api_url.rstrip("/"),
+            api_key=config.api_key,
+            timeout_seconds=config.timeout_seconds,
+        )
+        self._api_prefix = normalize_api_version(config.api_version)
+        self._client: httpx.Client | None = None
+        self._handle: AtomicMemoryHandle | None = None
+        self._initialized = False
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def initialize(self) -> None:
+        if self._client is None:
+            self._client = httpx.Client()
+        if self._handle is None:
+            self._handle = AtomicMemoryHandle(self._client, self._http_options, self._route)
+        self._initialized = True
+
+    def close(self) -> None:
+        self._handle = None
+        if self._client is not None:
+            self._client.close()
+            self._client = None
+        self._initialized = False
+
+    # ------------------------------------------------------------------
+    # V3 core methods
+    # ------------------------------------------------------------------
+
+    def do_ingest(self, input: IngestInput) -> IngestResult:
+        body = _build_ingest_body(input)
+        path = self._route("/memories/ingest/quick" if input.mode == "verbatim" else "/memories/ingest")
+        raw = fetch_json(self._require_client(), self._http_options, path, method="POST", json=body)
+        return to_ingest_result(raw)
+
+    def do_search(self, request: SearchRequest) -> SearchResultPage:
+        body = _build_search_body(request)
+        raw = fetch_json(
+            self._require_client(),
+            self._http_options,
+            self._route("/memories/search/fast"),
+            method="POST",
+            json=body,
+        )
+        return SearchResultPage(
+            results=[to_search_result(m, request.scope) for m in raw.get("memories", [])],
+        )
+
+    def do_get(self, ref: MemoryRef) -> Memory | None:
+        path = self._route(f"/memories/{ref.id}?user_id={_qs(ref.scope.user)}")
+        raw = fetch_json_or_none(self._require_client(), self._http_options, path)
+        if raw is None:
+            return None
+        return to_memory(raw, ref.scope)
+
+    def do_delete(self, ref: MemoryRef) -> None:
+        path = self._route(f"/memories/{ref.id}?user_id={_qs(ref.scope.user)}")
+        delete_ignore_404(self._require_client(), self._http_options, path)
+
+    def do_list(self, request: ListRequest) -> ListResultPage:
+        offset = int(request.cursor) if request.cursor else 0
+        limit = request.limit if request.limit is not None else 20
+        path = self._route(f"/memories/list?user_id={_qs(request.scope.user)}&limit={limit}&offset={offset}")
+        raw = fetch_json(self._require_client(), self._http_options, path)
+        memories = [to_memory(m, request.scope) for m in raw.get("memories", [])]
+        next_offset = offset + len(memories)
+        cursor = str(next_offset) if len(memories) == limit else None
+        return ListResultPage(memories=memories, cursor=cursor)
+
+    # ------------------------------------------------------------------
+    # Capabilities + extension dispatch
+    # ------------------------------------------------------------------
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities(
+            ingest_modes=["text", "messages", "verbatim"],
+            required_scope=CapabilitiesRequiredScope(default=["user"]),
+            extensions=CapabilitiesExtensions(
+                package=True,
+                temporal=True,
+                versioning=True,
+                health=True,
+            ),
+            custom_extensions=_ATOMICMEMORY_CUSTOM_EXTENSIONS,
+        )
+
+    def get_extension(self, name: str) -> Any | None:
+        if name in {"package", "temporal", "versioning", "health"}:
+            return self
+        if name == "atomicmemory.base":
+            return self._handle
+        if name == "atomicmemory.lifecycle" and self._handle is not None:
+            return self._handle.lifecycle
+        if name == "atomicmemory.audit" and self._handle is not None:
+            return self._handle.audit
+        if name == "atomicmemory.lessons" and self._handle is not None:
+            return self._handle.lessons
+        if name == "atomicmemory.config" and self._handle is not None:
+            return self._handle.config
+        if name == "atomicmemory.agents" and self._handle is not None:
+            return self._handle.agents
+        return None
+
+    # ------------------------------------------------------------------
+    # V3 extensions implemented inline (`Packager`, `TemporalSearch`,
+    # `Versioner`, `Health`)
+    # ------------------------------------------------------------------
+
+    def package(self, request: PackageRequest) -> ContextPackage:
+        body = _build_package_body(request)
+        raw = fetch_json(
+            self._require_client(),
+            self._http_options,
+            self._route("/memories/search"),
+            method="POST",
+            json=body,
+        )
+        results: list[SearchResult] = [to_search_result(m, request.scope) for m in raw.get("memories", [])]
+        budget_constrained = raw.get("budget_constrained")
+        if not isinstance(budget_constrained, bool):
+            raise ValueError(
+                "atomicmemory provider.package: backend response missing required boolean field `budget_constrained`"
+            )
+        return ContextPackage(
+            text=raw.get("injection_text") or "",
+            results=results,
+            tokens=raw.get("estimated_context_tokens") or 0,
+            budget_constrained=budget_constrained,
+        )
+
+    def search_as_of(self, request: SearchRequest, as_of: datetime) -> SearchResultPage:
+        body = _build_search_body(request)
+        body["as_of"] = as_of.isoformat()
+        raw = fetch_json(
+            self._require_client(),
+            self._http_options,
+            self._route("/memories/search"),
+            method="POST",
+            json=body,
+        )
+        return SearchResultPage(
+            results=[to_search_result(m, request.scope) for m in raw.get("memories", [])],
+        )
+
+    def history(self, ref: MemoryRef) -> list[MemoryVersion]:
+        path = self._route(f"/memories/{ref.id}/audit?user_id={_qs(ref.scope.user)}")
+        raw = fetch_json(self._require_client(), self._http_options, path)
+        return [to_memory_version(entry) for entry in raw.get("trail", [])]
+
+    def health(self) -> HealthStatus:
+        path = self._route("/memories/health")
+        raw = fetch_json(self._require_client(), self._http_options, path)
+        return HealthStatus(ok=raw.get("status") == "ok")
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _route(self, path: str) -> str:
+        return f"{self._api_prefix}{path}"
+
+    def _require_client(self) -> httpx.Client:
+        if self._client is None:
+            raise ProviderError(
+                "AtomicMemoryProvider is not initialized. Call initialize() first.",
+                provider=self.name,
+            )
+        return self._client
+
+
+# ---------------------------------------------------------------------------
+# Body builders — pure functions, shared with the async provider in Phase 4.
+# ---------------------------------------------------------------------------
+
+
+_PACKAGE_FORMAT_TO_RETRIEVAL_MODE: dict[PackageFormat, str] = {
+    "flat": "flat",
+    "tiered": "tiered",
+    "structured": "abstract-aware",
+}
+
+
+def _ingest_input_to_conversation(input: IngestInput) -> str:
+    match input.mode:
+        case "text" | "verbatim":
+            return input.content
+        case "messages":
+            return "\n".join(f"{m.role}: {m.content}" for m in input.messages)
+
+
+def _build_ingest_body(input: IngestInput) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "user_id": input.scope.user,
+        "conversation": _ingest_input_to_conversation(input),
+        "source_site": input.provenance.source if input.provenance and input.provenance.source else "sdk",
+        "source_url": input.provenance.source_url if input.provenance and input.provenance.source_url else "",
+    }
+    if input.mode == "verbatim":
+        body["skip_extraction"] = True
+        if input.metadata:
+            body["metadata"] = input.metadata
+    return body
+
+
+def _build_search_body(request: SearchRequest) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "user_id": request.scope.user,
+        "query": request.query,
+    }
+    if request.limit is not None:
+        body["limit"] = request.limit
+    if request.threshold is not None:
+        body["threshold"] = request.threshold
+    if request.scope.namespace is not None:
+        body["namespace_scope"] = request.scope.namespace
+    return body
+
+
+def _build_package_body(request: PackageRequest) -> dict[str, Any]:
+    body = _build_search_body(request)
+    if request.format is not None:
+        body["retrieval_mode"] = _PACKAGE_FORMAT_TO_RETRIEVAL_MODE[request.format]
+    if request.token_budget is not None:
+        body["token_budget"] = request.token_budget
+    body["skip_repair"] = True
+    return body
+
+
+def _qs(value: str | None) -> str:
+    """URL-encode a query-string value; empty string when falsy."""
+    return quote(value, safe="") if value else ""

atomicmemory/providers/atomicmemory/scope_mapper.py

@@ -0,0 +1,98 @@
+"""Scope mapper for the AtomicMemory namespace.
+
+Port of `atomicmemory-sdk/src/memory/atomicmemory-provider/scope-mapper.ts`.
+Serializes the AtomicMemory-specific :class:`MemoryScope` discriminated
+union to the body/query fields atomicmemory-core expects, with the same
+"agent_scope only on POST search routes" policy.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from atomicmemory.core.errors import ValidationError
+from atomicmemory.providers.atomicmemory.handle import MemoryScope, WorkspaceScope
+
+
+def scope_to_fields(
+    scope: MemoryScope,
+    *,
+    include_agent_scope: bool = False,
+) -> dict[str, Any]:
+    """Translate a `MemoryScope` to wire-format request fields.
+
+    Args:
+        scope: The scope discriminated union.
+        include_agent_scope: Emit ``agent_scope`` on the wire. Defaults
+            to ``False``; only the search routes opt in (core ignores
+            ``agent_scope`` on expand/list/get/delete).
+
+    Returns:
+        A dict with ``user_id`` always set, plus ``workspace_id`` /
+        ``agent_id`` (and optionally ``agent_scope``) for workspace
+        scopes.
+    """
+    if not isinstance(scope, WorkspaceScope):
+        return {"user_id": scope.user_id}
+    fields: dict[str, Any] = {
+        "user_id": scope.user_id,
+        "workspace_id": scope.workspace_id,
+        "agent_id": scope.agent_id,
+    }
+    if include_agent_scope and scope.agent_scope is not None:
+        fields["agent_scope"] = scope.agent_scope
+    return fields
+
+
+def scope_to_query_pairs(
+    scope: MemoryScope,
+    *,
+    include_agent_scope: bool = False,
+) -> list[tuple[str, str]]:
+    """Translate a scope to ``[(key, value)]`` pairs for query strings.
+
+    httpx's ``params=`` accepts a list of pairs, which lets us repeat a
+    key (``agent_scope``) for list values without joining with commas.
+    Defaults to **not** sending ``agent_scope`` — only POST search
+    routes honor it, and they use bodies, not query strings.
+    """
+    pairs: list[tuple[str, str]] = [("user_id", scope.user_id)]
+    if isinstance(scope, WorkspaceScope):
+        pairs.append(("workspace_id", scope.workspace_id))
+        pairs.append(("agent_id", scope.agent_id))
+        if include_agent_scope and scope.agent_scope is not None:
+            value = scope.agent_scope
+            if isinstance(value, list):
+                pairs.extend(("agent_scope", v) for v in value)
+            else:
+                pairs.append(("agent_scope", value))
+    return pairs
+
+
+def assert_scope_allows_visibility(scope: MemoryScope, visibility: str | None) -> None:
+    """Raise if a user-scope ingest tries to set workspace-only `visibility`.
+
+    Visibility is a workspace-only write-time label. Sending it on
+    user-scope ingest is silently dropped by core; the SDK fails closed.
+    """
+    if visibility is not None and not isinstance(scope, WorkspaceScope):
+        raise ValidationError(
+            "ingest `visibility` is only valid with workspace scope; omit it or use a workspace scope variant.",
+            context={"scope_kind": scope.kind, "visibility": visibility},
+        )
+
+
+def strip_agent_scope(scope: MemoryScope) -> MemoryScope:
+    """Drop ``agent_scope`` from a workspace scope before echoing it back.
+
+    Used on routes that don't honor ``agent_scope`` (expand/list/get/
+    delete) so returned memories don't lie about the filter that wasn't
+    applied.
+    """
+    if not isinstance(scope, WorkspaceScope):
+        return scope
+    return WorkspaceScope(
+        user_id=scope.user_id,
+        workspace_id=scope.workspace_id,
+        agent_id=scope.agent_id,
+    )

atomicmemory/providers/mem0/__init__.py

@@ -0,0 +1,41 @@
+"""Mem0 provider — HTTP client for Mem0 OSS or hosted instances.
+
+Port of `atomicmemory-sdk/src/memory/mem0-provider/`. Importing this
+package registers `Mem0Provider` on the sync default registry and
+`AsyncMem0Provider` on the async registry.
+"""
+
+from atomicmemory.memory.registry import (
+    AsyncProviderRegistration,
+    ProviderRegistration,
+    default_async_registry,
+    default_registry,
+)
+from atomicmemory.providers.mem0.async_provider import AsyncMem0Provider
+from atomicmemory.providers.mem0.config import Mem0ProviderConfig
+from atomicmemory.providers.mem0.provider import Mem0Provider
+
+
+def _coerce_config(config: object) -> Mem0ProviderConfig:
+    if isinstance(config, Mem0ProviderConfig):
+        return config
+    return Mem0ProviderConfig.model_validate(config)
+
+
+def _factory(config: object) -> ProviderRegistration:
+    return ProviderRegistration(provider=Mem0Provider(_coerce_config(config)))
+
+
+def _async_factory(config: object) -> AsyncProviderRegistration:
+    return AsyncProviderRegistration(provider=AsyncMem0Provider(_coerce_config(config)))
+
+
+default_registry.register("mem0", _factory)
+default_async_registry.register("mem0", _async_factory)
+
+
+__all__ = [
+    "AsyncMem0Provider",
+    "Mem0Provider",
+    "Mem0ProviderConfig",
+]

atomicmemory/providers/mem0/async_provider.py

@@ -0,0 +1,191 @@
+"""Async Mem0Provider — V3 core + Health.
+
+Async counterpart of :class:`Mem0Provider`. Same capabilities; same
+verbatim-rejection invariant; same body builders.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+import httpx
+
+from atomicmemory.core.errors import ProviderError
+from atomicmemory.memory.provider import BaseAsyncMemoryProvider
+from atomicmemory.memory.types import (
+    Capabilities,
+    CapabilitiesExtensions,
+    CapabilitiesRequiredScope,
+    HealthStatus,
+    IngestInput,
+    IngestResult,
+    ListRequest,
+    ListResultPage,
+    Memory,
+    MemoryRef,
+    SearchRequest,
+    SearchResultPage,
+)
+from atomicmemory.providers.mem0.config import Mem0ProviderConfig
+from atomicmemory.providers.mem0.http import (
+    HttpOptions,
+    adelete_ignore_404,
+    afetch_json,
+    afetch_json_or_none,
+)
+from atomicmemory.providers.mem0.mappers import (
+    build_ingest_body,
+    build_search_body,
+    resolve_infer_flag,
+    to_ingest_result,
+    to_memory,
+    to_search_result,
+    unwrap_mem0_array,
+)
+
+_logger = logging.getLogger("atomicmemory.providers.mem0")
+
+
+class AsyncMem0Provider(BaseAsyncMemoryProvider):
+    """Async HTTP-backed V3 provider for Mem0."""
+
+    name = "mem0"
+
+    def __init__(self, config: Mem0ProviderConfig) -> None:
+        self._config = config
+        self._http_options = HttpOptions(
+            api_url=config.api_url.rstrip("/"),
+            api_key=config.api_key,
+            timeout_seconds=config.timeout_seconds,
+        )
+        self._prefix = config.path_prefix
+        self._client: httpx.AsyncClient | None = None
+        self._initialized = False
+        # Hold strong refs to background tasks so the event loop's weak
+        # reference doesn't garbage-collect them mid-flight (RUF006).
+        self._background_tasks: set[asyncio.Task[None]] = set()
+
+    async def initialize(self) -> None:
+        if self._client is None:
+            self._client = httpx.AsyncClient()
+        self._initialized = True
+
+    async def close(self) -> None:
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+        self._initialized = False
+
+    async def do_ingest(self, input: IngestInput) -> IngestResult:
+        if input.mode == "verbatim":
+            raise ProviderError(
+                "mem0 does not support verbatim ingest; use the atomicmemory provider for "
+                "deterministic one-input-equals-one-memory storage.",
+                provider=self.name,
+                context={"operation": "ingest", "mode": "verbatim"},
+            )
+        user_id = input.scope.user or ""
+        body = build_ingest_body(input, user_id, self._config)
+        should_defer = self._config.defer_inference and resolve_infer_flag(input, self._config)
+        if should_defer:
+            body["infer"] = False
+        raw = await afetch_json(
+            self._require_client(),
+            self._http_options,
+            self._path("/memories/"),
+            method="POST",
+            json=body,
+        )
+        memories = unwrap_mem0_array(raw)
+        if should_defer:
+            task = asyncio.create_task(self._fire_background_inference(body))
+            self._background_tasks.add(task)
+            task.add_done_callback(self._background_tasks.discard)
+        return to_ingest_result(memories)
+
+    async def do_search(self, request: SearchRequest) -> SearchResultPage:
+        body = build_search_body(request.query, request.scope, self._config, request.limit)
+        raw = await afetch_json(
+            self._require_client(),
+            self._http_options,
+            self._search_path(),
+            method="POST",
+            json=body,
+        )
+        results = [to_search_result(m, request.scope) for m in unwrap_mem0_array(raw)]
+        return SearchResultPage(results=results)
+
+    async def do_get(self, ref: MemoryRef) -> Memory | None:
+        raw = await afetch_json_or_none(self._require_client(), self._http_options, self._path(f"/memories/{ref.id}/"))
+        if raw is None:
+            return None
+        return to_memory(raw, ref.scope)
+
+    async def do_delete(self, ref: MemoryRef) -> None:
+        await adelete_ignore_404(self._require_client(), self._http_options, self._path(f"/memories/{ref.id}/"))
+
+    async def do_list(self, request: ListRequest) -> ListResultPage:
+        limit = request.limit if request.limit is not None else 20
+        offset = int(request.cursor) if request.cursor else 0
+        page = (offset // limit) + 1 if offset > 0 else None
+        path = self._path(f"/memories/?user_id={request.scope.user or ''}&page_size={limit}")
+        if page is not None:
+            path += f"&page={page}"
+        raw = await afetch_json(self._require_client(), self._http_options, path)
+        memories = [to_memory(m, request.scope) for m in unwrap_mem0_array(raw)]
+        next_offset = offset + len(memories)
+        cursor = str(next_offset) if len(memories) == limit else None
+        return ListResultPage(memories=memories, cursor=cursor)
+
+    def capabilities(self) -> Capabilities:
+        return Capabilities(
+            ingest_modes=["text", "messages"],
+            required_scope=CapabilitiesRequiredScope(default=["user"]),
+            extensions=CapabilitiesExtensions(health=True),
+        )
+
+    def get_extension(self, name: str) -> Any | None:
+        if name == "health":
+            return self
+        return None
+
+    async def health(self) -> HealthStatus:
+        start = time.monotonic()
+        try:
+            await afetch_json(
+                self._require_client(),
+                self._http_options,
+                self._path("/memories/?user_id=health-check&page_size=1"),
+            )
+            return HealthStatus(ok=True, latency_ms=(time.monotonic() - start) * 1000.0)
+        except (ProviderError, ValueError):
+            return HealthStatus(ok=False, latency_ms=(time.monotonic() - start) * 1000.0)
+
+    def _path(self, endpoint: str) -> str:
+        return f"{self._prefix}{endpoint}"
+
+    def _search_path(self) -> str:
+        return "/memories/search/" if self._prefix == "" else "/v2/memories/search/"
+
+    def _require_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise ProviderError(
+                "AsyncMem0Provider is not initialized. Call await initialize() first.",
+                provider=self.name,
+            )
+        return self._client
+
+    async def _fire_background_inference(self, body: dict[str, Any]) -> None:
+        try:
+            await afetch_json(
+                self._require_client(),
+                self._http_options,
+                self._path("/memories/"),
+                method="POST",
+                json={**body, "infer": True},
+            )
+        except Exception as exc:
+            _logger.warning("[mem0] deferred AUDN failed: %s", exc)

atomicmemory/providers/mem0/config.py

@@ -0,0 +1,51 @@
+"""Mem0 provider configuration.
+
+Port of `atomicmemory-sdk/src/memory/mem0-provider/types.ts`.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+MEM0_DEFAULT_TIMEOUT_SECONDS: float = 30.0
+MEM0_DEFAULT_PATH_PREFIX: str = "/v1"
+
+
+class Mem0ProviderConfig(BaseModel):
+    """Inputs to construct a Mem0 provider."""
+
+    model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+    api_url: str = Field(alias="apiUrl")
+    """Mem0 API base URL.
+
+    Hosted: ``https://api.mem0.ai``. OSS self-hosted:
+    ``http://localhost:8888``.
+    """
+
+    api_key: str | None = Field(default=None, alias="apiKey")
+    """API key for hosted Mem0 instances. Sent as ``Authorization: Bearer …``."""
+
+    timeout_seconds: float = Field(
+        default=MEM0_DEFAULT_TIMEOUT_SECONDS,
+        alias="timeoutSeconds",
+    )
+
+    default_infer: bool = Field(default=True, alias="defaultInfer")
+    """Whether to enable LLM inference on ingest by default."""
+
+    defer_inference: bool = Field(default=False, alias="deferInference")
+    """When True, ingest sends ``infer=false`` synchronously and fires a
+    background re-ingest with ``infer=true`` (deferred AUDN extraction).
+    Only applies when the effective infer value would be True. Default
+    False (single-call behaviour)."""
+
+    path_prefix: str = Field(default=MEM0_DEFAULT_PATH_PREFIX, alias="pathPrefix")
+    """Path prefix for memory-identifier endpoints.
+
+    ``/v1`` (default) for hosted Mem0; ``''`` for OSS self-hosted. Note
+    that search uses the v2 endpoint regardless of this prefix.
+    """
+
+    org_id: str | None = Field(default=None, alias="orgId")
+    project_id: str | None = Field(default=None, alias="projectId")