TypeScript SDK

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

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

npm install wontopos
import { Client } from "wontopos";

const mem = new Client({ apiKey: "wos-live-..." });

모델 선택

API 키는 어느 기억(당신 계정)을, 모델은 어느 엔진이 그 기억을 읽을지 정합니다. 모든 모델이 기억을 공유하므로, 한 모델로 저장하고 다른 모델로 회수할 수 있습니다. 생성자에 기본값을 두고, withModel()로 호출마다 바꾸세요.

const mem = new Client({ apiKey: "wos-live-...", model: "tablet-1" });  // default
mem.recall("...", "alice");                          // tablet-1
mem.withModel("scroll-1").recall("...", "alice");  // or pick a model per call

listModels

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

await mem.listModels();
실제 응답
[{"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 키가 유효한지 한 줄로 확인합니다.

await mem.ping();   // true, or throws AuthenticationError / PaymentRequiredError

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

쓰기

add

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

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

addTurn

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

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

speaker

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

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

addBulk

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

await mem.addBulk("Alice moved to Brooklyn in March. She works at a design studio downtown.", "alice");
실제 응답
{"elapsed_secs": 0.154154944, "status": "ok", "stored": 1, "total_chunks": 1}

update

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

await mem.update("576700aa-...", "she switched to coffee this year", "alice");
실제 응답
{"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보다 많을 수 있습니다. 요청한 숫자가 아니라 받은 배열을 기준으로 프롬프트 크기를 잡으십시오.

const r = await mem.search("what does she drink?", "alice", 1);
실제 응답 (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에 필요한 모든 것을 돌려줍니다 - 결과를 프롬프트에 그대로 넣으면 됩니다. 저장량과 무관하게 항상 고정 크기입니다.

const ctx = await mem.recall("what does she drink?", "alice");
실제 응답 (구조 - 목록 축약)
{"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

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

const turns = await mem.history("alice");
실제 응답 (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

한 사용자의 기억 통계.

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

get

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

const m = await mem.get("alice", "576700aa-...");
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}

listMemories

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

const page = await mem.listMemories("alice", { limit: 100 });
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}
 ]}

iterMemories · exportMemories

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

for await (const m of mem.iterMemories("alice")) console.log(m.id, m.content);
const everything = await mem.exportMemories("alice");

삭제

delete

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

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

deleteAll

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

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

오류와 신뢰성

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

import { NotFoundError, PaymentRequiredError } from "wontopos";
try {
  await mem.add("...", "alice");
} catch (e) {
  if (e instanceof NotFoundError) await mem.createStore("alice");
  else if (e instanceof PaymentRequiredError) topUp();   // out of credit
  else throw e;
}

rateLimit

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

await mem.search("...", "alice");
const rl = mem.rateLimit;   // { limit: 150, remaining: 3, reset: ... }

searchSelf

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

const { memories, self_memories } = await mem.searchSelf("what did I promise?", "alice");
// memories = what others said · self_memories = the agent's OWN words

listEngrams

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

const { engrams, forms } = await mem.listEngrams();  // ask, never hard-code

filters

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

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

idempotencyKey

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

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

withTimeout / withRetries / withDeadline

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

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

await mem.withTimeout(120_000).addBulk(bigBlob, "alice");  // this slow call only
await mem.withRetries(0).add("...", "alice");            // you retry, not the SDK
await mem.withDeadline(5_000).recall("...", "alice");          // 5s for the whole call
await mem.withSignal(ctrl.signal).recall("...", "alice");      // caller can cancel