API Reference

Base URL https://rememberos.ai (or your own host). All endpoints take Authorization: Bearer mv_… unless marked public. Errors return {"detail": "…"} with 400/401/403/404 status codes.

Interactive explorer: browse every endpoint in the API Explorer (generated from the OpenAPI spec; raw spec at /openapi.json).

Rate limits. Requests are limited per API key (a generous fixed window per minute). Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (unix seconds); over the limit you get 429 with Retry-After. The limiter fails open, so an outage never blocks traffic.

Collections · Memories · Search · Graph memory · Files & drop · Account & keys · Email · BYO config · Managed connectors · Agents & provenance · Intelligent memory · Admin · Misc

Collections

Memories

Create#

POST /v1/memory/collections/{collection}/memories
{"text": "…",                  // required, 1–10000 chars
 "importance": 0.7,            // 0–1
 "category": "other",
 "source": "api",
 "metadata": {},
 "container_tag": null}        // optional sub-namespace
→ 201 {"id", "text", "importance", "category", "source", "metadata",
        "images", "created_at", "updated_at"}

Everything else#

Search

POST /v1/memory/collections/{collection}/search     # one collection
POST /v1/memory/search                              # all collections
{"query": "…",                // required
 "limit": 5,                  // 1–50
 "min_score": 0.3,            // vector threshold
 "mode": "hybrid",            // hybrid | vector | text
 "category": null,
 "metadata_filter": null,     // JSONB containment
 "container_tag": null,
 "rewrite": false,            // optional LLM query expansion (+1 LLM call)
 "rerank": false}             // optional LLM re-ranking of top results (+1 LLM call)
→ {"results": [{"id","text","category","importance","score","source",
                "metadata","images","created_at","collection?"}],
   "query_embedding_ms": 12.3, "search_ms": 4.5, "cached": false}

Results exclude superseded and expired memories. Exact-repeat queries return from the cache (~1 ms) until the collection changes.

Graph memory

Files & drop

Per-file limit 10 MB.

Account & keys

Email drop

BYO configuration

Each follows the same shape: GET current (secrets never returned), PUT validates with a live self-test before saving (credentials encrypted at rest), DELETE reverts to the platform default.

Managed connectors

A managed connector is a connection RememberOS syncs for you server-side — you store the source's credentials once and RememberOS keeps a collection in sync (no code to run). This is distinct from the self-host connector recipes, which you run yourself via dlt. Credentials are encrypted at rest (Fernet) and never returned by the API.

How sync works. RememberOS fetches records newer than the connection's stored cursor from the provider (using the encrypted credentials), embeds and stores them in the connection's collection (scoped by its container_tag), and advances the cursor — so re-syncs are incremental. A failed sync sets status="error" with last_error and never affects other connections.

Automatic sync. Active connections also sync on their own: a background scheduler re-syncs each due connection (default every 60 min; set config.sync_interval_minutes to override). POST …/sync triggers one immediately.

Auto-pause. After 5 consecutive failed syncs a connection is set to status="paused" so the scheduler stops retrying a broken source (bad credentials, revoked token). It still appears in your connections; trigger POST …/sync manually once the cause is fixed — a successful run flips it back to active.

Server-syncable providers today: Slack (credentials.token + config.channel_id), Notion (credentials.token; optional config.database_id to sync one database instead of every shared page — pages are walked newest-edited first using the Notion API, version 2022-06-28), and Google Drive (credentials.token = a Google OAuth access token; optional config.folder_id or config.query — files are walked newest-modified first and native Google Docs are exported to text), and Linear (credentials.token = a Linear API key; issues are pulled newest-updated first via the GraphQL API, with title, description, state, assignee, team, and labels), and Confluence (Cloud: credentials.email + credentials.api_token, config.base_url, optional config.space_key — pages are walked newest-modified first and storage-format bodies are rendered to text), and Gmail (credentials.token = a Google OAuth access token with the gmail.readonly scope; optional config.query — messages are walked newest-first, subject/from + plain-text body), and HubSpot (credentials.token = a private-app token — CRM contacts are walked newest-modified first with name, title, company, and lifecycle stage). Postgres remains a self-host recipe while its managed sync rolls out.

In the dashboard. The dashboard has a Connections panel — add a connection, trigger a sync, watch its status and last error, and remove it, without writing any code.

Connect via OAuth (when configured). Instead of pasting a token, a tenant can authorize an OAuth app: GET /v1/memory/connections/oauth/{provider}/start?collection=&name= returns an authorize_url to send the user to; after they approve, the provider redirects back to GET /v1/memory/connections/oauth/{provider}/callback, which exchanges the code, stores the encrypted token as a connection, and bounces to the dashboard. Available for notion, slack, Google Drive, and Gmail once the operator sets that provider's OAuth app credentials; otherwise start returns 503 and pasting a token still works. Google Drive and Gmail use offline access, so RememberOS stores a refresh token and renews the access token automatically before each sync. The dashboard Connections panel shows a Connect with OAuth button for those providers that drives this flow for you.

Agent identities & provenance

Each API key is an agent identity (give it a label when you create it under keys). Multiple agents can share one tenant's collections — and every memory records which agent wrote it: writes (add, bulk, connectors) stamp created_by = {id, label}, returned on the memory. This is the foundation for shared, multi-agent memory — see who contributed what in a common collection.

Access control (shared vs private collections)#

By default a collection is open: every agent of the tenant can read and write it. Add a grant and the collection becomes restricted — only granted agents may access it, with per-agent read/write. So "Customer Support" can be shared across several agents while "Personal Memory" stays private to one. Writes/reads by a disallowed agent get 403; restricted collections are also excluded from that agent's tenant-wide search.

Intelligent memory

RememberOS doesn't just store memory — it keeps it clean. Dedup finds near-identical memories in a collection (cosine similarity over the most recent 500) and consolidates each cluster to one keeper (highest importance, then newest).

Archived memories are excluded from recall by default; pass include_archived: true on search or ?include_archived=true when listing to surface them. More intelligent-memory ops (collection summaries) are rolling out.

Operator endpoints

Require an admin-flagged tenant; aggregates only, tenant isolation intact.

Misc

Endpoints not listed here (/_internal/embed, /stripe/webhook, /email/inbound) are internal: secured by shared secrets or signatures, not for client use.