Knowledge & Memory

Orq.ai provides three approaches to backing an agent with persistent knowledge:

Knowledge Bases

Upload and index documents for retrieval-augmented generation. Ground model responses in your domain data.

External Knowledge Bases

Connect your own vector database via a standard API. Keep data management on your infrastructure.

Memory Stores

Entity-scoped long-term memory that persists across sessions. Enables personalization and context continuity.

All three can be attached to an Agent to build richer, context-aware experiences:

Connect Knowledge Bases to Agents

Attach a Knowledge Base so the agent queries it automatically when relevant.

Connect Memory Stores to Agents

Give the agent persistent per-entity memory across conversations.

Use-cases

All three solutions store information that an agent can retrieve, but they serve different purposes depending on where the data lives and how it changes. Knowledge Bases index documents you upload into Orq.ai. The platform handles embeddings, chunking, and retrieval. Use them when you have documents to ingest and want a fully managed RAG pipeline. External Knowledge Bases connect to a vector database you already operate. Orq.ai calls your API at query time and passes the results to the model. Use them when your data cannot leave your infrastructure, or when you already have an embedding pipeline. Memory Stores store arbitrary text per entity, such as a user or session. Documents accumulate over time and are retrieved semantically on each interaction. Use them when your agent needs to remember what a specific person said or did in a previous conversation.

	Knowledge Base	External Knowledge Base	Memory Store
Data hosted by	Orq.ai	Your infrastructure	Orq.ai
Document upload	Via Studio or API	Managed externally	Via API per entity
Embeddings	Managed by Orq.ai	Managed externally	Managed by Orq.ai
Search config	Full control	Delegated to your API	Automatic
Reranking	Supported	Post-processing	Not applicable
Agentic RAG	Supported	Supported	Not applicable
Metadata filtering	Full support	Depends on your API	Via entity metadata
Scoped per entity	No	No	Yes
Persists across sessions	Yes (static content)	Yes (static content)	Yes (accumulates over time)
Best for	Domain documents, FAQs, policies	Existing vector DBs	User history, preferences, session state

Knowledge Bases

A Knowledge Base is a database that provides relevant, specific information for an LLM to retrieve at query time. Knowledge can include domain-specific or business-specific information, ensuring the details surfaced to models are both correct and accurate.

Create a Knowledge Base

AI Studio
API & SDK

Use the button in a chosen Project and select Knowledge Base > Internal.Press Create Knowledge. The following modal appears:

Enter a unique Key used to reference your Knowledge Base within Prompts and Deployments. Choose an Embedding Model for knowledge search.

You can only create a Knowledge Base once you have activated an embedding model within the AI Gateway.

Use the Create a Knowledge API.Required inputs:

key: the name used to reference the Knowledge Base
embedding_model: formatted as supplier/model_name, for example cohere/embed-english-v3.0. Find embedding models in the AI Gateway by filtering for Model Type = Embedding.
path: the Project and folder, formatted as project/path, for example Default/Production

curl --request POST \
     --url https://api.orq.ai/v2/knowledge \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --data '
{
  "key": "<key>",
  "embedding_model": "<model>",
  "path": "<path>",
  "type": "internal"
}
'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create(request={
        "key": "key",
        "embedding_model": "supplier/model",
        "path": "project/path",
        "type": "internal"
    })

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.create({
  key: "key",
  embeddingModel: "supplier/model",
  path: "project/path",
  type: "internal",
});

console.log(result);

Save the knowledge_id returned from the response.

Datasource and Chunking

A source represents a document loaded within the Knowledge Base. Documents are parsed and split into chunks that models search and retrieve at query time.

Create a Datasource

AI Studio
API & SDK

Select Add Source to upload a document. Supported formats: TXT, PDF, DOCX, CSV, XML.

Datasources list view showing uploaded datasources with their processing status and an Add Datasource button.

A single source document must be a maximum of 10MB.

Once your document has been processed, the following summary is displayed:

See details of the data parsed into your Knowledge Base and estimate the cost of retrieval.

The most common workflow is uploading a file before creating a datasource. Use the Upload a file API.

The maximum file size is 10MB.

curl --request POST \
     --url https://api.orq.ai/v2/files \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: multipart/form-data' \
     --form file='@file_path'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.files.create(file={
        "file_name": "example.file",
        "content": open("example.file", "rb"),
    })

    print(res)

import { Orq } from "@orq-ai/node";
import { openAsBlob } from "node:fs";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.files.create({
  file: await openAsBlob("example.file"),
});

console.log(result);

Save the file_id returned from the response, then create a datasource with the Create a datasource API.Required fields: knowledge_id, display_name, and optionally file_id to pre-populate the datasource.

curl --request POST \
     --url https://api.orq.ai/v2/knowledge/knowledge_id/datasources \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "display_name": "name",
  "file_id": "file_id"
}
'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create_datasource(knowledge_id="knowledge_id",
                                          file_id="file_id",
                                          display_name="name")

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.createDatasource({
  knowledgeId: "knowledge_id",
  requestBody: {
    displayName: "name",
    fileId: "file_id",
  },
});

