Rust SDK

Rust - 모든 메서드, 세 그룹.

쓰고, 읽고, 지우고. 아래 모든 예제는 2026-08-01 라이브 API에서 실제로 실행했고, 응답은 실물 그대로입니다.

cargo add wontopos
use wontopos::Client;

let mem = Client::new("wos-live-...");

모델 선택

API 키는 어느 기억(당신 계정)을, 모델은 어느 엔진이 그 기억을 읽을지 정합니다. 모든 모델이 기억을 공유하므로, 한 모델로 저장하고 다른 모델로 회수할 수 있습니다. with_model()로 기본값을 두고, 한 번 더 체이닝하면 그 호출만 바뀝니다.

let mem = Client::new("wos-live-...").with_model("tablet-1");  // default
mem.recall("...", "alice").await?;                       // tablet-1
mem.with_model("scroll-1").recall("...", "alice").await?;  // or pick a model per call

list_models

카탈로그 - with_model에 넣을 수 있는 id와 각 모델의 가용 여부. memory: "shared"는 같은 저장소를, "isolated"는 자기 저장소를 씁니다. API 키가 필요 없습니다.

mem.list_models().await?;
실제 응답
[{"id": "tablet-1", "name": "Tablet 1", "available": true, "memory": "shared"},
 {"id": "tablet-2", "name": "Tablet 2", "available": true, "memory": "shared"},
 {"id": "scroll-1", "name": "Scroll 1", "available": true, "memory": "shared"},
 {"id": "scroll-1.2", "name": "Scroll 1.2", "available": true, "memory": "shared"}]

ping

연결과 API 키가 유효한지 한 줄로 확인합니다.

mem.ping().await?;   // Ok(true), or Err whose .kind() is Auth / PaymentRequired

위 카탈로그는 항상 지금 쓸 수 있는 모델만 보여줍니다 - 다른 id를 넣으면 명확한 에러가 돌아옵니다. 새 모델은 출시되면 자동으로 거기에 나타납니다.

쓰기

add

기억 하나를 저장합니다. 적재에 LLM 호출이 없어, 쓰기 요금만 듭니다.

