세 개의 모델, 하나의 계보.

WOS 모델은 사람이 지식을 지녀 온 방식에서 이름을 땁니다 - Tablet, Scroll, Codex. 돌판, 두루마리, 제본된 책. 뒤로 갈수록 엔진이 에이전트를 위해 해내는 일이 늘어납니다.

Tablet 1의 전체 벤치마크 리포트는 벤치마크 페이지에 있습니다.

우리에게 $2, LLM에선 그 몇 배를 아낍니다.

WOS는 매 프롬프트에 전체 히스토리를 욱여넣는 대신, 쿼리당 ~1,200개의 관련 토큰만 LLM에 전달합니다. 그 격차는 막대하고, 히스토리가 커질수록 더 벌어집니다.

절감이 나오는 곳

• WOS 없이는 매 프롬프트에 전체 히스토리를 넣습니다 - 100K 토큰 × $2.50/1M = $0.25, 매 쿼리마다 (GPT-4o 입력 단가 기준, Opus급 모델은 약 2배).
• WOS는 한 번만 적재($2/1M)하고, 이후 각 쿼리는 작은 검색($3/1M × 1,200)과 ~1,200 토큰에 대한 LLM 호출뿐입니다.
• LLM이 읽는 토큰이 적을수록 비용이 줄고, WOS는 기억이 커져도 그 수치를 일정하게 유지합니다.

모든 언어, 같은 정확도.

검색은 순수 의미 기반입니다 - 임베딩만 쓰고 키워드나 BM25 매칭은 전혀 없습니다. 그래서 사용자가 日本語, 中文, Español, English 무엇으로 적어도 검색 품질이 동일합니다.

BM25 같은 어휘 매칭은 특정 언어의 형태 - 형태소, 띄어쓰기, 문자 체계 - 에 맞춰 동작합니다. 여러 언어를 섞어 쓰는 저장소에서는 그만큼 언어별로 검색 품질이 달라진다는 뜻입니다. WOS는 어휘 매칭을 아예 사용하지 않아, 모든 언어가 같은 경로를 지납니다.

한 저장소에 세 언어를 동시에

저장소마다 언어를 정할 필요가 없습니다 - 자유롭게 섞으세요. 아래는 한 사용자의 기억에 일본어·영어·스페인어가 동시에 들어있고, 어떤 언어로 묻든 맞는 기억을 찾아오는 모습입니다. 라이브 API에서 실제로 주고받은 내용입니다:

# one user, three languages stored together
mem.add("彼女はコーヒーより紅茶が好き", user_id="alice")                      # Japanese
mem.add("she works at a design studio in Brooklyn", user_id="alice")       # English
mem.add("A ella le encanta hacer senderismo los sábados", user_id="alice")  # Spanish

"¿Qué bebe ella?"               -> 彼女はコーヒーより紅茶が好き
"what does she do on weekends?" -> A ella le encanta hacer senderismo los sábados
"彼女の仕事は?"                  -> she works at a design studio in Brooklyn

번역 단계도, 언어 감지도, 언어별 설정도 없습니다. 기억과 질문은 언어가 아니라 의미로 배치됩니다 - 맥락과 의미만 같으면 언어가 달라도 찾아냅니다.

키워드를 일부러 금지한 이유

BM25 같은 어휘 점수는 특정 언어를 더 강화하는 성질이 있어, 한 저장소에 여러 언어를 담는 사용에서는 방해가 됩니다. 그래서 엔진에서 완전히 제거했고 코드 리뷰에서 규칙으로 강제합니다: 어휘 점수가 경로에 끼면 언어별로 검색 품질이 달라지기 때문입니다.

당신의 기억 위엔 모델이 돌지 않습니다.

저장은 말한 그대로 두고, 엔진은 임베딩으로 검색합니다 - 저렴하고 빠르고 결정론적입니다. 당신의 저장된 기억 위에선 어떤 모델도 돌지 않습니다. Tablet은 모델을 전혀 쓰지 않고, Scroll·Codex는 더 나은 결과를 위해 엔진 둘레에 모델을 더하지만, 그 모델은 당신의 질문만 볼 뿐 저장한 것은 보지 않습니다.

• 결정론적 엔진. 엔진은 같은 쿼리에 같은 기억을 반환합니다 - 그래서 벤치마크 편차가 리더 모델에서만 발생합니다.
• 대규모에서도 저렴. 저장·검색에 생성 비용이 없어, 기억이 커져도 비용이 모델 사용량이 아니라 저장량을 따라갑니다.

당신의 말, 그대로

쓰기 시점에 언어 모델로 텍스트에서 "사실"을 추출해 다시 쓰는 설계도 흔합니다. 그 설계는 세 가지를 맞바꿉니다: 매 쓰기마다의 생성 비용, 추가 지연, 그리고 원문 대신 모델의 의역이 저장된다는 점. WOS는 반대쪽을 선택했습니다 - 말한 그대로 저장하고, 해석은 읽기 시점에 당신의 LLM이 원문을 들고 하게 합니다.

측정되고 재현 가능한 90.7%.

LongMemEval-S에서 90.7%, 5회 독립 실행 평균(σ 0.5%, 체리피킹 없음), 벤치마크 표준 채점자인 GPT-4o로 채점.

같은 벤치마크라도 채점 프로토콜에 따라 수치가 크게 달라집니다 - 채점자, 프롬프트, 검색 레이어에 무엇을 허용하는지가 다르기 때문입니다. 우리는 벤치마크가 공표한 표준 제3자 GPT-4o 채점자를 그대로 쓰고, 시험에 맞춰 아무것도 바꾸지 않으며, 채점 코드와 리더 프롬프트를 공개해 누구나 90.7%를 그대로 재현할 수 있게 합니다.

측정 프로토콜 한눈에

정직하게 유지하는 것: 제3자 채점자, 변경 없이 공개한 리더 프롬프트, 순수 의미 기반 검색, 그리고 최고 회차가 아니라 전 회차 보고. 검색 엔진은 결정론적이라 다시 돌려도 같은 기억이 나옵니다.

더 어려운 벤치로 올라갑니다

우리는 아직 정복하지 못한 가장 어려운 표준 벤치마크 위에서 겨룹니다 - 적힌 점수는 모든 WOS 모델이 세운 최고 기록이고, 더 나은 모델이 나올 때마다 새로 쓰입니다. 94%를 넘기는 순간, 더 어려운 벤치마크로 졸업합니다.

모델당 토큰 단가 둘,
요청당 $0.0001.

100만 토큰 단가에 요청당 $0.0001을 더해, 쓴 만큼만. 구독도, 저장료도, 기억 개수 제한도 없습니다. 에이전트가 쓰고 읽을 때만 내고 - 기억하고 있는 것에는 내지 않습니다.

