How to Use API Results

A recall response is structured JSON. Your model wants prose. This page shows how to bridge that gap - turning a RetrievalResult into a clean, grounded prompt for an LLM. The same pattern works for full_recall, recall_preferences, and combinations of the two.

1. What you get back

The retrieval endpoints (full_recall and recall_preferences) return the same core response shape:

{
  "chunks": [
    {
      "chunk_uuid": "doc-001_chunk_0",
      "source_title": "my_document.pdf",
      "chunk_content": "Text content of the retrieved chunk...",
      "relevancy_score": 1.09,
      "extra_context_ids": ["ctx-id-1"],
      "additional_metadata": { ... }
    }
  ],
  "graph_context": {
    "query_paths": [
      {
        "triplets": [
          {
            "source": { "name": "EntityA" },
            "target": { "name": "EntityB" },
            "relation": {
              "canonical_predicate": "DEPENDS_ON",
              "context": "reason text",
              "temporal_details": "2024-01"
            }
          }
        ]
      }
    ],
    "chunk_id_to_group_ids": {
      "doc-001_chunk_0": ["group-1"]
    },
    "chunk_relations": [
      {
        "group_id": "group-1",
        "triplets": [ ... ]
      }
    ]
  },
  "additional_context": {
    "ctx-id-1": {
      "source_title": "related_doc.pdf",
      "chunk_content": "Extra related content..."
    }
  }
}

Four things matter for prompt construction:

chunks - the primary retrieval output. Ranked by relevance; preserve the order HydraDB returns.
graph_context.query_paths - entity traversal paths derived from your query. Useful for relational reasoning. See Context Graphs.
graph_context.chunk_relations + chunk_id_to_group_ids - per-chunk graph relations grouped by group_id, so you can attach the right triplets to each chunk.
additional_context - a map keyed by chunk_uuid. When a chunk includes extra_context_ids, use those IDs to look up related chunks here.

Don’t pass the raw object to the LLM. Convert it into a structured context string first.

2. Transforming the response into LLM context

The helper below takes a RetrievalResult and produces a single string with:

Entity paths from graph_context.query_paths (when present)
Ranked chunks in server order, each preceded by Source: <title>
Graph relations per chunk, matched via chunk_id_to_group_ids → chunk_relations
Extra context for any extra_context_ids attached to a chunk

The output is delimited by === ENTITY PATHS === and === CONTEXT === blocks so the LLM can read it cleanly. First, call the recall endpoint with the parameters you need:

Python
TypeScript

import httpx

response = httpx.post(
    "https://api.hydradb.com/recall/full_recall",
    headers={"Authorization": "Bearer YOUR_HYDRA_DB_API_KEY"},
    json={
        "tenant_id": "your-tenant",
        "sub_tenant_id": "your-sub-tenant",
        "query": "How does authentication work?",
        "max_results": 5,
        "mode": "fast",
        "alpha": 0.8,
        "recency_bias": 0,
        "graph_context": True,
        "search_forceful_relations": True,
        "metadata_filters": {
            "category": "engineering",
        },
    }
)

result = response.json()

const res = await fetch("https://api.hydradb.com/recall/full_recall", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_HYDRA_DB_API_KEY",
  },
  body: JSON.stringify({
    tenant_id: "your-tenant",
    sub_tenant_id: "your-sub-tenant",
    query: "How does authentication work?",
    max_results: 5,
    mode: "fast",
    alpha: 0.8,
    recency_bias: 0,
    graph_context: true,
    search_forceful_relations: true,
    metadata_filters: {
      category: "engineering",
    },
  }),
});

const result = await res.json();

Then pass the response into the helper below to build a context string:

# build_context_string is a client-side utility that converts the data
# returned by /recall/full_recall or /recall/recall_preferences into a
# formatted context string.
#
# The logic remains the same, except that recall objects are now dictionaries
# instead of JSON objects.
#
# SDKs access values using dot notation (result.xyz), whereas API responses
# use dictionary access (result.get("xyz")).

