Knowledge

What Knowledge is, how it differs from Memories, and how to ingest it correctly.

1. What it is

Knowledge is the source material your agent searches to answer questions: product docs, policy PDFs, Slack threads, wiki pages, CSVs, and emails. One uploaded file or app record is a source. HydraDB splits its text into searchable passages called chunks.

Use Memories for preferences and history you want to carry between conversations. The content category does not set permissions: knowledge can be private, and either category can be stored in a collection you choose.

	Knowledge	Memories
Content	Documents, files, app-generated content	User preferences, conversations, inferred traits
Scope	Searches the selected collection; use ACLs to restrict documents	Usually stored in a user’s collection; your application chooses it
Mutability	Versioned: replaced or deleted explicitly	Updated when your application sends new information
Query via	POST /query with type: "knowledge"	POST /query with type: "memory"
vectorstore_status	vectorstore_status.knowledge	vectorstore_status.memories

One endpoint, two stores. Knowledge and memories are stored separately, but a single POST /query call can hit both via type: "all". Both stores are read from the same collection scope, and results are merged and re-ranked together. Pick type: "knowledge" for document questions, type: "memory" for per-user context, or type: "all" for personalized answers grounded in both. See Query for the full picture.

---

2. What it does

When you call POST /context/ingest with type=knowledge, HydraDB walks each source through a pipeline:

1. Parses the input: PDF, DOCX, Markdown, CSV, plain text, or app-source JSON.
2. Splits the text into passages that can be retrieved independently.
3. Finds entities (named people, teams, services, or topics) and their relationships (see Context Graphs).
4. Builds search indexes for matching by meaning and by keywords.
5. Indexes the result so it becomes queryable via POST /query.

The pipeline runs asynchronously: ingest returns 202 Accepted with ids, and the content becomes queryable once indexing_status reaches graph_creation. Section 5 shows how to poll.

---

3. When to use it

Reach for Knowledge ingestion when the content is:

• Reference material: product docs, policy PDFs, runbooks, wikis, or tickets. Choose collections and document permissions separately.
• Static or infrequently updated: versioned by replacing the source rather than appending.
• Document-structured rather than conversational: files, threads, pages, articles.

Reach for Memories instead when the content is:

• User preferences or behavioral signals tied to one person.
• Per-user conversation history that should shape future answers for that user.
• Anything that should personalize a single user’s experience.

---

4. Two ingestion paths

POST /context/ingest with type=knowledge accepts two content formats, and you can send either or both in one multipart/form-data request. Pick the path that matches what you have:

• Path A when you have binary files HydraDB should parse for you.
• Path B when you have pre-extracted text from an app or connector and want to skip parsing.

Path A: Files

Binary files HydraDB should parse and chunk: PDF, DOCX, Markdown, CSV, TXT.

Python SDK

import json

with open("/path/to/policy.pdf", "rb") as f1, open("/path/to/runbook.pdf", "rb") as f2:
    result = client.context.ingest(
        type="knowledge",
        database="acme_corp",
        documents=[
            ("policy.pdf", f1, "application/pdf"),
            ("runbook.pdf", f2, "application/pdf"),
        ],
        document_metadata=json.dumps([
            {"id": "policy_v2", "metadata": {"document_type": "policy", "status": "approved"}},
            {"id": "runbook_deploy", "metadata": {"document_type": "runbook"}},
        ]),
    )

Path B: App sources

Pre-parsed records from connected apps. You supply app-native fields (kind, provider, external_id, and fields), metadata, and optional attachments/comments. Use this when your application already extracts content from Slack messages, Notion pages, Gmail messages, tickets, or CRM records and you want HydraDB to preserve app structure instead of treating the item as generic text.

Python SDK

import json