• 요청당 $0.0001. 모든 API 호출에 붙는 정액 요금으로, 토큰 사용량에 더해집니다.
• 저장은 무료입니다. 적재할 때 한 번 내면 보관은 공짜입니다. 개수 제한도, 보관 기간 제한도 없습니다.
• 보관만 합니다. 학습하지 않고, 사용하지 않고, 보지 않습니다. 에이전트의 기억은 당신의 것 - 저희는 회수할 수 있게 정리만 합니다.
• Tablet이 이렇게 싼 이유: 엔진이 모델을 돌리지 않아 원가가 임베딩과 디스크지 GPU가 아니기 때문입니다. Scroll·Codex는 모델을 더하며, 그 비용이 더 높은 가격에 담겨 있습니다.

사용량 티어별 한도 보기 →

세 번의 호출: 저장, 회수, 답변.

하나의 API. recall() 호출이 단기·장기 기억과 주변 컨텍스트를 한 번의 왕복으로 돌려줘, 프롬프트에 바로 넣을 수 있습니다.

from wontopos import Client
mem = Client(api_key="wos-...")
mem.add("she prefers tea over coffee", user_id="alice")
mem.add("I suggested the jasmine tea", user_id="alice", speaker="me")  # its own words
# one call: short + long + context
ctx = mem.recall("what does alice drink?", user_id="alice")

기억에는 화자가 있습니다. 기본은 사용자의 말이고, speaker "me"는 어시스턴트 자신이 한 말을, "밥" 같은 이름은 사용자 주변 누가 한 말인지를 기억합니다. 그래서 사람 단위로 회수할 수 있습니다.

5분 안에 첫 recall.

키 하나, 설치 한 줄, 호출 세 번이면 에이전트에 기억이 생깁니다. 이 페이지의 모든 코드는 실제로 실행해 검증했고, 응답도 실물 그대로입니다.

pip install wontopos        # Python
npm install wontopos        # TypeScript / JavaScript
cargo add wontopos          # Rust
# curl - nothing to install, just set WOS_API_KEY

from wontopos import Client

mem = Client(api_key="wos-live-...", user_id="alice")  # set the store once
mem.create_store()              # create it (stores are explicit)
mem.add("she prefers tea over coffee")  # no user_id needed

# one call → short-term + long-term + context
ctx = mem.recall("what does alice drink?")

import { Client } from "wontopos";

const mem = new Client({ apiKey: "wos-live-...", userId: "alice" });  // set the store once
await mem.createStore();            // create it (stores are explicit)
await mem.add("she prefers tea over coffee");  // no userId needed

// one call → short-term + long-term + context
const ctx = await mem.recall("what does alice drink?");

use wontopos::Client;

let mem = Client::new("wos-live-...").with_user("alice");  // set the store once
mem.create_store(None).await?;            // create it (stores are explicit)
mem.add("she prefers tea over coffee", None, json!({})).await?;

// one call → short-term + long-term + context
let ctx = mem.recall("what does alice drink?", None).await?;

# create the store once - stores are explicit
curl -X POST https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'

# store - embedded on the way in, no LLM call
curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'

# one call → short-term + long-term + context
curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does alice drink?"}'

{"user_id": "alice", "status": "created"}

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

recall()은 네 블록을 돌려줍니다 - short_term(최근 대화), long_term(관련 기억), context(가장 관련된 기억의 주변), 그리고 LLM에게 쓰는 법을 알려주는 instruction. 이 덩어리를 그대로 프롬프트에 넣으면 됩니다.

언어별 메서드 전부 보기 →

저장소 - 만들고, 보고, 지우기.

저장소는 저장·회수의 단위인 user_id - 최종 사용자·에이전트·주제마다 격리된 기억 공간 하나입니다. 저장소는 명시적이라 저장·회수 전에 먼저 만들어야 하고, 아니면 404가 돌아옵니다. 모든 계정엔 default 저장소가 기본으로 있어 만들지 않고도 바로 시작할 수 있습니다.

mem.create_store("alice")        # create (idempotent)
mem.list_stores()              # [{"user_id","created_at"}, ...]
mem.delete_store("alice")        # delete the store + all its memories

await mem.createStore("alice");
await mem.listStores();          // [{ user_id, created_at }, ...]
await mem.deleteStore("alice");     // store + all its memories

mem.create_store("alice").await?;
let stores = mem.list_stores().await?;
mem.delete_store("alice").await?;

# create
curl -X POST https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" -d '{"user_id":"alice"}'
# list
curl https://api.wontopos.com/api/v1/memory/collections -H "X-API-Key: $WOS_API_KEY"
# delete (store + all its memories)
curl -X DELETE https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" -d '{"user_id":"alice"}'

{ "user_id": "alice", "status": "created" }   // "exists" if it already did

{ "collections": [
  { "user_id": "default", "created_at": "2026-06-26T02:23:14Z" },
  { "user_id": "alice",   "created_at": "2026-06-26T02:24:01Z" }
], "count": 2 }

{ "error": { "type": "not_found_error",
  "message": "Store 'ghost' does not exist. Create it first with
              POST /api/v1/memory/collection {\"user_id\":\"ghost\"}, then store or recall." } }

반복되는 리콜은 10분의 1 가격으로.

요청당 옵트인하면 WOS가 검색 결과를 쿼리 텍스트 기준으로 캐시합니다. 규칙은 LLM 프롬프트 캐싱과 동일한 프리픽스 방식입니다. 캐시가 살아 있는 동안 반복되거나 이어지는 쿼리는 이전 결과를 재사용하고, 캐시된 부분은 정상 토큰 단가의 10%로 청구됩니다.

대화 하나, 세 턴

에이전트가 기억과 계속 대화할 때 실제로 벌어지는 일입니다. 매 턴, 지금까지의 대화를 쿼리로 보내고 cache_control을 켭니다.

요율

얼마나 아끼나

구체적인 예시입니다. 에이전트가 3,000토큰짜리 대화를 쿼리로 보내고 5분 안에 10번 반복하거나 이어갑니다. 캐싱이 없으면 정가로 30,000 입력 토큰입니다. 5분 캐시를 켜면 첫 쓰기 6,000(2배) + 아홉 번의 캐시 읽기 약 2,700 = 청구 토큰 8,700, 71% 절약입니다. 대화가 길어질수록 절약도 커집니다.

프리픽스 규칙

매칭은 쿼리의 앞부분 기준입니다. 앞이 그대로이고 뒤에 새 텍스트만 붙으면 캐시된 부분을 재사용하고 새 부분만 검색합니다. 캐시된 텍스트 끝보다 앞에서 무언가 바뀌면 아무것도 재사용할 수 없습니다.

cached    [ A B C D E F G ]

○   [ A B C D E F G ] E
✗   [ B C D E F G ] E

○ 히트 - 앞이 그대로이고 E만 새로 들어왔습니다
✗ 미스 - 앞이 바뀌어서 전체 쿼리를 다시 검색하고 다시 캐시합니다

기억해야 할 규칙 세 가지

• 연장하면 새 꼬리까지 다시 캐시합니다. [A B C D E F G] + E 다음에는 캐시가 E에서 끝납니다. 꼬리는 쓰기 요금으로 한 번 계산되고, 다음 턴은 A부터 E까지 전체를 프리픽스로 다시 매칭할 수 있습니다.
• 요청당 연속된 프리픽스 하나입니다. 하나의 쿼리를 두 개의 캐시 조각으로 나눌 수 없고, 오직 앞부분만 매칭됩니다.
• 쓰기는 즉시 무효화합니다. store, store-turn, bulk-store, forget, supersede, 저장소 삭제가 일어나면 그 저장소의 캐시는 버려집니다. 캐시된 답이 낡은 기억을 돌려주는 일은 없습니다.

켜는 법

hits = mem.search(
    "...the conversation so far...", user_id="alice",
    cache_control={"ttl": "5m"},   # or "1h"
)

const hits = await mem.search(
  "...the conversation so far...", "alice", 10,
  { cache_control: { ttl: "5m" } },   // or "1h"
);

let hits = mem.search_with(
    "...the conversation so far...", "alice", 10,
    serde_json::json!({"cache_control": {"ttl": "5m"}}),   // or "1h"
).await?;

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice",
       "query":"...the conversation so far...",
       "cache_control":{"ttl":"5m"}}'   # or "1h"

