# 记忆 API

通过有明确 scope 边界的 REST 和 MCP contracts 读写 memory。

- Canonical: https://docs.xmemo.dev/zh/docs/api/memory
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 446b069541121da293fcc920696cb4e6d4e9fd7cc186d28bbbc1c688a7b3ffcc
- Edition-Digest: 3c748196225bed752669654a2cb094f16152fa67ccbf926e2e4bb43e46e106ad
- Source-Revision: sha256:004c0ac7668443326dc253ae102d38bbd116e9cc540e7df7d066772f28b3a152

## 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。

```http
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。

```json
{
  "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 获得授权的范围。

```http
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。

```http
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 规范中均为强类型。

```http
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 中声明。

```json
{
  "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"
}
```