export interface VectorStoreChunk {
  chunk_uuid: string;
  source_id: string;
  chunk_content: string;
  source_type: string;
  source_upload_time: string;
  source_title: string;
  source_last_updated_time: string;
  layout: string | null;
  relevancy_score: number | null;
  additional_metadata: Record<string, unknown> | null;
  metadata: Record<string, unknown> | null;
  extra_context_ids: string[] | null;
}

export interface Entity {
  name: string;
  type: string;
  namespace: string;
  entity_id: string;
  identifier: string | null;
}

export interface RelationEvidence {
  canonical_predicate: string;
  raw_predicate: string;
  context: string;
  confidence: number;
  temporal_details: string | null;
  timestamp: string;
  relationship_id: string;
  chunk_id: string | null;
  source_entity_id: string | null;
  target_entity_id: string | null;
}

export interface PathTriplet {
  source: Entity;
  relation: RelationEvidence;
  target: Entity;
}

export interface ScoredPathResponse {
  triplets: PathTriplet[];
  relevancy_score: number;
  combined_context: string | null;
  group_id: string | null;
  source_chunk_ids: string[] | null;
}

export interface GraphContext {
  query_paths: ScoredPathResponse[];
  chunk_relations: ScoredPathResponse[];
  chunk_id_to_group_ids: Record<string, string[]>;
}

export interface SourceInfo {
  id: string;
  title: string;
  type: string;
  description: string;
  url: string;
  timestamp: string;
  metadata: Record<string, unknown>;
  additional_metadata: Record<string, unknown>;
}

export interface RetrievalResult {
  chunks: VectorStoreChunk[];
  sources: SourceInfo[];
  graph_context: GraphContext;
  additional_context: Record<string, VectorStoreChunk>;
}

function formatPathChain(path: ScoredPathResponse): string {
  return path.triplets
    .map((t) => {
      let str = `[${t.source.name}] -> ${t.relation.canonical_predicate} -> [${t.target.name}]`;
      if (t.relation.context) str += `: ${t.relation.context}`;
      if (t.relation.temporal_details) str += ` [Time: ${t.relation.temporal_details}]`;
      return str;
    })
    .join("\n  ↳ ");
}

export function buildContextString(result: RetrievalResult): string {
  const lines: string[] = [];
  const gc = result.graph_context;

  // --- Entity paths -----------------------------------------------------------
  if (gc?.query_paths?.length) {
    lines.push("=== ENTITY PATHS ===");
    for (const path of gc.query_paths) {
      lines.push(formatPathChain(path));
    }
    lines.push("");
  }

  // --- Chunks -----------------------------------------------------------------
  if (result.chunks?.length) {
    lines.push("=== CONTEXT ===");
    for (let i = 0; i < result.chunks.length; i++) {
      const chunk = result.chunks[i];
      lines.push(`Chunk ${i + 1}`);
      lines.push(`Source: ${chunk.source_title}`);
      lines.push(chunk.chunk_content);

      // Graph relations for this chunk
      if (gc?.chunk_id_to_group_ids && gc.chunk_relations) {
        const groupIds = gc.chunk_id_to_group_ids[chunk.chunk_uuid] || [];
        const relations = gc.chunk_relations.filter(
          (r) => r.group_id && groupIds.includes(r.group_id)
        );
        if (relations.length) {
          lines.push("Graph Relations:");
          for (const rel of relations) {
            for (const t of rel.triplets) {
              let line = `  [${t.source.name}] -> ${t.relation.canonical_predicate} -> [${t.target.name}]: ${t.relation.context}`;
              if (t.relation.temporal_details) line += ` [Time: ${t.relation.temporal_details}]`;
              lines.push(line);
            }
          }
        }
      }

      // Extra context
      if (chunk.extra_context_ids?.length && result.additional_context) {
        const extras = chunk.extra_context_ids
          .map((id) => result.additional_context[id])
          .filter(Boolean);
        if (extras.length) {
          lines.push("Extra Context:");
          for (const extra of extras) {
            lines.push(`  Related Context (${extra.source_title}): ${extra.chunk_content}`);
          }
        }
      }

      lines.push("---");
      lines.push("");
    }
  }

  return lines.join("\n");
}

from __future__ import annotations

from typing import Any