{ "memories": [ ... ],
  "cache": { "status": "hit",              // "write" | "hit" | "extend"
             "ttl": "5m",
             "cache_read_input_tokens": 412,
             "cache_creation_input_tokens": 0 } }

이 기능에 SDK가 꼭 필요한 것은 아닙니다. 캐싱은 HTTP 호출 하나에 붙는 필드 하나라서 어떤 프로그래밍 언어에서든 동작합니다. curl 탭이 만능 레시피이고, Python·TypeScript·Rust SDK는 똑같은 호출을 감싼 편의 도구일 뿐입니다.

누가 한 말인지 아는 기억.

사람의 기억은 사람 단위로 움직입니다. 밥이 뭘 약속했는지, 내가 뭘 하기로 했는지. 기억마다 화자를 달아주면 에이전트도 똑같이 기억합니다. 모든 태블릿·스크롤 모델에서 동일하게 동작합니다.

한 팀, 기억 세 조각

저장소 하나가 여러 사람의 목소리를 섞이지 않게 지킵니다. 사람을 한 번 등록하고, 말이 나올 때마다 화자를 달아 저장한 뒤, 사람 단위로 물어보세요.

규칙은 세 개예요

• "me"는 어시스턴트 자신입니다. 등록도 카운트도 없습니다. 예약어이고 소문자만 유효합니다. speaker: "Me"나 "ME"는 조용히 변환되지 않고 400 invalid_request_error를 반환합니다.
• 한도는 등록에서 셉니다. 저장소당 시작 50명. 초과 등록은 400 invalid_request_error를 반환하고 에러 본문에 speaker_limit: 50이 들어 있습니다. 미등록 이름으로 store하면 역시 400이고 아무것도 저장되지 않습니다. 미등록 이름으로 검색을 필터하면 404 not_found_error입니다. 메시지 문자열이 아니라 상태 코드와 필드로 분기하세요. 한도는 올릴 계획입니다.
• 라벨은 모든 읽기에 붙습니다. 검색 결과, recall의 장기 맥락, 엔그램 결과 모두 화자를 달고 나옵니다. 모델이 지금 들고 있는 말이 누구 것인지 항상 알 수 있습니다. 검색에 speaker를 주면 그 사람의 말만 돌아오고, supersede하면 화자가 따라가며, forget하면 함께 지워집니다.
• 이름은 유니코드라 어떤 언어든 됩니다. さくら, Иван, 하늘 전부 유효한 화자이고, 귀속 동작은 모든 언어에서 동일합니다. 매칭은 트림과 유니코드 정규화 후 정확 일치라 Bob과 bob은 서로 다른 사람입니다. 이름은 80자까지입니다.

# POST /speakers past the limit
{ "type": "error",
  "error": { "type": "invalid_request_error",
             "message": "This store already has 50 registered speakers, ...",
             "speaker_limit": 50 } }

# store with an unregistered name → 400, nothing stored
{ "type": "error",
  "error": { "type": "invalid_request_error",
             "message": "speaker 'Bob' is not registered in this store. Register it first: ...",
             "speaker": "Bob" } }

# search filtered by an unregistered name → 404
{ "type": "error",
  "error": { "type": "not_found_error",
             "message": "speaker 'Bob' is not registered in this store.",
             "speaker": "Bob" } }

범위 노트 둘. speaker는 add/store에 붙습니다. add_turn은 대화 한 턴을 통째로 기억하고, 사람별 라벨과 필터는 speaker를 명시해 저장한 기억에서 나옵니다. 그리고 세션 패시지(expand)는 여러 기억의 합성이라 라벨이 붙지 않습니다. speaker 필터는 항상 원자 단위의 라벨된 기억을 반환합니다. 그리고 완전히 동일한 내용은 첫 기억으로 dedup됩니다. 그런 store는 status "duplicate"와 명시적 note를 반환하고, 화자는 붙지 않습니다.

저희는 이 기능을 어렵게 테스트합니다. 본문에 이름이 하나도 없는 기억들을 저장하고 사람 단위로 회수합니다. 귀속이 단어 매칭이 아니라 화자 기록에서 나오기 때문에, 어떤 언어에서든 똑같이 동작합니다.

사용법

mem.add_speaker("Bob", user_id="alice")  # once per person; "me" needs no registration
mem.add("Bob said the deadline moved to Tuesday", user_id="alice", speaker="Bob")
mem.add("I promised the summary by Friday", user_id="alice", speaker="me")
hits = mem.search("what did Bob say about the deadline?", user_id="alice", speaker="Bob")
mem.list_speakers(user_id="alice")
mem.remove_speaker("Bob", user_id="alice")  # memories stay, the tag goes

await mem.addSpeaker("Bob", "alice");  # once per person; "me" needs no registration
await mem.add("Bob said the deadline moved to Tuesday", "alice", { speaker: "Bob" });
await mem.add("I promised the summary by Friday", "alice", { speaker: "me" });
const hits = await mem.search("what did Bob say about the deadline?", "alice", 10, { speaker: "Bob" });
await mem.listSpeakers("alice");
await mem.removeSpeaker("Bob", "alice");  // memories stay, the tag goes

mem.add_speaker("Bob", "alice").await?;  # once per person; "me" needs no registration
mem.add("Bob said the deadline moved to Tuesday", "alice", json!({"speaker": "Bob"})).await?;
mem.add("I promised the summary by Friday", "alice", json!({"speaker": "me"})).await?;
let hits = mem.search_with("what did Bob say about the deadline?", "alice", 10, json!({"speaker": "Bob"})).await?;
mem.list_speakers("alice").await?;
mem.remove_speaker("Bob", "alice").await?;  // memories stay, the tag goes

