능동적 서피싱

처음이라면 STM 개요에서 전체 파이프라인을 먼저 확인하세요.

기존 RAG는 에이전트가 명시적으로 검색을 요청해야만 관련 정보를 제공합니다. memtomem-stm의 능동적 서피싱은 프록시된 MCP 호출을 관찰하여 현재 작업 맥락을 파악하고, 부합하는 기억을 LTM에서 조회하여 자동으로 응답에 주입합니다. v0.1.24의 mms hook은 지원되는 Claude Code 네이티브 도구 PostToolUse 이벤트에도 additionalContext 형태로 서피싱을 확장합니다.

동작 원리

에이전트가 MCP 도구를 호출하면, STM 프록시가 다음 파이프라인을 실행합니다:

도구 호출 → 컨텍스트 추출 → LTM 검색 → 관련성 판정 → 응답에 주입

에이전트 코드를 수정할 필요 없이, STM 프록시를 거치는 것만으로 MCP 통신에서 기억이 자동 주입됩니다. Claude Code built-in 도구에는 mms hook을 host hook으로 등록합니다. 기본적으로 warm local daemon을 사용하므로 반복 hook 호출에서 LTM cold start 비용을 치르지 않습니다.

5단계 컨텍스트 추출

STM이 LTM에 기억을 조회하려면 먼저 검색 쿼리가 필요합니다. 단일 신호에 의존하지 않고, 서로 다른 소스를 시도하는 5단계 파이프라인을 순차 실행합니다. 가장 먼저 사용 가능한 쿼리를 생성한 단계가 채택됩니다. _context_query 인자가 명시된 호출은 해당 값을 직접 사용하며, fs__read_file(path=...) 같은 단순 호출에도 검색 가능한 쿼리를 생성할 수 있습니다.

우선순위	추출 방법	설명
1	도구별 쿼리 템플릿	도구 이름에 매핑된 미리 정의된 쿼리 패턴
2	_context_query 인자	에이전트가 명시적으로 전달한 검색 쿼리
3	경로 인자	path / file / filepath / file_path / filename 키 전용 토큰화 (구분자 분리, 확장자 제거)
4	시맨틱 키	query / search / url / description 등 인자 값의 키워드 조합
5	도구명	최후 수단 — 도구 이름 자체를 쿼리로 사용

관련성 게이팅

서피싱된 기억이 실제로 유용한지 5단계로 필터링합니다:

1. 컨텍스트 추출 — 도구 호출에서 의미 있는 쿼리 생성 가능 여부
2. 관련성 판정 — 추출된 쿼리가 기억 검색에 적합한지 평가
3. LTM 검색 — 하이브리드 검색으로 관련 기억 후보 검색
4. 점수 필터링 — min_score 임계값 이하의 결과 제거
5. 중복 제거 — 세션 내 + 교차 세션(7일) 중복 방지

주입 모드

서피싱된 기억이 응답에 엮이는 방식은 MEMTOMEM_STM_SURFACING__INJECTION_MODE 로 제어합니다:

모드	동작
append (기본값)	기억을 응답 아래에 덧붙임. progressive delivery offset을 보존하며 적격 continuation 경로에서도 동작.
prepend	기억을 헤더로 앞에 붙임. stm_proxy_read_more offset을 밀어버리므로 progressive delivery에서는 스킵.
section	기억을 전용 섹션에 배치. progressive 연속 호출에서도 서피싱 트리거 (F6).

모델 인식 기본값

에이전트의 컨텍스트 윈도우 크기를 인식하여 자동 스케일링합니다:

컨텍스트 윈도우	압축 비율	주입 크기	검색 결과 수
≤ 32K	높은 압축	소형	적음
32K ~ 200K	기본 압축	중형	기본
> 200K	낮은 압축	대형	많음

피드백 루프

에이전트가 서피싱 품질을 평가하면, 자동 튜너가 도구별 관련성 임계값을 지속적으로 최적화합니다:

• helpful → 해당 도구의 min_score 유지 또는 하향
• partially_helpful → 중립 피드백으로 집계
• not_relevant → min_score 상향 (더 엄격한 필터링)
• already_known → negative feedback으로 집계하고 로컬 demotion / dedup 동작에 반영

안전 장치

• 회로 차단기 (3-state: closed / open / half-open) — circuit_max_failures(기본 3)회 연속 실패 후 open 상태가 되며, circuit_reset_seconds(기본 60s) 경과 후 half-open으로 전환
• 서피싱 타임아웃 — 호출당 3s 하드 제한
• 레이트 리밋 — 전체 도구 합산 15 calls / minute 상한
• 쓰기 도구 스킵 — 파일 쓰기, 삭제 등 부수효과가 있는 도구에서는 서피싱 비활성화
• 쿼리 쿨다운 — 동일 쿼리의 빈번한 반복 검색 방지
• 교차 세션 중복 제거 — 기본 TTL 604800s (7일), MEMTOMEM_STM_SURFACING__DEDUP_TTL_SECONDS 로 조정
• 주입 크기 상한 — 주입당 기본 3000 chars
• 로컬 피드백 demotion — 같은 기억이 서로 다른 이벤트에서 not_relevant 또는 already_known으로 반복 평가되면 feedback_demotion_negative_threshold(기본 3) 이후 주입 전에 필터링
• 쿼리 텍스트 프라이버시 — query_retention_days는 기본 30일 이후 저장된 원문 쿼리를 비우고, persist_query_text=false는 원문 대신 sha256: digest를 저장

LTM 전송

STM은 LTM과 MCP 프로토콜로 통신합니다. 기본값은 stdio로 memtomem-server를 실행하는 방식이며, v0.1.24부터는 장기 실행 LTM 서비스를 sse 또는 streamable_http로 연결할 수 있습니다:

export MEMTOMEM_STM_SURFACING__LTM_MCP_TRANSPORT=streamable_http
export MEMTOMEM_STM_SURFACING__LTM_MCP_URL=https://ltm.example/mcp
export MEMTOMEM_STM_SURFACING__LTM_MCP_HEADERS='{"Authorization":"Bearer ..."}'

LTM 응답은 서피싱 엔진이 소비하며, 프록시 압축/캐시 파이프라인을 거치지 않습니다.

trace_id가 서피싱과 점진적 전달 경로에 끼워져, 후속 읽기가 Langfuse(또는 OpenTelemetry 계열 트레이서)에서 초기 청크와 자동으로 묶입니다.