def _format_path_chain(path: Any) -> str:
    """Format a ScoredPathResponse into a readable chain string.

    Each triplet becomes: [src] -> predicate -> [tgt]: context [Time: ...]
    Multiple triplets are joined with ↳ to show traversal direction.
    """
    triplets = getattr(path, "triplets", None) or []
    parts = []
    for t in triplets:
        src  = t.source.name if t.source else ""
        tgt  = t.target.name if t.target else ""
        rel  = t.relation
        pred = rel.canonical_predicate if rel else ""
        line = f"[{src}] -> {pred} -> [{tgt}]"
        ctx  = rel.context if rel else None
        if ctx:
            line += f": {ctx}"
        temporal = rel.temporal_details if rel else None
        if temporal:
            line += f" [Time: {temporal}]"
        parts.append(line)

    return "\n  ↳ ".join(parts)


def build_context_string(result) -> str:
    """
    Build a formatted context string from a HydraDB full_recall response.

    Combines entity paths, chunk content, graph relations, and extra context
    into a single readable string ready to pass into an LLM prompt.
    """
    lines: list[str] = []
    gc = result.graph_context

    # --- Entity paths -----------------------------------------------------------
    query_paths = gc.query_paths if gc else []
    if query_paths:
        lines.append("=== ENTITY PATHS ===")
        for path in query_paths:
            lines.append(_format_path_chain(path))
        lines.append("")

    # --- Chunks -----------------------------------------------------------------
    chunks = result.chunks or []
    additional_context = result.additional_context or {}
    chunk_id_to_group_ids = gc.chunk_id_to_group_ids if gc else {}
    chunk_relations = gc.chunk_relations if gc else []

    if chunks:
        lines.append("=== CONTEXT ===")
        for i, chunk in enumerate(chunks):
            lines.append(f"Chunk {i + 1}")
            source = chunk.source_title or ""
            if source:
                lines.append(f"Source: {source}")
            lines.append(chunk.chunk_content or "")

            # Graph relations for this chunk
            chunk_uuid = chunk.chunk_uuid or ""
            if chunk_uuid and chunk_id_to_group_ids and chunk_relations:
                group_ids = chunk_id_to_group_ids.get(chunk_uuid, [])
                relevant_relations = [
                    r for r in chunk_relations
                    if r.group_id in group_ids
                ]
                if relevant_relations:
                    lines.append("Graph Relations:")
                    for rel in relevant_relations:
                        for triplet in (rel.triplets or []):
                            src  = triplet.source.name if triplet.source else ""
                            tgt  = triplet.target.name if triplet.target else ""
                            pred = triplet.relation.canonical_predicate if triplet.relation else ""
                            ctx  = triplet.relation.context if triplet.relation else ""
                            line = f"  [{src}] -> {pred} -> [{tgt}]: {ctx}"
                            temporal = triplet.relation.temporal_details if triplet.relation else None
                            if temporal:
                                line += f" [Time: {temporal}]"
                            lines.append(line)

            # Extra context
            extra_ids = getattr(chunk, "extra_context_ids", None) or []
            if extra_ids and additional_context:
                extras = [
                    additional_context[eid]
                    for eid in extra_ids
                    if eid in additional_context
                ]
                if extras:
                    lines.append("Extra Context:")
                    for extra in extras:
                        extra_source = extra.source_title or ""
                        extra_content = extra.chunk_content or ""
                        lines.append(f"  Related Context ({extra_source}): {extra_content}")

            lines.append("---")
            lines.append("")

    return "\n".join(lines)

3. Feeding the context into your LLM

Once you have a context string, call your model with a grounded system prompt:

# HydraDB does not wrap LLM calls. Pass your context string to any LLM provider.
# Example using OpenAI's chat completions endpoint directly:
curl -X POST 'https://api.openai.com/v1/chat/completions' \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "Answer the user'\''s question using only the context below. If the answer is not in the context, say you don'\''t know."
      },
      {
        "role": "user",
        "content": "Context:\n<your_context_string>\n\nQuestion: <your_question>"
      }
    ]
  }'

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_OPENAI_API_KEY" });
const question = "How does authentication work?";

