Recall Preferences

Recall preferences (memories)

import requests

url = "https://api.hydradb.com/recall/recall_preferences"

payload = {
    "tenant_id": "tenant_1234",
    "query": "Which mode does user prefer",
    "sub_tenant_id": "sub_tenant_4567",
    "max_results": 123,
    "mode": "fast",
    "alpha": 0.8,
    "recency_bias": 1,
    "graph_context": True,
    "search_forceful_relations": True,
    "additional_context": "<string>",
    "metadata_filters": {
        "category": "engineering",
        "department": "R&D"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tenant_id: 'tenant_1234',
    query: 'Which mode does user prefer',
    sub_tenant_id: 'sub_tenant_4567',
    max_results: 123,
    mode: 'fast',
    alpha: 0.8,
    recency_bias: 1,
    graph_context: true,
    search_forceful_relations: true,
    additional_context: '<string>',
    metadata_filters: {category: 'engineering', department: 'R&D'}
  })
};

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

curl --request POST \
  --url https://api.hydradb.com/recall/recall_preferences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenant_id": "tenant_1234",
  "query": "Which mode does user prefer",
  "sub_tenant_id": "sub_tenant_4567",
  "max_results": 123,
  "mode": "fast",
  "alpha": 0.8,
  "recency_bias": 1,
  "graph_context": true,
  "search_forceful_relations": true,
  "additional_context": "<string>",
  "metadata_filters": {
    "category": "engineering",
    "department": "R&D"
  }
}
'

{
  "chunks": [],
  "sources": [
    {
      "id": "HydraDoc1234",
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "url": "<url>",
      "timestamp": "<timestamp>",
      "tenant_metadata": {},
      "document_metadata": {}
    }
  ],
  "graph_context": {
    "query_paths": [],
    "chunk_relations": [],
    "chunk_id_to_group_ids": {}
  },
  "additional_context": {}
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

POST

recall

recall_preferences

Recall preferences (memories)

import requests

url = "https://api.hydradb.com/recall/recall_preferences"

payload = {
    "tenant_id": "tenant_1234",
    "query": "Which mode does user prefer",
    "sub_tenant_id": "sub_tenant_4567",
    "max_results": 123,
    "mode": "fast",
    "alpha": 0.8,
    "recency_bias": 1,
    "graph_context": True,
    "search_forceful_relations": True,
    "additional_context": "<string>",
    "metadata_filters": {
        "category": "engineering",
        "department": "R&D"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tenant_id: 'tenant_1234',
    query: 'Which mode does user prefer',
    sub_tenant_id: 'sub_tenant_4567',
    max_results: 123,
    mode: 'fast',
    alpha: 0.8,
    recency_bias: 1,
    graph_context: true,
    search_forceful_relations: true,
    additional_context: '<string>',
    metadata_filters: {category: 'engineering', department: 'R&D'}
  })
};

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

curl --request POST \
  --url https://api.hydradb.com/recall/recall_preferences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tenant_id": "tenant_1234",
  "query": "Which mode does user prefer",
  "sub_tenant_id": "sub_tenant_4567",
  "max_results": 123,
  "mode": "fast",
  "alpha": 0.8,
  "recency_bias": 1,
  "graph_context": true,
  "search_forceful_relations": true,
  "additional_context": "<string>",
  "metadata_filters": {
    "category": "engineering",
    "department": "R&D"
  }
}
'

{
  "chunks": [],
  "sources": [
    {
      "id": "HydraDoc1234",
      "title": "<title>",
      "type": "<type>",
      "description": "<description>",
      "url": "<url>",
      "timestamp": "<timestamp>",
      "tenant_metadata": {},
      "document_metadata": {}
    }
  ],
  "graph_context": {
    "query_paths": [],
    "chunk_relations": [],
    "chunk_id_to_group_ids": {}
  },
  "additional_context": {}
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

When to use it

/recall/recall_preferences retrieves user-specific context that was ingested via POST /memories/add_memory. Use it when your agent needs to:

Personalize responses based on user preferences
Recall past conversations with the user
Surface user notes or settings relevant to the current task

The request and response shapes are identical to POST /recall/full_recall – the only difference is which collection is searched. Use full_recall for documents and knowledge, recall_preferences for user memories.

Endpoint

Auth: Bearer token
Idempotency: Read-only
Async: No

Example

curl -X POST 'https://api.hydradb.com/recall/recall_preferences' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my_first_tenant",
    "sub_tenant_id": "user_alex",
    "query": "What are my display preferences?",
    "max_results": 3,
    "mode": "thinking"
  }'

const result = await client.recall.recallPreferences({
  tenant_id: "my_first_tenant",
  sub_tenant_id: "user_alex",
  query: "What are my display preferences?",
  max_results: 3,
  mode: "thinking"
});

result = client.recall.recall_preferences(
    tenant_id="my_first_tenant",
    sub_tenant_id="user_alex",
    query="What are my display preferences?",
    max_results=3,
    mode="thinking",
)

Request parameters

Identical to POST /recall/full_recall. The most important ones for memory recall:

Name	Type	Required	Default	Description
`tenant_id`	string	Yes	–	The tenant to search.
`query`	string	Yes	–	Search terms or natural-language question.
`sub_tenant_id`	string	No	default	Critical for B2C apps – pass the end user’s sub-tenant to scope the search to that user’s memories.
`max_results`	integer	No	–	Maximum number of memory chunks to return.
`mode`	enum	No	`fast`	`fast` or `thinking`. Use `thinking` for richer personalization.
`alpha`	number\|string	No	`0.8`	Hybrid weight: `0.0` = keyword, `1.0` = semantic, `"auto"`.
`recency_bias`	number	No	`0.0`	Recency preference. Often more useful on memories than knowledge.
`graph_context`	boolean	No	`false`	Include entity relationships in the response.
`metadata_filters`	object	No	–	Filter by metadata. See note below.

