Skip to content

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 conversa

View as Markdown Open the plain-text version of this page.

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.

Next steps#