Test hosted memory candidates

The hosted memory candidate plane is deployed at api.praxa.io, but it remains a qualification preview. Its unauthenticated gateway boundary is proven. A complete authenticated positive, wrong-scope, revoked-key, and two-tenant by two-subject canary matrix is still pending.

Candidate records do not become Praxa personal memory, Vectorize content, Cognitive Events, AHCE observations, task context, or world-model facts. Use disposable test data until your authenticated qualification passes.

Prerequisites

A personal workspace key with memory:write for create and delete.
A personal workspace key with memory:read for query and export.
A subject identifier owned by your application.
A provider/source record you can safely represent as a portable candidate.

Organization workspaces cannot mint hosted memory scopes. Identity and tenant come from the authenticated key; neither is accepted from the request body.

1. Create one candidate

Save this body as candidate.json:

candidate.json

{
  "apiVersion": "v1",
  "providerId": "custom",
  "sourceId": "customer-profile",
  "externalRecordId": "preference-42",
  "revision": "revision-1",
  "kind": "fact",
  "subject": "customer-42",
  "visibility": "subject",
  "content": "Prefers concise weekly summaries.",
  "metadata": {
    "category": "communication-preference"
  },
  "provenance": {
    "origin": "explicit",
    "confidence": 1,
    "capturedAt": "2026-08-13T12:00:00.000Z",
    "evidenceIds": [],
    "metadata": {}
  },
  "occurredAt": "2026-08-13T12:00:00.000Z",
  "observedAt": "2026-08-13T12:00:00.000Z",
  "originChain": []
}

curl --fail-with-body https://api.praxa.io/v1/memory/records \
  -H "Authorization: Bearer $PRAXA_MEMORY_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tutorial-memory-create-0001" \
  --data-binary @candidate.json

The first successful request returns 201 with replayed: false. Persist candidate.id. Replaying the exact body under the same key returns the same candidate with replayed: true. A different body under that key returns 409.

2. Query the subject

curl --fail-with-body https://api.praxa.io/v1/memory/query \
  -H "Authorization: Bearer $PRAXA_MEMORY_READ_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "apiVersion": "v1",
    "subject": "customer-42",
    "query": "weekly summaries",
    "providerIds": ["custom"],
    "kinds": ["fact"],
    "limit": 20
  }'

The response always identifies retrievalMode: "lexical". Do not describe this hosted endpoint as semantic or graph retrieval.

3. Export candidate and deletion history

curl --fail-with-body --get https://api.praxa.io/v1/memory/export \
  -H "Authorization: Bearer $PRAXA_MEMORY_READ_KEY" \
  -H "Accept: application/x-ndjson" \
  --data-urlencode "subject=customer-42" \
  --data-urlencode "limit=50"

The response is newline-delimited JSON. If X-Praxa-Next-Cursor is present, send it as cursor on the next request. Each line is either a candidate event or a content-free deletion receipt event.

4. Erase the candidate

curl --fail-with-body \
  -X DELETE "https://api.praxa.io/v1/memory/records/$CANDIDATE_ID" \
  -H "Authorization: Bearer $PRAXA_MEMORY_WRITE_KEY" \
  -H "Idempotency-Key: tutorial-memory-delete-0001"

Deletion hard-erases the candidate content and returns an immutable receipt. The receipt retains identifiers, digests, and timestamps, not the content. It does not delete the original record from customer-profile or any other provider-owned source.

5. Run the qualification matrix

Check	Expected result
Exact create retry	Same candidate, `replayed: true`
Changed body under create key	`409 conflict`
Subject A query	Candidate appears
Subject B query in tenant A	Candidate does not appear
Subject A query in tenant B	Candidate does not appear
Read with write-only key	Fails closed
Create with read-only key	Fails closed
Request after key revocation	Fails closed
Delete retry	Same deletion receipt, `replayed: true`
Query after delete	Candidate content absent
Export after delete	Content-free deletion event present
Source-provider read after delete	Original provider record unchanged

