> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Memories

> POST /v1/search — Full-text search without embedding costs.

<Snippet file="snippets/wallet-auth-callout.mdx" />

**Price:** FREE

Full-text keyword search using BM25 ranking. A lightweight alternative to `/v1/recall` when you don't need semantic embeddings or want to reduce costs.

This endpoint uses PostgreSQL full-text search (tsvector) rather than vector similarity, making it faster and free from embedding API costs.

## Request Body

<ParamField body="query" type="string" required>
  Search query string. Max 1,000 characters.
</ParamField>

<ParamField body="limit" type="number">
  Maximum number of results. Default: `10`. Max: `100`.
</ParamField>

<ParamField body="namespace" type="string">
  Filter by namespace.
</ParamField>

<ParamField body="memory_type" type="string">
  Filter by memory type: `correction`, `preference`, `decision`, `project`, `observation`, or `general`.
</ParamField>

<ParamField body="tags" type="string[]">
  Filter by tags.
</ParamField>

<ParamField body="session_id" type="string">
  Filter by session ID.
</ParamField>

<ParamField body="agent_id" type="string">
  Filter by agent ID.
</ParamField>

## Response (200 OK)

<ResponseField name="memories" type="array">
  Array of matching memories sorted by BM25 relevance.

  <Expandable title="Memory object">
    <ResponseField name="id" type="string">
      UUID of the memory.
    </ResponseField>

    <ResponseField name="content" type="string">
      Memory text content.
    </ResponseField>

    <ResponseField name="importance" type="number">
      Importance score (0-1).
    </ResponseField>

    <ResponseField name="memory_type" type="string">
      Memory type.
    </ResponseField>

    <ResponseField name="namespace" type="string">
      Namespace.
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      Tags.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of matches.
</ResponseField>

<ResponseField name="query" type="string">
  The search query used.
</ResponseField>

## When to Use Search vs Recall

| Use Case                          | Endpoint     |
| --------------------------------- | ------------ |
| Natural language semantic search  | `/v1/recall` |
| Keyword/exact match search        | `/v1/search` |
| Need vector similarity scoring    | `/v1/recall` |
| Reduce embedding API costs        | `/v1/search` |
| Find memories with specific words | `/v1/search` |

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.memoclaw.com/v1/search \
    -H "Content-Type: application/json" \
    -H "x-wallet-auth: 0xYourWallet:1699900000:0xSignature..." \
    -d '{
      "query": "dark mode preferences",
      "limit": 10,
      "tags": ["preferences"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.memoclaw.com/v1/search", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-wallet-auth": await getAuthHeader(),
    },
    body: JSON.stringify({
      query: "dark mode preferences",
      limit: 10,
      tags: ["preferences"],
    }),
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  from memoclaw import MemoClaw

  client = MemoClaw()

  result = client.search(
      query="dark mode preferences",
      limit=10,
      tags=["preferences"],
  )
  for m in result.memories:
      print(f"[{m.id}] {m.content}")
  ```

  ```typescript TypeScript theme={null}

  import { MemoClawClient } from "memoclaw";

  const client = new MemoClawClient();

  const result = await client.search({
    query: "dark mode preferences",
    limit: 10,
    tags: ["preferences"],
  });
  result.memories.forEach(m => {
    console.log(`[${m.id}] ${m.content}`);
  });
  ```
</CodeGroup>

```json Response theme={null}
{
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User prefers dark mode",
      "importance": 0.8,
      "memory_type": "preference",
      "namespace": "default",
      "tags": ["preferences", "ui"],
      "created_at": "2026-02-13T10:30:00Z"
    }
  ],
  "total": 1,
  "query": "dark mode preferences"
}
```