curl -X POST https://api.wontopos.com/api/v1/memory/speakers \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","speaker":"Bob"}'   # once per person

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"Bob said the deadline moved to Tuesday","metadata":{"speaker":"Bob"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did Bob say about the deadline?","speaker":"Bob"}'

curl "https://api.wontopos.com/api/v1/memory/speakers?user_id=alice" -H "X-API-Key: $WOS_API_KEY"

curl -X DELETE https://api.wontopos.com/api/v1/memory/speakers \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","speaker":"Bob"}'   # memories stay, the tag goes

{ "memories": [
    { "content": "Bob said the deadline moved to Tuesday",
      "speaker": "Bob", ... } ] }

{ "user_id": "alice",
  "speakers": [ { "speaker": "Bob", "memories": 2, "created_at": "2026-07-10T04:20:39Z" } ],
  "count": 1, "limit": 50 }

목록은 저장소가 아는 사람들을 사람별 기억 수·한도와 함께 보여줍니다. 해제는 등록만 지웁니다. 그 사람의 기억은 남고 이름표만 사라집니다.

MCP - AI 도구를 위한 기억

WOS의 본체는 API와 SDK입니다. MCP 서버는 그 위의 부가기능입니다. 같은 기억을, 당신이 만들지 않은 도구에 꽂습니다 - Claude Code, Claude Desktop, Cursor.

설치 한 줄이면 에이전트가 기억 도구 9개를 받아 스스로 씁니다. 기억은 계정에 있어 한 도구가 저장한 것을 다른 모든 도구가 회수합니다. SDK로 직접 만든 에이전트도 마찬가지입니다.

이걸로 뭐가 되나

• 프로젝트를 기억하는 Claude Code. 결정, 버그 픽스, 선호 - 다음 세션에서 다시 설명할 필요 없이 그대로 회수됩니다.
• ChatGPT에서 시작해 Claude에서 이어가기. 같은 저장소, 같은 기억 - 대화가 처음부터 다시가 아니라 도구를 건너 이어집니다.
• 내 개인 에이전트도 같은 기억 안에. Claude Code가 배운 걸 SDK 에이전트가 회수하고, 에이전트가 저장한 걸 Claude Code가 되받아 회수합니다.

Claude Code, Claude Desktop, Cursor, Windsurf 등 모든 MCP 호스트에서 동작합니다. ChatGPT는 Actions + OpenAPI 스펙으로 같은 기억에 닿습니다.

설치

claude mcp add wontopos --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp

에이전트는 아홉 개의 툴을 받습니다 - recall · remember · search · update · forget · list_memories · engram · stats · create_store - 각 툴 설명이 언제 쓸지까지 알려줘서 스스로 판단해 씁니다.

개발자 문서 열기 →

OpenAPI 스펙

API의 완전한 기계 판독용 지도 - 모든 엔드포인트, 요청, 응답, 에러.

OpenAPI는 HTTP API를 기계가 읽는 파일로 기술하는 업계 표준 형식입니다.

https://api.wontopos.com/openapi.json

이걸로 뭐가 되나

Postman: File → Import → URL 붙여넣기 - 16개 엔드포인트가 클릭 가능한 콜렉션으로 뜹니다. ChatGPT: GPT를 만들고 Action에 같은 URL을 붙여넣으세요. 코드 생성: openapi-generator -i .../openapi.json -g go로 우리가 안 만든 언어의 클라이언트도 뽑아냅니다.

Postman에 임포트하고, 우리가 안 만든 언어의 클라이언트를 생성하고, ChatGPT Actions를 연결하고, CI에서 계약 검증을 돌리세요. 테스트가 실제 라우트에 고정해 두니 어긋날 수 없습니다.

llms.txt

AI가 읽을 수 있는 텍스트 한 장에 담긴 API 전체.

llms.txt는 웹 관습입니다: 사이트 루트에 두는 순수 텍스트 한 장으로, AI에게 제품에 대해 필요한 전부를 알려줍니다.

https://wontopos.com/llms.txt

IDE나 코딩 에이전트에 넣으면 WOS 위에 어떻게 빌드하는지 바로 압니다 - 인증, 엔드포인트, 패턴, 에러까지. 릴리스마다 갱신됩니다.

OpenAPI 스펙과 같은 사실, 다른 청중입니다: 스펙은 도구를 위한 정밀한 구조이고, 이 파일은 AI나 사람이 한 번에 읽는 문서입니다. 둘 다 릴리스마다 함께 갱신됩니다.

모든 AI 도구 안의 내 기억

명령 한 줄이면 Claude Code, Claude Desktop, Cursor 등 모든 MCP 호스트가 WOS 계정 기반 장기기억을 갖습니다. 통합 코드는 필요 없습니다. 에이전트가 기억 도구 9개를 받아 스스로 판단해 씁니다.

설치

Claude Code는 한 줄입니다 (키는 콘솔에서 먼저 발급):

claude mcp add wontopos --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp
# pick which store it remembers into (optional): add --env WONTOPOS_USER_ID=my-project

# ~/.cursor/mcp.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

# .vscode/mcp.json
{ "servers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

# ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

# Claude Desktop and any other MCP host
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Add to Cursor →  ·  Add to VS Code →

선택 env: WONTOPOS_USER_ID는 기본 저장소, WONTOPOS_MODEL은 엔진, WONTOPOS_BASE_URL은 셀프호스팅 배포를 지정합니다. WONTOPOS_READ_ONLY=1은 읽기 전용으로 전환합니다(회수·검색·조회만).

저장소를 공유하기 전에 알아둘 것

• 전용 키를 쓰세요. 키는 워크스페이스를 품고 있어서, MCP 전용으로 만든 키는 연결된 도구들이 닿을 수 있는 범위 자체를 좁힙니다 - 앱 키는 건드리지 않고 콘솔에서 언제든 회전할 수 있습니다.
• 읽기 전용 모드. WONTOPOS_READ_ONLY=1이면 쓰기 툴이 아예 등록되지 않습니다: 에이전트는 회수·검색·기억 목록·engram 실행·통계 조회만 할 수 있고 저장·갱신·삭제는 불가능합니다. 기억을 소유하는 게 아니라 참고만 해야 하는 에이전트에 맞습니다.
• 툴 실행 확인은 켜두세요. MCP 호스트는 기본적으로 툴 실행 전에 물어봅니다 - 특히 forget은 켜두세요. 삭제는 그 저장소의 모든 도구에 공유되기 때문입니다.
• 저장된 것은 키를 가진 모든 도구가 회수할 수 있습니다. 비밀 - API 키, 비밀번호 - 은 절대 기억으로 저장하지 마세요.
• 회수된 기억은 데이터지 지시가 아닙니다. 툴 설명이 에이전트에게 이걸 명시적으로 말해줍니다. 그래도 자율 에이전트가 따르는 저장소에는 신뢰할 수 없는 제3자 텍스트를 기억으로 저장하지 마세요.
• 삭제도 공유됩니다. 한 도구에서의 forget·delete_all은 모든 도구에서 사라지는 것입니다.
• "me"는 그 저장소에 쓰는 에이전트 자신을 뜻합니다. 여러 에이전트가 한 저장소를 공유하면 "me"의 목소리가 섞입니다. 정체성을 구분하려면 에이전트마다 저장소를 따로 지정하세요(WONTOPOS_USER_ID).
• 과금은 계정 하나로 모입니다. 연결된 모든 도구가 같은 잔액과 속도 한도에서 차감됩니다.

그다음은 대화만 하면 됩니다

이렇게 말해보세요

• "이 레포는 pnpm 써, 기억해둬" → remember가 저장하고, 다음 세션은 이미 알고 있습니다.
• "지난주에 정한 에러 응답 형식이 뭐였지?" → recall이 그 결정을 컨텍스트로 다시 불러옵니다.
• "사실 마감이 금요일로 바뀌었어" → 에이전트가 회수한 기억과 어긋난 걸 알아채고 update로 그 기억을 제자리에서 고칩니다.
• "그거 잘못 기억한 거야, 지워" → 에이전트가 기억 id를 찾아 forget을 호출합니다. 실행 전에 호스트가 확인을 요청합니다.
• "나에 대해 뭘 기억해?" → list_memories가 저장된 걸 전부 훑어서, 에이전트가 답하거나 정리할 수 있습니다.

특별한 명령어 문법은 없습니다 - 위 예시는 전부 평범한 문장입니다. 에이전트가 각 툴 설명을 읽고 스스로 고릅니다.

아홉 개의 툴

• recall - 한 번의 호출로 컨텍스트: 최근 턴 + 관련 장기기억. 과거 맥락이 필요할 때 가장 먼저 호출하도록 툴 설명에 명시해 두었습니다.
• remember - 지속될 사실·결정을 저장. speaker: "me"는 에이전트 자신의 말, 등록된 이름은 그 사람의 말로 남습니다.
• search - 시맨틱 검색. 선택적으로 speaker로 사람별 필터.
• forget - id로 기억 하나를 삭제.
• speakers - 저장소가 기억하는 사람들을 등록·조회·해제.
• create_store - 저장소는 명시적입니다. 최종 사용자·프로젝트·에이전트마다 하나씩.

SDK랑 MCP, 뭐가 다르지?

• SDK는 당신이 짜는 앱 안에 들어갑니다. 언제 저장하고 무엇을 회수할지 당신의 코드가 정확히 결정합니다 - 결정론적이고, 타입이 있고, 버전 관리됩니다. 제품을 만든다면 SDK입니다.
• MCP는 당신이 만들지 않은 AI 도구에 꽂습니다. 기억을 언제 쓸지는 에이전트가 툴 설명을 보고 판단합니다 - 코드 0줄. Claude Code·Claude Desktop·Cursor에, 혹은 완성된 어시스턴트에 기억을 달 때 맞습니다.

밑은 같은 API, 같은 저장소입니다 - SDK로 만든 앱과 MCP로 붙인 Claude Code 세션이 하나의 기억을 공유합니다. 양자택일이 아니라 표면마다 골라 쓰는 것입니다.

모든 도구를 가로지르는 하나의 기억

기억은 도구가 아니라 계정에 속합니다. ChatGPT(Actions + OpenAPI 스펙)에서 쓴 저장소가 Claude Code에서, 당신의 에이전트에서 그대로 회수되고, 반대도 됩니다. 한 도구에서 시작한 대화가 다른 도구에서 이어집니다.

그리고 하나의 저장소이기 때문에, Claude Code에 붙여 쓰다가 그대로 개인 에이전트와 대화를 이어갈 수 있습니다. 같은 키·같은 저장소의 SDK 에이전트는 Claude Code가 방금 배운 걸 전부 회수하고, 에이전트가 저장한 건 다음 세션의 Claude Code가 회수합니다.

Claude Code

대표 경로입니다. 터미널 명령 한 줄이면 모든 세션이 기억과 함께 시작됩니다.

1. 콘솔에서 API 키를 만드세요. 키는 워크스페이스를 품고 있어서, 키 하나 = 기억 공간 하나입니다.
2. 서버를 등록하세요. --scope user면 모든 프로젝트에서 쓸 수 있고, 없으면 현재 프로젝트에서만 보입니다.
3. 확인: Claude Code 안에서 /mcp를 실행하면 wontopos가 툴 9개와 함께 떠야 합니다.
4. 자동화 팁: CLAUDE.md에 "과거 맥락이 필요하면 wontopos recall을 먼저 호출" 한 줄을 넣으면, 시키지 않아도 매 세션이 기억과 함께 시작합니다.

claude mcp add wontopos --scope user \
  --env WONTOPOS_API_KEY=wos-live-... -- npx -y wontopos-mcp
# pick a store (optional): add --env WONTOPOS_USER_ID=my-project

Claude Desktop

아래 블록을 claude_desktop_config.json에 넣고(설정 → 개발자 → Edit Config) 앱을 재시작하면 툴 9개가 나타납니다. 참고: 웹·모바일 claude.ai는 원격 MCP 서버가 필요한데 WOS는 아직 제공하지 않습니다 - 데스크톱 앱이 지원 경로입니다.

# claude_desktop_config.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Cursor

아래 블록을 ~/.cursor/mcp.json에 넣거나 원클릭 버튼을 누르고 Cursor를 재시작하세요. 에이전트가 툴 9개를 집어 듭니다.

# ~/.cursor/mcp.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Add to Cursor →

VS Code

VS Code(Copilot 에이전트 모드)는 프로젝트의 .vscode/mcp.json에서 MCP 서버를 읽습니다. 아래 블록을 넣거나 원클릭 버튼을 누르세요.

# .vscode/mcp.json
{ "servers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

Add to VS Code →

Windsurf

Windsurf(Cascade)는 ~/.codeium/windsurf/mcp_config.json을 읽습니다. 아래 블록을 넣고 리로드하면 같은 툴 9개가 나타납니다.

# ~/.codeium/windsurf/mcp_config.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

ChatGPT

ChatGPT의 MCP 커넥터는 원격 서버만 받아서, 지금의 지원 경로는 커스텀 GPT의 Action입니다: GPT를 만들고 Action을 추가한 뒤 아래 OpenAPI 스펙 URL을 붙여넣고 API 키를 인증 헤더로 설정하세요. 그러면 그 GPT가 다른 도구들과 같은 기억을 호출합니다.

# GPT → Configure → Actions → Import from URL
https://api.wontopos.com/openapi.json
# Authentication: API Key · Header name: X-API-Key

같은 저장소, 같은 기억입니다. ChatGPT가 Action으로 저장한 걸 Claude Code가 MCP로 회수하고, 반대도 됩니다.

Gemini CLI

Gemini CLI는 ~/.gemini/settings.json에서 MCP 서버를 읽습니다. 아래 블록을 넣고 CLI를 재시작하면 같은 툴 9개가 거기서도 나타납니다.

# ~/.gemini/settings.json
{ "mcpServers": {
    "wontopos": {
      "command": "npx",
      "args": ["-y", "wontopos-mcp"],
      "env": { "WONTOPOS_API_KEY": "wos-live-...",
               "WONTOPOS_USER_ID": "my-project" }
    } } }

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

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

pip install wontopos

from wontopos import Client

mem = Client(api_key="wos-live-...")  # or read from an env var

모델 선택

mem = Client(api_key="wos-live-...", model="tablet-1")  # default engine
mem.recall("...", user_id="alice")                  # tablet-1
mem.recall("...", user_id="alice", model="scroll-1")  # or pick a model per call

mem.list_models()

[{"id": "tablet-1", "name": "Tablet 1", "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"}]

mem.ping()   # True, or raises AuthenticationError / PaymentRequiredError

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

쓰기

mem.add("she prefers tea over coffee", user_id="alice")
mem.add("I promised the summary by Friday", user_id="alice", speaker="me")  # its own words - no registration needed

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

mem.add_turn("hi", "hello!", user_id="alice")

{"status": "ok"}

mem.add_speaker("Bob", user_id="alice")  # once per person; "me" needs no registration
mem.add("I promised to send the report on Friday", user_id="alice", speaker="me")
mem.add("Bob said the deadline moved to Tuesday", user_id="alice", speaker="Bob")
mem.search("what did Bob say about deadlines?", user_id="alice", speaker="Bob")

{"memories": [{"content": "Bob said the deadline moved to Tuesday", "speaker": "Bob", ...}]}

mem.add_bulk("Alice moved to Brooklyn in March. She works at a design studio downtown.", user_id="alice")

{"elapsed_secs": 0.154154944, "status": "ok", "stored": 1, "total_chunks": 1}

mem.update("576700aa-...", "she switched to coffee this year", user_id="alice")

{"new_memory_id": "07e94433-b7cc-4e49-8d8f-f37fc1a392b7",
 "old_memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "superseded"}

읽기

r = mem.search("what does she drink?", user_id="alice", limit=1)

{"memories": [{
   "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"
 }], "search_ms": 315, "total_found": 1}

ctx = mem.recall("what does she drink?", user_id="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."}

turns = mem.history("alice")

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

mem.stats("alice")

{"short_term_turns": 2, "total_memories": 4, "user_id": "alice"}

m = mem.get("alice", memory_id="576700aa-...")

{"id": "576700aa-...", "content": "she prefers tea over coffee",
 "category": "general", "source_type": "user_said",
 "created_at": "2026-07-10T04:20:39Z", "event_date": null, "is_superseded": false}

page = mem.list_memories("alice", limit=100)

{"count": 2, "next_cursor": null, "memories": [
   {"id": "576700aa-...", "content": "she prefers tea over coffee",
    "category": "general", "source_type": "user_said",
    "created_at": "2026-07-10T04:20:39Z", "event_date": null, "is_superseded": false}
 ]}

for m in mem.iter_memories("alice"):   # every page, no cursor bookkeeping
    print(m["id"], m["content"])
everything = mem.export_memories("alice")   # the whole store as a list

삭제

mem.delete("alice", memory_id="576700aa-...")

{"memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "deleted"}

mem.delete_all("alice")

{"memories_deleted": 4, "status": "deleted", "user_id": "alice"}

오류와 신뢰성

from wontopos import PaymentRequiredError, NotFoundError
try:
    mem.add("...", user_id="alice")
except NotFoundError:
    mem.create_store("alice")   # store didn't exist yet
except PaymentRequiredError:
    top_up()                       # out of credit - don't retry

mem.search("...", user_id="alice")
rl = mem.rate_limit   # {"limit": 150, "remaining": 3, "reset": ...}

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

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

npm install wontopos

import { Client } from "wontopos";

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

모델 선택

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

await mem.listModels();

[{"id": "tablet-1", "name": "Tablet 1", "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"}]

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

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

쓰기

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)"}

await mem.addTurn("hi", "hello!", "alice");

{"status": "ok"}

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" });

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}

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"}

읽기

const r = await mem.search("what does she drink?", "alice", 1);

{"memories": [{
   "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"
 }], "search_ms": 315, "total_found": 1}

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."}

const turns = await mem.history("alice");

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

await mem.stats("alice");

{"short_term_turns": 2, "total_memories": 4, "user_id": "alice"}

const m = await mem.get("alice", "576700aa-...");

{"id": "576700aa-...", "content": "she prefers tea over coffee",
 "category": "general", "source_type": "user_said",
 "created_at": "2026-07-10T04:20:39Z", "event_date": null, "is_superseded": false}

const page = await mem.listMemories("alice", { limit: 100 });

{"count": 2, "next_cursor": null, "memories": [
   {"id": "576700aa-...", "content": "she prefers tea over coffee",
    "category": "general", "source_type": "user_said",
    "created_at": "2026-07-10T04:20:39Z", "event_date": null, "is_superseded": false}
 ]}

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

삭제

await mem.delete("alice", "576700aa-...");

{"memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "deleted"}

await mem.deleteAll("alice");

{"memories_deleted": 4, "status": "deleted", "user_id": "alice"}

오류와 신뢰성

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;
}

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

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

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

cargo add wontopos

use wontopos::Client;

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

모델 선택

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

mem.list_models().await?;

[{"id": "tablet-1", "name": "Tablet 1", "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"}]

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

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

쓰기

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)"}

mem.add_turn("hi", "hello!", "alice").await?;

{"status": "ok"}

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?;

mem.add_bulk("Alice moved to Brooklyn in March...", "alice", "general").await?;

{"elapsed_secs": 0.154154944, "status": "ok", "stored": 1, "total_chunks": 1}

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"}

읽기

let r = mem.search("what does she drink?", "alice", 1).await?;

{"memories": [{
   "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"
 }], "search_ms": 315, "total_found": 1}

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."}

let turns = mem.history("alice").await?;

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

mem.stats("alice").await?;

{"short_term_turns": 2, "total_memories": 4, "user_id": "alice"}

let m = mem.get("alice", "576700aa-...").await?;

{"id": "576700aa-...", "content": "she prefers tea over coffee",
 "category": "general", "source_type": "user_said",
 "created_at": "2026-07-10T04:20:39Z", "event_date": null, "is_superseded": false}

mem.list_memories("alice", 100, None).await?;

{"count": 2, "next_cursor": null, "memories": [
   {"id": "576700aa-...", "content": "she prefers tea over coffee",
    "category": "general", "source_type": "user_said",
    "created_at": "2026-07-10T04:20:39Z", "event_date": null, "is_superseded": false}
 ]}

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

삭제

mem.delete("alice", "576700aa-...").await?;

{"memory_id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "deleted"}

mem.delete_all("alice").await?;

{"memories_deleted": 4, "status": "deleted", "user_id": "alice"}

오류와 신뢰성

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),
}

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

curl - 설치 없이, 같은 메서드.

설치할 SDK가 없습니다 - 어떤 HTTP 클라이언트든 됩니다. 키만 한 번 설정하면 SDK가 감싸는 그 엔드포인트를 그대로 호출합니다. Base URL https://api.wontopos.com, 인증은 X-API-Key, 입출력은 JSON.

# set your key once (never hard-code it)
export WOS_API_KEY="wos-live-..."

쓰기

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

curl -X POST https://api.wontopos.com/api/v1/memory/store-turn \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","user_msg":"hi","assistant_msg":"hello!"}'

{"status": "ok"}

curl -X POST https://api.wontopos.com/api/v1/memory/speakers \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","speaker":"Bob"}'   # once per person

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"I promised to send the report on Friday","metadata":{"speaker":"me"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"Bob said the deadline moved to Tuesday","metadata":{"speaker":"Bob"}}'

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what did Bob say about deadlines?","speaker":"Bob"}'

curl -X POST https://api.wontopos.com/api/v1/memory/supersede \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","old_memory_id":"576700aa-...","new_content":"she switched to coffee this year"}'

{"new_memory_id": "07e94433-...", "old_memory_id": "576700aa-...", "status": "superseded"}

읽기

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does she drink?","max_results":1}'

{"memories": [{"id": "576700aa-...", "content": "she prefers tea over coffee",
   "similarity": 0.63, "is_superseded": false}], "search_ms": 315, "total_found": 1}

curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does she drink?"}'

{"short_term": {"count": 2, "turns": [...]},
 "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"]},
 "instruction": "Use short_term for recent context, long_term for relevant past memories..."}

