> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hydradb.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> AGENTS.md is HydraDB's maintained agent guide. Read https://docs.hydradb.com/AGENTS.md once, then use its content. /llms.txt and /llms-full.txt redirect to the same guide; they are not separate documentation indexes. If the guide is already loaded, continue with it instead of fetching either alias or reloading the guide.

# Context: Overview

> Ingest, inspect, and manage knowledge and memories.

Context is everything you store in HydraDB: knowledge and memories. Each stored unit is a **source** (an uploaded document, an app source, or a memory). Ingestion returns an `id` for each source, and the other endpoints in this group take that `id`.

## Endpoint references

SDK methods are listed by their Python names. The TypeScript SDK uses the same names in camelCase, such as `context.updateSourceMetadata`.

| Endpoint | SDK method | Purpose |
| - | - | - |
| [`POST /context/ingest`](https://docs.hydradb.com/api-reference/v2/endpoint/ingest-context) | `context.ingest` | Ingest documents, app sources, or memories. Asynchronous: sources are queued for indexing. |
| [`GET /context/status`](https://docs.hydradb.com/api-reference/v2/endpoint/source-status) | `context.status` | Poll indexing progress |
| [`POST /context/list`](https://docs.hydradb.com/api-reference/v2/endpoint/list-context) | `context.list` | Browse stored sources or memories |
| [`GET /context/inspect`](https://docs.hydradb.com/api-reference/v2/endpoint/fetch-content) | `context.inspect` | Inspect original source content |
| [`PATCH /context/{id}/metadata`](https://docs.hydradb.com/api-reference/v2/endpoint/update-source-metadata) | `context.update_source_metadata` | Update a source's metadata without re-ingesting |
| [`GET /context/relations`](https://docs.hydradb.com/api-reference/v2/endpoint/source-relations) | `context.relations` | Inspect graph relations |
| [`GET /context/{id}/subgraph`](https://docs.hydradb.com/api-reference/v2/endpoint/subgraph) | `context.subgraph` | Get everything connected to one source |
| [`DELETE /context`](https://docs.hydradb.com/api-reference/v2/endpoint/delete-source) | `context.delete` | Delete sources or memories |

## Choose an ingest payload

`POST /context/ingest` accepts three payloads. `type` picks the store, and within `type=knowledge` you pick the payload shape:

| To ingest | Send | Guide |
| :- | :- | :- |
| PDFs, DOCX, CSVs, and other documents HydraDB should parse | `type=knowledge` and `documents` | [Context](https://docs.hydradb.com/essentials/v2/context.md) |
| Slack messages, Notion pages, Gmail threads, or web pages with pre-extracted text | `type=knowledge` and `app_knowledge` | [Context](https://docs.hydradb.com/essentials/v2/context.md#send-app-sources) |
| User preferences, conversation history, or inline notes | `type=memory` and `memories` | [Context](https://docs.hydradb.com/essentials/v2/context.md#2-save-memories) |

You can send `documents` and `app_knowledge` in the same request.

## Typical call sequence

1. Ingest context: `POST /context/ingest`. The response returns an ID for each source.
2. Wait for indexing: poll `GET /context/status` with those IDs. A source is searchable at `graph_creation` and its graph is ready at `completed`. `errored` means indexing failed.
3. Retrieve context: `POST /query`.
4. Manage what is stored: list, inspect, update metadata, or delete by ID.

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

## Key concepts

* **Knowledge and memories:** Knowledge is the documents, app sources, and facts your AI uses. Memories are preferences, decisions, and past conversations. Both live in a collection, and `type: "all"` on `POST /query` searches both from the same scope.
* **IDs:** `/context/ingest` returns an ID for each source. To assign your own, set `id` in the `document_metadata`, `app_knowledge`, or `memories` item. Use IDs to poll status, inspect content, and delete context.
* **Metadata:** [Metadata Filters](https://docs.hydradb.com/essentials/v2/metadata.md) covers metadata fields, ingestion, updates, and filtering.
* **Forceful relations:** Links you declare between sources with `relations.ids`. In `thinking` mode, a query returns the linked sources in `additional_context` alongside the matching chunks. 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](https://docs.hydradb.com/essentials/v2/context.md#6-link-sources-that-belong-together): linking sources at ingestion
* [Context](https://docs.hydradb.com/essentials/v2/context.md#2-save-memories): memories and knowledge, and when to use which
* [Metadata Filters](https://docs.hydradb.com/essentials/v2/metadata.md): schema-backed and free-form metadata
* [Query: Overview](https://docs.hydradb.com/api-reference/v2/endpoint/query-overview.md): retrieve ingested context


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