Run the matrix with two disposable tenants and two subjects per tenant before using real customer data. Passing package tests or an unauthenticated 401 probe does not substitute for this authenticated boundary test.

Open the memory API playground

Inspect the generated request schema and examples. Use only disposable least-privilege keys while the plane remains a qualification preview.

Troubleshooting

Symptom	Resolution
Expected record is absent	Verify provider-native data shape, namespace mapping, filters, and source status.
Another subject sees a record	Stop the rollout and repair server-owned tenant-subject resolution before further tests.
Provider outage looks like no memory	Expose the source status and keep unavailable distinct from an empty successful recall.
Delete did not remove provider data	Use the provider’s lifecycle; read-only federation and hosted-candidate deletion do not erase provider sources.

Best practices

Keep provider writes and lifecycle under the provider’s documented API.
Resolve tenant and subject in trusted backend code and test 2x2 isolation.
Preserve provenance, source matches, contradictions, and per-source status.
Bound concurrency, result count, context bytes, and source timeout.
Never promote checkpoint, hidden, or unverified content into portable recall.

Optimize for production

Query only providers and record kinds relevant to the current purpose.
Use bounded parallel recall and give each source an explicit timeout budget.
Deduplicate normalized content while retaining every source match and contradiction.
Measure source p50/p95 latency, partial/failed recalls, result precision, context bytes, and isolation failures.

Optimize only after the correctness and isolation matrix passes. Lower latency or cost is not an improvement if verified outcomes, authority checks, or recovery rates regress.

Cleanup and next steps

Delete synthetic provider records using the provider’s normal API.
Hard-erase disposable hosted candidates and verify content-free receipts when used.
Revoke test credentials and remove namespace fixtures for every tenant and subject.
Retain only non-content source statuses, identifiers, and test results required for audit.

After cleanup, run the shared integration test matrix and record any environment-specific check that remains pending.

Frequently asked questions

What proves this tutorial works?

The minimum observable result is that create, lexical query, export, hard erasure, replay, and 2x2 isolation all pass. A compile, package import, mocked response, or initial admission alone does not prove the complete workflow.

Can a browser, mobile app, or model prompt hold the credential?

No. Provider clients and Praxa credentials stay in the backend; adapters receive clients, not raw credentials.

How should an ambiguous mutation be retried?

Persist the exact logical input and idempotency key before the first attempt. Reconcile through authoritative readback or replay the exact request with that same key before creating new work.

What should we monitor after release?

Monitor per-source latency/status, partial and failed recall rates, result precision, context bytes, provenance coverage, and isolation failures. Alert on authorization bypass, cross-tenant disclosure, repeated conflicts, or cleanup failure.

Get started

Core Concepts

Releases

Test hosted memory candidates

Prerequisites

1. Create one candidate

2. Query the subject

3. Export candidate and deletion history

4. Erase the candidate

5. Run the qualification matrix

Open the memory API playground

Troubleshooting

Best practices

Optimize for production

Cleanup and next steps

Frequently asked questions

What proves this tutorial works?

Can a browser, mobile app, or model prompt hold the credential?

How should an ambiguous mutation be retried?

What should we monitor after release?

​Prerequisites

​1. Create one candidate

​2. Query the subject

​3. Export candidate and deletion history

​4. Erase the candidate

​5. Run the qualification matrix

Open the memory API playground

​Troubleshooting

​Best practices

​Optimize for production

​Cleanup and next steps

​Frequently asked questions

​What proves this tutorial works?

​Can a browser, mobile app, or model prompt hold the credential?

​How should an ambiguous mutation be retried?

​What should we monitor after release?

Prerequisites

1. Create one candidate

2. Query the subject

3. Export candidate and deletion history

4. Erase the candidate

5. Run the qualification matrix

Troubleshooting

Best practices

Optimize for production

Cleanup and next steps

Frequently asked questions

What proves this tutorial works?

Can a browser, mobile app, or model prompt hold the credential?

How should an ambiguous mutation be retried?

What should we monitor after release?