console.log(result);

Save the datasource_id returned from the response.

Add Chunks to a Datasource

API & SDK

Use the Create chunk API to manually add chunks to a datasource.

curl --request POST \
   --url https://api.orq.ai/v2/knowledge/<knowledge_id>/datasources/<datasource_id>/chunks \
   --header 'accept: application/json' \
   --header 'authorization: Bearer <API_KEY>' \
   --header 'content-type: application/json' \
   --data '
[
  {
    "text": "Your chunk content here.",
    "metadata": {
      "source": "manual",
      "topic": "example"
    }
  }
]
'

from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    res = orq.knowledge.create_chunks(
        knowledge_id="<knowledge_id>",
        datasource_id="<datasource_id>",
        request_body=[{
            "text": "Your chunk content here.",
            "metadata": {
                "source": "manual",
                "topic": "example"
            }
        }]
    )

import { Orq } from "@orq-ai/node";

const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] ?? "" });

await orq.knowledge.createChunks({
  knowledgeId: "<knowledge_id>",
  datasourceId: "<datasource_id>",
  requestBody: [{
    text: "Your chunk content here.",
    metadata: {
      source: "manual",
      topic: "example",
    },
  }],
});

View Datasource Chunks

API & SDK

Use the List all chunks API to inspect chunks in a datasource.

curl --request GET \
     --url https://api.orq.ai/v2/knowledge/<knowledge_id>/datasources/<datasource_id>/chunks \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.list_chunks(knowledge_id="<id>", datasource_id="<id>", status="completed")

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.listChunks({
  knowledgeId: "<id>",
  datasourceId: "<id>",
  status: "completed",
});

console.log(result);

Chunk Strategy

AI Studio
API & SDK

When using the AI Studio, you only have access to the following chunk strategies. For more options, see the API & SDK tab.

Choose a chunking option when uploading a file in the Knowledge Base

Default

Automatically set chunk and preprocessing rules. Recommended for unfamiliar users.

Advanced

Maximum Chunk Length: Defines the maximum size of each chunk. Larger size means more information per chunk.Chunk Overlap: Defines the number of characters overlapping neighboring chunks. Higher values increase redundancy between chunks but improve the likelihood that relevant information is returned to models.

Use the sidebar to preview chunks using the chosen chunking strategy.

Use the Chunking API to prepare content for datasource ingestion before adding chunks manually.Common parameters:

text (required): the text content to chunk
strategy (required): token, sentence, recursive, semantic, or agentic
metadata (optional, default: true): include metadata per chunk (start_index, end_index, token_count)
return_type (optional, default: "chunks"): "chunks" (with metadata) or "texts" (plain strings)

curl --request POST \
     --url https://api.orq.ai/v2/chunking \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ORQ_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "strategy": "semantic",
  "text": "Your text content here...",
  "chunk_size": 55,
  "embedding_model": "openai/text-embedding-3-small"
}
'

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.chunking.parse({
  text: "Your text content here...",
  metadata: true,
  strategy: "semantic",
  chunkSize: 256,
  threshold: 0.8,
  embeddingModel: "openai/text-embedding-3-small",
  mode: "window",
  similarityWindow: 1,
});

console.log(result);

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.chunking.parse(request={
        "text": "Your text content here...",
        "metadata": True,
        "strategy": "semantic",
        "chunk_size": 256,
        "threshold": 0.8,
        "embedding_model": "openai/text-embedding-3-small",
        "mode": "window",
        "similarity_window": 1,
    })

    print(res)

The response returns a chunks array. Each chunk contains id, text, index, and optional metadata (start_index, end_index, token_count).

Chunks can be then uploaded to an existing Datasource using the Add Chunk to Datasource API.

Chunk Settings and StrategiesLarger chunks hold more information but increase token use and generation cost.

Token

Splits text into chunks based on token count. Best for ensuring chunks fit within LLM context windows and maintaining consistent chunk sizes for embedding models.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`chunk_overlap`	Number of tokens to overlap between chunks	0

Sentence

Splits text at sentence boundaries while respecting token limits. Ideal for maintaining semantic coherence and readability.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`chunk_overlap`	Number of overlapping tokens between chunks	0
`min_sentences_per_chunk`	Minimum number of sentences per chunk	1

Recursive

Recursively splits text using a hierarchy of separators (paragraphs, sentences, words). Versatile general-purpose chunker that preserves document structure.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`separators`	Hierarchy of separators to use	`["\n\n", "\n", " ", ""]`
`min_characters_per_chunk`	Minimum characters allowed per chunk	24

Semantic

Groups semantically similar sentences using embeddings. Excellent for maintaining topic coherence and context within chunks.

Parameter	Description	Default
`chunk_size`	Maximum tokens per chunk	512
`embedding_model`	Embedding model for similarity (required)	-
`dimensions`	Number of dimensions for embedding output	-
`threshold`	Similarity threshold (0-1) or “auto"	"auto”
`mode`	Chunking mode: “window” or “sentence"	"window”
`similarity_window`	Window size for similarity comparison	1

Agentic

