Public memory endpoints and scopes
下面的 examples 使用已存在于 committed OpenAPI contract 中的 /v1 paths。使用 X-API-Key（或 server 接受的 Bearer form）进行认证；read operations 需要具备 read capability 的 token，writes 需要具备 write capability 的 token。大多数 memory endpoints 的 OpenAPI response schema 有意保持 untyped，因此在 server 当前返回这些 keys 的地方会单独指出。GET /v1/memories 当前返回包含 memories（array）和 total（number）的 object，但这些 properties 没有在 OpenAPI 中声明。
- Create/capture：POST /v1/remember 和 POST /v1/memories（201）。
- List：GET /v1/memories，支持 limit、offset 和 path（200）。
- Search：GET /v1/memories/search；GET /v1/recall 是相同的 search operation（200）。
- Assemble context：POST /v1/recall/context（200）。
- Update：PATCH /v1/memories/{memory_id}；delete：DELETE /v1/memories/{memory_id}。
- 遗忘: POST /v1/memories/{memory_id}/forget; 恢复: POST /v1/memories/{memory_id}/restore; 完成提醒: POST /v1/reminders/{reminder_id}/complete。
Create request schemas
POST /v1/remember 接受 MemoryRememberRequest；POST /v1/memories 接受 MemoryStoreRequest。两者都要求 content（string）和 path（string）。OpenAPI schemas 中的 optional fields 包括 metadata（object）、source（string 或 null）、logic_path（string 或 null）、embedding（number array 或 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 和 provenance。MemoryRememberRequest 还声明 dedupe（boolean，default true）；MemoryStoreRequest 将 memory_type 默认设为 semantic，将 importance/confidence 默认设为 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
两个 create operations 的 OpenAPI 201 response content 都是 untyped JSON object。当前 remember implementation 返回 {id: string, status: "remembered"}；store implementation 返回 created memory identifier。应将它们视为 implementation behavior，而不是比 committed OpenAPI document 声明更强的 schema。
{
"id": "<memory-id>",
"status": "remembered"
}Search and recall
GET /v1/memories/search 和 GET /v1/recall 共享 Search Memories operation，并返回 Cache-Control: no-store, private。Filters 只会缩小 retrieval 范围，不会扩大 token 获得授权的范围。
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 是 query（string，required）、limit（integer，default 5）、threshold（number 或 null）、path（string，default %）、bucket（string，default %）、scope（string 或 null）、team_id（string 或 null）、memory_type（string，default %）、status（string，default active）、explain（boolean，default false）、prefer_working（boolean，default false）和 candidate_count（integer 或 null）。OpenAPI 将 200 response 保持为 untyped JSON object；当前 implementation 返回 results（array）和 coverage（number），适用时还可能添加 keyguard_decrypt_grant_ids。
- 当前观察到的 response shape：{ results: [...], coverage: number }。
- spec 没有声明 search limit 或 candidate_count 的最大值；client 应使用保守值并处理 validation errors。
Context request and response schemas
POST /v1/recall/context 接受 RecallContextRequest。query（string）是 required；path 和 bucket 默认 %，memory_type 默认 auto，status 默认 active，max_items 默认 8，max_tokens 默认 1500，prefer_working 默认 true，include_knowledge 默认 false，而 scope、team_id、threshold 和 limit 可为 null。OpenAPI 200 response 是 untyped object；正常的 authenticated-owner implementation 返回带有 version、query、retrieval_plan、budget、items、context_text 和 answer_status 的 value-density-v2 context object。temporary-agent branch 返回 version 1.0，但具有相同的核心 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} 接受 MemoryUpdateRequest：所有字段均为可选，声明了 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（默认 true）、merge_provenance（默认 true）和 detect_conflicts（默认 true）。DELETE /v1/memories/{memory_id} 接受 query mode（默认 soft_delete）和 reason；mode=hard_delete 与 mode=redact 是不可逆的，且兼容性规则接受 memory:write，因此写 token 可以触发永久删除。POST /v1/memories/{memory_id}/forget 接受包含 mode（默认 soft_delete）、reason、replacement_content 和 metadata 的 MemoryForgetRequest。POST /v1/memories/{memory_id}/restore 恢复软删除记录。这些生命周期操作的 200 响应在公开 OpenAPI 规范中均为强类型。
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
只有 GET /v1/memories 在 OpenAPI 中暴露 list pagination：limit 默认 100，offset 默认 0，并带有可选的 path filter。Search 使用 limit 而不是 offset；context 使用 max_items/max_tokens 而不是 page cursors。文档化的 validation error 是 HTTPValidationError：{detail: [{loc: (string|integer)[], msg: string, type: string}]}。Runtime authorization failures 使用 Authentication page 的 shared error contract。当启用时，runtime 在 60 秒 window 内对 writes/lifecycle mutations 应用每分钟 180 次的 memory_write policy，对 search、recall、context 和 memory reads 应用每分钟 300 次的 memory_search policy；quotas 可配置且不在 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"
}