result = client.context.ingest(
    type="knowledge",
    database="acme_corp",
    app_knowledge=json.dumps([
        {
            "database": "acme_corp",
            "collection": "default",
            "id": "slack_C01_1716213600_000100",
            "title": "Pricing discussion - Slack #product",
            "kind": "message",
            "provider": "slack",
            "external_id": "1716213600.000100",
            "fields": {
                "kind": "message",
                "body": "We agreed on three tiers: Starter at $29, Pro at $79, Enterprise at $199.",
                "author": "alice",
                "thread_id": "1716213600.000100",
                "created_at": "2026-05-20T10:00:00Z",
            },
            "metadata": {"channel": "product", "status": "finalized"},
            "additional_metadata": {"slack_ts": "1716213600.000100"},
        }
    ]),
)

Response (both paths):

{
  "success": true,
  "data": {
    "success": true,
    "message": "Knowledge uploaded successfully",
    "results": [
      { "id": "policy_v2", "filename": "policy.pdf", "status": "queued", "error": null }
    ],
    "success_count": 1,
    "failed_count": 0
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

The /context and /query endpoints return this envelope shape. Access the payload via response.data (e.g. response.data.results), not at the top level.

---

5. Verifying processing

Ingestion is async, so you need to confirm each source actually finished before it’ll show up in query. Poll GET /context/status with the ids you got back from ingestion. The snippets below loop until every item reaches a terminal state (completed or errored):

Python SDK

import time

ids = ["policy_v2", "runbook_deploy"]
terminal = {"completed", "errored"}

while True:
    status = client.context.status(
        database="acme_corp",
        collection="default",
        ids=ids,
    )
    if all(s.indexing_status in terminal for s in status.data.statuses):
        break
    time.sleep(5)

Each status in the data payload looks like this:

{
  "statuses": [
    {
      "id": "policy_v2",
      "indexing_status": "completed",
      "success": true
    }
  ]
}

Status values move forward through queued, processing, graph_creation, and completed (or land in errored on failure). Poll every few seconds; most documents complete in 1 to 5 minutes. The full table is on Ingestion Status.

graph_creation is already queryable. Items in this state are retrievable via POST /query. Wait for completed only when you specifically need full graph traversal (graph_context: true).

---

6. Key parameters

The full schema lives on POST /context/ingest. Below are the fields you’ll touch most often, grouped by where they live in the request.

File metadata (document_metadata array items)

Send one item per file in documents, in the same order. The item count must match the file count.

Field	Description
	Optional stable identifier. Used as upsert key when upsert: true.
	Filterable fields. Keys must match the database metadata schema. Up to 16 KiB as compact JSON.
	Free-form fields for display and bookkeeping. Filterable only when nested under additional_metadata in metadata_filters. Up to 1 KiB as compact JSON.
	Forcefully connect this source to others with { "ids": [...] }.

Any other key, including title, type, url, and timestamp, returns 400. App sources accept title, url, and timestamp.

App source model (app_knowledge array items)

Field	Description
	Stable ID. Used as the upsert/delete/status key.
	Database that owns the item. Must match form-level database (formerly tenant_id) when present.
	Logical partition. Must match form-level collection when present.
	Short title, subject, ticket title, or page name.
	App object kind. Selects the app parser for fields.
	App namespace such as slack, gmail, jira, notion, salesforce, or linear.
	Stable provider ID for this exact item. Enables exact lookup and relation resolution.
	App-native content and structure. Put primary text here (body, description, title, or data depending on kind).
	Canonical URL or reference link.
	Creation, sent, or last-updated time.
	Filterable fields matching the database schema.
	Free-form fields. Filterable only when nested under additional_metadata in metadata_filters.
	Optional related attachments. Include extracted text in attachments[].content.text or .markdown.
	Optional embedded snapshot comments. For live incremental comments, prefer a first-class kind: "comment" source.
	App-native relation array: [{ "predicate": "linked_to", "target": { "external_id": "AUTH-123", "provider": "jira" } }].

Request-level fields

Field	Default	Description
	None	Target database.
	default collection	Scope this knowledge to a collection. If omitted, knowledge goes to the database’s default collection, which a query naming another collection does not read.
	true	Replace existing items with the same id.

---

7. Forceful relations

Forceful relations let you declare links between Knowledge sources at ingestion time. When a query matches a source that has forceful relations attached, HydraDB pulls the linked sources into the additional_context field of the query response alongside the primary chunks.

This is separate from the entity and relationship context graph HydraDB builds automatically. Graph extraction is derived from content; forceful relations are declared by you, which is useful when you know two documents belong together (a contract and its addendum, a runbook and its troubleshooting guide) but the text doesn’t make the connection explicit. Forceful relations link whole sources; to declare the full entity/relation graph within a single document (replacing extraction for it), use Bring Your Own Graph.

For file uploads, set relations.ids on the matching document_metadata item. For app sources, prefer the app-native relations[] shape so each link can carry a predicate and provider-aware target:

{
  "relations": [
    {
      "predicate": "linked_to",
      "target": {
        "id": "auth-troubleshooting"
      }
    },
    {
      "predicate": "related_to",
      "target": {
        "external_id": "AUTH-FAQ",
        "provider": "notion"
      }
    }
  ]
}

Python SDK

client.context.ingest(
    type="knowledge",
    database="acme_corp",
    app_knowledge=json.dumps([
        {
            "database": "acme_corp",
            "collection": "default",
            "id": "auth-guide",
            "title": "Authentication Guide",
            "kind": "knowledge_base",
            "provider": "notion",
            "external_id": "AUTH-GUIDE",
            "fields": {"kind": "knowledge_base", "title": "Authentication Guide", "body": "..."},
            "relations": [
                {"predicate": "linked_to", "target": {"id": "auth-troubleshooting"}},
                {"predicate": "related_to", "target": {"external_id": "AUTH-FAQ", "provider": "notion"}},
            ],
        }
    ]),
)

At query time, linked sources are returned in the additional_context field of the query response. query_forceful_relations defaults to true, so you only need to set it explicitly if you want to disable forceful-relation expansion.

Knowledge items only. Forceful relations work within the same store. Pointing a Knowledge item at a Memory ID will silently return nothing at query time.

thinking mode only. Forceful-relation context is fetched only when mode: "thinking" is set on the query request (or when mode: "auto" routes to thinking). In fast mode, query_forceful_relations is ignored even if set to true.

---

8. Metadata on knowledge

Metadata is how you bridge structured filters and semantic search. Attach metadata at ingestion to enable deterministic narrowing at query time:

{
  "metadata": { "document_type": "runbook", "environment": "production" }
}

Then at query time:

{
  "query": "How do I rotate API keys?",
  "metadata_filters": { "document_type": "runbook", "environment": "production" }
}

Declare the metadata keys you filter on in the database metadata schema. In a database with a schema, ingest rejects undeclared keys, so filtering on one returns nothing. additional_metadata is stored alongside the source for display and bookkeeping; to filter on it, nest the keys under additional_metadata in metadata_filters (e.g. {"metadata_filters": {"additional_metadata": {"author": "Alice"}}}). document_metadata is accepted only as a legacy alias for that nested filter namespace.

See Metadata for schema design, filter examples, and the metadata vs additional_metadata decision rule. See Create Database for the schema field configuration (enable_dense_embedding, enable_sparse_embedding).

---

9. Common mistakes

Mistake	What goes wrong	Fix
Querying Knowledge with type: "memory"	Nothing returned: wrong store	Use type: "knowledge" (or "all") on POST /query.
Using additional_metadata for hot filterable fields	Filters work only with nested syntax and are less efficient than schema-backed metadata filters	Put hot filter keys in metadata and declare them in the database schema, or filter under metadata_filters: {"additional_metadata": {...}} for occasional/free-form fields. See Metadata.
Not polling /context/status before querying	Chunks aren’t indexed yet, so query results are empty	Wait for indexing_status: completed (or graph_creation for partial availability).
Sending document_metadata as a JSON object instead of a JSON string	multipart/form-data validation fails	Stringify document_metadata before sending in the -F field.
Omitting database	400 error (database is required)	Required on every call.

---

Related

• Memories: the per-user counterpart to Knowledge
• Query: how POST /query retrieves Knowledge
• Metadata: designing filterable schemas
• Context Graphs: how the graph layer enriches retrieval
• Ingest Content: API Reference
• Ingestion Status: API Reference