AI-powered intelligent chunking that uses an LLM to determine optimal split points. Best for complex documents requiring intelligent segmentation.

Parameter	Description	Default
`model`	LLM model to use for chunking (required)	-
`chunk_size`	Maximum tokens per chunk	1024
`candidate_size`	Size of candidate splits for LLM evaluation	128
`min_characters_per_chunk`	Minimum characters allowed per chunk	24

Fast

High-performance SIMD-optimized byte-level chunking. Best for large files (>1MB) where speed and memory efficiency are critical. 2x faster and 3x less memory than token-based chunking.

Parameter	Description	Default
`target_size`	Target chunk size in bytes	4096
`delimiters`	Single-byte delimiters to split on (e.g., `"\n.?!"`)	`"\n.?"`
`pattern`	Multi-byte pattern for splitting (e.g., `"▁"` for SentencePiece)	-
`prefix`	Attach delimiter to start of next chunk	false
`consecutive`	Split at START of consecutive delimiter runs	false
`forward_fallback`	Search forward if no delimiter found backward	false

When to use Fast: Large files (>1MB), high-throughput ingestion, memory-constrained environments.When NOT to use Fast: When you need precise token counts for embedding models, small documents where speed isn’t critical, or when semantic boundaries matter more than byte boundaries.

Strategy Selection Guide

Use Case	Recommended Strategy
Large files (>1MB)	Fast: 2x faster, 3x less memory
RAG with precise tokens	Token or Recursive
Semantic search	Semantic
Complex document understanding	Agentic
General purpose	Recursive

Chunk Metadata

Each chunk in a Knowledge Base can carry a metadata object: a set of key-value pairs that describe the chunk’s origin, topic, or any custom attribute relevant to your use case. Metadata lets you store all your content in a single Knowledge Base while still scoping retrieval to exactly the right subset of chunks at query time. Common use cases:

Multi-tenant RAG: tag chunks by client_id to isolate results per customer.
Source filtering: filter by filetype or source to restrict results to PDFs, support tickets, or a specific data feed.
Topic scoping: tag chunks by topic or category and filter queries to stay on a single subject.

AI Studio
API & SDK

Open a chunk from the datasource view to access the Edit Chunk panel. The panel has three sections:

Text: the chunk content.
Metadata: a JSON editor pre-filled with the current metadata, or {} if none has been set.
Enabled: toggle to enable or disable the chunk.

Edit the metadata JSON directly and save. The metadata object must be valid JSON with all values as strings, numbers, or booleans. Nested arrays or objects are not supported.

Pass an optional metadata object when creating chunks. Metadata values must be primitive types: strings, numbers, or booleans.

curl --request POST \
   --url https://api.orq.ai/v2/knowledge/<knowledge_id>/datasources/<datasource_id>/chunks \
   --header 'accept: application/json' \
   --header 'authorization: Bearer <API_KEY>' \
   --header 'content-type: application/json' \
   --data '
[
  {
    "text": "Acme Corp signed a 3-year enterprise contract in Q1 2025.",
    "metadata": {
      "client_id": "acme_corp",
      "source": "contracts",
      "filetype": "pdf",
      "page_number": 3
    }
  }
]
'

from orq_ai_sdk import Orq
import os

with Orq(api_key=os.getenv("ORQ_API_KEY", "")) as orq:
    res = orq.knowledge.create_chunks(
        knowledge_id="<knowledge_id>",
        datasource_id="<datasource_id>",
        request_body=[{
            "text": "Acme Corp signed a 3-year enterprise contract in Q1 2025.",
            "metadata": {
                "client_id": "acme_corp",
                "source": "contracts",
                "filetype": "pdf",
                "page_number": 3
            }
        }]
    )

import { Orq } from "@orq-ai/node";

const orq = new Orq({ apiKey: process.env["ORQ_API_KEY"] ?? "" });

await orq.knowledge.createChunks({
  knowledgeId: "<knowledge_id>",
  datasourceId: "<datasource_id>",
  requestBody: [{
    text: "Acme Corp signed a 3-year enterprise contract in Q1 2025.",
    metadata: {
      client_id: "acme_corp",
      source: "contracts",
      filetype: "pdf",
      page_number: 3,
    },
  }],
});

Metadata constraints:

Use metadata for concise, discrete filter attributes to maximize search performance.
Avoid placing large text blobs in metadata. Long strings result in slower queries.
Keep each field’s data type consistent. Non-coercible values are discarded and omitted from the chunk.

Data and PII Cleanup

AI Studio
API & SDK

Modify the data loaded within your sources to clean or anonymize it. Toggle on each cleanup option within the Data Cleanup panel.

Processing options panel showing seven Data cleanup toggles: Delete email addresses, Delete telephone numbers, Delete credit card numbers, Clean bullet points, Clean numbered list, Clean dashes, and Clean extra whitespaces.

Option	Description
Delete email addresses	Removes email addresses from chunk content
Delete credit card numbers	Removes credit card numbers from chunk content
Delete telephone numbers	Removes phone numbers from chunk content
Clean bullet points	Normalizes bullet point formatting
Clean numbered list	Normalizes numbered list formatting
Clean dashes	Removes or normalizes dash characters
Clean extra whitespaces	Removes excess whitespace from chunk content