삭제

curl -X POST https://api.wontopos.com/api/v1/memory/forget \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'  # omit memory_id = delete all

{"memories_deleted": 1, "status": "deleted", "user_id": "alice"}

엔드포인트 + 바디 필드 전부 보기 →

Engrams

모델이 호출하는 회수 도구 - 같은 기억 위에서 서로 다른 검색 전략을 씁니다. 하나만 쓰거나 여러 개를 동시에 호출하세요.

엔그램은 계속 추가됩니다 - 목록은 늘어납니다.

회고록 & 아카이브 Scroll 1.2+

이건 호출하는 도구가 아니라 전달 형식입니다. Scroll 1.2 이상에서 호출마다 form: "memoir" 또는 form: "archive"를 고르면, 그냥 검색을 포함한 그 회수에 시간이 그 방식으로 적혀 돌아옵니다.

Time_awareness Scroll 1.2+

호출마다 고르는 전달 형식. 형식을 지원하는 모델(Scroll 1.2 이상)에서 아무 호출에나 form(memoir 또는 archive)을 넘기면 - 그냥 검색이든 recall이든 엔그램이든 - 그 응답이 그 방식으로 렌더링되어 돌아옵니다. SDK에서는 tz처럼 form 필드로, HTTP에서는 X-WOS-Form 헤더로 넘깁니다. 회고록은 사람이 기억하듯, 아카이브는 정확한 기록 그대로 - 차이는 시간을 적는 방식에서 가장 잘 드러납니다.

