# Knowledge

Knowledge turns agent conversations into structured, reviewable project memory. A project defines
Learning Goals that describe what matters; Provon extracts matching items from new traces and
historical conversations while preserving evidence references.

Knowledge is intentionally category-agnostic. The meaning of an item is determined by the goal's
instruction rather than a fixed taxonomy.

## Where Knowledge fits

```mermaid
flowchart LR
  traces["Trace evidence"] --> goals["Learning Goals"]
  goals --> extract["Extraction"]
  extract --> items["Knowledge Items"]
  items --> review["Review"]
  review --> agent["Coding agent context"]
  review --> datasets["Datasets: teach_project_knowledge"]
```

Every item keeps a path back to the conversation that motivated it, so project memory stays
reviewable instead of becoming undocumented folklore.

## When to use it

Use knowledge extraction when you want to:

- capture reusable facts, constraints, or preferences observed in agent behavior;
- build a project knowledge base from production traces without manual curation;
- feed extracted items into downstream workflows such as prompt improvement or fine-tuning Datasets.

## Core concepts

| Concept                | Description                                                                                                                  |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **Learning Goal**      | A project-scoped instruction that describes what to extract, for example "extract user preferences about output formatting". |
| **Knowledge Item**     | A structured result produced from a conversation: title, content, confidence, and evidence references.                       |
| **Extraction setting** | A project toggle that enables or disables automatic extraction on new conversations.                                         |
| **Backfill**           | A one-off run that extracts items from existing traces for a goal.                                                           |
| **Evidence reference** | A link from an item back to the source conversation and trace IDs.                                                           |

## Goal and item lifecycles

A Learning Goal can be `active`, `paused`, or `archived`:

- `active` goals participate in automatic extraction and can be backfilled.
- `paused` goals are excluded from automatic extraction but can be reactivated. Pause while iterating
  on the instruction.
- `archived` goals are permanently excluded from extraction. Existing items remain unless archived
  separately.

A Knowledge Item can be `active` or `archived`:

- `active` items are returned by default search and included in local snapshots.
- `archived` items are hidden from default views but retained for auditability.

## Enable extraction

Open **Knowledge** in the Workbench and enable automatic extraction. New conversations become
candidates after they are inactive for about 10 minutes.

The switch records the desired state. Each Learning Goal selects its own model. Goals with available
models continue to run even when another goal's model needs setup.

Extraction applies every active Learning Goal independently. Start with one focused goal so the
resulting items are easy to judge before adding broader instructions.

See [Knowledge quickstart](./quickstart.md) for step-by-step setup.

## Manage goals

Create a Learning Goal with:

- a specific name;
- an instruction that states what to retain and what to ignore;
- an extraction model;
- an active, paused, or archived status.

Use separate goals for facts with different review, retention, or model needs. Paused and archived
goals do not participate in automatic extraction.

See [Knowledge best practices](./best-practices.md) for instruction templates and goal-splitting
guidance.

## Backfill existing traces

Select **Scan past traces** for an active goal in the Workbench and choose the evidence window.
Backfills run asynchronously and use the same extraction behavior as new conversations.

When automating backfills through the API, use an `Idempotency-Key` header to avoid duplicate runs
for the same goal and window.

## Review items

Each item includes the extracted content, a confidence score, and `evidenceRefs` pointing back to the
source conversation and spans. Review the title and content against that evidence before treating it
as project truth. Correct the item when the evidence supports a more precise statement, or archive it
when it should no longer be consumed.

Confidence is a review signal, not a calibrated probability. High-confidence items are usually direct
statements; low-confidence items often involve interpretation and should be checked carefully.

## Use knowledge

Knowledge can guide prompt and workflow changes, provide local context to coding agents, and supply
examples for a Dataset configured to teach project knowledge.

Materialize active items as managed Markdown:

```bash
provon knowledge pull
provon knowledge find "deployment region" --format paths
```

See [Knowledge CLI](../cli/knowledge.md) for local consumption and the
[Knowledge API](../api/knowledge.md) for automation.

## Extraction behavior

- Extraction runs asynchronously after a conversation is inactive, similar to diagnostic Rules.
- A goal with no instruction or an inactive status produces no items.
- Items from repeated or similar evidence update the existing item rather than creating duplicates.
- Extraction requires the conversation trajectory to be present; spans alone are not always enough.
- Each goal's selected model must support Chat Completions and JSON Mode. Work for that goal is not
  scheduled while its model needs setup; an unavailable extraction runtime is reported as
  `extractor_unavailable`.

## Limitations

- Automatic extraction is only available when the runtime provides a `KnowledgeExtractionService`.
- Extraction quality depends on the goal instruction; ambiguous instructions produce inconsistent
  items.
- Knowledge is project-scoped; there is no automatic sharing across projects or organizations.
- Backfills are bounded by a maximum of 100,000 conversations per request.

## Learn more

- [Quickstart](./quickstart.md) — create your first Learning Goal and extracted item.
- [Best practices](./best-practices.md) — write better goals, review items, and consume Knowledge.
- [Troubleshooting](./troubleshooting.md) — no items, low confidence, and skipped extractions.
- [Knowledge CLI](../cli/knowledge.md) — local snapshots and search.
- [Knowledge API](../api/knowledge.md) — automate settings, goals, items, and backfills.