Pass chunking_cleanup_options inside chunking_options when creating a datasource to clean or anonymize source content before it is chunked and indexed.

Option	Description
`delete_emails`	Removes email addresses from chunk content
`delete_credit_cards`	Removes credit card numbers from chunk content
`delete_phone_numbers`	Removes phone numbers from chunk content
`clean_bullet_points`	Normalizes bullet point formatting
`clean_numbered_list`	Normalizes numbered list formatting
`clean_unicode`	Removes or normalizes non-standard unicode characters
`clean_dashes`	Removes or normalizes dash characters
`clean_whitespaces`	Removes excess whitespace from chunk content

curl --request POST \
     --url https://api.orq.ai/v2/knowledge/knowledge_id/datasources \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "display_name": "name",
  "file_id": "file_id",
  "chunking_options": {
    "chunking_configuration": {
      "type": "default"
    },
    "chunking_cleanup_options": {
      "delete_emails": true,
      "delete_credit_cards": true,
      "delete_phone_numbers": true,
      "clean_bullet_points": true,
      "clean_numbered_list": true,
      "clean_unicode": true,
      "clean_dashes": true,
      "clean_whitespaces": true
    }
  }
}
'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.knowledge.create_datasource(
        knowledge_id="knowledge_id",
        file_id="file_id",
        display_name="name",
        chunking_options={
            "chunking_configuration": {
                "type": "default"
            },
            "chunking_cleanup_options": {
                "delete_emails": True,
                "delete_credit_cards": True,
                "delete_phone_numbers": True,
                "clean_bullet_points": True,
                "clean_numbered_list": True,
                "clean_unicode": True,
                "clean_dashes": True,
                "clean_whitespaces": True
            }
        }
    )

    print(res)

import { Orq } from "@orq-ai/node";

const orq = new Orq({
  apiKey: process.env["ORQ_API_KEY"] ?? "",
});

const result = await orq.knowledge.createDatasource({
  knowledgeId: "knowledge_id",
  requestBody: {
    displayName: "name",
    fileId: "file_id",
    chunkingOptions: {
      chunkingConfiguration: {
        type: "default",
      },
      chunkingCleanupOptions: {
        deleteEmails: true,
        deleteCreditCards: true,
        deletePhoneNumbers: true,
        cleanBulletPoints: true,
        cleanNumberedList: true,
        cleanUnicode: true,
        cleanDashes: true,
        cleanWhitespaces: true,
      },
    },
  },
});

console.log(result);

Embedding Models

An embedding model is a machine learning tool that transforms complex, high-dimensional data into simpler, numerical values that machines can understand, enabling semantic search. Configure which embedding model to use to query the Knowledge Base from the Knowledge Settings panel.

Agentic RAG

Incorporates AI agents into the RAG pipeline to orchestrate its components and perform additional actions beyond simple information retrieval, overcoming the limitations of a non-agentic pipeline. Enable the Agentic RAG toggle in Knowledge Settings, then select a Model to use. The chosen model drives two actions:

Document Grading: ensures only relevant chunks are retrieved.
Query Refinement: rewrites the query if needed to improve retrieval quality.

Enable Agentic RAG in Knowledge Base Settings. Configure the related model after enabling.

Example: Query Refinement

See the screenshot below on how the input query gets refined.Input query: is my suitcase too big? is reformulated to luggage size requirements and restrictions for carry-on and checked baggage

Search Modes

Different Search modes are available for Information to be found in Knowledge Bases:

Vector Search

Vector search is the fastest method of searching through a database built with your Knowledge Sources. The system takes the user query and looks for the text segments most similar to their vector representations.The search returns the preprocessed chunks from the sources most similar and relevant to the user’s query.

Keyword Search

Keyword Search retrieves relevant results by indexing the entire content and searching for segments containing the words from the user’s query.

Hybrid Search

Hybrid search uses both Vector and Keyword search, then combines results and returns the most relevant chunks to the model.

Search Settings

Chunk limit

Sets the number of chunks most similar to the user’s question to return.

Threshold

Controls the relevance of results on a scale from 0 to 1. Results scoring below the threshold are excluded from retrieval.The closer to 1, the more relevant and narrow the results will be.

Setting too high a threshold can yield little to no results.

Rerank Model

Reranking invokes a model that analyzes your initial query and the results fetched by the Knowledge Base search. The model scores and ranks the chunks by similarity to the user query, ensuring the most relevant results are returned.

To use reranking, you must enable at least one Reranking model within the AI Gateway.

Search a Knowledge Base

Once your Knowledge Base is populated, you can query it in several ways.

AI Studio
API & SDK
MCP

Test via the Studio

Test your Knowledge Base search directly in the AI Studio using the built-in search panel.

Open Knowledge Settings

Navigate to your Knowledge Base and click Knowledge Settings.

Enter your search query

Type your query in the Search query field in the right panel.

View results

Results appear below showing:

