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. Drop obsolete state. A reason is required and is audited.
client.forget("user.preference", reason="superseded by profile service")

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

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.