Memory & learning
Memory
Section titled “Memory”With memory = true, koda keeps <project>/.koda/memory.md. It is plain markdown you can
read, edit or delete. Nothing is inferred behind your back and nothing is hidden — if you
want to know what koda thinks it knows about your project, you open the file.
It records three things:
| Kind | Source | Cap |
|---|---|---|
| Notes | Facts the agent recorded through the remember tool. Say forget with a phrase to drop one. |
60 |
| Commands | Which shell commands succeeded and failed here, so the next session runs your real test command instead of guessing. | 40 |
| Files | How many times each file has been edited, so koda can orient at the parts of the project you actually work in. | — |
The file count is observed fact, not inference about intent: koda knows you edit
src/context.rs a lot; it does not claim to know why.
The memory block in the prompt scales with the window — one remembered fact per roughly 1k of context, between four and twenty — so a small model does not spend its context on notes instead of on the task.
Learning from how you work
Section titled “Learning from how you work”learning = true (off by default) goes a step further: koda watches how you work and
distils explicit, inspectable rules it can follow next time. It is fully local — no
model, no network — and every artifact is a plain file under <project>/.koda/learning/
you can read, edit or delete.
What it observes
Section titled “What it observes”observations.jsonl records the raw signals, append-only and greppable: the edits koda
made (the before and after of a write), which commands succeeded or failed, and approvals
you denied.
What it induces
Section titled “What it induces”At the end of each turn koda mines those observations, deterministically, into candidate rules. A rule needs repeated evidence before it is proposed, so one-offs are ignored.
From your corrections. koda remembers what it last wrote to each file, under
last_writes/, so this survives a restart. When you change that file yourself — swapping
koda’s logging for your internal log.audit, say — koda notices the difference next
time it reads or edits the file and, after you have made the same kind of change a couple
of times, proposes “prefer log.audit over logging.” This is the strongest signal for
adapting to your style. koda only acts on changes it can attribute clearly, a single
swapped token; it never guesses.
From your project’s shape. koda reads the code graph and notices
the internal helpers and modules that are load-bearing here — a function defined once and
called across many files, a module imported everywhere. That becomes “log_audit is a
load-bearing function here — prefer it over reinventing an equivalent,” so koda reaches
for your project’s own tools instead of generic ones. Once per session, from the graph, no
model involved.
From what actually works. The command that succeeds here, and the ones that only ever failed. The project’s function-naming convention. Library preferences.
How a rule gets promoted
Section titled “How a rule gets promoted”Nothing takes effect until it is promoted, and there are two paths.
You promote it. /learn lists the candidates. /learn accept <n> or /learn all
accepts; /learn reject <n> drops one. Accepted rules are written to rules.md and
injected into the system prompt.
It earns it. With learning_daily = true, once a calendar day koda promotes
candidates that have been re-derived on learning_promote_days (default 3) different
days — a habit, not one busy afternoon. Auto-promoted rules are marked auto in
rules.md, take effect immediately, and are recorded in journal.md: a plain, dated
record of what koda has learned about your project.
If an auto-promoted rule stops being reinforced for learning_retire_days (default 30) it
drops back to a candidate. Rules you accepted yourself are never retired. Set
learning_daily = false to keep promotion entirely manual.
The kill switch
Section titled “The kill switch”Set learning = false, or delete .koda/learning/, and the whole loop is gone with no
residue. If you edit or delete a rule, that is authoritative.
Which mechanism for which thing
Section titled “Which mechanism for which thing”| You want koda to remember… | Use |
|---|---|
| A fact — the staging URL, the ticket prefix | remember, or edit memory.md |
| A style rule — prefer this helper over that one | learning + /learn, or a skill |
| A procedure — how to cut a release here | A skill |
| A rule that must always apply | instructions in the config, or AGENTS.md |