Document name (e.g., “Logistics FAQ.docx”)
Relevance score for each chunk (e.g., 0.49, 0.48)
Chunk content preview

Experiment with different search modes and threshold values to find the optimal configuration for your use case. Lower thresholds return more results but may include less relevant chunks.

Integrate to a Deployment

Attach a Knowledge Base to a Deployment to automatically retrieve relevant chunks on every call.

Open the Deployment’s configuration and go to Knowledge Bases.
Select Knowledge Base and choose your Knowledge Base.
Set the query type:
- Last User Message: the user’s latest message is used as the search query automatically.
- Query: use a predefined query. You can make it dynamic with an input variable such as {{query}}.
Reference the retrieved chunks in your prompt with the {{knowledge_base_key}} syntax. If not explicitly referenced, the chunks are appended to the end of the system message.

To learn more, see Using a Knowledge Base in a Deployment.

Integrate to an Agent

Add a Knowledge Base as context to an Agent. Unlike Deployments, the Agent only queries the Knowledge Base when it determines it is necessary, using the query_knowledge_base tool automatically.

In the Agent configuration, go to the Context section and click Add context.
Select your Knowledge Base.
In the Agent’s Instructions, explicitly tell it to use the Knowledge Base. For example:

“First use retrieve_knowledge_bases to see what knowledge sources are available, then use query_knowledge_base to find relevant information before answering.”

The Knowledge Base description must be explicit so the Agent can identify the right source to query.

To learn more, see Knowledge Bases with Agents.

Use in Prompts

To add a Knowledge Base in a Prompt, open the Knowledge Base tab in the Configuration screen and select Add a Knowledge Base.

Select which Knowledge Base to include by clicking on the key. Press Save when done.

Choose whether the Knowledge Base type is Last User Message or Query. This defines how the Knowledge Base will be queried.Use the {{key}} syntax in your prompt, where key is the key of your Knowledge Base.

Your Knowledge Base is correctly referenced when its key appears in blue.

Last User Message: the user message is used as a query to retrieve the relevant chunks.

Playground with the apple knowledge base attached, showing a user question about Apple green bonds and an assistant response citing retrieved context. — An example of using a Knowledge Base in Orq.ai

Query: your predefined query is used to retrieve the relevant chunks.Within a Deployment context, make the query dynamic by using an input variable in the query field.

Use the input variable {{query}} reachable through the invoke call as an input, letting you dynamically define the Knowledge Base query at runtime.

Query a Knowledge Base directly using the Search Knowledge Base API.Basic Search

curl --location 'https://api.orq.ai/v2/knowledge/KNOWLEDGE_BASE_ID/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ORQ_API_KEY' \
--data '{
    "query": "What are the benefits of machine learning?"
}'

from orq_ai_sdk import Orq
import os

client = Orq(api_key=os.getenv("ORQ_API_KEY"))

results = client.knowledge.search(
    knowledge_id="KNOWLEDGE_BASE_ID",
    query="What are the benefits of machine learning?"
)

import { Orq } from '@orq-ai/node';

const orq = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

const results = await orq.knowledge.search({
  knowledgeId: 'KNOWLEDGE_BASE_ID',
  query: 'What are the benefits of machine learning?'
});

Filter by MetadataPass a filter_by object to restrict results to chunks whose metadata matches specified conditions.Supported filter operators (MongoDB-inspired, no $ prefix):

Filter	Description	Example
`eq`	Equal to	`{"page_id": {"eq": "page_x1i2j3"}}`
`ne`	Not equal to	`{"page_id": {"ne": "page_x1i2j3"}}`
`gt`	Greater than	`{"edition": {"gt": 2019}}`
`gte`	Greater than or equal to	`{"edition": {"gte": 2020}}`
`lt`	Less than	`{"edition": {"lt": 2022}}`
`lte`	Less than or equal to	`{"edition": {"lte": 2020}}`
`in`	In array	`{"page_id": {"in": ["a", "b"]}}`
`nin`	Not in array	`{"page_id": {"nin": ["a", "b"]}}`
`and`	Logical AND	`{"and": [{...}, {...}]}`
`or`	Logical OR	`{"or": [{...}, {...}]}`

curl --location 'https://api.orq.ai/v2/knowledge/<knowledge_id>/search' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $ORQ_API_KEY' \
--data '{
    "query": "What are the contract renewal terms?",
    "filter_by": {
        "client_id": { "eq": "acme_corp" },
        "source": { "eq": "contracts" }
    },
    "search_options": {
        "include_metadata": true,
        "include_scores": true
    }
}'

from orq_ai_sdk import Orq
import os

client = Orq(api_key=os.getenv("ORQ_API_KEY"))

client.knowledge.search(
    knowledge_id="<knowledge_id>",
    query="What are the contract renewal terms?",
    filter_by={
        "client_id": {"eq": "acme_corp"},
        "source": {"eq": "contracts"},
    },
    search_options={
        "include_metadata": True,
        "include_scores": True,
    },
)

import { Orq } from '@orq-ai/node';

const orq = new Orq({
  apiKey: process.env['ORQ_API_KEY'] ?? '',
});

