The hosted memory lifecycle over HTTP.

Every public Cloud endpoint, and what it costs.

CloudClient wraps the hosted API.

import os
from bilinc import CloudClient

client = CloudClient(api_key=os.environ["BILINC_API_KEY"])

# 1. Write. The returned version is your optimistic-concurrency token.
written = client.commit("user.preference", {"theme": "dark"})
version = written["entryVersion"]

# 2. Read.
client.recall("user preference", profile="balanced", limit=5)

# 3. Correct something you already know. Fails if it does not exist.
client.revise(
    "user.preference",
    {"theme": "light"},
    reason="user changed it in settings",
    expected_version=version,
)

# 4. Checkpoint before risky agent work.
snapshot = client.create_snapshot(label="before-autonomous-run")["snapshot"]

# 5. See what the run changed. Values are redacted by default.
client.diff(snapshot["id"])

# 6. Review what is stored and how one memory changed. Both reads are free.
client.list_memories(prefix="user.", limit=50)
client.history("user.preference")

# 7. Drop obsolete state. A reason is required and is audited.
client.forget("user.preference", reason="superseded by profile service")

# 8. Recover. Preview is free; execute is destructive and needs the token.
preview = client.rollback_preview(snapshot["id"], reason="undo bad agent run")
client.rollback(
    snapshot["id"],
    confirmation_token=preview["confirmationToken"],
    reason="undo bad agent run",
)

Two different questions, two different endpoints.

Health answers “is the service reachable?” and needs no key. Status answers “what can this authenticated key do?” Keep them apart in monitoring, so an entitlement problem never looks like an outage.

curl https://bilinc.space/api/cloud/status \
  -H "Authorization: Bearer $BILINC_API_KEY"

# Returns the workspace, plan, entitlement state, supported tools and recall
# profiles, limits, month-to-date usage, and credits. Never billed, and it
# never returns key material.
#
# For "is the service up?" use the unauthenticated /api/cloud/health instead.

Write one durable memory.

curl https://bilinc.space/api/cloud/memory/commit \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "agent.memory.bootstrap",
    "value": {
      "goal": "keep durable state between runs",
      "owner": "agent-runtime"
    },
    "memoryType": "semantic",
    "importance": 0.8,
    "metadata": { "source": "cloud-quickstart" }
  }'

Read prior state with a recall profile.

curl https://bilinc.space/api/cloud/memory/recall \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "durable state between runs",
    "profile": "balanced",
    "limit": 5
  }'

Correct something you already know.

curl https://bilinc.space/api/cloud/memory/revise \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "key": "agent.memory.bootstrap",
    "value": { "goal": "keep durable state between runs, verified" },
    "reason": "corrected after review",
    "expectedVersion": "v1_..."
  }'

# 404 memory_not_found if the key does not exist: revise never creates.
# 409 version_conflict if expectedVersion is stale.

Drop obsolete state, with a reason.

curl https://bilinc.space/api/cloud/memory/forget \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "agent.memory.bootstrap",
    "reason": "superseded by the profile service"
  }'

# Destructive. The reason is required and is written to the audit trail.
# The deleted value is never returned.

Say a memory is still right, without rewriting it.

Confirm keeps the value, type, and importance exactly as stored and moves updatedAt to now. It needs a key that exists, accepts an optional expectedVersion and reason (up to 512 characters), and returns the new entryVersion. It is a write: one memory_write operation, and it honors Idempotency-Key like every other write.

curl https://bilinc.space/api/cloud/memory/confirm \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "user.preference",
    "expectedVersion": "v1_...",
    "reason": "user said it is still right"
  }'

# Records that the memory is still accurate without resending it. The value
# stays as stored, updatedAt moves to now, and history shows a confirm.
# One memory_write operation. 404 memory_not_found, 409 version_conflict.

See everything a project stores, a page at a time.

Entries come back ordered by key. Filters: prefix (matched literally, so _ and % are not wildcards), memoryType, and updatedAfter / updatedBefore as ISO-8601 dates (2026-10-01) or times with Z or an offset. limit is 1–100 (default 50). values is preview (default, the first 200 characters), full, or none; a full page larger than the response bound is refused with invalid_request rather than cut short, so ask for a smaller page. Each entry carries key, memoryType, importance, source, createdAt, updatedAt, and entryVersion. An unreadable cursor returns invalid_request.

curl https://bilinc.space/api/cloud/memory/list \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prefix": "user.",
    "memoryType": "semantic",
    "updatedAfter": "2026-10-01T00:00:00Z",
    "limit": 50,
    "values": "preview"
  }'

# Free and read-only. Ordered by key. Pass nextCursor back as "cursor" for the
# next page; a cursor stays valid while other writes land. total counts every
# memory that matches the filters, not only this page.

How one memory changed, newest first.

Every write, confirmation, forget, and rollback step is kept in a memory’s history. Each entry has op (create, update, confirm, forget, or delete), at, reason, source, and the value before and after; a step made by a rollback also carries rollbackSnapshotId. limit is 1–100 (default 20) and values defaults to full. Forgetting a memory removes its value from every read: entries recorded at or before the latest forget carry valuesRedacted: true and no values. exists says whether the key is stored now, and truncated says older entries exist. A key with no history returns an empty list, not an error.

curl https://bilinc.space/api/cloud/memory/history \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "user.preference", "limit": 20, "values": "full" }'

# Free and read-only. Newest change first; each entry has op, at (ISO-8601),
# reason, source, and before/after values. values: full | preview | none.
# Values recorded at or before the memory was last forgotten are never
# returned; those entries carry "valuesRedacted": true instead.

Checkpoint before risky work.

# Create a checkpoint (billed as one snapshot event)
curl https://bilinc.space/api/cloud/memory/snapshots \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "before-autonomous-run" }'

# List checkpoints, newest first (free)
curl "https://bilinc.space/api/cloud/memory/snapshots?limit=20" \
  -H "Authorization: Bearer $BILINC_API_KEY"

See what changed without exporting values.

curl https://bilinc.space/api/cloud/memory/diff \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromSnapshotId": "snap_...",
    "includeValues": false
  }'

# Free and read-only. Omit toSnapshotId to compare against current state.
# Values are redacted unless includeValues is set.

Recovery is preview plus explicit execution.

# Stage 1: preview. Free, changes nothing, returns a short-lived token.
curl https://bilinc.space/api/cloud/memory/rollback/preview \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "snapshotId": "snap_...", "reason": "undo bad agent run" }'

# Stage 2: execute. DESTRUCTIVE. Requires that token.
curl https://bilinc.space/api/cloud/memory/rollback \
  -H "Authorization: Bearer $BILINC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshotId": "snap_...",
    "reason": "undo bad agent run",
    "confirmationToken": "<token-from-preview>"
  }'

# 409 state_changed_since_preview if the project changed after the preview.
# 410 rollback_confirmation_expired if the token aged out. Take a new preview.

Retry a write without applying it twice.

Send an Idempotency-Key header on any write you might retry. The same key with the same payload replays the original result and is billed once; the same key with a different payload is refused with 409 idempotency_conflict. If usage finalization is delayed, the response remains replayable and reports _meta.reconciliationPending. A rare ambiguous outcome fails closed with503 mutation_outcome_unknown; do not issue the mutation under a fresh key.

Responses use camelCase fields and ISO-8601 timestamps. History, list, and confirm return 503 capability_unavailable while the hosted runtime does not offer them yet; nothing is written or billed in that case.