How it works
What gets learned
Learning runs deterministic patterns first, then optionally a model — because a model is a good judge and a poor witness, and a fact plainly stated must never depend on it agreeing to store it.
On this page
Patterns first, then optionally a model
Learning runs deterministic patterns first, then optionally a model. The order is the point. A model is a good judge and a poor witness, because it can refuse, hedge, or return nothing — and a fact the user plainly stated then never gets learned at all.
With no model configured the service is not degraded, it is rules-only, and GET /api/v1/health says so: extractor: "rules-only". That field is the first thing to check when extraction looks broken.
The rules
| Rule | What it catches |
|---|---|
| URLs | Unambiguous. A host with a dot in it is captured whole, so a value like internal-hbr-2291.pineapple.example is never truncated at the first period. |
| Stated requirements | always / never / must / should / make sure to — kept in your own words, because paraphrasing once turned “Never force push” into “requires: force push”. |
| Assignments | “X is Y” where Y is identifier-shaped. Function words and filler are rejected, so “this is fine” never becomes a memory. |
| Model extraction | Optional, on top. Project facts, preferences and constraints the patterns cannot see — with the user’s statement treated as the signal, not the assistant’s confidence. |
Identifier-shaped is doing real work in that third rule. “X is Y” is the shape of almost every English sentence, so the constraint is on Y, not on the pattern.
Three things are always refused
Refusals are returned with a reason rather than dropped, so a caller can tell a deliberate decision from a bug.
{ stored: [], skipped: [{ reason: "question-turn", detail: "…" }] }Instructions about this conversation. “Do not verify this against the repo” is a request about how to behave right now, not a durable fact about the project. Learning it would make it permanent, which is the opposite of what was meant.
Turns whose message contains a question. A question is a lookup, not a lesson. Extracting from recall turns stored the assistant’s own answers back as memories, which duplicated facts and evicted the real ones — so a turn with a question is skipped entirely.
Anything interaction-scoped. Returned as a rejection with a reason, not silently absent.
From statement to stored fact
After capture comes reconciliation against everything already held, then filing into a tier. Reconciliation is where the interesting failure lives, and it is worth reading before adding facts faster than the store can absorb them.
To see what a turn actually produced, record it and read the response: POST /v1/turns returns what was stored, what was merged and what was rejected, with reasons. The activity log keeps the same record per turn, with the block that was sent.