# Knowledge Quickstart

This guide creates your first extracted Knowledge item: enable extraction, define a Learning Goal,
and either wait for automatic extraction or run a backfill over existing conversations.

## Prerequisites

- A Provon project with at least one ingested conversation or trace.
- Knowledge extraction requires a configured model provider for the project. Without a provider,
  goals and items can still be managed, but automatic extraction produces no candidates.
- For CLI steps: `provon` is installed and authenticated with access to the project.

## Step 1: Enable automatic extraction

Open the project in the Workbench, navigate to **Knowledge**, and turn on automatic extraction.

Or use the CLI:

```bash
provon knowledge settings set-extraction true
```

Extraction is project-scoped and disabled by default.

## Step 2: Create a Learning Goal

A Learning Goal tells Provon what to retain. Start with one focused goal so the results are easy
to judge.

In the Workbench, click **New goal**:

- **Name**: Output format preferences
- **Instruction**: Extract explicit user preferences about response format, length, or tone.
  Ignore one-off requests that contradict earlier preferences.

Or use the CLI:

```bash
provon knowledge goals create "Output format preferences" \
  "Extract explicit user preferences about response format, length, or tone. Ignore one-off requests that contradict earlier preferences."
```

The goal is created in the `active` state and immediately participates in automatic extraction.

## Step 3: Produce or wait for a conversation

New conversations become extraction candidates after they are inactive for about 10 minutes. If
you already have recent traces, you can skip to the backfill step.

To generate a fresh conversation for testing, send a traced request through Provon Gateway or OTLP
and tag it with a stable `gen_ai.conversation.id`.

## Step 4: Review extracted items

Open **Knowledge** in the Workbench. Each item shows:

- a title and content derived from the conversation;
- a confidence score;
- `evidenceRefs` linking back to the source conversation and trace IDs.

Read the item against its evidence before treating it as project truth. Edit the title or content
if the evidence supports a more precise statement, or archive the item if it should not be
consumed.

Pull the active items to a local snapshot and inspect them:

```bash
provon knowledge pull
provon knowledge status
```

Or retrieve a specific item by ID:

```bash
provon knowledge items get <item-id>
```

## Step 5 (optional): Backfill historical conversations

If you want to extract from existing traces instead of waiting for new ones, run a backfill for the
goal:

```bash
provon knowledge goals backfill <goal-id> \
  --start 1755216000000 \
  --end 1755302400000 \
  --max-conversations 1000
```

The backfill is asynchronous and uses the same extraction logic as automatic extraction. Use
`--max-conversations` to limit cost and latency.

## Step 6: Consume active Knowledge locally

Materialize active Knowledge as Markdown for coding agents or local search:

```bash
provon knowledge pull
```

This writes files under `.provon/knowledge` and records a manifest. Search the snapshot:

```bash
provon knowledge find "response format"
provon knowledge find "response format" --format paths
```

The `paths` format returns the Markdown files associated with matching goals, which is useful when
passing focused context to a coding agent.

## Automation example

For a complete shell example that emits a trace, enables extraction, creates a goal, triggers a
backfill, and polls for items, see the [knowledge-extraction example](../../examples/knowledge-extraction/README.md).

## Next steps

- [Knowledge best practices](./best-practices.md) — write better goals and review items.
- [Knowledge troubleshooting](./troubleshooting.md) — debug missing or low-quality items.
- [Knowledge API](../api/knowledge.md) — automate goals, items, and backfills.
- [Knowledge CLI](../cli/knowledge.md) — manage snapshots and search locally.