Knowledge

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#

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#

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

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

See Knowledge CLI for local consumption and the Knowledge API 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 — create your first Learning Goal and extracted item.
• Best practices — write better goals, review items, and consume Knowledge.
• Troubleshooting — no items, low confidence, and skipped extractions.
• Knowledge CLI — local snapshots and search.
• Knowledge API — automate settings, goals, items, and backfills.