# search

Search authorized memory when the relevant wording or record is not known in advance.

- Canonical: https://docs.xmemo.dev/docs/tools/search
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: e4c087a8f0e12c7c67bbf556d6d2f73b0e61a736a9b8686e77e1b181a14238a7
- Edition-Digest: 034e3f4ee3a3d5b0202753104714b0d77c36f76de455123ed919ef14b977bc76
- Source-Revision: sha256:0f9b76db3972abc862d49a83f61e83eed6529dc4507a3c290949f892dcaa48f9

## Tool Reference: `search_memory`

### Purpose

Search authorized XMemo memories with strict targeted-match semantics, so weak matches are not silently treated as the answer.

### Parameters

- `query` (string, required): Exact topic or wording to match.
- `limit` (integer, optional, default: 5): Result count.
- `path_filter` (string, optional, default: %): Claude plugin profile only: logical-path ILIKE filter. Not accepted on the generic public profile.
- `memory_type` (string, optional, default: %): Claude plugin profile only: memory type filter. Not accepted on the generic public profile.
- `prefer_working` (boolean, optional, default: false): Claude plugin profile only: place active working state before vector results.

### Returns

A ranked text response with opaque references, locations, content, and optional explanation/agent-boundary metadata. The result is still limited to authorized memories.

### Errors

- 401/403: the request lacks memory:read or cannot access the selected scope/team.
- Validation failure: query, limit, path pattern, or memory type is invalid.
- No-match response: no strong result satisfies the target and authorized filters; callers should not substitute recall semantics silently.

### Examples

#### Strict project-scoped lookup



```typescript
search_memory({
  query: "token identity fallback",
  limit: 5
})
```

### Related Tools

- [recall](/docs/tools/recall): Use forgiving best-effort retrieval when strict matching is unnecessary.
- [recall_context](/docs/tools/recall-context): Use bounded multi-memory retrieval for prompt context.
- [forget](/docs/tools/forget): Remove an exact record only after reviewing its returned reference.

## Narrow a search that returns too much

Add the scope and path filters before raising the limit; a wider limit on an unscoped query returns more noise, not more signal.

```ts
search_memory({
  query: "token identity fallback",
  limit: 5
})
```