const completion = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [
    {
      role: "system",
      content:
        "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
    },
    {
      role: "user",
      content: `Context:\n${context}\n\nQuestion: ${question}`,
    },
  ],
});

console.log(completion.choices[0].message.content);

from openai import OpenAI

client = OpenAI(api_key="YOUR_OPENAI_API_KEY")
question = "How does authentication work?"

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {
            "role": "system",
            "content": "You are a helpful assistant. Answer the user's question using only the context provided. If the answer is not in the context, say you don't know.",
        },
        {
            "role": "user",
            "content": f"Context:\n{context}\n\nQuestion: {question}",
        },
    ],
)

print(completion.choices[0].message.content)

4. Combining Knowledge and Memories

For personalised answers, run full_recall and recall_preferences in parallel, format each result, and combine them into one prompt. There’s no required ordering - preferences before docs is purely for readability.

# Combine both recall results in your application layer.
# 1. Run full_recall for Knowledge:
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": "refund policy", "mode": "thinking"}'

# 2. Run recall_preferences for Memories:
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_123", "query": "answer style preferences"}'

# 3. Merge both context strings in your application before prompting the LLM.

const memoryCtx = buildContextString(memoryResult);
const knowledgeCtx = buildContextString(knowledgeResult);

const prompt =
  `User preferences:\n${memoryCtx}\n\n` +
  `Relevant docs:\n${knowledgeCtx}\n\n` +
  `Question: ${question}`;

memory_ctx = build_context_string(memory_result)
knowledge_ctx = build_context_string(knowledge_result)

prompt = (
    f"User preferences:\n{memory_ctx}\n\n"
    f"Relevant docs:\n{knowledge_ctx}\n\n"
    f"Question: {question}"
)

If memory recall fails or times out, fall back to the Knowledge-only prompt - personalisation is an enhancement, not a hard dependency.

5. Practical guidance

Preserve server order. Don’t re-sort chunks client-side.
Start small on chunks. max_results: 10 is a reasonable default. Drop to 5 if you hit token limits, raise to 20 if you rerank downstream.
Use graph context selectively. It improves relational queries and bloats simple lookups. See Context Graphs.
Always ground the model. A system prompt like “answer only from the provided context” prevents the model from inventing answers when retrieval is thin.
Format consistently. Whatever section delimiters you choose (=== CONTEXT ===, Chunk N, Source:), keep them stable across calls so the model learns the structure.

6. Common mistakes

Mistake	What goes wrong	Fix
Passing the raw result object to the LLM	Wastes tokens on IDs and metadata; the model struggles to read the content	Format into a context string first.
Ignoring Memories when personalisation matters	Answers feel generic	Call `recall_preferences` and include it in the prompt.
Including too many chunks	Token overflow or answer quality drops	Start at `max_results: 10`; reduce if needed.
Re-sorting chunks client-side	Overrides HydraDB’s ranking	Preserve the server-returned order.
Missing a grounding instruction	The model invents answers when context is thin	System prompt: answer only from the provided context.
Expecting graph fields without requesting them	Graph context will not be populated	Set `graph_context: true` on the recall call.
Looking up `chunk_relations` without `chunk_id_to_group_ids`	The right relations don’t attach to the right chunk	Use `chunk_id_to_group_ids[chunk_uuid]` to find the `group_id`s, then filter `chunk_relations` by them.

Recall - request parameters and response shape
Memories - what recall_preferences searches
Knowledge - what full_recall searches
Context Graphs - what graph_context fields contain

Get Started

Essentials

Plugins

For Agents

How to Use API Results

1. What you get back

2. Transforming the response into LLM context

3. Feeding the context into your LLM

4. Combining Knowledge and Memories

5. Practical guidance

6. Common mistakes

​1. What you get back

​2. Transforming the response into LLM context

​3. Feeding the context into your LLM

​4. Combining Knowledge and Memories

​5. Practical guidance

​6. Common mistakes

​Related

1. What you get back

2. Transforming the response into LLM context

3. Feeding the context into your LLM

4. Combining Knowledge and Memories

5. Practical guidance

6. Common mistakes

Related