Reference

Memory lifecycle

The memory API separates transport success from retention, retrieval, rendering, and deletion state. This page follows one event through the current v1 contract and names the boundaries that remain future work.

Current runtime.

The hosted path is a backend-backed deterministic mock. It stores submitted text when the authenticated API key has an active managed storage connection and private-memory consent. It ranks retained text with lexical overlap and can return selected text as context. It does not create semantic embeddings, evaluate learned surprise, or execute a learned Palo Bloom model.

1. Write an event

A write accepts text, a namespace, an event time, and an idempotency key. The key defaults to a generated event identifier in the SDK and CLI, but production callers should supply a stable key when a request may be retried.

curl -X POST https://api.mpalo.com/api/v1/memory/write \
  -H "Authorization: Bearer $PALO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conversation-42-message-7" \
  -d '{
    "contract_version": "v1",
    "operation": "memory.write",
    "namespace": "conversation",
    "idempotency_key": "conversation-42-message-7",
    "event": {
      "event_id": "conversation-42-message-7",
      "occurred_at": "2026-09-11T10:00:00Z",
      "content": {"text": "The appointment moved to Monday afternoon."},
      "source": {"type": "direct_user_input", "id": "message-7"}
    }
  }'

The CLI equivalent is palo memory write "The appointment moved to Monday afternoon." --namespace conversation --source-type direct_user_input --source-id message-7. The source declaration is caller-attested metadata, not verified identity or consent.

A write may also declare event.supersedes for earlier events in the same scope. The current runtime marks found targets as superseded and records each relation for export. A missing target is reported as unresolved in the relation ledger. This is a storage-selection control, not truth resolution or learned correction.

2. Read the retention decision

A successful request does not always mean a memory was retained. The response includes a versioned decision object and a representation object. In the current managed mock, an allowed write reports memorized under the runtime policy and representation.status: not_available because no semantic representation is created.

Decision	Meaning in the contract	Current mock behavior
`memorized`	The runtime retained the event as a memory.	Used when managed storage and consent allow the current path.
`not_retained`	Retention was prevented before a memory was created.	Returned when private-memory consent is missing or unavailable.
`not_memorized`	The runtime evaluated the event and chose not to retain it.	Available only through the authorized write-only test profile. The current mock does not produce learned surprise.
`not_evaluated`	The active runtime could not make a retention decision.	Reserved for an unavailable decision capability.

The surprise object is intentionally unavailable today. No raw activation, threshold, embedding size, or model confidence should be invented from this field.

3. Optionally find a related memory after writing

A write may request a lookup among existing memories. The new event is not treated as its own retrieval result. Without an override, a future retention decision of not_memorized suppresses this lookup. With an override, the runtime may search existing eligible memories, but it cannot bypass consent or authorization.

Wire state	Human meaning
`not_requested`	No related lookup was requested.
`suppressed_not_memorized`	The event was not retained, so the normal lookup was not run.
`no_data`	No eligible related memory was found.
`distant_memory`	Candidate records existed, but none met the current closeness policy.
`close_memory`	A candidate met the current closeness policy. Human-facing surfaces call this a related memory.
`not_available`	The active runtime cannot perform the requested lookup.

The CLI uses --recall-nearest, --recall-override, and --recall-top-k. An authorized write simulation may use the not_memorized profile to exercise suppression and override behavior. The mock's score kind is mock_lexical_overlap, not cosine similarity or model confidence.

4. Recall and render context

Recall accepts a text cue, a namespace, an optional temporal cutoff, and a result limit. The contract calls the input a cue because it is an instruction to activate related retained records, not a claim that the request is a database query or that the result is objectively true. The CLI calls the same field query for clarity.

palo memory recall "What changed about the appointment?" \
  --namespace conversation \
  --top-k 3 \
  --as-of 2026-09-11T12:00:00Z

A related result includes its event and memory identifiers, event time, returned text, score kind, and caller-attested source metadata when present. Rendered context is assembled from selected retained text. It is context for the application and does not mean that Mpalo generated the application's final answer.

5. Retry safely and preserve state

If a write times out after the server may have accepted it, repeat the request with the same idempotency key and event fingerprint. The service can return the original result instead of creating a second memory or a second charge. A changed payload with the same key is an idempotency conflict and should not be treated as a safe retry.

Accepted

The request was claimed and its result can be returned.

Replayed

The same request identity returned the original result. Billing is not duplicated.

Conflict

The idempotency key was reused with a different request fingerprint.

Retryable

The response identifies whether repeating the operation is appropriate.

6. Export and delete

Infrastructure export returns retained private-memory records, recorded supersession relations, and redacted operational history for the verified scope. Memory deletion removes retained memory, supersession relations, and idempotency state for the requested namespace. The minimum redacted operational history remains for billing, security, and operational accountability.

palo infra export --namespace conversation --json
palo memory delete --namespace conversation --confirm-namespace conversation

Deletion is scoped.

The current contract does not promise universal erasure across future providers, caches, backups, or unrelated account systems. It also does not provide customer-controlled encryption keys. Read the applicable policy for legal retention requirements.

The lifecycle is the same through HTTP, the Python SDK, and the Palo CLI. Their presentation can differ, but the response states, request IDs, retryability, provenance, data policy, usage, and billing meaning must remain aligned.

Was this page helpful?

Your feedback helps us improve our documentation.