orq.knowledge.search({
  knowledgeId: '<knowledge_id>',
  query: 'What are the contract renewal terms?',
  filterBy: {
    client_id: { eq: 'acme_corp' },
    source: { eq: 'contracts' },
  },
  searchOptions: {
    includeMetadata: true,
    includeScores: true,
  },
});

See knowledge base search used end-to-end in a real application. Read our cookbook Multilingual FAQ Bot.

Use the Orq MCP server to find and manage knowledge bases from an AI code assistant.Find an existing knowledge base:

Search for knowledge bases in my workspace

The assistant uses search_entities with type: "knowledge" to locate knowledge bases by name or key.

Delete a knowledge base:

Delete the knowledge base with ID "old-docs"

The assistant uses delete_entity with type: "knowledge" and the knowledge base ID.

See knowledge base retrieval in a complete application. Read our cookbook Multilingual FAQ Bot.

Retrieval Traces and Logs

When using a Knowledge Base within Playground, Experiment, Deployment, or Agent, traces are generated containing details of how Knowledge Bases were accessed.

Traces
Logs

To find Traces, go to the Traces tab in the AI Studio.

Traces show the full breakdown of queries made to the knowledge base, including results and scores

Retrieval Spans show the following:

Query: the query used to retrieve relevant chunks.
Documents: the retrieved chunks, ordered by relevance score.

External Knowledge Bases

To connect to an external Knowledge Base, click the button on the desired Project and select Knowledge Base > External.

Choose External when connecting your Knowledge Base

The following modal opens to configure the external knowledge base.

Connect External Kb — Configuration Modal

Field	Description	Example
Key	Unique identifier, alphanumeric with hyphens/underscores	`external_kb`
Description	Description of the knowledge base	`External Knowledge Base`
Name	Display name	`External Knowledge Base Name`
API URL	URL to search the knowledge base, must be HTTPS	`https://api.example.org/search`
API Key	Authentication API key. Orq.ai will use Bearer Authentication to call your API.	`<API_KEY>`

orq.ai includes the API Key in the Authorization: Bearer <API_KEY> header when calling your endpoint.

API keys are encrypted using workspace-specific keys (AES-256-GCM).

Select Connect to finalize.

API Payloads

Example payloads for the request and response expected from your external API:

Request Payload

{
  "query": "<string>",
  "top_k": 50,
  "threshold": 0.5,
  "filter_by": {},
  "search_options": {
    "include_vectors": true,
    "include_metadata": true,
    "include_scores": true
  },
  "rerank_config": {
    "model": "cohere/rerank-multilingual-v3.0",
    "threshold": 0,
    "top_k": 10
  }
}

Response Payload

{
  "matches": [
    {
      "id": "<string>",
      "text": "<string>",
      "vector": [123],
      "metadata": {},
      "scores": {
        "rerank_score": 123,
        "search_score": 123
      }
    }
  ]
}

The API must respond like a standard Knowledge Base search. See our Search API for the expected payload format.

Example Implementations

Python Implementation

An Example Python Server for External Knowledge Base

Get the Code

Clone the Python example Server

Install Dependencies

pip install -r requirements.txt

Run the Server

uvicorn main:app --reload

Test the API

The API is running at http://localhost:8000Dynamic Documentation is available at http://localhost:8000/docs

Node.js Implementation

An Example Node Server for External Knowledge Base

Get the Code

Clone the Node example Server

Install Dependencies

npm install

Run the Server

npm run dev

Test the API

The API is running at http://localhost:8000Dynamic Documentation is available at http://localhost:8000/doc

Integrate Vector Database Providers

Orq.ai supports providers like Weaviate and Pinecone, as both platforms expose REST APIs that conform to the expected payload format.

Show Weaviate

Configuration in Orq.ai:

API URL: https://your-cluster.weaviate.cloud/v1/graphql
API Key: Your Weaviate API key

Show Pinecone

Configuration in Orq.ai:

API URL: https://$INDEX_HOST/records/namespaces/$NAMESPACE/search
API Key: Your Pinecone API key

Troubleshoot Common Errors

Scenario	Error Message
HTTP instead of HTTPS	”External knowledge base URL must use HTTPS protocol”
Local/private IP	”External knowledge base URL cannot point to local network”
API unreachable	”Failed to verify external knowledge base connectivity”
API timeout (>50s)	“External API request timed out”

Cannot connect to external API

Verify your API endpoint is publicly accessible via HTTPS.
Check your API logs for incoming requests from orq.ai IP addresses.
Verify your firewall/security groups allow inbound HTTPS traffic.

API key authentication failing

Verify the API key is correct and has not expired.
Check that your API expects Bearer authentication in the Authorization header.
Confirm your API key has the necessary permissions to perform searches.

No results returned or poor quality results

Verify your API returns the expected response format (see Response Payload above).
Check that scores.search_score values are between 0 and 1.
Test with different threshold values (lower threshold = more results).
If using reranking, ensure both search_score and rerank_score are provided.
Verify your external vector database has sufficient indexed documents.

Slow response times