mem.add("she prefers tea over coffee", "alice", json!({})).await?;
mem.add("I promised the summary by Friday", "alice", json!({"speaker": "me"})).await?;  // its own words - no registration needed
실제 응답
{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

add_turn

대화 한 턴(사용자 + 어시스턴트)을 단기·장기 기억에 한 번에 저장합니다.

mem.add_turn("hi", "hello!", "alice").await?;
실제 응답
{"status": "ok"}

speaker

모든 기억에 누가 한 말인지 담을 수 있습니다. 사람은 한 번 등록하고, 그다음부터 이름을 speaker로 넘기세요. "me"(어시스턴트 자신의 말)는 등록이 필요 없습니다. 검색에도 speaker를 주면 그 사람의 말만 회수합니다.

mem.add_speaker("Bob", "alice").await?;  // once per person; "me" needs no registration
mem.add("I promised to send the report on Friday", "alice", json!({"speaker": "me"})).await?;
mem.add("Bob said the deadline moved to Tuesday", "alice", json!({"speaker": "Bob"})).await?;
mem.search_with("what did Bob say about deadlines?", "alice", 10, json!({"speaker": "Bob"})).await?;
화자는 저장소처럼 명시적입니다. 사람을 먼저 등록하고 그 이름으로 저장합니다. 오타가 조용히 새 사람이 되는 일이 없습니다. 저장소당 시작 기준 50명까지 등록되고(차차 늘릴 예정), "me"는 등록도 카운트도 필요 없습니다.

add_bulk

긴 텍스트를 한 번에 적재합니다. 서버에서 나누어 색인합니다 - 기존 히스토리 이관에 적합합니다.

mem.add_bulk("Alice moved to Brooklyn in March...", "alice", "general").await?;
실제 응답
{"elapsed_secs": 0.154154944, "status": "ok", "stored": 1, "total_chunks": 1}

update

사실이 바뀌었을 때. 옛 기억은 superseded 로 마킹되어 보존되고, 새 기억이 회수에서 그 자리를 차지합니다.

mem.update("576700aa-...", "she switched to coffee this year", "alice").await?;
실제 응답
{"new_memory_id": "07e94433-b7cc-4e49-8d8f-f37fc1a392b7",
 "old_memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "superseded"}

읽기

search

의미 검색, 관련도 순. 어떤 언어로 물어도, 어떤 언어로 적힌 기억이든 찾습니다. SDK는 memories 배열을 바로 돌려주며, 아래는 HTTP 원문입니다. 어떤 모델은 결과 묶음을 둘 이상으로 답하고 SDK가 그것을 합쳐 돌려주므로, 배열이 max_results보다 많을 수 있습니다. 요청한 숫자가 아니라 받은 배열을 기준으로 프롬프트 크기를 잡으십시오.

let r = mem.search("what does she drink?", "alice", 1).await?;
실제 응답 (HTTP 원문)
[{
   "id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624",
   "content": "she prefers tea over coffee",
   "category": "general",
   "time_bucket": "2026-06",
   "importance": 0.3,
   "similarity": 0.6316057443618774,
   "is_superseded": false,
   "superseded_by": null,
   "created_at": "2026-07-10T04:20:39.688276876Z"
 }]
필드의미
similarity질문과 이 기억이 얼마나 가까운지 (0–1).
is_supersededupdate()로 교체된 기억이면 true.
search_ms서버 검색 소요 시간.

recall

한 번의 왕복으로 LLM에 필요한 모든 것을 돌려줍니다 - 결과를 프롬프트에 그대로 넣으면 됩니다. 저장량과 무관하게 항상 고정 크기입니다.

let ctx = mem.recall("what does she drink?", "alice").await?;
실제 응답 (구조 - 목록 축약)
{"short_term":  {"count": 2, "turns": [{"role": "user", "content": "hi", ...}]},
 "long_term":   {"count": 4, "memories": [{"content": "she prefers tea over coffee",
                                           "similarity": 0.63, ...}]},
 "context":     {"count": 4, "around_top_memory": [
                  "[match] she prefers tea over coffee",
                  "[after] Alice moved to Brooklyn in March. ..."]},
 "instruction": "Use short_term for recent context, long_term for relevant
                 past memories, context for surrounding conversation of the
                 most relevant memory."}

history

최근 대화 턴(단기 기억), 오래된 것부터.

let turns = mem.history("alice").await?;
실제 응답 (HTTP 원문)
{"count": 2, "turns": [
   {"role": "user",      "content": "hi",     "timestamp": "2026-07-10T04:20:40.989011337Z"},
   {"role": "assistant", "content": "hello!", "timestamp": "2026-07-10T04:20:40.989013416Z"}
 ], "user_id": "alice"}

stats

한 사용자의 기억 통계.

mem.stats("alice").await?;
실제 응답
{"short_term_turns": 2, "total_memories": 4, "user_id": "alice"}

get

id로 기억 하나를 조회합니다 - add나 list_memories가 돌려준 그 id입니다. 저장한 원문과 메타데이터만 반환합니다. 다른 스토어의 id나 삭제·무효화된 기억은 404입니다.

let m = mem.get("alice", "576700aa-...").await?;
response
{"id": "576700aa-...", "content": "she prefers tea over coffee",
 "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}

list_memories

스토어에 저장된 기억을 나열합니다. 저장한 원문과 메타데이터만 반환합니다. 커서로 페이지를 넘깁니다 - 응답의 next_cursor를 다음 호출에 넘기면 됩니다.

mem.list_memories("alice", 100, None).await?;
response
{"count": 2, "next_cursor": null, "memories": [
   {"id": "576700aa-...", "content": "she prefers tea over coffee",
    "category": "general", "created_at": "2026-07-10T04:20:39Z", "event_date": null,
 "is_superseded": false, "superseded_by": null}
 ]}

list_all_memories

커서를 직접 관리하지 않고 모든 기억을 순회하거나, 스토어 전체를 한 번에 가져옵니다.

let all = mem.list_all_memories("alice").await?;   // every page, collected

삭제

delete

기억 하나를 id로 삭제합니다.

mem.delete("alice", "576700aa-...").await?;
실제 응답
{"memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "deleted"}

delete_all

한 사용자의 모든 기억을 삭제 - 한 번의 호출, GDPR 대응.

mem.delete_all("alice").await?;
실제 응답
{"memories_deleted": 4, "status": "deleted", "user_id": "alice"}

오류와 신뢰성

모든 실패는 타입이 있는 오류입니다. 상황별(rate limit·인증·결제)로 골라 잡거나, 기본 WosError로 한꺼번에 잡습니다.

use wontopos::ErrorKind;
match mem.search("...", "alice", 10).await {
    Ok(hits) => { /* use hits */ }
    Err(e) if e.kind() == ErrorKind::NotFound => { mem.create_store("alice").await?; }
    Err(e) if e.is_rate_limited() => { /* back off */ }
    Err(e) => return Err(e),
}

rate_limit

호출 직후 남은 한도를 읽어, 한계에 닿기 전에 속도를 늦춥니다.

mem.search("...", "alice", 10).await?;
let rl = mem.rate_limit();   // Some(RateLimit { remaining: Some(3), .. })

search_self

자기기억 모델(Scroll 1.2+)에서 한 번의 호출로 두 갈래를 받습니다: 남이 한 말과 에이전트 자신이 한 말을 따로 돌려주므로, 읽는 쪽이 누가 말했는지 헷갈리지 않습니다.

let r = mem.search_self("what did I promise?", "alice", 10).await?;
// r.memories = what others said · r.self_memories = the agent's OWN words

list_engrams

이 모델이 실행할 수 있는 엔그램과 딜리버리 폼을 서비스에 물어봅니다. 이름을 하드코딩하면 새 엔그램이 나온 순간부터 그 코드에는 영영 보이지 않습니다.

let cat = mem.list_engrams().await?;  // ask, never hard-code

filters

검색을 저장소의 일부로 좁힙니다. 랭킹 전에 걸리므로 필터 안에서의 최선이 나옵니다 - 상위 N 을 걸러낸 것이 아닙니다.

mem.search_with("what did we decide", "alice", 10, json!({"filters": {
    "categories": ["work"], "event_from": "2026-01-01"   // when it HAPPENED
}})).await?;
키: categories · event_from / event_to (내용이 언제 일어났나 - metadata.event_date) · time_from / time_to (언제 적재됐나) · min_importance. 목록에 없는 키는 거부가 아니라 버려지므로, 오타는 조용히 검색을 넓힙니다.

add_idempotent

쓰기 하나를 다시 보내도 안전하게 만듭니다. 재시도가 내 쪽에서 일어날 때 씁니다 - 죽었다 다시 돈 작업, 다시 전달하는 큐.

mem.add_idempotent("she prefers tea", "alice", json!({}), &format!("import:{}", row.id)).await?;
키는 저장하려는 대상에서 뽑아 만드세요(import:row-42). 상수를 쓰면 안 됩니다 - 서로 다른 두 쓰기에 같은 키를 쓰면 첫 응답이 재생되고 두 번째 쓰기는 조용히 사라집니다. 형식: [A-Za-z0-9._:-] 1~128 자.

with_timeout / with_retries / with_deadline

이미 만들어 둔 클라이언트를 건드리지 않고 호출 지점 하나만 조정합니다. 큰 백필에는 타임아웃이 긴 복제본을, 직접 재시도 루프를 돌 때는 재시도를 끈 복제본을 씁니다.

timeout은 시도 하나를 묶습니다. 그래서 재시도하는 호출은 그보다 오래 걸릴 수 있습니다 — 기본값이면 한 번의 호출이 30초를 붙들고, 물러섰다가, 다시 시도하고, 또 시도합니다. deadline은 대신 호출 전체를 묶습니다. 매 시도가 남은 시간만큼으로 잘리고, 물러서는 시간도 예산을 넘겨 자지 않습니다. 호출하는 쪽에 실제 한도가 있을 때 — 5초짜리 요청 핸들러 같은 곳에 — 설정하세요.

mem.with_timeout(120).add_bulk(big_blob, "alice", "general").await?;
mem.with_retries(0).add("...", "alice", json!({})).await?;
mem.with_deadline(Duration::from_secs(5)).recall("...", "alice").await?;  // 5s for the whole call