Recall

Recall turns stored context into the right context for a specific query. This page covers what recall is, the endpoints HydraDB exposes, the parameters that matter, and the patterns you’ll reach for in production. For request/response schemas, see the API reference: Full Recall, Memory Recall, Boolean Recall.

1. What is Recall

Recall returns the chunks most likely to help your agent succeed on a query - not just the chunks most textually similar to it. Pure vector search gives you similarity; recall gives you usefulness. HydraDB stores two kinds of context in separate vector stores:

Store	Contains	`vectorstore_status` index	Recall endpoint
Memories	User preferences, conversation history, per-user inferred content	Index `0` (`[0]`)	`recall_preferences`
Knowledge	Ingested documents, files, and app sources	Index `1` (`[1]`)	`full_recall`

A single recall call hits one store. To use both in one prompt, call the matching endpoint for each and merge the results. When graph_context is enabled, recall also traverses the context graph - a graph of relationships between stored context that HydraDB derives automatically from your data - so related material that pure similarity would miss can come back with the result.

2. When to use Recall

Use recall when you need:

Grounded answers from documents or app sources
Personalized responses for a specific user
Context-aware retrieval across multiple sources
Deterministic metadata filtering combined with semantic search

Reach for something else when:

You need the full document, not ranked chunks → use /fetch/content.

3. Types of Recall

