Module vocabulary 

An inventory of what a user’s memory contains, for the model to read.

Why this exists

recall_context lets the model narrow a search by about and attribute. Those are only useful if it can name the values, and it cannot guess them: the corpus files a haircut under barber and a coffee order under beverage_preference, and a model asked to invent those from an utterance produces something reasonable and wrong.

Measured over 93 questions (tests/memory_map_probe.rs), asking gemini-2.5-flash-lite to fill the filter fields:

condition	about	attribute	about + attribute
with no map	49%	2%	2%
with this map	67%	69%	48%

attribute goes from 2% to 69%. That is the difference between a filter that costs more than it earns and one that pays: with the filter applied as a soft ranking, break-even is 8% accuracy, so 2% is a net loss and 48% is worth about five questions on top-5.

It is a fixed cost

The map is bounded by the user’s vocabulary rather than by how much they have accumulated — people acquire more facts about the same handful of people and properties, not endlessly more kinds of thing:

records	subjects	predicates	map tokens
250	38	16	242
1,000	42	16	262
16,000	42	16	282

Flat from a thousand records up.

Where to put it

In the system instruction, not the tool description. Live sessions fix tool declarations at connect time and the corpus grows while the session runs, so a map in the schema goes stale and cannot be refreshed. Instructions can be updated mid-session. It is also set once and cached rather than resent per call, which is what makes 282 tokens the whole price.

Constants

DEFAULT_LIMIT

How many values of each field the map names before summarising the rest.

Functions

memory_map

Render the inventory a model needs to write filters.

memory_map_from_index

The same map, built from the live BM25 index rather than a record list.

memory_map_with_limit

memory_map with an explicit cap on values named per field.