Skip to content

Foundations

One contract, three interfaces

The SDK, CLI, and direct HTTP client are different ways to reach the same tenant-scoped API. They should not invent separate semantics. The server derives account scope from the verified credential, validates the request, executes the configured runtime, records usage, and returns provenance with the result.

Control plane
Account, API keys, memory storage connections, limits, usage, billing, and settings.
Data plane
Memory write, recall, and delete operations, with rendering and future stages reported in the response when the runtime supports them.
Observability plane
Health, capabilities, events, metrics, anomaly signals, and exports.

Credentials and scope

API keys are application credentials for memory calls and tenant-scoped telemetry. A browser session is an account credential for interactive Mind Platform control-plane work. The API never treats a browser session as an API key for a data-plane memory call, and an operator capability is separately required for privileged simulation.

CredentialTypical useDo not assume
API keyMemory operations, application integrations, metered requests.It can perform account administration without the required role.
Browser sessionCLI login and Mind Platform controls.It can replace an API key on data-plane or tenant telemetry routes.
Simulation tokenAuthorized operator simulations in an explicitly enabled environment.It bypasses consent, authorization, billing policy, or production controls.
Credential precedence is observable.

Use palo auth or --json to see which local source is selected without revealing the secret. Never log full authorization headers.

Memory stores, namespaces, and scope

A memory operation needs an active storage connection. The storage connection identifies where retained memory state lives. A namespace separates application data within that connection. User and organization scope are derived from the authenticated account, not accepted as an arbitrary cross-tenant parameter.

Managed storage
Mpalo-managed memory storage selected through the Mind Platform or CLI.
BYO storage
A customer-controlled storage connection represented in the control plane. Current v1 memory requests do not execute against it.
Namespace
A caller-selected logical partition, such as conversation or support.
Decision
The write result states whether the event was retained and why. A successful HTTP response is not identical to retained memory.

The reference runtime uses deterministic lexical fixtures for predictable tests. It can exercise the request, persistence, retrieval, response, usage, and deletion path, but it is not evidence of Palo Bloom model quality, embeddings, semantic vector search, or production latency.

Event origin and provenance

A memory write may identify the origin of an event with event.source. This is caller-attested metadata. It helps an application distinguish direct input, imports, generated summaries, and future device or provider events, but it is not proof of who supplied the data, who the data describes, or whether Mpalo verified the source.

FieldMeaningBoundary
source.typeThe submitting application’s declared origin category.One of the documented v1 origin values, including direct_user_input, imported_archive, external_application, model_inference, and sensor_or_device_input.
source.idAn optional opaque source identifier.At most 255 characters. Do not put raw text, secrets, or credentials here.
Verified scopeThe tenant and user receiving the event.Derived from the authenticated credential. It cannot be replaced by source or client-supplied identity fields.

The current runtime stores and returns this origin metadata, while representations, semantic retrieval, surprise, learned traversal, and provider verification remain unavailable. A source label does not make a future adapter active.

Usage and billing

Every accepted customer request should have a request record, operation attribution, usage units when measurable, and a billing state. The CLI and Mind Platform read these records from the backend. In the current hosted reference deployment, model-dependent output is simulated, while request history, storage, metering, charge records, and operational receipts use the backend path. A pure offline fixture may return no units or no charge because it does not contact the backend.

StateMeaningOperator action
observedA request was measured, including failures and blocked attempts where policy allows.Inspect request count, errors, latency, and event history.
billableThe accepted operation produced billable usage under the active pricing version.Compare usage records with immutable charge records.
no_dataNo measurable requests or pricing data exist in the selected window.Do not interpret it as zero cost for a different window.
voidA previously recorded charge was voided through the billing ledger.Keep the original request and charge history for auditability.

Reliability vocabulary

Clients should preserve request IDs, send idempotency keys on retried writes, respect retryable flags, and keep response state separate from transport status. A 200 response can describe a retained event, a safe replay, or a no-data result. A 503 response means the caller should follow the documented retry policy and inspect the request ID.

try:
    result = client.memory.write(text, idempotency_key="event-42")
except TimeoutError:
    # Retry with the same idempotency key.
    result = client.memory.write(text, idempotency_key="event-42")