Endpoints y scopes de memoria pública
Los ejemplos siguientes usan las rutas /v1 presentes en el contrato OpenAPI versionado. Autentícate con X-API-Key (o con la forma Bearer aceptada por el servidor); las operaciones de lectura necesitan un token con capacidad de lectura y las escrituras uno con capacidad de escritura. El esquema de respuesta OpenAPI no tiene tipo intencionadamente para la mayoría de los endpoints de memoria, por lo que las claves de implementación documentadas se señalan aparte cuando el servidor las devuelve. GET /v1/memories devuelve actualmente un objeto con memories (array) y total (number), pero esas propiedades no están declaradas en OpenAPI.
- Crear/capturar: POST /v1/remember y POST /v1/memories (201).
- Listar: GET /v1/memories con limit, offset y path (200).
- Buscar: GET /v1/memories/search; GET /v1/recall es la misma operación de búsqueda (200).
- Ensamblar contexto: POST /v1/recall/context (200).
- Actualizar: PATCH /v1/memories/{memory_id}; eliminar: DELETE /v1/memories/{memory_id}.
- Olvidar: POST /v1/memories/{memory_id}/forget; restaurar: POST /v1/memories/{memory_id}/restore; completar recordatorio: POST /v1/reminders/{reminder_id}/complete.
Esquemas de solicitud de creación
POST /v1/remember acepta MemoryRememberRequest; POST /v1/memories acepta MemoryStoreRequest. Ambos requieren content (string) y path (string). Los campos opcionales de los esquemas OpenAPI incluyen 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 y provenance. MemoryRememberRequest declara además dedupe (boolean, default true); MemoryStoreRequest establece memory_type en semantic e importance/confidence en 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" }
}Esquemas de respuesta de creación
El contenido de respuesta 201 de OpenAPI es un objeto JSON sin tipo para ambas operaciones de creación. La implementación actual de remember devuelve {id: string, status: "remembered"}; la implementación de store devuelve el identificador de la memoria creada. Trátalos como comportamiento de implementación, no como un esquema más fuerte que el declarado por el documento OpenAPI versionado.
{
"id": "<memory-id>",
"status": "remembered"
}Búsqueda y recall
GET /v1/memories/search y GET /v1/recall comparten la operación Search Memories y devuelven Cache-Control: no-store, private. Los filtros acotan la recuperación y no pueden ampliar lo que autoriza el token.
GET /v1/memories/search?query=current%20MCP%20decision&limit=5&scope=memory-os&explain=true
X-API-Key: <your-assigned-api-key>Parámetros de solicitud y respuesta de búsqueda
Los parámetros de consulta OpenAPI son 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) y candidate_count (integer or null). OpenAPI deja la respuesta 200 como objeto JSON sin tipo; la implementación devuelve actualmente results (array) y coverage (number), y puede añadir keyguard_decrypt_grant_ids cuando corresponda.
- Forma de respuesta observada actualmente: { results: [...], coverage: number }.
- La especificación no declara un máximo para search limit o candidate_count; los clientes deben usar valores conservadores y gestionar los errores de validación.
Esquemas de solicitud y respuesta de contexto
POST /v1/recall/context acepta RecallContextRequest. query (string) es obligatorio; path y bucket tienen por defecto %, memory_type por defecto auto, status active, max_items 8, max_tokens 1500, prefer_working true, include_knowledge false, y scope, team_id, threshold y limit son anulables. La respuesta 200 de OpenAPI es un objeto sin tipo; la implementación normal para un owner autenticado devuelve un objeto de contexto value-density-v2 con version, query, retrieval_plan, budget, items, context_text y answer_status. La rama de agente temporal devuelve version 1.0 con los mismos campos base query/budget/items/context_text.
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
}Esquemas de actualización y forget de memoria
PATCH /v1/memories/{memory_id} acepta MemoryUpdateRequest: todos los campos son opcionales, declarando 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 (predeterminado true), merge_provenance (predeterminado true) y detect_conflicts (predeterminado true). DELETE /v1/memories/{memory_id} acepta query mode (predeterminado soft_delete) y reason; mode=hard_delete y mode=redact son irreversibles, y memory:write se acepta por reglas de compatibilidad, permitiendo que tokens de escritura eliminen permanentemente. POST /v1/memories/{memory_id}/forget acepta MemoryForgetRequest con mode (predeterminado soft_delete), reason, replacement_content y metadata. POST /v1/memories/{memory_id}/restore restaura registros eliminados de forma recuperable. Las respuestas 200 para estas operaciones de ciclo de vida están tipadas en el esquema OpenAPI público.
POST /v1/memories/<memory-id>/forget
X-API-Key: <your-assigned-api-key>
Content-Type: application/json
{
"mode": "soft_delete",
"reason": "No longer needed"
}Paginación, errores y límites de velocidad
Solo GET /v1/memories expone paginación de lista en OpenAPI: limit tiene por defecto 100 y offset 0, con un filtro path opcional. Search usa limit en lugar de offset; context usa max_items/max_tokens en lugar de cursores de página. El error de validación documentado es HTTPValidationError: {detail: [{loc: (string|integer)[], msg: string, type: string}]}. Los fallos de autorización del runtime usan el contrato de error compartido de la página Authentication. El runtime aplica la política memory_write de 180 por minuto a escrituras/mutaciones del ciclo de vida y la política memory_search de 300 por minuto a search, recall, context y lecturas de memoria, dentro de una ventana de 60 segundos cuando está habilitado; las cuotas son configurables y no aparecen en 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"
}Fuente: Superficie de herramientas MCP