How much of a store has been rewritten
revisions answers revised out of total: how many memories in a store were altered after they were written. It is worth asking before leaning on memory for something that matters, or when a recalled fact does not fit what the user is saying now. A store where three in ten facts have been replaced deserves less confidence than one nobody has edited.
Supported on Tablet 2 and newer. Callable over the HTTP API, from the Python, TypeScript and Rust SDKs, and as an MCP tool. Older engines answer 501 and name the model that cannot serve it.
Counts
It counts what a transform touched - superseded, updated, retracted, and images removed.
mem.revisions()
# {"revised": 3, "unrevised": 37, "total": 40, …}| Field | What it means |
|---|---|
| revised | Memories a transform has touched. |
| unrevised | Memories nothing has touched since they were written. revised + unrevised always equals total - it is derived, not counted separately, so a concurrent write cannot make the three disagree. |
| total | Memories in the store. |
| counts / excludes | Plain sentences, not flags, spelling out what the numbers cover. The caller is often a model. |
Reading the list
Pass include to get the memories themselves, not just how many. Omit it and you get counts only, which is the cheap call.
page = mem.revisions(include="revised", limit=20)
page["memories"], page["matched"], page["has_more"]| Field | What it does |
|---|---|
| include | "revised" or "unrevised". Any other value is refused with a 400 rather than falling back to counts - a typo that silently drops the list looks exactly like an empty store. |
| limit | 5 to 20, default 20. Out of range, or the wrong type, is refused rather than clamped. |
| matched | Total rows behind this page, not the size of the page. |
| ordered_by | The service states its own ordering: newest stored first, not most recently edited. |
| next_before | Cursor for the next page, with next_skip_ids. Hand both back; ids accumulate across pages. |
The list is ordered by when a memory was stored, not when it was changed. A caller who assumes "most recently edited first" reads the page wrong, which is why the response says which it is.
Deletions are not counted. A deleted memory leaves nothing to count, so a store that was heavily pruned still reports a low
revised. This number tells you how much was rewritten, not how much is gone.