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

# Knowledge

> Source-grounded project context with scoped agent access

Knowledge stores project documentation, policies, and reference material as
versioned sources. It is separate from Agent Memory: Knowledge is explicitly
managed and source-grounded, while Memory captures durable facts and
preferences learned by an agent.

Each source has a trust level, immutable versions, parsed chunks, citations,
and an agent allowlist. Retrieval checks project and agent access before a
result can enter the runtime context.

## Source types

Polpo Cloud currently accepts:

* pasted UTF-8 text;
* public HTTP or HTTPS URLs.

URL ingestion rejects local, private, link-local, metadata, credential-bearing,
oversized, and unsafe redirect targets. File and Connection-backed sources are
not yet available in the hosted ingestion path.

## Ingestion lifecycle

When durable ingestion is enabled for a project, creating or reindexing a
source queues bounded background work and returns the source in a pending
state. The source progresses through `pending`, `indexing`, and `indexed`, or
ends as `failed` with a sanitized diagnostic.

Reindexing does not remove the current indexed version while the replacement
is processing. Duplicate deliveries are idempotent, failed jobs can be retried,
and deleting a source cancels its queued work.

Polpo waits for the durable queue to accept each new job. If dispatch is
unavailable, the request fails, the job becomes visibly `failed`, and its
staged payload is retained for an explicit retry. A lost queue response cannot
overwrite a job that a worker has already claimed or completed.

The managed dashboard shows source status, the latest ingestion attempt, and a
retry action. Durable ingestion availability is controlled by the project's
hosted rollout; when disabled, the existing bounded ingestion behavior remains
unchanged.

## API

| Method   | Path                                   | Description                            |
| -------- | -------------------------------------- | -------------------------------------- |
| `GET`    | `/v1/brain/sources`                    | List authorized Knowledge sources      |
| `POST`   | `/v1/brain/sources`                    | Add a source                           |
| `GET`    | `/v1/brain/sources/{sourceId}`         | Read source metadata                   |
| `PATCH`  | `/v1/brain/sources/{sourceId}`         | Update metadata and grants             |
| `DELETE` | `/v1/brain/sources/{sourceId}`         | Delete a source and cancel queued work |
| `POST`   | `/v1/brain/sources/{sourceId}/reindex` | Queue a new immutable version          |
| `POST`   | `/v1/brain/search`                     | Test scoped retrieval with citations   |

Hosted projects with observable durable ingestion can also inspect
`GET /v1/brain/sources/{sourceId}/ingestion-jobs`. In enforcing modes, retry a
failed job with `POST /v1/brain/ingestion-jobs/{jobId}/retry`.

## Runtime use

Grant a source only to the agents that need it. Authorized agents can retrieve
relevant chunks through Knowledge tools or automatic runtime context when that
policy is enabled. Retrieved text remains clearly separated from system
instructions and preserves source, version, trust, and citation metadata.