Skip to content

memory-external-provider-runtime.md

Latest commit

 

History

History
37 lines (29 loc) · 2.34 KB

memory-external-provider-runtime.md

File metadata and controls

37 lines (29 loc) · 2.34 KB
Raw

External memory provider runtime

External memory providers must preserve two identifiers:

  • ManagedMemoryRecord.id is a stable Hypha-owned identifier.
  • metadata.providerExternalId is the provider-owned identifier.

Use createExternalMemoryId(providerId, externalId) when adapting provider records. Persist the association with StructuredExternalMemoryMappingStore in production so get, update, history and delete operations can resolve the provider identifier after a process restart. The in-memory mapping store is intended for tests and ephemeral deployments only.

ExternalMemoryClient operations accept an optional AbortSignal. Provider clients must pass it to their HTTP or SDK transport. ExternalMemoryManagementAdapter derives a child signal for each attempt and aborts it when either the caller cancels or the configured provider timeout expires.

Use Mem0OssClient for the unprefixed self-hosted REST API and Mem0PlatformClient for the v3 additive/search/list pipeline. MemoryBankManagedClient represents Vertex AI Memory Bank. HindsightLocalMemoryBankClient implements the pinned self-hosted Hindsight HTTP 0.8 dialect. MemoryBankLocalClient is retained only as a package-level protocol compatibility fixture; it is not a supported product runtime or live acceptance target. Deployment semantics are never inferred from a URL. Secrets and customer endpoints remain application configuration and must not be embedded in Framework profiles or fixtures.

External HTTP clients validate their base URL before resolving or attaching credentials. Mem0 OSS permits cleartext only on loopback for local development; Mem0 Platform and Vertex Memory Bank require HTTPS. Provider URLs containing user-info, query strings, fragments, or non-HTTP schemes are rejected at composition time.

Managed asynchronous operations remain provider facts until reconciliation completes. The durable operation Store records the provider operation name, scope, principal, profile revision, deadline, attempt count, and operation kind. Update and delete callers receive queued or partial results until the cloud LRO reaches a successful terminal state; attempt exhaustion is dead-lettered rather than converted into a synthetic success.

See the adapter and operations guide and profile configuration.