# plain search - no engram - the memoir form on Scroll 1.2
r = mem.search("what does Alice drink?", user_id="alice", model="scroll-1.2", form="memoir", tz=9)
# every hit gets a .time field → "a couple weeks ago"  (form="archive" → "2 weeks ago (Jun 09)")

// plain search - no engram - the memoir form on Scroll 1.2
const r = await mem.withModel("scroll-1.2").search("what does Alice drink?", "alice", 10, { form: "memoir", tz: 9 });

// search_with merges extra fields into the body - form picks the render, tz the local clock
let r = mem.with_model("scroll-1.2").search_with("what does Alice drink?", "alice", 10, json!({"form": "memoir", "tz": 9})).await?;

curl -X POST https://api.wontopos.com/api/v1/memory/search \
  -H "X-API-Key: wos-live-..." -H "X-WOS-Model: scroll-1.2" -H "X-WOS-Form: memoir" -H "X-WOS-Timezone: 9" \
  -d '{"user_id":"alice","query":"what does Alice drink?"}'
# each memory comes back with a "time" field; use X-WOS-Form: archive for exact time

tz는 호출자의 UTC 오프셋(시간) - 라 "this morning" 같은 표현과 새벽 4시 경계가 그 사람 현지 시간으로 찍힙니다. 안 주면 UTC, HTTP에선 X-WOS-Timezone 헤더. 지역별 대략값: 미국 동부 -5, 중부 -6, 서부 -8 · 영국 / 리스본 0 · 중부 유럽 +1 · 동유럽 +2 · 인도 +5.5 · 중국 / 싱가포르 +8 · 한국 / 일본 +9 · 시드니 +10. (표준시 기준 - 서머타임이면 일부 지역은 +1, 사용자가 실제로 쓰는 값을 그대로 넣으세요.)

