Public memory endpoints and scopes
The examples below use the /v1 paths that are present in the committed OpenAPI contract. Authenticate with X-API-Key (or the server's accepted Bearer form); read operations need a read-capable token and writes need a write-capable token. The OpenAPI response schema is intentionally untyped for most memory endpoints, so the documented implementation keys are called out separately where the server currently returns them. GET /v1/memories currently returns an object with memories (array) and total (number), but those properties are not declared in OpenAPI.
- Create/capture: POST /v1/remember and POST /v1/memories (201).
- List: GET /v1/memories with limit, offset, and path (200).
- Search: GET /v1/memories/search; GET /v1/recall is the same search operation (200).
- Assemble context: POST /v1/recall/context (200).
- Update: PATCH /v1/memories/{memory_id}; delete: DELETE /v1/memories/{memory_id}.
- Forget: POST /v1/memories/{memory_id}/forget; restore: POST /v1/memories/{memory_id}/restore; complete reminder: POST /v1/reminders/{reminder_id}/complete.
Create request schemas
POST /v1/remember accepts MemoryRememberRequest; POST /v1/memories accepts MemoryStoreRequest. Both require content (string) and path (string). Optional fields in the OpenAPI schemas include metadata (object), source (string or null), logic_path (string or null), embedding (number array or null), bucket (string, default public), memory_id, semantic_key, memory_type, version, status, superseded_by, embedding_provider, embedding_model, embedding_dimension, importance, confidence, expires_at, scope, team_id, and provenance. MemoryRememberRequest additionally declares dedupe (boolean, default true); MemoryStoreRequest defaults memory_type to semantic and importance/confidence to 0.5/1.0.
POST /v1/remember
X-API-Key: <your-assigned-api-key>
Content-Type: application/json
{
"content": "The actual text to remember.",
"path": "projects/memory-os/decisions",
"scope": "memory-os",
"source": "codex",
"metadata": { "kind": "decision" }
}Create response schemas
The OpenAPI 201 response content is an untyped JSON object for both create operations. The current remember implementation returns {id: string, status: "remembered"}; the store implementation returns the created memory identifier. Treat these as implementation behavior, not a stronger schema than the committed OpenAPI document declares.
{
"id": "<memory-id>",
"status": "remembered"
}Search and recall
GET /v1/memories/search and GET /v1/recall share the Search Memories operation and return Cache-Control: no-store, private. Filters narrow retrieval and cannot widen what the token authorizes.
GET /v1/memories/search?query=current%20MCP%20decision&limit=5&scope=memory-os&explain=true
X-API-Key: <your-assigned-api-key>Search request parameters and response
OpenAPI query parameters are query (string, required), limit (integer, default 5), threshold (number or null), path (string, default %), bucket (string, default %), scope (string or null), team_id (string or null), memory_type (string, default %), status (string, default active), explain (boolean, default false), prefer_working (boolean, default false), and candidate_count (integer or null). OpenAPI leaves the 200 response as an untyped JSON object; the implementation currently returns results (array) and coverage (number), and may add keyguard_decrypt_grant_ids when applicable.
- Response shape currently observed: { results: [...], coverage: number }.
- The spec does not declare a maximum for search limit or candidate_count; clients should use conservative values and handle validation errors.
Context request and response schemas
POST /v1/recall/context accepts RecallContextRequest. query (string) is required; path and bucket default to %, memory_type defaults to auto, status to active, max_items to 8, max_tokens to 1500, prefer_working to true, include_knowledge to false, and scope, team_id, threshold, and limit are nullable. The OpenAPI 200 response is an untyped object; the normal authenticated-owner implementation returns a value-density-v2 context object with version, query, retrieval_plan, budget, items, context_text, and answer_status. The temporary-agent branch returns version 1.0 with the same core query/budget/items/context_text fields.
POST /v1/recall/context
X-API-Key: <your-assigned-api-key>
Content-Type: application/json
{
"query": "recent progress on memory-os",
"scope": "memory-os",
"memory_type": "auto",
"status": "active",
"max_items": 8,
"max_tokens": 1500,
"prefer_working": true
}Memory update and forget schemas
PATCH /v1/memories/{memory_id} accepts MemoryUpdateRequest: all fields are optional, and content, path, metadata, source, logic_path, embedding, bucket, semantic_key, memory_type, status, superseded_by, embedding_provider, embedding_model, embedding_dimension, importance, confidence, expires_at, scope, team_id, provenance, supersession_reason, merge_metadata (default true), merge_provenance (default true), and detect_conflicts (default true) are declared. DELETE /v1/memories/{memory_id} accepts query mode (default soft_delete) and reason; mode=hard_delete and mode=redact are irreversible, and memory:write is accepted by compatibility rules so write tokens can permanently delete records. POST /v1/memories/{memory_id}/forget accepts MemoryForgetRequest with mode (default soft_delete), reason, replacement_content, and metadata. POST /v1/memories/{memory_id}/restore restores soft-deleted records. The 200 responses for these lifecycle operations are typed in the public OpenAPI schema.
POST /v1/memories/<memory-id>/forget
X-API-Key: <your-assigned-api-key>
Content-Type: application/json
{
"mode": "soft_delete",
"reason": "No longer needed"
}Pagination, errors, and rate limits
Only GET /v1/memories exposes list pagination in OpenAPI: limit defaults to 100 and offset to 0, with an optional path filter. Search uses limit rather than offset; context uses max_items/max_tokens rather than page cursors. The documented validation error is HTTPValidationError: {detail: [{loc: (string|integer)[], msg: string, type: string}]}. Runtime authorization failures use the shared error contract on the Authentication page. The runtime applies the 180-per-minute memory_write policy to writes/lifecycle mutations and the 300-per-minute memory_search policy to search, recall, context, and memory reads, inside a 60-second window when enabled; quotas are configurable and absent from OpenAPI.
{
"version": "value-density-v2",
"query": "recent progress on memory-os",
"retrieval_plan": {},
"budget": {
"max_items": 8,
"max_tokens": 1500,
"used_items": 3,
"used_tokens": 412,
"skipped_items": 0,
"filtered_items": 0,
"structured_skipped_items": 0,
"budget_skipped_items": 0,
"truncated_items": 0,
"candidate_items": 3,
"selection_strategy": "top-primary-plus-stable-value-density",
"budget_tradeoff": false,
"token_scope": "context_text"
},
"items": [],
"context_text": "",
"answer_status": "no_confirmed_answer"
}Source: MCP tool surface