# Memory API

明示的なscope boundaryを持つ、文書化されたRESTとMCP contractを通じてmemoryをread/writeします。

- Canonical: https://docs.xmemo.dev/ja/docs/api/memory
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 446b069541121da293fcc920696cb4e6d4e9fd7cc186d28bbbc1c688a7b3ffcc
- Edition-Digest: 095954dd3880ee061becb961011c91cb5d97043ca69d130fceb0196070b9d91e
- Source-Revision: sha256:004c0ac7668443326dc253ae102d38bbd116e9cc540e7df7d066772f28b3a152

## 公開memory endpointとscope

以下の例では、committed OpenAPI contractに存在する/v1 pathを使います。X-API-Key（またはserverが受け付けるBearer形式）で認証し、read operationにはread-capable token、writeにはwrite-capable tokenが必要です。ほとんどのmemory endpointではOpenAPI response schemaが意図的にuntypedなので、serverが現在返すimplementation keyは別途示します。GET /v1/memoriesは現在、memories（array）とtotal（number）を持つobjectを返しますが、これらのpropertyは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）。
- 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 schema

POST /v1/rememberはMemoryRememberRequestを受け取り、POST /v1/memoriesはMemoryStoreRequestを受け取ります。どちらもcontent（string）とpath（string）が必須です。OpenAPI schemaのoptional fieldには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のdefaultはsemantic、importance/confidenceのdefaultは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 schema

OpenAPIの201 response contentは、どちらのcreate operationでもuntyped JSON objectです。現在のremember implementationは{id: string, status: "remembered"}を返し、store implementationは作成したmemory identifierを返します。これを、committed OpenAPI documentが宣言するものより強いschemaとは扱わず、implementation behaviorとして扱ってください。

```json
{
  "id": "<memory-id>",
  "status": "remembered"
}
```

## Searchとrecall

GET /v1/memories/searchとGET /v1/recallはSearch Memories operationを共有し、Cache-Control: no-store, privateを返します。filterは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 parameterとresponse

OpenAPI query parameterは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のmaximumを宣言していないため、clientは控えめな値を使い、validation errorを処理してください。

## Context requestとresponse schema

POST /v1/recall/contextはRecallContextRequestを受け取ります。query（string）は必須で、pathとbucketのdefaultは%、memory_typeはauto、statusはactive、max_itemsは8、max_tokensは1500、prefer_workingはtrue、include_knowledgeはfalseです。scope、team_id、threshold、limitはnullableです。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は同じcore query/budget/items/context_text fieldを持つversion 1.0を返します。

```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とforget schema

PATCH /v1/memories/{memory_id}はMemoryUpdateRequestを受け入れます。すべてのフィールドはoptionalで、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）、detect_conflicts（default true）が宣言されています。DELETE /v1/memories/{memory_id}はquery mode（default soft_delete）とreasonを受け入れます。mode=hard_deleteとmode=redactは不可逆であり、互換性ルールによりmemory:writeが受け入れられるため、書き込みtokenで永久削除をトリガーできます。POST /v1/memories/{memory_id}/forgetはmode（default 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、error、rate limit

OpenAPIでlist paginationを公開しているのはGET /v1/memoriesだけです。limitのdefaultは100、offsetのdefaultは0で、optionalなpath filterがあります。Searchはoffsetではなくlimitを使い、contextはpage cursorではなくmax_items/max_tokensを使います。文書化されたvalidation errorはHTTPValidationError: {detail: [{loc: (string|integer)[], msg: string, type: string}]}です。runtime authorization failureはAuthentication pageのshared error contractを使います。runtimeは有効な60秒window内で、writes/lifecycle mutationに180-per-minute memory_write policyを、search、recall、context、memory readに300-per-minute memory_search policyを適用します。quotaはconfigurableで、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"
}
```