Endpoints públicos de memória e escopos
Os exemplos abaixo usam os caminhos /v1 presentes no contrato OpenAPI versionado. Autentique com X-API-Key (ou com a forma Bearer aceita pelo servidor); operações de leitura exigem um token com capacidade de leitura e gravações exigem um token com capacidade de escrita. O esquema de resposta OpenAPI é intencionalmente sem tipo para a maioria dos endpoints de memória; as chaves da implementação atual são destacadas separadamente quando o servidor as retorna. GET /v1/memories atualmente retorna um objeto com memories (array) e total (number), mas essas propriedades não estão declaradas no OpenAPI.
- Criar/capturar: POST /v1/remember e POST /v1/memories (201).
- Listar: GET /v1/memories com limit, offset e path (200).
- Buscar: GET /v1/memories/search; GET /v1/recall é a mesma operação de busca (200).
- Montar contexto: POST /v1/recall/context (200).
- Atualizar: PATCH /v1/memories/{memory_id}; excluir: DELETE /v1/memories/{memory_id}.
- Esquecer: POST /v1/memories/{memory_id}/forget; restaurar: POST /v1/memories/{memory_id}/restore; concluir lembrete: POST /v1/reminders/{reminder_id}/complete.
Esquemas de solicitação de criação
POST /v1/remember aceita MemoryRememberRequest; POST /v1/memories aceita MemoryStoreRequest. Ambos exigem content (string) e path (string). Os campos opcionais nos esquemas OpenAPI incluem 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 e provenance. MemoryRememberRequest também declara dedupe (boolean, default true); MemoryStoreRequest define memory_type como semantic e importance/confidence como 0.5/1.0 por padrão.
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 resposta de criação
O conteúdo de resposta 201 do OpenAPI é um objeto JSON sem tipo para as duas operações de criação. A implementação atual de remember retorna {id: string, status: "remembered"}; a implementação de store retorna o identificador da memória criada. Trate isso como comportamento da implementação, não como um esquema mais forte que o documento OpenAPI declara.
{
"id": "<memory-id>",
"status": "remembered"
}Busca e recall
GET /v1/memories/search e GET /v1/recall compartilham a operação Search Memories e retornam Cache-Control: no-store, private. Os filtros restringem a recuperação e não podem ampliar o que o token autoriza.
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 solicitação e resposta da busca
Os parâmetros de consulta OpenAPI são 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) e candidate_count (integer or null). O OpenAPI deixa a resposta 200 como um objeto JSON sem tipo; a implementação atualmente retorna results (array) e coverage (number), e pode adicionar keyguard_decrypt_grant_ids quando aplicável.
- Formato de resposta observado atualmente: { results: [...], coverage: number }.
- A especificação não declara um máximo para search limit ou candidate_count; os clientes devem usar valores conservadores e tratar erros de validação.
Esquemas de solicitação e resposta de contexto
POST /v1/recall/context aceita RecallContextRequest. query (string) é obrigatório; path e bucket têm % como padrão, memory_type tem auto como padrão, status tem active, max_items tem 8, max_tokens tem 1500, prefer_working tem true, include_knowledge tem false, e scope, team_id, threshold e limit aceitam null. A resposta 200 do OpenAPI é um objeto sem tipo; a implementação normal autenticada do proprietário retorna um objeto de contexto value-density-v2 com version, query, retrieval_plan, budget, items, context_text e answer_status. A ramificação de agente temporário retorna a versão 1.0 com os mesmos campos principais 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 atualização e esquecimento de memória
PATCH /v1/memories/{memory_id} aceita MemoryUpdateRequest: todos os campos são opcionais, 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 (padrão true), merge_provenance (padrão true) e detect_conflicts (padrão true). DELETE /v1/memories/{memory_id} aceita query mode (padrão soft_delete) e reason; mode=hard_delete e mode=redact são irreversíveis, e memory:write é aceito pelas regras de compatibilidade, permitindo que tokens de escrita excluam permanentemente. POST /v1/memories/{memory_id}/forget aceita MemoryForgetRequest com mode (padrão soft_delete), reason, replacement_content e metadata. POST /v1/memories/{memory_id}/restore restaura registros excluídos suavemente. As respostas 200 para essas operações do ciclo de vida são tipadas no 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"
}Paginação, erros e limites
Somente GET /v1/memories expõe paginação de lista no OpenAPI: limit tem padrão 100 e offset tem padrão 0, com um filtro path opcional. A busca usa limit em vez de offset; o contexto usa max_items/max_tokens em vez de cursores de página. O erro de validação documentado é HTTPValidationError: {detail: [{loc: (string|integer)[], msg: string, type: string}]}. Falhas de autorização do runtime usam o contrato de erro compartilhado na página Authentication. O runtime aplica a política memory_write de 180 por minuto a gravações/mutações do ciclo de vida e a política memory_search de 300 por minuto a busca, recall, context e leituras de memória, dentro de uma janela de 60 segundos quando habilitado; as cotas são configuráveis e não constam no 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"
}Origem: Superfície de ferramentas MCP