> ## Documentation Index
> Fetch the complete documentation index at: https://cortex-e852fafe-docs-pro-2457-api-response-cleanup.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Management: Overview

> Every context endpoint, the ingestion lifecycle, and which call to use for which content.

## 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

```mermaid theme={"dark"}
flowchart LR
    A([Choose content type]) --> B{Knowledge or memory?}

    subgraph Ingestion [" "]
      direction LR
      SI([POST /context/ingest])
    end

    B -- Documents / app sources --> SI
    B -- User memories --> SI

    SI --> Q([queued])
    Q --> P([processing])
    P --> G([graph_creation])
    G --> R([Search ready])
    G --> C([completed])
    C --> GR([Graph ready])

    P -. failure .-> E([errored])
    G -. failure .-> E

    linkStyle default stroke:#64748b,stroke-width:2px,color:#f8fafc
    style A fill:#0f172a,stroke:#334155,stroke-width:2px,color:#f8fafc
    style B fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style SI fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style Q fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style P fill:#1e293b,stroke:#334155,stroke-width:2px,color:#f8fafc
    style G fill:#CC4515,stroke:#FF571A,stroke-width:3px,color:#ffffff,font-weight:bold
    style C fill:#0f172a,stroke:#10b981,stroke-width:2px,color:#f8fafc
    style R fill:#0f172a,stroke:#10b981,stroke-width:3px,color:#f8fafc
    style GR fill:#0f172a,stroke:#10b981,stroke-width:3px,color:#f8fafc
    style E fill:#0f172a,stroke:#ef4444,stroke-width:2px,color:#f8fafc
```

<Note>
  **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.
</Note>

## Core ingestion concepts

* **Knowledge vs. memories:** [Knowledge](/essentials/v2/knowledge) is shared content (documents, app pages, Slack messages). [Memories](/essentials/v2/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](/essentials/v2/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 Python SDK theme={"dark"}
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"]},
        }]),
    )
```

## Related

* [Knowledge: forceful relations](/essentials/v2/knowledge#7-forceful-relations): linking sources at ingestion
* [Memories](/essentials/v2/memories): memories vs knowledge, when to use which
* [Metadata](/essentials/v2/metadata): database-level vs document-level metadata
* [Query](/api-reference/v2/endpoint/query-overview): retrieve ingested content


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.