Uteke Cloud docs
Uteke Cloud is the managed version of Uteke — agent memory with hybrid recall. No server to run: point your agents at the API below and manage keys from the keys portal. Prefer to self-host? The open-source build runs the same API from a single Docker image.
Base URL & auth
Every REST route is available under /api/v2 (and mirrored at /api/v1 for compatibility). Authenticate with your API key as a Bearer token — generate keys at /portal/keys. Keys are shown once at creation; store them safely.
Core endpoints
| Method | Path | What it does / when to call it |
|---|---|---|
| POST | /remember | Store a memory (content, tags, metadata, namespace, type, importance, pinned) After each conversation turn or session ends — write what is worth remembering. |
| POST | /recall | Hybrid recall — vector + full-text fused (RRF). Query-time embedding When answers need meaning, not just keywords: paraphrases and related concepts both hit. |
| POST | /search | Keyword search — no embedding, plain full-text + substring fallback Exact names, error strings, technical terms. Cheaper and instant (no embedding). |
| GET | /list | List memories (limit 1–100, filter by tag / namespace) Browsing or syncing state — walk the workspace with limit + offset. |
| GET | /memory/{id} | Fetch one memory by id You already know the id (from a previous recall/list) and want the full record. |
| POST | /forget | Delete a memory by id Removing wrong or superseded content on request. |
| GET | /tags | List tags in use Building filters or a tag picker for your UI. |
| GET | /usage | Today’s usage + plan + quota snapshot Before heavy operations, or to show users where their quota stands. |
| GET | /export | Export the workspace as NDJSON (manifest on line 1) Backups and migration — your data is never locked in. |
| POST | /import | Import NDJSON or a JSON array (dedup, id/created_at preserved) Moving from self-hosted to cloud, or restoring an export. Re-running is safe (dedup). |
| POST | /mcp | Remote MCP endpoint — JSON-RPC 2.0 over HTTP (protocol 2025-06-18) Connecting MCP clients (Claude Desktop, Cursor, …) instead of raw REST. See Connect. |
Room and document endpoints (/room/*, /doc/*) follow the same auth
pattern — see the open-source API reference for full request/response shapes, which the cloud
mirrors.
Common pitfalls
| Problem | Fix |
|---|---|
| Recalling right after a write returns nothing | Embeddings are applied asynchronously after the write. Write at end-of-turn; recall from the next turn on. Keyword /search works immediately. |
| Filtering by metadata | Metadata is stored but not filterable. Put anything you plan to filter on into tags (then /list?tag=…). |
| Asking /list for more than 100 items | The limit is clamped to 1–100. Page with offset instead of raising the limit. |
| Storing secrets in memories | Content is stored as-is — never retain credentials, tokens, or keys. Scrub before writing. |
| Expecting /search to rank by meaning | Search is lexical (full-text, substring fallback). For semantic matches use /recall. |
Where to go next
- Connect — first curl calls and MCP client configuration.
- Import / Export — migrate a self-hosted workspace to the cloud, or leave with your data anytime.
Errors
Errors return a JSON envelope: { "error": code, "message": "…" }.
Quota breaches answer 403 with an upgrade_url hint;
monthly quota (e.g. exports) exhaustion answers 429.