같은 검색, 두 형식 - 기억은 똑같고 time만 달라집니다:

{ "count": 3, "memories": [
  { "content": "Alice prefers tea over coffee", "time": "a couple weeks ago" },
  { "content": "met Alice at the cafe downtown",  "time": "yesterday afternoon" },
  { "content": "Alice moved to Brooklyn",          "time": "about half a year ago" }
] }

{ "count": 3, "memories": [
  { "content": "Alice prefers tea over coffee", "time": "2 weeks ago (Jun 09)" },
  { "content": "met Alice at the cafe downtown",  "time": "yesterday at 14:00" },
  { "content": "Alice moved to Brooklyn",          "time": "6 months ago (Dec 2025)" }
] }

위 값은 전부 렌더러의 실제 출력입니다. "어제" 두 줄을 보세요: 회고록은 낮과 밤을 가르지만 - 하루는 잠 한 번 - 아카이브는 시계 시각 하나로 적고 낮·밤을 나누지 않습니다.

모드별 시간 읽는 법

회고록 - 사람이 실제로 말하는 방식. 최근은 비교적 또렷하다가(약 15분 전, 30분 전) 멀어질수록 표현이 넓어집니다 - 2주쯤 전, 반년쯤 전, 몇 년 전 - 기억 자체가 멀수록 풀어지듯. 하루 안에서는 시계 대신 landmark를 씁니다: 오늘 아침, 어젯밤, 어제 오후. 그리고 하루는 달력 한 칸이 아니라 잠 한 번: 경계가 현지 새벽 4시쯤이라, 늦은 밤도 여전히 '오늘 밤'으로 읽히지 벌써 내일이 되지 않습니다.

아카이브 - 정밀, 항상 앵커와 함께. 모든 줄에 정확한 경과 시간 + 모델이 계산할 수 있는 절대 기준이 붙고, 가까울수록 앵커가 촘촘해집니다: 오늘은 시계(8시간 전, 07:10), 이번 주는 요일+시계(2일 전 (화 15:10)), 이번 달은 날짜(지난주 (6월 16일)), 그 너머는 월·연도(6개월 전 (2025년 12월)). 모호함 없이, 틀림 없이.

