> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovara-labs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating and managing lessons
> Create, organize, and maintain Sovara lessons.
The Lessons page is where reviewed domain knowledge becomes reusable context.
The goal is not to collect every observation. The goal is to keep a small,
high-quality set of lessons that can be retrieved when they matter.
Open Lessons from the
project sidebar.
## Create a lesson
Click New Lesson to create a
lesson, or New Folder to
organize lessons by domain, workflow, or product area.
Fill in the lesson:
* **Title**: short and readable
* **Use this when**: the situations where retrieval should find this lesson
* **Content**: the rule the agent should follow
The **Use this when** field matters. It is the retrieval-facing description of
the lesson. If it is too vague, Sovara may miss the lesson. If it is too broad,
the lesson may show up when it should not.
Use Suggest to draft the
**Use this when** field from the lesson content, then edit it until it describes
the situations where the lesson should be retrieved.
## Review quality
Click Review before
turning an important draft into an active lesson. Sovara checks whether the lesson
is suitable for reuse.
The checks focus on practical quality:
* **Actionable**: it tells the agent what to do differently
* **Concise**: it preserves the useful rule without unnecessary narrative
* **Self-contained**: it includes the conditions needed to apply the rule
* **Precise**: it avoids vague advice
* **Well-scoped**: it generalizes without causing mistakes in nearby cases
* **Faithful**: it does not invent facts or constraints
* **Retrieval-friendly**: it uses the terms that should trigger retrieval
* **Non-conflicting**: it does not contradict existing lessons
Use Polish when a draft has
the right lesson but needs cleaner wording.
When the draft is ready, click Save.
## Avoid duplicates and conflicts
Two lessons can be individually reasonable and still make the system worse
together. Sovara checks for overlap and conflict so the lesson library does not
become a pile of competing instructions.
When a new lesson overlaps with an existing lesson, prefer one of these outcomes:
* Update the existing lesson if it already owns the rule
* Split the lesson if two different situations are being mixed together
* Narrow the **Use this when** field if the rule is firing too broadly
* Delete or archive the weaker lesson if it only repeats another one
The goal is a library that stays useful as it grows.
## Preserve provenance
When a lesson comes from a concrete run, keep the link to that run. Provenance
answers the question: "Why does this lesson exist?"
That link is important during review. It lets someone inspect the original
failure, confirm the lesson, and decide whether the lesson still applies after
the agent changes.
## Balance recall, precision, and latency
Lesson retrieval has three competing goals:
* **Recall**: missing a relevant lesson can mean repeating a known mistake
* **Precision**: injecting too many lessons dilutes attention
* **Latency**: retrieval should add only a small overhead to the agent run
Sovara is designed around that tradeoff. Recall is paramount because a missed
lesson can recreate the same failure. Precision still matters because context is
not free: irrelevant lessons make the prompt longer and can distract the agent
from the rule it actually needs.
The target is low overhead, ideally below `10%` of the run's normal latency.
That is why Sovara uses retrieval-aware lesson generation, compact lesson content,
and project-level latency controls instead of injecting the whole lesson library.
Next, see how Sovara applies lessons automatically at runtime in [Sovara's
auto-injection](/sovaradb/auto-injection).