Recall Memories

POST /v1/recall — Semantic search across your memories.

POST /v1/recall

Recall Memories

cURL

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>"
  }
}
'

import requests

url = "https://api.memoclaw.com/v1/recall"

payload = {
    "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>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'}
  })
};

fetch('https://api.memoclaw.com/v1/recall', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.memoclaw.com/v1/recall",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.memoclaw.com/v1/recall"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"limit\": 123,\n  \"min_similarity\": 123,\n  \"namespace\": \"<string>\",\n  \"session_id\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"include_relations\": true,\n  \"filters\": {\n    \"filters.tags\": [\n      \"<string>\"\n    ],\n    \"filters.after\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.memoclaw.com/v1/recall")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"limit\": 123,\n  \"min_similarity\": 123,\n  \"namespace\": \"<string>\",\n  \"session_id\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"include_relations\": true,\n  \"filters\": {\n    \"filters.tags\": [\n      \"<string>\"\n    ],\n    \"filters.after\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.memoclaw.com/v1/recall")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"limit\": 123,\n  \"min_similarity\": 123,\n  \"namespace\": \"<string>\",\n  \"session_id\": \"<string>\",\n  \"agent_id\": \"<string>\",\n  \"include_relations\": true,\n  \"filters\": {\n    \"filters.tags\": [\n      \"<string>\"\n    ],\n    \"filters.after\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

200

{
  "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.

Show Filter fields

filters.tags · string[]

Match memories with any of these tags. Max 10.

filters.after · string

ISO 8601 date. Only return memories created after this date.

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.

Show Memory object fields

memories[].id · string

UUID of the memory.

memories[].content · string

The memory text.

memories[].similarity · number

Weighted similarity score.

memories[].metadata · object

Metadata attached to the memory.

memories[].importance · number

Importance value (0–1).

memories[].namespace · string

Namespace of the memory.

memories[].memory_type · string

Memory type: correction, preference, decision, project, observation, or general.

memories[].session_id · string | null

Session identifier, if set.

memories[].agent_id · string | null

Agent identifier, if set.

memories[].created_at · string

ISO 8601 creation timestamp.

memories[].access_count · number

Number of times this memory has been recalled.

memories[].pinned · boolean

Whether the memory is pinned (exempt from decay).

memories[]._signals · object

Signal breakdown for debugging/transparency. Includes vector, keyword, recency, base_importance, effective_importance, context_importance, relation_count, and type_decay.

query_tokens · number

Tokens used for the query embedding.

Example

curl

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"]
    }
  }'

const response = await fetch("https://api.memoclaw.com/v1/recall", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "What are the user editor preferences?",
    limit: 5,
    filters: {
      tags: ["preferences"],
    },
  }),
});

const data = await response.json();

from memoclaw import MemoClaw

client = MemoClaw()
result = client.recall(
    "What are the user editor preferences?",
    limit=5,
    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
}