deep_recall

멀티홉 회수. 쿼리로 검색한 뒤 최상위 매치의 내용으로 한 번 더 검색해 단일 검색이 놓칠 연결 맥락을 끌어옵니다. 기억이 서로를 참조할 때(사람 → 프로젝트 → 세부) 가장 좋습니다. 최대 ~12개.

out = mem.engram("deep_recall", "what should I know about Alice?", user_id="alice")

const out = await mem.engram("deep_recall", "what should I know about Alice?", "alice");

let out = mem.engram("deep_recall", "what should I know about Alice?", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"deep_recall","user_id":"alice","query":"what should I know about Alice?"}'

{ "engram": "deep_recall", "hops": 2, "count": 12,
  "memories": [ ... ],
  "usage": { "input_tokens": 5, "output_tokens": 61 } }

timeline

시간순 회수. 관련도가 아니라 사건 발생 시점 기준 최신순으로 정렬해 반환합니다. "언제 X했지", 이력, 순서 질문에. 최대 15개.

events = mem.engram("timeline", "project milestones", user_id="alice")

const events = await mem.engram("timeline", "project milestones", "alice");

let events = mem.engram("timeline", "project milestones", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"timeline","user_id":"alice","query":"project milestones"}'

{ "engram": "timeline", "hops": 1, "count": 15,
  "memories": [ ... ],
  "usage": { "input_tokens": 4, "output_tokens": 88 } }

gather

넓은 수집. 검색 후 상위 세 매치 주변을 확장해 deep_recall보다 더 넓게 훑습니다. 한 사람·프로젝트·주제 관련된 걸 한 번에 다 모을 때. 최대 ~18개.

related = mem.engram("gather", "everything about Project Atlas", user_id="alice")

const related = await mem.engram("gather", "everything about Project Atlas", "alice");

let related = mem.engram("gather", "everything about Project Atlas", "alice").await?;

curl -X POST https://api.wontopos.com/api/v1/engram/run \
  -H "X-API-Key: wos-live-..." -H "Content-Type: application/json" \
  -d '{"name":"gather","user_id":"alice","query":"everything about Project Atlas"}'

{ "engram": "gather", "hops": 4, "count": 18,
  "memories": [ ... ],
  "usage": { "input_tokens": 6, "output_tokens": 142 } }

모든 엔드포인트, 하나의 Base URL.

SDK 없이도 됩니다 - 어떤 HTTP 클라이언트든 가능. Base URL https://api.wontopos.com, 인증은 X-API-Key 헤더, 입출력은 JSON. 기억 작업은 POST, 저장소 관리는 /collection에 POST / GET / DELETE. 저장소가 먼저 있어야 하고(Stores 참고), 없으면 404.

# create the store once (stores are explicit)
curl -X POST https://api.wontopos.com/api/v1/memory/collection \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice"}'

# store a memory
curl -X POST https://api.wontopos.com/api/v1/memory/store \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","content":"she prefers tea over coffee"}'

# recall - one call, ready for your prompt
curl -X POST https://api.wontopos.com/api/v1/memory/recall \
  -H "X-API-Key: $WOS_API_KEY" -H "Content-Type: application/json" \
  -d '{"user_id":"alice","query":"what does alice drink?"}'

{"id": "576700aa-f0e0-4c26-99a0-10e2d5b0d624", "status": "stored (1 chunks)"}

기능은 모두에게 동일.
티어는 한도만 올립니다.

모든 티어가 같은 엔진을 씁니다 - 같은 recall 품질, 같은 다국어, 모든 메서드. Tier 5까지는 누적 충전액이 쌓이면 신청이나 영업 통화 없이 자동으로 올라갑니다. Enterprise(Tier 6)만 예외입니다.

지출 한도

티어마다 한 달에 쓸 수 있는 금액에 상한이 있습니다. 누적 충전액이 다음 기준에 도달하면 즉시 승급됩니다.

속도 한도

속도 한도는 계정 단위입니다 - 한 계정의 모든 API 키가 하나의 한도를 공유하며, 티어에 따라 올라갑니다. 넘으면 retry-after 헤더와 함께 429를 돌려주므로, 잠시 물러났다(1초 → 2초 → 4초) 재시도하면 됩니다. 모든 엔드포인트가 멱등에 친화적이라 재시도해도 안전합니다.

Enterprise(Tier 6)는 커스텀 한도, SLA, 전담 지원, 그리고 선택적 self-host 라이선스를 제공합니다 - 문의하세요.

문제가 생겼을 때.

에러는 안정적인 type, 사람이 읽는 메시지, 그리고 문의 시 함께 보낼 수 있는 request_id가 담긴 JSON 봉투로 옵니다.

{"type": "error", "error": {
   "type": "authentication_error",
   "message": "Invalid or revoked API key.",
   "request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
 }}

# SDK error handling (Python)
from wontopos import Client, WosError

try:
    mem.search("...", user_id="alice")
except WosError as e:
    if e.status == 401: ...  # bad key
    elif e.status == 429: ...  # back off and retry

요청 한도는 계정 단위로 모든 키가 공유하며, 티어에 따라 올라갑니다 - 사용량 티어 참고. 계정 사용량은 콘솔에 표시됩니다.

당신의 서버, 당신의 데이터.

엔진을 자체 인프라에서 운영할 수 있습니다 - 같은 API, 같은 SDK. 클라이언트가 바라보는 주소만 바꾸면 나머지는 그대로입니다.

mem = Client(api_key="...", base_url="https://wos.your-host.com")

const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });

let mem = Client::with_base_url("...", "https://wos.your-host.com");

• 데이터 주권. 기억이 당신의 네트워크 밖으로 나가지 않습니다.
• 동일한 인터페이스. 같은 메서드와 엔드포인트가 동일하게 동작합니다.
• 라이선스. 셀프 호스팅 패키지는 배포 단위로 협의합니다 - 문의하기.

컨텍스트 윈도를 넘어서.

WOS는 어떤 LLM 컨텍스트 윈도보다도 큰 140만 토큰 히스토리에서도 회수하고, 여전히 ~1,470 토큰의 짧은 조각만 돌려줍니다.

에이전트의 기억은 프롬프트에 들어가는 양에 갇히지 않습니다. 전부 보관하고 중요한 것만 회수합니다. 히스토리가 아무리 커져도 마찬가지입니다.

비공개, 그리고 당신의 것.

데이터는 당신의 저장소에 머뭅니다. 저희는 그것으로 학습하지도, 열람하지도, 재사용하지도 않습니다 - 회수할 수 있게 정리만 합니다.

• BYOK. LLM 키는 요청마다 전달되며 저장되지 않습니다.
• 격리. 기억은 계정별, 그리고 user_id별로 분리됩니다.
• GDPR 삭제 & 셀프 호스팅. 한 번의 호출로 사용자를 삭제하고, 원하면 엔진을 자체 환경에서 운영할 수 있습니다.