Read, search and propose memory.
The Cloud alpha exposes four retrieval tools and, with memory:propose permission, propose_memory. Access comes from the OAuth connection grant at the Cloud /mcp endpoint.
Access comes from the connection.
The workspace and authorised collections come from the authenticated connection. Optional collection and data-class filters narrow that access; they do not grant new permissions.
This reference describes the Cloud implementation checked on 14 September 2026. The original pilot used different inputs, including list_projects; its proposal format must not be reused here.
Retrieval tools.
{
"collection_id": "memory",
"kind": "decision",
"limit": 20,
"offset": 0
}Optional filters: collection_id, prefix, kind, limit (1–1000), offset. Read returned document paths rather than guessing them.
{
"path": "projects/launch/decision.md",
"collection_id": "memory"
}Required: path. Optional: collection_id. The path above is illustrative; use a path from your own authorised results.
{
"task_summary": "Draft the launch update using the current date and beta access decision.",
"collection_id": "memory",
"requested_lanes": [
"current_state",
"relevant_memory",
"open_threads"
]
}Required: task_summary (1–4000 characters). Optional: collection_id, requested_lanes, data_classes, source_kinds, entity_ids. Lanes: working_rules, current_state, relevant_memory, open_threads, history_if_relevant.
{
"query": "current launch date",
"collection_id": "memory",
"page_size": 10
}Required: query (1–2000 characters). Optional: collection_id, context_id, data_classes, source_kinds, entity_ids, page_size (1–50), cursor. Reuse a returned context handle or cursor only within its original authority and lifetime.
Open the source before relying on it.
Search excerpts may be truncated. Use get_document to read the source your answer depends on. Check temporal status: project background and superseded decisions are not automatically the current answer.
A published memory can become stale if its source is not updated. Follow the freshness information returned by the service; do not treat the existence of a connection as proof that the record is current.
Recover without widening access.
| Situation | Next step |
|---|---|
| Unauthorised or expired connection | Stop and reconnect through the supported authorisation flow. |
| Material is outside the grant | Use permitted sources or ask the owner to review the connection. Do not probe alternative paths. |
| Expired context handle or cursor | Make a fresh context or search request; do not replay a handle under another grant. |
| Stale or insufficient context | Report the gap and ask for the source to be updated. Do not invent a current answer. |
Capture and changes.
{
"collection_id": "memory",
"idempotency_key": "launch-date-2026-11-12",
"session_id": "launch-planning-session",
"kind": "decision",
"text": "Move the launch to 12 November. Keep the beta invite-only.",
"data_class": "internal",
"source": {
"type": "user_statement",
"reference": "session:launch-planning:message-12"
}
}Required: idempotency_key, session_id, kind, text, data_class and source. collection_id is optional only when the connection has exactly one permitted writable collection. Kinds: fact, decision, preference, open_thread, correction. Source requires type (user_statement, verified_result, external_source or agent_inference) and reference (up to 512 characters); its reported type does not grant trust. Identifiers are up to 128 characters. The API accepts text up to 8,000 characters within its payload limit; current active-memory claims are limited to 4,000 characters, so use concise, self-contained proposals for automatic processing. Data classes are public, internal, confidential and restricted, within the connection grant.
Retry an identical payload with the same idempotency_key; different content needs a new key. A receipt includes entry_id, status: pending, canonical: false and replayed. Do not claim the memory is active until processing and activation have been verified.
propose_memory appends a pending proposal to a writable cloud-owned collection. It requires memory:propose consent and is not advertised to read-only connections. A pending receipt confirms capture, not activation.
Cloud consolidation, source-linked corrections and automatic activation run for explicitly enabled collections. A scoped Codex setup also captures user statements and delivers current context automatically. Enrollment and the first activation remain guided; creating an account or connecting MCP alone does not enable this full loop.