운영

메모리는 chat() 호출에 연결되어 있습니다. 이제 실제로 무언가를 recall하는지 확인하고, 해당 활동을 자체 로그에 기록하며, 느리거나 고장 난 저장소가 채팅을 중단하지 않는다는 것을 확인하려고 합니다. 이 페이지에서는 미들웨어의 옵션과 이를 관찰하고 운영하는 방법을 다룹니다.

메모리가 처음이라면 먼저 Overview와 Quickstart를 살펴보세요.

memoryMiddleware 옵션

옵션	타입	기본값	목적
adapter	MemoryAdapter	(필수)	recall 및 save할 백엔드입니다.
scope	MemoryScope | (ctx) => MemoryScope	(필수)	격리 범위로, 정적이거나 요청마다 파생됩니다.
role	'recall+save' | 'save-only'	'recall+save'	'save-only'는 recall하거나 주입하지 않고 턴을 영속화합니다.
onRecall	({ scope, query, result }) => void	없음	각 recall 후 실행되는 앱 텔레메트리입니다.
onSave	({ scope, turn, receipts }) => void	없음	각 지연된 save 후 실행되는 앱 텔레메트리입니다.

모든 옵션을 한곳에서 확인합니다.

import { memoryMiddleware } from '@tanstack/ai-memory'
import { inMemory } from '@tanstack/ai-memory/in-memory'

const mw = memoryMiddleware({
  adapter: inMemory(),
  // Function form derives scope per request. `ctx.threadId` is the stable
  // per-conversation id; add `userId` from your server-validated session.
  scope: (ctx) => ({ threadId: ctx.threadId }),
  role: 'recall+save', // or 'save-only' to persist without injecting
  onRecall: ({ query, result }) => {
    console.log('recalled', result.fragments?.length ?? 0, 'hits for', query)
  },
  onSave: ({ receipts }) => {
    console.log('saved', receipts.filter((r) => r.ok).length, 'records')
  },
})

recall하지 않고 영속화하기

기본적으로 미들웨어는 recall과 save를 모두 수행합니다(role: 'recall+save'). 각 턴을 메모리에서 다시 읽거나 프롬프트에 주입하지 않고 영속화하려면 role: 'save-only'로 설정합니다. recall을 켜기 전에 사용자의 기록을 쌓거나, 현재 답변의 형태에는 영향을 주지 않고 턴을 기록하려는 라우트에서 사용합니다.

onRecall 및 onSave를 사용한 텔레메트리

아래의 devtools 이벤트는 개발 중 메모리를 확인하기 위한 것입니다. 앱과 함께 배포되는 텔레메트리에는 위의 onRecall 및 onSave 콜백을 사용합니다. onRecall은 각 recall 후 query와 result를 전달하므로 적중 수를 셀 수 있습니다. onSave는 각 지연된 save 후 쓰기 영수증과 함께 실행되므로 쓰기 수를 셀 수 있습니다. 이를 console.log 대신 메트릭 클라이언트로 보냅니다.

devtools에서 확인하기

AI DevTools에는 memoryMiddleware가 연결된 모든 채팅을 위한 Memory 탭이 있습니다. 각 턴의 recall(query, fragment 수, 주입된 문자 수, recall 소요 시간)과, inspect/ listFacts를 구현하는 어댑터(내장 inMemory() 및 redis()가 구현함)의 경우 현재 저장된 레코드와 사실을 보여줍니다. 무엇을 렌더링하는지와 서버 측 메모리가 패널에 도달하는 방법은 Memory Inspector를 참조하세요.

내부적으로 미들웨어는 aiEventClient에서 다음 이벤트를 내보냅니다(@tanstack/ai-event-client에서 가져옵니다). 패널이 이 이벤트를 읽으며, 직접 구독할 수도 있습니다.

이벤트	시점
memory:retrieve:started	Recall이 시작됩니다.
memory:retrieve:completed	Recall이 반환됩니다(fragment 수와 도구가 주입되었는지 포함).
memory:persist:started	지연된 save가 시작됩니다.
memory:persist:completed	Save가 완료됩니다(receipt 수 포함).
memory:error	recall 또는 save에서 예외가 발생했습니다(phase: 'recall' 또는 'save'). 이미 확인된 경우에만 scope를 전달하며, resolver가 실패했거나 실행되지 않았다면 생략합니다.

오류는 치명적이지 않습니다

메모리 오류가 채팅 실행을 중단하는 일은 없습니다. 예외를 발생시키는 recall 또는 save는 memory:error를 내보내고, 실행은 성능이 저하된 메모리 상태로 계속됩니다. recall은 아무것도 반환하지 않고 실패한 save는 버려집니다. 스트리밍은 절대 차단되지 않으며, 실패한 save가 턴을 실패시키지도 않습니다. 따라서 불안정한 저장소는 채팅을 중단시키는 대신 경험을 저하시킵니다.

다음 단계

• Overview: recall/save 계약과 턴의 흐름
• Adapters: 각 어댑터의 옵션 및 각각의 예시
• Custom Adapter: 제공되지 않는 백엔드에 recall/save를 구현하는 방법