Creating and managing 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.