HydraDB exposes three endpoints under /recall/*. Pick one based on what you need back.

Endpoint	Searches	Returns	Use when
`POST /recall/full_recall`	Knowledge	`RetrievalResult`	You need facts from documents
`POST /recall/recall_preferences`	Memories	`RetrievalResult`	You need user-specific context
`POST /recall/boolean_recall`	Knowledge or Memories (`search_mode`)	`RetrievalResult`	You need exact term, AND, or phrase matching

full_recall and recall_preferences share the same request and response shape (RecallSearchRequest → RetrievalResult). boolean_recall accepts a smaller set of parameters and runs deterministic lexical matching - no graph traversal, no metadata filters. To deliver a personalized answer, the canonical pattern is two parallel calls - full_recall for shared Knowledge, recall_preferences for the user’s Memories - merged into a single LLM prompt. See Minimal Working Example.

4. How Recall Works

The semantic recall endpoints (full_recall, recall_preferences) accept a mode:

Mode	Pipeline	Latency
`fast` (default)	Single query	Lower
`thinking`	Multi-query expansion with reranking	Higher

thinking produces higher-quality results by expanding the query into sub-queries and reranking candidates. It also surfaces forceful-relation extras (extra_context_ids and the additional_context map on the response) when matching sources have them. fast skips both steps. boolean_recall has no mode parameter - it always runs deterministic term matching. Rule of thumb. If a human will read the result, use thinking. If a machine will filter it further or low latency is the priority, use fast.

5. Key Parameters

These apply to full_recall and recall_preferences (RecallSearchRequest):

Parameter	Type	Default	Purpose
`tenant_id`	string	- (required)	Tenant identifier - the top-level scoping identifier.
`sub_tenant_id`	string \| null	none	Scopes recall to a user, workspace, or partition. If omitted, HydraDB uses the tenant’s default sub-tenant.
`query`	string	- (required)	Search terms.
`mode`	`"fast"` \| `"thinking"`	`"fast"`	Retrieval pipeline.
`max_results`	integer \| null	server default	Maximum chunks to return. Start with 10.
`alpha`	number \| `"auto"`	`0.8`	Hybrid ranking weight (`0.0` = keyword, `1.0` = semantic).
`recency_bias`	number	`0.0`	Boost for newer content (`0.0`–`1.0`).
`graph_context`	boolean	`false`	Set `true` to populate `graph_context` in the response.
`metadata_filters`	object \| null	`null`	Equality filters on declared, match-enabled metadata fields. Undeclared filters are ignored.
`additional_context`	string \| null	`null`	Extra hint to guide retrieval (e.g. `"User is on the billing page"`).
`search_forceful_relations`	boolean	`true`	Whether to fetch forceful-relation extras. Only takes effect in `"thinking"` mode.

boolean_recall (FullTextSearchRequest) is intentionally narrower:

Parameter	Type	Default	Purpose
`tenant_id`, `sub_tenant_id`, `query`	-	-	As above. `query` and `tenant_id` are required.
`operator`	`"or"` \| `"and"` \| `"phrase"`	`"or"`	How search terms combine.
`max_results`	integer	`10`	Result cap.
`search_mode`	`"sources"` \| `"memories"`	`"sources"`	Which store to search.

It does not accept mode, alpha, recency_bias, graph_context, metadata_filters, or additional_context. If you need any of those, use a semantic endpoint.

graph_context defaults to false - set it to true to receive graph data in the response.
recency_bias defaults to 0 - no recency boost is applied unless you set it.

Top-level filter keys should be defined in tenant_metadata_schema with matching enabled. Undeclared filters are ignored, so plan filterable keys before your first ingestion.

See Create Tenant.

Tuning heuristics

alpha - Start at 0.8. Lower toward 0.3–0.5 when the query contains literal tokens (error codes, SKUs, product names). Raise toward 0.9 for conceptual questions. Use "auto" when the query shape varies.
recency_bias - Leave at 0 for static reference material. Set 0.2–0.4 for mixed content, 0.6–0.8 for changelogs, news, or status updates.
max_results - Start at 10. Drop to 5 for tight context windows; raise to 20 if you rerank downstream.
additional_context - Use it when the query alone is ambiguous. Keep it short and factual.

6. Minimal Working Example

The canonical personalized-answer flow: recall Knowledge, recall the user’s Memories in parallel, merge into one LLM prompt.

Setup

# Set your key as an environment variable - used in every request below
export HYDRA_DB_API_KEY="your_api_key"
# All requests: -H "Authorization: Bearer $HYDRA_DB_API_KEY"

import { HydraDBClient } from "@hydradb/sdk";

const client = new HydraDBClient({
  token: process.env.HYDRA_DB_API_KEY,
});

import os
from hydra_db import HydraDB

client = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])

Recall - Knowledge and Memories in parallel

# Run both in parallel from your shell or application layer

curl -X POST 'https://api.hydradb.com/recall/full_recall' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme_corp",
    "query": "How do I reset my password?",
    "mode": "thinking",
    "max_results": 5,
    "graph_context": true
  }'

curl -X POST 'https://api.hydradb.com/recall/recall_preferences' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme_corp",
    "sub_tenant_id": "user_john_123",
    "query": "answer style and tone preferences",
    "mode": "thinking",
    "max_results": 3
  }'

async function gatherContext(
  tenantId: string,
  userId: string,
  query: string,
) {
  const [knowledge, memories] = await Promise.all([
    client.recall.fullRecall({
      tenant_id: tenantId,
      query,
      mode: "thinking",
      max_results: 5,
      graph_context: true,
    }),
    client.recall.recallPreferences({
      tenant_id: tenantId,
      sub_tenant_id: userId,
      query: "answer style and tone preferences",
      mode: "thinking",
      max_results: 3,
    }),
  ]);
  return { knowledge, memories };
}

import asyncio
from hydra_db import AsyncHydraDB

async_client = AsyncHydraDB(token=os.environ["HYDRA_DB_API_KEY"])

async def gather_context(tenant_id: str, user_id: str, query: str):
    knowledge, memories = await asyncio.gather(
        async_client.recall.full_recall(
            tenant_id=tenant_id,
            query=query,
            mode="thinking",
            max_results=5,
            graph_context=True,
        ),
        async_client.recall.recall_preferences(
            tenant_id=tenant_id,
            sub_tenant_id=user_id,
            query="answer style and tone preferences",
            mode="thinking",
            max_results=3,
        ),
    )
    return knowledge, memories

Merge into the LLM prompt

Both calls return the same shape: chunks[], sources[], and (when applicable) graph_context and additional_context. Format each into a context string - the helper in How to Use API Results does this - and feed both into your prompt:

const knowledgeCtx = buildContextString(knowledge);
const memoryCtx = buildContextString(memories);

const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "system",
      content: "Answer using only the provided context. Match the user's preferred style.",
    },
    {
      role: "user",
      content: `User preferences:\n${memoryCtx}\n\nRelevant docs:\n${knowledgeCtx}\n\nQuestion: How do I reset my password?`,
    },
  ],
});

Production checklist

Parallelize the two recall calls - they’re independent.
Set per-call timeouts. Generous for thinking (3–5s), tight for fast (≤500ms).
Degrade gracefully. If memory recall fails or times out, continue with Knowledge only.
Pass additional_context with known session state (page, feature, role). It can sharpen retrieval without requiring additional calls.

7. Common Mistakes

Symptom	Cause	Fix
Empty `query_paths` / `chunk_relations`	`graph_context` not set, or no relations exist for the result set	Set `graph_context: true`; empty arrays are normal when there’s nothing to return.
Recent uploads don’t appear	Indexing not finished	Poll `/ingestion/verify_processing` - chunks are invisible until processing completes.
`metadata_filters` does not narrow results	Filter key is undeclared or not match-enabled	Declare filterable keys in `tenant_metadata_schema` with `enable_match: true` before ingestion.
Memories missing from `full_recall` (or vice versa)	Knowledge and Memories are separate stores	Call both endpoints and merge.
Recency doesn’t seem to matter	`recency_bias` defaults to `0`	Set it explicitly between `0.1` and `1.0`.
`400` / `422` on `boolean_recall` with `alpha`, `mode`, or `graph_context`	Boolean recall doesn’t accept those parameters	Drop them, or switch to a semantic endpoint.

8. Advanced Patterns

Hybrid: boolean_recall + full_recall. When a query mixes a literal token (error code, SKU, function name) with natural-language intent, run both, dedupe by chunk_uuid, and treat boolean hits as a “must include” floor. Recall-then-rerank. Request more chunks than you need (max_results: 20), then apply your own reranker - recency windows, compliance filters, business rules - before picking the final top-k for the prompt.

Memories - user-scoped dynamic context
Knowledge - shared document context
Metadata - designing filterable fields
Context Graphs - how graph traversal enriches recall
How to Use API Results - turning RetrievalResult into an LLM prompt

Get Started

Essentials

Plugins

For Agents

1. What is Recall

2. When to use Recall

3. Types of Recall

4. How Recall Works

5. Key Parameters

Tuning heuristics

6. Minimal Working Example

Setup

Recall - Knowledge and Memories in parallel

Merge into the LLM prompt

Production checklist

7. Common Mistakes

8. Advanced Patterns

​1. What is Recall

​2. When to use Recall

​3. Types of Recall

​4. How Recall Works

​5. Key Parameters

​Tuning heuristics

​6. Minimal Working Example

​Setup

​Recall - Knowledge and Memories in parallel

​Merge into the LLM prompt

​Production checklist

​7. Common Mistakes

​8. Advanced Patterns

​Related

1. What is Recall

2. When to use Recall

3. Types of Recall

4. How Recall Works

5. Key Parameters

Tuning heuristics

6. Minimal Working Example

Setup

Recall - Knowledge and Memories in parallel

Merge into the LLM prompt

Production checklist

7. Common Mistakes

8. Advanced Patterns

Related