Memory API

에이전트 런

POST /v1/ask — 에이전트 실행, SSE 진행 스트림, 후속 턴.

/v1/search 가 단발 RAG 검색이라면, /v1/ask 는 앱의 채팅과 같은 에이전트 엔진을 돌립니다 — 여러 단계로 메모리를 검색하고, 연결된 커넥터를 읽고, 웹을 검색하고, 필요하면 서브에이전트 검증까지 거쳐 인용이 달린 답변을 만듭니다. 실행은 백그라운드에서 완주하며 스레드로 영속되므로 연결이 끊겨도 결과를 잃지 않고, 같은 thread_id 로 이전 턴의 맥락·인용을 재사용하는 후속 질문을 이어갈 수 있습니다. 스레드는 앱에서도 그대로 보입니다.

이 표면은 읽기 전용입니다 — 커넥터 쓰기 액션·샌드박스 코드 실행·파일(아티팩트) 생성은 앱 전용입니다. 실행은 워크스페이스 사용량을 소모합니다.

런 시작

POST/v1/ask

필드	타입	설명
`question`	string (필수)	질문/지시. 최대 4,000자
`thread_id`	uuid	후속 턴 대상 스레드. 생략 시 새 스레드 생성
`model`	string	답변 LLM (`/v1/models` 의 id). 생략 시 워크스페이스 기본
`locale`	string	답변 언어 힌트(`ko`, `en` …). 생략 시 질문 언어
`idempotency_key`	string	전송 1회당 멱등 키 — 같은 키로 재전송하면 새 턴을 만들지 않고 같은 id 들을 반환

curl -X POST 'https://api.memory.inc/v1/ask' \
  -H 'authorization: Bearer pwk_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{ "question": "지난주 결제 장애 타임라인과 원인을 정리해줘" }'

{
  "ok": true,
  "data": {
    "thread_id": "0d2f…",
    "user_message_id": "a41c…",
    "assistant_message_id": "b7e9…",
    "status": "running",
    "stream_url": "https://api.memory.inc/v1/ask/0d2f…/stream"
  }
}

응답은 즉시 반환됩니다(런은 백그라운드). status 가 complete 면 이미 답변이 있는 턴의 멱등 재전송입니다. 진행 중 스레드에 다른 질문을 보내면 409 conflict — 스트림이 끝난 뒤 후속 턴을 보내세요(같은 질문/같은 idempotency_key 재전송은 409 없이 기존 id 들을 돌려줍니다).

진행 스트림

GET/v1/ask/{thread_id}/stream

data: <json> SSE 프레임이 흐르고 마지막에 event: end 로 닫힙니다. 순수 tail 이라 몇 번을 붙어도 안전하며(생성을 재시작하지 않음), 끊겨도 런은 완주합니다 — 재접속하면 처음부터 다시 재생되고, 이미 끝난 스레드면 마지막 답변을 스냅샷으로 재생합니다.

`type`	의미
`thread`	스트림 시작 — `threadId` 에코
`reasoning`	생각 과정/진행 나레이션 델타
`text`	답변 본문 델타
`text_reset`	지금까지 받은 본문을 비우고 다시 그리라는 신호(중간 나레이션 → 최종 답변 전환)
`step`	실행 트레일 단계 `{ id, kind, phase, meta }` — `agent_search`(메모리 검색)·`agent_read`·`agent_web_search`·`agent_action`(커넥터 읽기)·`agent_subagent`·`agent_verify`(자체 검증)·`agent_plan` 등
`citation`	인용 하나 — `[n]` 번호가 본문과 대응
`done`	최종 결과. `result.answer.text` 와 `result.answer.citations` 가 본문·인용의 권위
`error`	`{ code: "INTERNAL" \| "STALE", message }` — `STALE` 은 생성 정체(재-POST 로 재시도)

curl -N 'https://api.memory.inc/v1/ask/0d2f…/stream' \
  -H 'authorization: Bearer pwk_YOUR_KEY'

후속 턴

thread_id 를 넣어 다시 POST 하면 같은 스레드의 다음 턴입니다. 에이전트는 이전 턴의 대화 맥락과 라이브로 가져온 자료(커넥터 읽기 결과 등)를 재사용하므로, "그중 두 번째 건 자세히"류의 후속 질문이 처음부터 재조회하지 않습니다.

curl -X POST 'https://api.memory.inc/v1/ask' \
  -H 'authorization: Bearer pwk_YOUR_KEY' \
  -H 'content-type: application/json' \
  -d '{ "thread_id": "0d2f…", "question": "그중 root cause 항목만 더 자세히" }'

가시성

personal 키·OAuth 토큰 — 발급자/사용자 본인으로 동작: 본인 개인 데이터 + 팀 공유 데이터, 본인 개인 커넥터 포함.
workspace 키 — 팀 공유 데이터만(어떤 멤버의 개인 데이터도 제외). 스레드는 키 생성자 소유로 영속됩니다.

생성된 스레드는 기본 개인(private) 스코프입니다 — 스트림/후속 턴은 같은 발급자(또는 팀 스코프로 공유된 스레드)만 접근할 수 있습니다.