Skip to main content
POST
/
v1
/
recall
Recall Memories
curl --request POST \
  --url https://api.memoclaw.com/v1/recall \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "limit": 123,
  "min_similarity": 123,
  "namespace": "<string>",
  "session_id": "<string>",
  "agent_id": "<string>",
  "include_relations": true,
  "filters": {
    "filters.tags": [
      "<string>"
    ],
    "filters.after": "<string>"
  }
}
'
{
  "memories": [
    {
      "memories[].id": "<string>",
      "memories[].content": "<string>",
      "memories[].similarity": 123,
      "memories[].metadata": {},
      "memories[].importance": 123,
      "memories[].namespace": "<string>",
      "memories[].memory_type": "<string>",
      "memories[].session_id": {},
      "memories[].agent_id": {},
      "memories[].created_at": "<string>",
      "memories[].access_count": 123,
      "memories[].pinned": true,
      "memories[]._signals": {}
    }
  ],
  "query_tokens": 123
}
This endpoint requires an x402 payment header.
Price: $0.005 USDC

​
Request Body

​
query
string
required
Natural language search query. Max 32,768 characters.
​
limit
integer
Maximum number of results, 1–100. Default: 5.
​
min_similarity
number
Minimum similarity threshold, 0–1. Default: 0.0.
​
namespace
string
Filter results to a specific namespace.
​
session_id
string
Filter results to a specific session.
​
agent_id
string
Filter results to a specific agent.
​
include_relations
boolean
Include related memories in results. Default: false.
​
filters
object
Additional filters to narrow results.

​
Scoring

Hybrid recall scoring (4-signal approach):
hybrid = vector_sim × 0.55 + keyword_match × 0.25 + recency × 0.20
score  = hybrid × context_importance × access_boost × type_decay
Signals:
  • vector_sim: Cosine similarity (0–1) — primary semantic signal
  • keyword_match: Full-text/BM25 match, normalized (0–1) — exact term matches
  • recency: exp(-age_days / 30) — temporal freshness
  • context_importance: Importance dynamically boosted by query relevance
  • access_boost: min(1 + access_count × 0.1, 2.0) — frequently recalled memories rank higher
  • type_decay: Exponential decay based on memory type half-life (correction: 180d, preference: 180d, decision: 90d, project: 30d, observation: 14d, general: 60d). Pinned memories are exempt from decay. Memories with more relations decay slower.
When keyword match is strong (>0.3), its weight increases to 0.35 (vector drops to 0.45) for adaptive boosting.

​
Response (200)

​
memories
array
Array of matching memories.
​
query_tokens
number
Tokens used for the query embedding.

​
Example

curl -X POST https://api.memoclaw.com/v1/recall \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the user editor preferences?",
    "limit": 5,
    "filters": {
      "tags": ["preferences"]
    }
  }'
Response
{
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "User prefers dark mode and vim keybindings",
      "similarity": 0.89,
      "metadata": {
        "tags": ["preferences", "ui"]
      },
      "importance": 0.8,
      "memory_type": "preference",
      "namespace": "default",
      "session_id": null,
      "agent_id": null,
      "created_at": "2025-01-15T10:30:00Z",
      "access_count": 3,
      "pinned": false,
      "_signals": {
        "vector": 0.92,
        "keyword": 0.15,
        "recency": 0.78,
        "base_importance": 0.8,
        "effective_importance": 0.96,
        "context_importance": 0.98,
        "relation_count": 1,
        "type_decay": 0.95
      }
    }
  ],
  "query_tokens": 12
}