Limits & errors
Plan limits, request caps, and the contract behind every typed refusal.
Plan limits
| limit | Free | Custom |
|---|---|---|
| Storage | 1 GiB | negotiated |
| Users / stores | 1,000 | negotiated |
A plan is these two numbers. A store is one end user's LodeDB instance, so
"users / stores" is a single count: how many end users the org can hold.
Queries and writes are never metered against a plan; per-minute rate floors
exist as abuse guards identical on every tier, and sustained workloads never
see them. Hitting a cap never stops serving: reads continue. Delete data for
more room, or contact us for custom limits. A negotiated
deal replaces either number, and GET /v1/orgs/{org}/usage always shows the
org's actual contract.
Request caps
| request | cap |
|---|---|
| Documents per write request | 1,000 |
| Text per document | 200,000 characters |
| Query text | 10,000 characters |
| Results per search (k) | 100 |
| Browse page size | 100 documents |
| Store-listing page size | 200 stores |
Error reference
| status | code | when | what to do |
|---|---|---|---|
| 402 | quota_exceeded | A plan cap was reached (storage, or the users/stores count). | Your data keeps serving; reads never stop. Delete data or resources, or upgrade. The detail carries kind, limit, used, plan, and a human message. |
| 429 | rate_limited | The per-org request-rate floor tripped (searches or writes per minute). | Back off briefly and retry; the window is one minute. |
| 409 | pointer conflict | A push/rollback lost a race with a concurrent head move, or a name is taken. | For syncs the SDK raises SyncConflictError. Re-run the sync (it reclassifies against the new head) or resolve with --force-push / --force-pull. |
| 425 | too early | A search asked for min_seq read-your-writes and even the served unfolded tail could not cover it yet. | Rare (reads normally serve accepted writes immediately); retry after a moment. |
| 503 | capacity/capability | Serving is at its concurrency cap, or this deployment lacks the embedding runtime. | Capacity 503s clear in seconds; retry with backoff. A runtime 503 names the missing extra (deployment fix, not a retry). |
| 410 | gone | A restore was attempted after the deletion grace window (7 days). | The data has been purged; restore is no longer possible. |
Every refusal carries a detail the SDK surfaces verbatim
(CloudError.detail); quota refusals are structured
(code / kind / limit / used / plan / message) so tooling can branch.
Stores are end users
A store is one end user of YOUR app: the store name is the user's id (a
single path component, up to 512 characters), and each store is that user's
own LodeDB instance. One user's agent can never reach another's memories,
because the other store is a different instance. Stores auto-provision on
the first write (cloud_writer + minilm + text exposed); a read of a user who
hasn't written yet answers 404 on the wire, which the SDK and MCP tools
translate to empty. Writes may carry optional agent_id/run_id provenance
and a per-memory ttl_seconds (expired memories hide from reads
immediately); reads can narrow on either axis. The _ctx_* metadata
namespace is reserved for the server's stamps (_ctx_agent, _ctx_run,
_ctx_at, _ctx_expires); requests naming it are refused (422). Memory
extras: recall (raw text in, fused hybrid retrieval out), context_block
(a prompt-ready string; needs text access), per-user export
(lodedb cloud store export), and in-place deletion
(lodedb cloud store delete-memories, expired memories included; the store
row stays). A store counts against the plan's users/stores cap when first
written; deleting the store (lodedb cloud store delete) forgets the user
and frees the slot. Each store is an MCP server at
https://api.egoistmachines.com/mcp/<org>/<environment>/<user>, always
three segments, the user's id URL-quoted in the last one.
Backups & restore
Every committed snapshot stays restorable for the retention window (14 days
by default): lodedb cloud store history lists the window,
lodedb cloud store rollback <snapshot-id> moves the head back (rollbacks
are themselves reversible), lodedb cloud pull restores a verified copy to
any machine, and lodedb cloud org export enumerates everything. Deleted
environments, stores, and orgs stay recoverable for 7 days.