너무 많은 결과가 나오는 검색 좁히기
limit을 늘리기 전에 scope와 path filter를 추가합니다. scope가 없는 query에서 limit만 넓히면 signal이 아니라 noise가 늘어납니다.
search_memory({
query: "token identity fallback",
limit: 5
})공개 MCP 도구
search_memory
목적
승인된 XMemo memory를 strict targeted-match 의미로 검색하여 약한 match가 조용히 answer로 처리되지 않게 합니다.
사용 시점
- 호출자가 관련 project, team, path 또는 memory type을 알고 targeted lookup이 필요한 경우.
- 약한 semantic match를 결과로 제시하면 오해를 일으키거나 안전하지 않은 경우.
- 명시적인 scope/team filter, retrieval 설명 또는 더 큰 통제된 결과 집합이 필요한 경우.
사용하지 않을 시점
- 빠르고 unscoped한 forgiving lookup에는 사용하지 않습니다. recall을 사용합니다.
- multi-memory prompt context pack을 만들 때 사용하지 않습니다. recall_context를 사용합니다.
- memory를 mutate하거나 제거할 때 사용하지 않습니다.
- REST API는 public MCP tool보다 더 넓은 field set을 허용합니다. scope, bucket, team 및 provenance filter는 /docs/api/memory를 참고합니다.
필수 스코프
- memory:read가 필요하며 scope 및 team_id filter는 호출자의 authorization boundary를 확장할 수 없습니다.
매개변수
| 이름 | 타입 | 설명 |
|---|---|---|
query | string · 필수 | 일치시킬 정확한 topic 또는 wording입니다. |
limit | integer · 기본값: 5 | 결과 수입니다. |
path_filter | string · 기본값: % | Claude plugin profile 전용 logical-path ILIKE filter입니다. Generic public profile에서는 허용되지 않습니다. |
memory_type | string · 기본값: % | Claude plugin profile 전용 memory type filter입니다. Generic public profile에서는 허용되지 않습니다. |
prefer_working | boolean · 기본값: false | Claude plugin profile 전용입니다. vector 결과보다 active working state를 먼저 배치합니다. |
반환 스키마
opaque reference, location, content 및 선택적 explanation/agent-boundary metadata를 포함한 ranked text 응답입니다. 결과도 승인된 memory로 제한됩니다.
예제
search_memory({
query: "token identity fallback",
limit: 5
})오류
- 401/403: 요청에 memory:read가 없거나 선택한 scope/team에 접근할 수 없습니다.
- Validation failure: query, limit, path pattern 또는 memory type이 유효하지 않습니다.
- No-match response: target과 승인된 filter를 만족하는 강한 결과가 없습니다. 호출자는 recall 의미를 조용히 대신 사용해서는 안 됩니다.
관련 도구
- recall — 엄격한 matching이 필요하지 않을 때 forgiving best-effort retrieval을 사용합니다.
- recall_context — prompt context에는 범위가 제한된 multi-memory retrieval을 사용합니다.
- forget — 반환된 reference를 검토한 후에만 정확한 record를 제거합니다.
출처: MCP 도구 표면