From account to working agent memory in four steps.

Give this to the agent after creating a Cloud key.

You are working with Bilinc Cloud as the hosted memory/state plane.

Use the API key only as a bearer token. Never print, log, commit, or expose it.

Base URL: https://bilinc.space

When durable agent memory matters:
1. Commit important state with POST /api/cloud/memory/commit.
2. Recall prior state with POST /api/cloud/memory/recall.
3. Keep keys stable and namespaced, for example agent.goal, user.preference, project.status.
4. Use semantic memory for durable facts, episodic memory for run outcomes, and procedural memory for reusable workflows.
5. If an operation fails, treat the write as not durable until the API returns success.

When you are correcting or removing state:
6. Use POST /api/cloud/memory/revise to correct something you already know. It returns 404 rather than creating, so the change stays distinguishable from an accidental overwrite.
7. Use POST /api/cloud/memory/forget only for genuinely obsolete state. A reason is required and is audited.
8. Pass the entryVersion from your last write as expectedVersion to avoid clobbering a concurrent change.

When work is risky or has gone wrong:
9. Checkpoint first with POST /api/cloud/memory/snapshots.
10. Inspect with POST /api/cloud/memory/diff. It is free and redacts values by default.
11. Recovery is two stages. POST /api/cloud/memory/rollback/preview is free and returns a short-lived confirmation token; POST /api/cloud/memory/rollback executes and permanently discards everything created or changed since the checkpoint. Never execute without showing the preview to a human first.

Operational notes:
12. Call GET /api/cloud/status to learn which capabilities and recall profiles this key may use before attempting them.
13. Send an Idempotency-Key header on writes you might retry, so a retry replays instead of applying twice.

Required headers:
Authorization: Bearer <BILINC_API_KEY>
Content-Type: application/json

Pick the path that matches the work.

pip install -U bilinc
bilinc start
bilinc login --api-key bil_live_...
bilinc quicktest

bilinc commit --key USER_PREF --value '{"theme":"dark"}'
bilinc recall --query "user preference"
bilinc revise --key USER_PREF --value '{"theme":"light"}' --reason "user changed it"
bilinc snapshot create --label before-autonomous-run
bilinc snapshot list
bilinc diff --from-snapshot snap_...
bilinc forget --key USER_PREF --reason "superseded by profile service"
bilinc status
bilinc health

# Rollback is two stages. Execute needs the token from the preview and
# never prompts interactively, so it stays safe inside automation.
bilinc rollback preview --snapshot snap_... --reason "undo bad agent run"
bilinc rollback execute --snapshot snap_... --reason "undo bad agent run" \
  --confirmation-token <token-from-preview>

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" }
  }'

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
  }'