Memory
Memory is how a project gets better at its own documents over time. When a transaction is reviewed and approved, the system can keep it as a sample: the document text paired with the field values a person confirmed. Later, when a similar document arrives, the closest samples are placed into the extraction prompt so the AI sees a real, corrected example of exactly this kind of document before it answers.
The effect is cumulative. A project with a handful of good samples for an unusual supplier layout stops making the same mistake on that layout.
Memory lives on the Memory page, under Design.
Where samples come from
There are three ways a sample enters memory:
| Source | When |
|---|---|
| Playground | Always. Anything you process and correct in the playground is captured. The playground is never capped and is not affected by the production settings below. |
| Production | Only when all the conditions in What production needs in order to learn are met. |
| Manually | A user with the "System can learn from user" permission can add a transaction to memory directly, or copy transactions into memory from another dataset. See Adding transactions by hand. |
Adding transactions by hand
Adding a transaction from My Work Queue works like production learning, because it is the same act done by a person: when production would learn right now, the transaction goes straight into production memory, with the same limits. That is when all of these hold:
- document examples are on, and What Memory collects is not Nothing, in the version the transaction ran on;
- learning is not paused;
- the transaction is waiting at a review step or completed. You can add one while you are still reviewing it: you answer for the data it holds;
- the draft memory has no unpublished change to that sample of its own.
Otherwise it goes into the draft memory and reaches production when the project is published. After adding, a message says how many went into the draft.
A transaction added to memory stays the same sample however often you add it. Keep reviewing and add it again, and the new data replaces the earlier sample; when the transaction is approved and production learns it, that replaces it too.
Transactions copied from Playground or an evaluation dataset always go into the draft memory.
What production needs in order to learn
Production learning is deliberately conservative, because it retains reviewed customer documents. Four conditions must all hold. If any one fails, the transaction completes normally and nothing is captured, silently.
- Document examples are enabled for the project.
- What Memory collects is not Nothing in the published configuration, and it covers whoever took the transaction's final review decision (see What Memory collects).
- Learning is not paused by an operator (see Pausing learning).
- Whoever took the final review decision may teach memory (see Who may teach memory). For a person, that is the "System can learn from user" permission.
Condition 4 is the one that catches people out. The built-in Reviewer role does not include "System can learn from user". If your reviewers hold only that role, every transaction they approve is discarded and memory stays permanently empty, with no error shown anywhere.
The fix is a permissions change, not a memory setting: add the System can learn from user grant to the reviewing role in Team → Roles. Among the built-in roles, Admin, Designer, and Supervisor already have it.
Condition 2 has its own trap: project settings are saved to the draft, and production runs the published version (Versions and Publishing). Changing what Memory collects and not publishing changes nothing in production.
What Memory collects
A project setting with three choices, on the Memory page's Settings tab, in the Extract step and in the publish dialog:
| Choice | What production adds to memory |
|---|---|
| Nothing | No samples. The samples already stored are kept and still used. |
| After a person's review (default) | A completed transaction whose final review decision a person took, when that person may teach memory. Every correction in it is collected, including those an agent made at an earlier step, since the person saw and kept them. A transaction the person only confirmed is collected too: a confirmed transaction is a verified example. |
| Every correction | Also a transaction an agent decided alone at an Agent Review step, when the agent may teach memory and changed data at that step. |
Under Every correction, a transaction an agent decided is collected only when the agent changed values, classes or documents at its own step: an agent that approved the data as it was teaches nothing, and changes made at other steps are not counted as the agent's. The comparison uses the checkpoints taken before and after the Agent Review step; a transaction without both is not collected, and the Monitoring page says the agent's changes could not be checked.
A transaction that left an Agent Review step on Not reviewed has no decision, so it is collected only after a later review.
Who may teach memory
| Who took the final decision | May teach memory when |
|---|---|
| A person | The person has the "System can learn from user" permission. |
| A person through an assistant (signed in, or on a personal API key) | The person has the permission, and so did the connection when they decided: an assistant connected with fewer permissions, or a personal key whose permissions leave it out, decides but does not teach. |
| An agent on an integration key | The key is still active, not expired, allowed in the project and has the "System can learn from user" permission. Agents teach only under Every correction. |
| The built-in agent | Its step's Memory may learn from this agent was on when it decided (on by default). Agents teach only under Every correction. |
An integration key's permissions are changed on the Agents & API page: see Managing API keys.
Who can do what
| Capability | Permission | Built-in roles |
|---|---|---|
| Open the Memory page, view and manage samples, change memory settings | Manage memory and System can learn from user | Admin, Designer |
| Cause learning: transactions this person approves may be captured. Also allows adding transactions to memory by hand, and editing a transaction in memory, including one opened with the Similar tool | System can learn from user | Admin, Designer, Supervisor |
| See whether a project is still learning, and why it is not | View memory learning status | Admin, Designer, Supervisor |
| Pause and resume learning without publishing | Pause and resume memory learning | Admin, Designer, Supervisor |
Custom roles can be given any of these. What a transaction in memory holds is what the system learns, so the Memory page and every change to a memory transaction need System can learn from user: only someone the system may learn from changes it. Without it, a transaction opened from memory is read-only. Note that "View memory learning status" and "Pause and resume memory learning" are operational permissions: they let a supervisor watch and stop learning from the Monitoring page without being handed the design-time Memory page.
The Memory page
Three tabs:
- Dataset lists the transactions held in memory, with the same table controls as any other transaction list (views, filters and custom columns all apply). Open one to inspect or correct the values it teaches.
- Similarity plots the samples as a cluster map, so you can see which document types are densely covered and which are represented by a single sample.
- Settings holds the production learning controls described below.
Memory versions
Memory is versioned along with the project. The version selector next to the page title switches which set of samples you are looking at:
- Draft is your working set. Every change to memory is made here, whichever version you are looking at, and does not affect production until you publish.
- Production is the set production is retrieving from right now. It changes when you publish, and when production learns, by itself or from a transaction you add from My Work Queue.
- A release number is the frozen set that shipped with that published version.
Publishing the project publishes the memory draft along with it. Rolling back a version rolls memory back too.
The Settings tab has no version selector, because settings are not per memory version: they are ordinary project settings that are saved to the draft and take effect when you publish.
Changing a sample
Every change to memory is made in the draft, whichever version you are looking at, and production memory changes only when you publish. That covers marking a sample golden, reverting it to a published version, deleting it and adding samples, as well as every change to what a sample holds. If you make one of these changes while looking at Production, the Memory page switches to the Draft and tells you the change was made there.
Every change to what a sample holds is made in the draft, whichever version you opened it in. That covers editing a value or a box, changing a document's class, adding or deleting table rows, rotating, moving or deleting pages, creating, deleting or merging documents, confirming values, and re-running the sample or one of its documents, whether you make the change or the Assistant does. Production memory changes only when you publish.
- A sample that production or a published version still uses gets its own draft copy first, and the change is made there. If you opened the sample in the Production view, the Transaction Viewer moves to the Draft view and tells you the change was saved to the draft.
- After each change the sample's examples are rebuilt from what it now holds, so its data and the examples the system learns from always match.
- A release is read-only. A sample you removed from the draft can't be changed from the Production view, because there is no draft copy to change.
Changing a sample needs System can learn from user.
Golden samples
A sample can be marked golden. Golden samples are never evicted when a cap is reached and are never dropped automatically. Use it for the handful of examples that represent a difficult document type correctly, so routine churn cannot push them out. Like every change to memory, marking or unmarking one is made in the draft; production follows when you publish.
Re-running samples
Re-running rebuilds a sample's examples with the project's current settings, for example after you switch Extract to a better model. Select samples and choose Re-run in the toolbar, or use a row's Re-run. It works like the Re-run menu elsewhere: from the beginning, or from after a step. It is offered while you look at the draft.
A re-run changes the draft memory only. A sample that production or a published version still uses gets its own draft copy first, exactly as when you edit it, so what is published stays as it is until you publish again. The sample's examples are replaced by what the re-run extracts. If it extracts nothing, the sample stays in Memory with no examples, so the examples always match what the sample shows.
Re-running one document from the Transaction Viewer works the same way: it runs on the sample's draft copy, and the sample's examples are rebuilt when it finishes, or put back as they were if it fails.
Re-running a sample needs System can learn from user, like editing one. The Assistant re-runs a sample the same way when you ask it to, and moves the Transaction Viewer to the draft copy when it makes one.
Settings
On the Memory page
The Settings tab carries the three controls that matter day to day. Changes save as you make them, to the project draft.
| Setting | What it does |
|---|---|
| What Memory collects | Nothing, After a person's review (default) or Every correction: see What Memory collects. With Nothing, production stops adding samples and everything already stored is kept and still used. The playground is captured either way. |
| Max samples per document class | Cap on production samples stored for each document class. |
| Max samples overall | Cap on total production samples across all document classes. |
In the Extract step
The full set of options lives in the workflow designer, in the Extract step's configure panel under Document Examples. This is where you enable the feature and tune how samples are used:
| Setting | What it does |
|---|---|
| Enable | Master switch for document examples. |
| Use examples in this step | Whether stored samples are injected into this Extract step's prompts. It belongs to the step, so two Extract steps can differ. Turning it off keeps memory intact but stops using it, which is a useful way to test whether memory is helping. |
| Memory collects | The same setting as "What Memory collects" on the Memory page. |
| Max examples in prompt | How many samples go into each extraction, from 1 to 3. More samples means more tokens and higher cost per document. |
| Similarity threshold | How close a stored sample must be to the incoming document before it is used. Raise it if irrelevant samples are being pulled in. |
| Dedup threshold | How similar a new document must be to an existing sample before it is treated as a duplicate and not stored. Lower it if memory is filling with near-identical documents. |
| Page selection, First pages, Last pages | Which pages of the sample document are stored and shown to the model. |
| Send example images, Max image pages | Whether page images of the sample are included alongside its text. |
| Include field groups | Whether group and repeating-group fields are part of the stored sample. |
| Training dimensions | Fields that split the caps and retrieval into separate buckets, for example one bucket per supplier. |
Settings save to the draft
All of the above except Use examples in this step, which is the step's, are project settings. Both are saved to the draft and production keeps running the published configuration until you publish a new version. If you change a cap or what Memory collects and nothing happens in production, publishing is almost always the missing step.
Caps and what happens when memory is full
The two caps bound how large production memory can grow. They apply to production samples only; the playground is never capped.
When a cap is reached, memory does not stop working and does not stop accepting new samples. Each new sample evicts an existing one, choosing the least useful first: samples that are rarely or never retrieved go before samples that are used often, and among unused samples the oldest goes first. Golden samples are never evicted.
A project sitting at its cap looks, from the outside, exactly like a project that has stopped learning: the sample count stops rising. It is not a fault. If memory should hold more, raise the cap and publish.
Lowering a cap does not just stop growth. The next time capture runs, samples above the new limit are permanently removed. Mark anything you cannot afford to lose as golden first.
Pausing learning without publishing
Sometimes you need learning to stop now, for example when a batch of bad extractions is being approved and you do not want it taught. Publishing a project just to stop learning would also ship every other unfinished draft change.
Instead, pause it. On the Monitoring page, the Memory learning section has a Pause button for anyone with the "Pause and resume memory learning" permission. Pausing:
- takes effect immediately, with no publish;
- stops new samples being captured, and leaves everything already stored in place and still in use;
- survives a publish, so shipping a new version will not silently restart it;
- stays in effect until somebody resumes it.
While a project is paused, the Memory page's Settings tab shows a notice saying so, so the two pages cannot appear to contradict each other.
Resume returns the project to its published configuration. It does not turn learning on. If the published configuration has document examples disabled or collects nothing, resuming changes nothing, and the settings plus a publish are what you actually need. This is deliberate: retaining reviewed customer documents is a decision that should carry a published version, so there is no runtime switch that can start it.
Why is memory empty?
Work through these in order. The first one that is true explains everything below it.
- Is learning paused? The Monitoring page's Memory learning section shows the state, who paused it, and when.
- Does the published configuration collect anything? Check What Memory collects on the Memory Settings tab, then check that the project has been published since you last changed it.
- Can your reviewers teach memory? This is the most common cause. See the warning in What production needs in order to learn.
- Is memory at its cap? Then it is working, not broken. Raise the cap or prune.
- Is anyone actually reviewing? Memory only learns from transactions someone decided: a person, or under Every correction an agent that changed data. Unattended and API-submitted transactions that complete without a review step are never captured. That is expected behaviour, but it does mean memory stays empty until the workflow has a review step.
The Memory learning section on Monitoring answers 1, 3, and 5 directly: it counts, per reason, why each completed transaction of the last seven days was or was not captured. See Monitoring.
Ask the assistant
The in-app assistant can do all of this. Useful things to ask:
- "Why is memory empty for this project?" It runs the full checklist above and names the cause.
- "Is this project still learning into memory?"
- "Pause memory learning, we are getting bad approvals."
- "Raise the total sample cap to 5000."
It reads the published configuration rather than the draft, so its answer reflects what production is actually doing, and it will tell you when a change needs publishing.