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

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 mock environment, charges are sandbox records and model execution is disabled. A fixture may return no units or no charge when the operation did not run a model.

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