Skip to main content
POST
https://api.memoclaw.com
/
v1
/
search
Search Memories
curl --request POST \
  --url https://api.memoclaw.com/v1/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "limit": 123,
  "namespace": "<string>",
  "memory_type": "<string>",
  "tags": [
    "<string>"
  ],
  "session_id": "<string>",
  "agent_id": "<string>"
}
'
{
  "memories": [
    {
      "id": "<string>",
      "content": "<string>",
      "importance": 123,
      "memory_type": "<string>",
      "namespace": "<string>",
      "tags": [
        "<string>"
      ],
      "created_at": "<string>"
    }
  ],
  "total": 123,
  "query": "<string>"
}
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

​
query
string
required
Search query string. Max 1,000 characters.
​
limit
number
Maximum number of results. Default: 10. Max: 100.
​
namespace
string
Filter by namespace.
​
memory_type
string
Filter by memory type: correction, preference, decision, project, observation, or general.
​
tags
string[]
Filter by tags.
​
session_id
string
Filter by session ID.
​
agent_id
string
Filter by agent ID.

​
Response (200 OK)

​
memories
array
Array of matching memories sorted by BM25 relevance.
​
total
number
Total number of matches.
​
query
string
The search query used.

​
When to Use Search vs Recall

Use CaseEndpoint
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

curl -X POST https://api.memoclaw.com/v1/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "query": "dark mode preferences",
    "limit": 10,
    "tags": ["preferences"]
  }'
Response
{
  "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"
}