Uteke Cloud docs
Uteke Cloud is long-term memory for AI agents, run for you: hybrid recall, isolated workspaces and NDJSON export, over REST and remote MCP. Point your agents at the API below and manage keys from the keys portal. Accounts are invite-only during the alpha.
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, 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 (default 10, up to 1000 per page, filter by tag) 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) Restoring an export or bringing memories in from another Uteke workspace. 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 1000 items | The limit is clamped to 1000 (recall and search: 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: back up, bring memories in, or leave with your data any time.
Plans and limits
Your first sign-in starts 14 days of Pro, no card. After that the account stays on Free, never locked; voucher codes add more Pro time. Free limits:
| Memories / documents | 250 / 25 |
| Recall (embedding) per day | 150 |
| Reads per day (search, list, get) | 1000 |
| Writes per day | 1000 |
| Exports per month | 4 |
| Import body | 8 MiB per call |
| Active API keys / workspaces | 3 / 1 |
Requests are also rate limited per account (all your keys share one budget); see GET /usage for your plan and today’s counters.
Errors
Errors return a JSON envelope: { "error": code, "message": "…" }.
A plan limit answers 403 quota_exceeded; the monthly export quota answers 429 quota_exceeded. Too many requests in a short time answer 429 rate_limited with a Retry-After header: wait that many seconds,
then retry.