SDK & CLI reference

The client ships in the lodedb package's [cloud] extra (current release on PyPI). Everything below is the released surface; docstrings in the package carry the full detail (help(lodedb.cloud.Client)).

pip install "lodedb[cloud]"

Authentication

from lodedb.cloud import Client

client = Client()                     # credential resolved from the environment
client = Client(token="ore_sk_...")   # or passed explicitly

The credential resolves in order: the token= argument, ORECLOUD_TOKEN, then the file lodedb cloud login stores. The host defaults to the hosted control plane (https://api.egoistmachines.com); host=/ORECLOUD_HOST override it for staging or self-hosted deployments. Environment keys carry their org and environment, so Client() needs no other configuration; personal tokens pass org=/environment= explicitly.

Store handles

client.store(name) returns a CloudStore: one end user's store. It makes no HTTP call; the store provisions on its first write.

memory = client.store("user-42", warm=True)   # warm=True pre-hydrates serving

Writing

method	what it does
`add(text, *, id=, metadata=, ttl_seconds=, agent_id=, run_id=) -> str`	Add or replace one memory; embedded server-side, durable when it returns.
`add_many(documents, *, ttl_seconds=, agent_id=, run_id=) -> list[str]`	Batch of `{"text", "id"?, "metadata"?}` as one accepted write.
`remove(id) -> str`	Queue one removal; returns the accepted write's id.
`remove_many(ids) -> str`	Batch removal as one accepted write.
`wait_for(write_id, *, timeout=30.0) -> dict`	Block until an accepted write folds; the handle records `last_write_id`.

Writes are accepted (durable and ordered) when the call returns, and become visible within seconds. Reads on the same handle wait for that handle's own writes, so read-your-writes holds without wait_for.

Reading

method	what it does
`search(query, *, k=10, filter=, mode=, include_text=False)`	Top-k hits, engine-scored.
`recall(text, *, k=10, filter=, include_text=False, agent_id=, run_id=)`	Raw user message in; the server derives sub-queries and fuses rankings.
`context_block(text=None, *, max_chars=4000, agent_id=, run_id=)`	One prompt-ready string of recent plus relevant memories. Needs text access.
`get(id) -> str \| None`	One memory's stored text. Needs text access.
`get_texts(ids) -> dict[str, str]`	Stored text for several ids at batch cost.
`browse(*, after=, limit=25, include_text=False, filter=, ids=, order=, agent_id=, run_id=)`	Keyset pages of ids + metadata (text when asked and allowed).
`list_documents(*, filter=, after=, limit=, max_documents=)`	Enumeration, not ranking: `{"id", "metadata", "chunk_count"}` records.
`count()` / `stats()`	Document count; metrics-only serving stats.

Hits are CloudSearchHit objects with score, id, metadata, text (when requested), and matched (recall only: the sub-queries that surfaced the hit). They unpack as (score, id, metadata) tuples, matching the local LodeSearchHit.

Forgetting

method	what it does
`delete_memories(*, agent_id=, run_id=)`	Delete memories in place (expired included); the store stays registered.
`client.delete_store(name, *, erase=False)`	Forget the user: soft-delete with a 7-day grace, or `erase=True` for immediate, unrestorable erasure.

Bring-your-own-vectors stores

Stores created with vector_dim= skip server-side embedding and take add_vectors / add_vectors_many / search_by_vector / search_many_by_vector with vectors of exactly the store's dimensionality.

Client management verbs

method	what it does
`create_store(name, , encrypted=False, key_material=None, *options)`	Explicit registration, for choosing `mode=`/`preset=`/`expose_text=`/`vector_dim=` up front.
`list_stores(**params)` / `store_stats()`	One keyset page of stores; fleet-level activity counts.
`update_store(store, key, **changes)`	Flip a store's `expose_text`/`mode` flags.
`store_history(store, key)` / `rollback_store(store, snapshot_id)`	The restore window; move the head back (reversible).
`mint_token(kind, scopes, **options)` / `list_tokens()` / `revoke_token(id)`	Token lifecycle. Scopes: `admin`, `write`, `read:search`, `read:text`.
`list_environments()` / `delete_environment()` / `restore_environment(slug)`	The fixed production/testing pair.
`me()` / `token_self()`	The signed-in account; what the presented credential is.
`list_trash()` / `restore_store(parked)` / `delete_org()` / `restore_org(parked)` / `export_org()`	Soft-delete lifecycle and offboarding.
`unseal_store(store, key_material, *, ttl_seconds=)` / `reseal_store(store)` / `rotate_store_key(store, new_key_material)`	Encrypted stores with caller-held key material.

Errors raise CloudError with the server's detail verbatim; the limits & errors reference lists every typed refusal.

Device-bound encrypted pulls

For an app using device-held P-256 keys, enroll the device once through the owner-approved enrollment ceremony. Immediately before each encrypted pull, the app calls device-unseal with a fresh proof of possession. That response returns the wrapped DEK and opens a 15-minute pull window for the same device and replica token, so the following pull needs no additional round trip.

The `lodedb cloud` CLI

Every command emits JSON when stdout is not a terminal (--json/--no-json force it), so the CLI is scriptable as-is.

lodedb cloud
├── login / logout / whoami        one browser approval; credential stored locally
├── init <dir> [--agents]          link a directory to an environment; --agents
│                                  scaffolds a coding agent's key + MCP config
├── tokens mint|list|revoke        API keys (--kind secret|publishable|personal)
├── store list|create|browse|export|recall|delete-memories
│         history|rollback|delete|restore
│         unseal|reseal            encrypted stores
├── environments list|delete|restore
├── org delete|restore|trash|export
├── mcp install <store>            ready-to-paste MCP configs (Claude Code, Cursor, VS Code)
├── auth print-headers             the stored credential as an MCP headers object
├── keys / status / push / pull / sync / verify
│                                  transfer verbs; remotes are a directory,
│                                  s3://, or orecloud://org/environment[/store]
└── link <dir>                     record a managed remote in orecloud.toml

lodedb cloud store create <name> prints a ready-to-run Python snippet with a freshly minted key, and lodedb cloud mcp install <store> prints the same for agents. The transfer verbs (push/pull/sync/status/verify) move whole stores between local disk and the cloud; see Portability.

On this page