# 메모리 API

명시적인 scope 경계를 두고 문서화된 REST 및 MCP contract를 통해 memory를 읽고 씁니다.

- Canonical: https://docs.xmemo.dev/ko/docs/api/memory
- Locale: ko-KR
- Content-Locale: ko-KR
- Canonical-Content-Digest: 446b069541121da293fcc920696cb4e6d4e9fd7cc186d28bbbc1c688a7b3ffcc
- Edition-Digest: 97fbc23819c3c1cb59293c79ada44d4bad470b28f08e735d2dda62328c82d449
- 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가 현재 반환하는 documented 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).
- 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 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 기본값은 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 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)는 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는 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를 수락합니다. 모든 필드는 선택 사항이며 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가 수락되므로 쓰기 토큰이 영구 삭제를 트리거할 수 있습니다. 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, error와 rate limit

OpenAPI에서 list pagination을 노출하는 것은 GET /v1/memories뿐이며 limit 기본값은 100, offset 기본값은 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-second 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"
}
```