Context Management: Overview

Endpoint references

Task	Endpoint
Upload PDFs, DOCX, CSVs, and other documents HydraDB should parse	`/context/ingest` with `type=knowledge` and `documents`
Upload Slack messages, Notion pages, Gmail threads, or webpages with pre-extracted text	`/context/ingest` with `type=knowledge` and `app_knowledge`
Upload user preferences, conversation history, or inline notes	`/context/ingest` with `type=memory` and `memories`
Poll indexing progress	`/context/status`
Browse stored sources or memories	`/context/list`
Inspect original source content	`/context/inspect`
Update a source’s metadata without re-ingesting	`PATCH /context/{id}/metadata`
Delete sources or memories	`DELETE /context`
Inspect graph relations	`/context/relations`
Get everything connected to one item	`/context/{id}/subgraph`

Lifecycle

Why both type=knowledge and app_knowledge? They answer different questions.

type picks the store: knowledge (shared documents) or memory (per-user context). It routes the ingest to the right store.
Within type=knowledge, you pick the payload shape: documents (binary documents HydraDB will parse: PDFs, DOCX, CSV) or app_knowledge (a JSON array of already-extracted content from your app: Slack messages, Notion pages, web pages). You can send both in the same request.

Core ingestion concepts

Knowledge vs. memories: Knowledge is shared content (documents, app pages, Slack messages). Memories are one user’s preferences and conversation history. Both live in a collection, and type: "all" on POST /query searches both from the same scope.
IDs: Unique identifiers returned by /context/ingest. You can assign custom IDs using id in document_metadata, app_knowledge, or memories items. Use them for polling status, inspecting content, and deleting context.
Metadata filtering: You can scope queries using metadata (structured fields defined in your database schema) or additional_metadata (free-form per-document JSON). For detailed guidelines on structuring metadata, see the Scoping using metadata guide.

Forceful relations and metadata

Forceful relations let you pre-wire document relationships at ingestion time so that relevant documents surface together during retrieval, even before the graph layer discovers connections organically. Think of them as explicit “see also” links between your documents. Linked sources come back in the query response’s additional_context (thinking mode). Set relations on the same document_metadata item as the file’s metadata:

Python SDK

import json

with open("runbook.pdf", "rb") as f:
    result = client.context.ingest(
        type="knowledge",
        database="acme_corp",
        documents=[("runbook.pdf", f, "application/pdf")],
        document_metadata=json.dumps([{
            "id": "runbook_deploy",
            "metadata": {"department": "ops"},
            "additional_metadata": {"owner": "platform-team"},
            "relations": {"ids": ["monitoring_guide"]},
        }]),
    )

Knowledge: forceful relations: linking sources at ingestion
Memories: memories vs knowledge, when to use which
Metadata: database-level vs document-level metadata
Query: retrieve ingested content

Start here

Databases

Context

Query

Connectors

Webhooks

Reference

Context Management: Overview

Endpoint references

Lifecycle

Core ingestion concepts

Forceful relations and metadata

​Endpoint references

​Lifecycle

​Core ingestion concepts

​Forceful relations and metadata

​Related

Endpoint references

Lifecycle

Core ingestion concepts

Forceful relations and metadata

Related