Learning
Besydr turns what you tell an agent into stored records called lessons, and adds the lessons that fit the current request to the agent's context in later sessions. The aim is that a correction is made once. No benefit of this has been measured yet.
Learning is on by default. Turn it off with [learning] enabled = false.
Kinds of lesson
| Kind | What it holds | Evidence required |
|---|---|---|
| Rule | An instruction you gave: a correction, a project convention, a preference. | A quote of your own words from a real message of yours. A rule without a matching quote is dropped. |
| Project fact | A lasting fact about how the project works. Besydr's files call it "orientation". | One to four cited messages from you or from tool output. Recalled as an assumption to verify, not as truth. |
| Work memo | A memo of 150 to 600 words on one piece of work and how it ended. Besydr's files call it "experience". | Cited messages, and an outcome label: verified (the completion check passed after the agent changed something and ran a recognized check), failed, or unknown. |
A candidate lesson must also pass a second check against its cited evidence. A rejected candidate is not stored. Generic advice, activity logs, secrets and facts found by one obvious search are not stored as work memos.
Each lesson has a scope. Most lessons are tied to one project and one agent role. A lesson that is clearly about how you work in general, and that passes a further check, is stored as global and applies in every project.
When lessons are extracted
Extraction runs in the background and never holds up the agent. It starts when:
- the client reports that a session ended, unless the reason is a switch to another session (the session may be resumed) or lessons were already extracted;
- the client reports a compaction. If you asked for it (octomind's
/done), extraction starts at once. If the agent chose it, Besydr takes a copy of the messages before the fold and extracts after the fold succeeds, so a failed fold teaches nothing; - a session has had no event for
[sessions] idle_extract_minutes(30 by default) and its client has not reported its end. Besydr checks for such sessions every five minutes, so extraction can start a few minutes after the limit.0turns this off.
Besydr waits for running extractions before the server exits. A client that is closed without reporting the end of its session is therefore still learned from, once the idle limit has passed and a Besydr server is running to notice it.
An extraction after idle time reads only the messages that no extraction has read yet, and Besydr remembers how many that was. If the session continues, a later idle period or the session's end extracts only the messages added since. A compaction or a new message list from the client starts the count again, because the old count then refers to messages that are gone. Ending a session that was already extracted in full does nothing.
One model call decides whether a session holds anything worth keeping. Rules are then written from your corrections and stated rules. Identical lessons are skipped. A new lesson replaces an older one only when the model names the older one and both have the same scope. A work memo is written for work that was verified or failed; for work with no verdict it needs at least 8 tool results and 8,000 tokens of transcript.
Where lessons are stored
Each lesson is one Markdown file with a small header, so you can read and edit it.
<data directory>/learning/
<project>/<role>/ lessons for one project and role
_/ global lessons
<project>is the name of the folder that holds the repository's.git, found by walking up from the working directory. Outside a repository it is the name of the working directory. The walk stops below your home folder, so a dotfiles repository in~does not name every project. Two repositories with the same folder name share lessons.<role>is the agent's role up to the first:. Octomind sends its own role. Claude Code, Codex, OpenCode and pi sessions use the roledeveloper.- A lesson file records its title, text, kind, importance, confidence, tags, the session it came from, the quotes and message references that ground it, its outcome, when it was last used and how often.
How lessons reach a session
Before each of your requests, Besydr chooses lessons and sends them to the agent as text in its context.
- On the first request of a session, a model call turns your request into search keywords, and lessons are ranked by keyword match and by similarity of meaning, with newer and more important lessons ranked higher. Later requests use similarity alone, with no extra model call.
- Global lessons are considered on every request. Your rules for the current project and role that were not chosen by relevance fill the room that is left, by importance.
- The whole pack is at most 2,000 tokens, of which global lessons may use at most 512. Whole lessons are admitted, never cut. A lesson that does not fit stays in the store.
- The decision model drops project lessons that do not bear on the request.
[decision] recall = falseturns this filter off. When the model is unavailable, no lesson is dropped. - Each pack replaces the one before it. After a compaction, the next request recalls again.
- A recalled lesson is information for the agent, not an order. A lesson earns credit only when the agent reports that it used it, and the completion check passes. Lessons that came from your own quoted words are never lowered by a failed turn.
The agent has no tool to search the store. Besydr alone decides what enters its context.
Keeping the store small
Besydr keeps a bounded number of lessons per project, role and kind. When a limit is passed, it first asks the model for a shorter merged record from two similar project facts or work memos; a second check must confirm that the merge adds nothing and loses no condition. Rules you stated are never merged. If the store is still too large, the least useful records move to .archive/ in the same folder. A weak lesson (importance 0.4 or lower) that was not used for 90 days moves there too. Archived files are kept. Besydr never deletes a lesson itself; only the commands below do.
A project rule that appears in three or more projects can be moved to the global folder, but only after a model check confirms that it governs how you work everywhere.
Inspect and remove lessons
In octomind, the command /learning works on the lessons of the current role and project plus the global lessons.
| Command | Effect |
|---|---|
/learning or /learning list [page] |
List lessons, 15 per page. |
/learning list *pattern* |
List lessons whose text, title or tags match a pattern, such as *auth*. A page number may follow. |
/learning show <number> |
Show one lesson in full, with its file path, evidence and outcome. Also get. |
/learning delete <number> |
Delete one lesson. Also rm and remove. |
/learning clear |
Delete every lesson of the current role and project. Global lessons stay. |
show and delete count from the full, unfiltered list: your project's lessons first, then global ones, each by importance. Numbers from a filtered list are not valid, and numbers can change when background learning adds a lesson. List without a filter, check the lesson with show, then delete.
The adapters for Claude Code, Codex, OpenCode and pi do not offer /learning, and Besydr has no other command for lessons. With those clients, read or delete the files in the folders above, and remove a project's lessons by deleting its folder.
Lessons octomind learned
The first time besydr serve starts (the shared server that every client uses), Besydr copies the learning folder of octomind's data directory into its own data directory, if both are true: octomind has such a folder, and Besydr has none yet. The copy is complete or not made at all: it is built in a temporary folder and moved into place at the end. Symbolic links are skipped. When something is imported, the log says Imported <n> lesson files from octomind. The import runs once; later lessons of octomind are not copied. The import happens before the server accepts its first client, so it only runs when Besydr has no learning folder yet; a folder you created by hand blocks it.
Generated rules (evolution)
Setting: [learning.evolution] enabled, default off.
When on, Besydr may compile grounded lessons into candidate skills, guidance and guards (a guard is a pattern that denies a matching tool call). A candidate is checked, then run in a trial before it is kept:
- In a shadow phase, Besydr only records when the candidate would have applied.
- After
min_samplesresults, a trial starts. Each session is randomly put in a treatment group (the candidate applied) or a control group (it is observed but withheld). - Both groups are scored on the completion check's result and on the number of model calls.
- The candidate is kept if it beats the control group by more than
noise_marginand by more than 2.5 standard deviations at an acceptable cost, or if it saves more thancost_allowancemodel calls at an equal pass rate. It is retired if it is worse, or ifmax_trial_usesuses pass with no decision. Unused candidates retire after 90 days.
Generated behavior never overwrites skills or rule files you wrote. It needs [gate] enabled = true, because trials are scored by the completion check. In octomind, /learning evolution lists candidates for the current project and role; show <id> inspects one; approve <id> moves a shadow candidate into a trial; reject <id> rejects one; rollback <id> moves a trial or active candidate back to shadow; distill starts a synthesis over the whole store in the background.
The numbers in the template (10 results, 0.15, 0.10, 2.0, 40) keep octomind's values. With them, a behavior with no effect was promoted in under 5% of simulated trials.