Monitor your external API response times.
Consider implementing caching for frequently searched queries.
Optimize your vector database indexes.
Check if your external API is rate limiting requests.

Configure your External Knowledge Base

Datasource configuration is not accessible within External Knowledge Bases, as data is hosted outside of Orq.ai.

The available configurations are:

Agentic RAG
Search retrieval parameters: Chunk Limit, Search Threshold
Rerank Model

For detailed configuration options, see Embedding Models, Agentic RAG, Search Modes, and Rerank Model above. All settings apply to both internal and external Knowledge Bases.

Your External Knowledge Base is connected:

Use it just like any other Knowledge Base. See Search a Knowledge Base.
Your knowledge base can also be used with Agents. See Connect Knowledge Bases.
Your API is called at runtime when the model needs to perform a search.

Memory Stores

Memory Stores provide persistent storage for agent memories, allowing agents to retain and retrieve information across conversations and sessions. Unlike Knowledge Bases, Memory Stores are entity-scoped: each Memory within a store is tied to a specific entity (a user, session, or any object you define), enabling personalized, per-entity recall. Only long-term memory is currently supported: stored information persists indefinitely with no automatic expiration. To use a Memory Store with an Agent, see Connect Memory Stores.

Architecture

Concept	Description
Memory Store	Top-level container organizing all memories for a use case
Memory	An entity within the store (e.g., a specific user, customer, or session)
Memory Document	The actual content item stored within a Memory, embedded for semantic search

Create a Memory Store

AI Studio
API & SDK

Head to a Project, use the button, and select Knowledge > Memory Store.

Creating Memory Stores — Select Knowledge > Memory Store.

The following modal opens:

Memory Store Create — Enter the Memory Store information.

Ensure the description is thorough, as Agents use it to identify the correct Memory Store:

Good example: “Customer communication preferences, contact times, and support tier information for personalized outreach”
Bad example: “Customer data”

Show Example Agent instruction

When a customer shares their communication preferences or contact information:

Extract key details (preferred contact method, time windows, support tier)
Store in the “customer_preferences” Memory Store
Use clear, descriptive language

Use the Create Memory Store API.Required inputs:

key: unique identifier for the store (immutable after creation)
path: the Project and folder (e.g., default)
embedding_config.model: embedding model for semantic search (e.g., cohere/embed-v4.0)

curl --request POST \
     --url https://api.orq.ai/v2/memory-stores \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "key": "customer_information",
  "description": "Store for customer interaction history and preferences",
  "path": "default",
  "embedding_config": {
    "model": "cohere/embed-v4.0"
  }
}'

from orq_ai_sdk import Orq
import os

client = Orq(api_key=os.environ["ORQ_API_KEY"])

store = client.memory_stores.create(request={
    "key": "customer_information",
    "description": "Store for customer interaction history and preferences",
    "path": "default",
    "embedding_config": {
        "model": "cohere/embed-v4.0"
    }
})

import { Orq } from '@orq-ai/node';

const client = new Orq({
  apiKey: process.env.ORQ_API_KEY,
});

await client.memoryStores.create({
  key: 'customer_information',
  description: 'Store for customer interaction history and preferences',
  path: 'default',
  embeddingConfig: {
    model: 'cohere/embed-v4.0',
  },
});

The key is immutable and must be unique within your workspace. It cannot be changed after creation.

Manage Memories and Documents

A Memory represents a specific entity within a Memory Store, identified by an entity_id. Each Memory holds Documents: the actual text content embedded for semantic search.

AI Studio
API & SDK

Create an EntityOnce a Memory Store is created, select Add Entity, enter an ID for the entity, and press Save.

Memory Add Entity Studio — Choose a clear identifier to find entities later.

View MemoriesSelect an entity to see all Memory Documents stored for it. Each document shows the date it was recorded. Use date filters to narrow results.

Memory Store Date Filter — Use the date filters to find memories in an entity.

Add a Memory DocumentUse Add Memory to manually add a Memory Document to an entity. Fill in the content and press Add Memory.

Memories are best managed dynamically through the API. See the API & SDK tab for programmatic access.

Create a Memory (entity)

curl --request POST \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "entity_id": "customer_456",
  "metadata": {
    "type": "customer",
    "segment": "premium",
    "region": "north_america",
    "status": "active"
  }
}'

memory = client.memory_stores.create_memory(
    memory_store_key="customer_information",
    entity_id="customer_456",
    metadata={
        "type": "customer",
        "segment": "premium",
        "region": "north_america",
        "status": "active"
    }
)

print(f"Created memory with ID: {memory._id}")

const memory = await client.memoryStores.createMemory({
  memoryStoreKey: 'customer_information',
  requestBody: {
    entityId: 'customer_456',
    metadata: {
      type: 'customer',
      segment: 'premium',
      region: 'north_america',
      status: 'active',
    },
  },
});

console.log(`Created memory with ID: ${memory._id}`);

Add a Memory DocumentDocuments hold the text content that agents can retrieve. Each document is embedded automatically when created.

