Call verifiable memory from Python.

Import CloudClient, then write, recall, and inspect hosted state.

import os
from bilinc import CloudClient

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

client.commit("user.preference", {"theme": "dark"})
results = client.recall("user preference", limit=5)

# What can this key do? (authenticated, never billed)
status = client.status()

# Is the service reachable? (public service health)
health = client.health()

Write, correct, checkpoint, inspect, forget, recover.

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",
)

The public surface, and what each call costs.

See what Bilinc remembers, and how it changed.

list_memories, history, and export only read and are never billed. The time filters take a datetime (a naive one is read as UTC) or an ISO-8601 string. The same commands are in the CLI: bilinc list, bilinc history KEY, bilinc confirm KEY, and bilinc export -o FILE.

import json
import os
from bilinc import CloudClient

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

# Every memory under a prefix, page by page (free).
for entry in client.iter_memories(prefix="user."):
    print(entry["key"], entry["updatedAt"], entry.get("value"))

# How one memory changed, newest first (free).
for step in client.history("user.preference")["entries"]:
    print(step["at"], step["op"], step.get("before"), "->", step.get("after"))

# Still accurate? Confirm it without resending the value (one write).
client.confirm("user.preference", reason="user said it is still right")

# Everything, with full values, as one JSON file (free).
with open("bilinc-memory.json", "w") as handle:
    json.dump(client.export(), handle, indent=2)

Use the right shape for the right state.

Reads retry themselves; writes do not.

The SDK retries read-only calls a bounded number of times on transport and 5xx failures. Writes are single-shot on purpose: a retried write could apply twice. Pass idempotency_key on a write you might retry, and the server replays the original result instead of executing again.