Sub-tenant scoping

For B2C apps, sub-tenants typically map to end users:

# When user "alex" interacts with your agent:
result = client.recall.recall_preferences(
    tenant_id="my_first_tenant",
    sub_tenant_id="user_alex",     # scope to alex's memories only
    query="what are my preferences for technical depth?",
)

Without sub_tenant_id, the search runs against the default sub-tenant – which is rarely what you want for personalized recall.

Metadata filters on memories

POST /recall/recall_preferences shares RecallSearchRequest with POST /recall/full_recall in OpenAPI. The canonical metadata_filters contract is defined on that schema in api-reference/openapi.json and summarized under Full recall → Metadata filters.

{
  "metadata_filters": {
    "additional_metadata": { "source": "onboarding" }
  }
}

Response

Same shape as POST /recall/full_recall. The chunks[] array contains memory chunks; sources[] contains the originating memory items.

{
  "chunks": [
    {
      "chunk_uuid": "...",
      "source_id": "1d50e5cd7c196a2bbcc1a59b037b3a44",
      "chunk_content": "User prefers detailed technical explanations and dark mode",
      "source_title": "User Preferences",
      "relevancy_score": 0.94,
      "additional_metadata": { "source": "onboarding" },
      "metadata": { "team": "engineering" }
    }
  ],
  "sources": [...],
  "graph_context": {...},
  "additional_context": {}
}

Behavior notes

Pass sub_tenant_id explicitly for B2C apps. Personalized recall only works when memories are scoped to the right user. Omitting sub_tenant_id falls back to the default sub-tenant.

thinking mode is especially valuable for memories. Memory recall benefits from query expansion because user preferences are often phrased indirectly (“I like X” → recall “user prefers X”).

For documents and knowledge: Full recall – same shape, targets the knowledge collection
Ingest memories: Add memory – store memories before they can be recalled
For exact-match memory search: Boolean recall – set search_mode: "memories"

Errors

Common codes: 400 INVALID_PARAMETERS, 404 TENANT_NOT_FOUND, 422 VALIDATION_ERROR, 429 RATE_LIMITED. See Error Responses for the full list. Read more: Essentials → Memories · Essentials → Recall

How to use API Results

Recall responses are chunks of data from knoledge, memory and graph relations in structured JSON. To extract context, we parse the data out of the response strucutre and feed it in prose to an LLM. For further details, explore Essentials → How to Use API Results.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request body for full recall (sources) and recall preferences (memories).

tenant_id

string

required

Unique identifier for the tenant/organization

Example:

"tenant_1234"

query

string

required

Search terms to find relevant content

Example:

"Which mode does user prefer"

sub_tenant_id

string | null

Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.

Example:

"sub_tenant_4567"

max_results

integer | null

Maximum number of results to return

mode

enum<string>

default:fast

Retrieval mode to use ('fast' or 'thinking')

Available options:

fast,

thinking

alpha

default:0.8

Search ranking algorithm parameter (0.0-1.0 or 'auto')

recency_bias

number

default:0

Preference for newer content (0.0 = no bias, 1.0 = strong recency preference)

Example:

1

graph_context

boolean

default:false

Enable graph context for search results

Example:

true

search_forceful_relations

boolean

default:true

Whether to search for forceful relations in thinking mode to augment context

Example:

true

additional_context

string | null

Additional context provided by the user to guide retrieval

metadata_filters

Metadata Filters · object | null

Optional object for exact-match metadata scoping. All provided conditions are combined with AND. Top-level keys (except the reserved nested object described below) must match tenant-level metadata field names declared with enable_match in tenant_metadata_schema; each value is compared with plain equality to the stored tenant metadata value for that field. For document-level metadata, supply a nested object under the key "additional_metadata" whose keys and values are compared with plain equality to per-source document metadata. Only equality on scalar-compatible values is part of this contract—do not send range operators, regular-expression operators, or Mongo-style operators such as $gte, $lt, $in, or $regex.

Example:

{
  "category": "engineering",
  "department": "R&D"
}

Response

Successful Response

Result of a hybrid search retrieval operation.

chunks

VectorStoreChunk · object[]

Show child attributes

Example:

[]

sources

SourceInfo · object[]

Deduplicated source documents corresponding to the returned chunks

Show child attributes

graph_context

GraphContext · object

Graph context containing query-based paths and chunk-based relation paths.

Show child attributes

additional_context

Additional Context · object

Map of chunk_uuid to VectorStoreChunk for extra context from forcefully related sources. Use chunk.extra_context_ids to look up chunks: extra_context[id] for id in chunk.extra_context_ids.

Show child attributes

Full Recall Boolean Recall

⌘I

API Documentation

Tenants

Knowledge & Memories

Recall

Managing Data

When to use it

Endpoint

Example

Request parameters

Sub-tenant scoping

Metadata filters on memories

Response

Behavior notes

Errors

How to use API Results

Authorizations

Body

Response

​When to use it

​Endpoint

​Example

​Request parameters

​Sub-tenant scoping

​Metadata filters on memories

​Response

​Behavior notes

​Related endpoints

​Errors

​How to use API Results

Authorizations

Body

Response

When to use it

Endpoint

Example

Request parameters

Sub-tenant scoping

Metadata filters on memories

Response

Behavior notes

Related endpoints

Errors

How to use API Results