curl --request POST \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/<memory_entity_id>/documents \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Customer prefers email communication. Best contact window: 2-4 PM EST. Premium support subscriber."
}'

document = client.memory_stores.create_document(
    memory_store_key="customer_information",
    memory_entity_id=memory._id,
    text="Customer prefers email communication. Best contact window: 2-4 PM EST. Premium support subscriber."
)

print(f"Created document with ID: {document._id}")

const document = await client.memoryStores.createDocument({
  memoryStoreKey: 'customer_information',
  memoryEntityId: memory._id,
  requestBody: {
    text: 'Customer prefers email communication. Best contact window: 2-4 PM EST. Premium support subscriber.',
  },
});

console.log(`Created document with ID: ${document._id}`);

Update a Memory Document

curl --request PATCH \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/<memory_entity_id>/documents/<document_id> \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>' \
     --header 'content-type: application/json' \
     --data '
{
  "text": "Customer strongly prefers email. Contact window: 2-4 PM EST weekdays. Premium support subscriber since Jan 2024."
}'

client.memory_stores.update_document(
    memory_store_key="customer_information",
    memory_entity_id="<memory_entity_id>",
    document_id="<document_id>",
    text="Customer strongly prefers email. Contact window: 2-4 PM EST weekdays. Premium support subscriber since Jan 2024."
)

await client.memoryStores.updateDocument({
  memoryStoreKey: 'customer_information',
  memoryEntityId: '<memory_entity_id>',
  documentId: '<document_id>',
  requestBody: {
    text: 'Customer strongly prefers email. Contact window: 2-4 PM EST weekdays. Premium support subscriber since Jan 2024.',
  },
});

Delete a Memory Document

curl --request DELETE \
     --url https://api.orq.ai/v2/memory-stores/customer_information/memories/<memory_entity_id>/documents/<document_id> \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <ORQ_API_KEY>'

client.memory_stores.delete_document(
    memory_store_key="customer_information",
    memory_entity_id="<memory_entity_id>",
    document_id="<document_id>"
)

await client.memoryStores.deleteDocument({
  memoryStoreKey: 'customer_information',
  memoryEntityId: '<memory_entity_id>',
  documentId: '<document_id>',
});

For the full CRUD reference (list, retrieve, update memory stores and memories), see the Memory Stores API Reference.

Best Practices

Entity ID strategy: Use consistent, unique identifiers. Prefix by type (e.g., user_123, session_456) and keep IDs stable across your system. Descriptions: Write exhaustive Memory Store descriptions. Agents use them to identify the correct store to query. Organization: Create separate stores for different contexts (customers, products, sessions). Use descriptive keys. Metadata: Use tags for filtering and categorization, not for storing large text content. Keep data types consistent per field.

See Memory Stores powering real agent applications. Read our cookbooks Multi-Agent HR System and Chat History.

Get Started

AI Gateway

AI Observability

AI Engineering

AI Governance

AI Chat

Organization

Knowledge Bases

External Knowledge Bases

Memory Stores

Connect Knowledge Bases to Agents

Connect Memory Stores to Agents

Use-cases

Knowledge Bases

Create a Knowledge Base

Datasource and Chunking

Create a Datasource

Add Chunks to a Datasource

View Datasource Chunks

Chunk Strategy

Chunk Metadata

Data and PII Cleanup

Embedding Models

Agentic RAG

Search Modes

Rerank Model

Search a Knowledge Base

Retrieval Traces and Logs

External Knowledge Bases

API Payloads

Example Implementations

Integrate Vector Database Providers

Troubleshoot Common Errors

Configure your External Knowledge Base

Memory Stores

Architecture

Create a Memory Store

Manage Memories and Documents

Best Practices

Knowledge Bases

External Knowledge Bases

Memory Stores

Connect Knowledge Bases to Agents

Connect Memory Stores to Agents

​Use-cases

​Knowledge Bases

​Create a Knowledge Base

​Datasource and Chunking

​Create a Datasource

​Add Chunks to a Datasource

​View Datasource Chunks

​Chunk Strategy

​Chunk Metadata

​Data and PII Cleanup

​Embedding Models

​Agentic RAG

​Search Modes

​Rerank Model

​Search a Knowledge Base

​Retrieval Traces and Logs

​External Knowledge Bases

​API Payloads

​Example Implementations

​Integrate Vector Database Providers

​Troubleshoot Common Errors

​Configure your External Knowledge Base

​Memory Stores

​Architecture

​Create a Memory Store

​Manage Memories and Documents

​Best Practices

Use-cases

Knowledge Bases

Create a Knowledge Base

Datasource and Chunking

Create a Datasource

Add Chunks to a Datasource

View Datasource Chunks

Chunk Strategy

Chunk Metadata

Data and PII Cleanup

Embedding Models

Agentic RAG

Search Modes

Rerank Model

Search a Knowledge Base

Retrieval Traces and Logs

External Knowledge Bases

API Payloads

Example Implementations

Integrate Vector Database Providers

Troubleshoot Common Errors

Configure your External Knowledge Base

Memory Stores

Architecture

Create a Memory Store

Manage Memories and Documents

Best Practices