Memory

A memory is a list of lines that belongs to one subject of one tenant: facts, events your software reports, rules with conditions, decisions you choose to keep. It lives in RAM on the machine that runs Jers and is flushed to disk in the background.

What a subject is

Anything you decide about more than once and know things about:

The id is yours: letters, digits, underscore and hyphen, up to 36 characters, scoped to your tenant.

Writing

POST /v1/memory/remember
{"subject": "acme", "text": "ACME Logistics holds an enterprise contract.\nRefunds for ACME go to the billing team within one business day."}

One fact per line; several lines per call. Write what is true or what to do. A line that forbids something names it, and naming an option pulls the engine toward it: in the Jers Dungeon demo the line "Never walk along the corridor with the gold coins." raised the coins from 83% to 94% (measured 2026-09-23). When an option must never be chosen, leave it out of the question in your code; a memory line cannot guarantee it (see Rules in memory). remember returns a memory_negative_rule warning for such lines, and memory_number_rule for lines that compare numbers in words; put those in a rule instead (see Rules in memory). Each subject holds up to 10,000 lines; a write that would pass that stores nothing (409). A line has at most 2,000 characters; a longer line refuses the whole write (422).

Using

Add "subject": "acme" to a decision. Jers recalls the lines that share names and phrases with the state, places them before the state (see State), and asks the engine. Recall takes up to memory.top_k lines (1 to 20, default 6) that reach memory.min_share of the best line's score (0.05 to 1, default 0.2). "memory": {"use": false} answers without the subject's memory and rules.

"memory": {"subject": "acme", "lines_used": 2, "lines_seen": 2, "lines_dropped": 0, "recall_ms": 0.2,
           "hits": [{"text": "ACME Logistics holds an enterprise contract.", ...}],
           "rules_fired": [], "rules_broken": [], "without_memory": null, "changes": null}

lines_used is how many lines were sent to the engine, fired rules first, then recalled lines; lines_seen how many of them the engine read; lines_dropped how many did not fit in its 64 context lines (computed facts, then fired rules, then recalled lines, each line at most 2,000 characters). lines_seen is lower than lines_used when the lines and the state together are longer than the engine reads (see State); the memory_cut and memory_full warnings say so.

When a subject holds lines about several similar situations, raise min_share so that only the lines about this one are read. In the Jers Dungeon demo (three rooms, one lesson line each), lines about the other rooms could pull the Coin Hall answer back to the trap; with "min_share": 0.5 only the Coin Hall line was read and the hero took the stair (64%, checked by the demo's test).

Checking what the memory did

• "memory": {"compare": true} also asks without the memory: without_memory and changes show per question what the memory changed. A tenant temperature (Quality) is applied to both answers alike, so the comparison shows only what the memory did. The second call is free.
• "memory": {"placebo": true} also asks with neutral lines instead of yours: each line becomes "<the name it starts with> has a record in this system.", for example "North Traders has a record in this system.". placebo.content_effect is the change the lines' content caused, memory_effect the change the whole memory caused, and presence_only lists questions that moved as much with neutral lines as with the real ones: there the memory worked by being present, not by what it says. The placebo pass is billed as answers.

Reading and forgetting

GET  /v1/memory?subject=acme&lines=true      every stored line and rule, word for word
POST /v1/memory/forget   {"subject": "hero", "concept": "Coin Hall plain stair"}
POST /v1/memory/delete   {"subject": "hero"}

forget removes every line that contains all the content words of the concept, and every rule whose text does, then checks recall: verified_forgotten is true only when recall, asked with the concept, with questions built from it and with the rest of each removed line, returns no line that still holds all the concept's content words, and no rule still holds them; leaks lists any that do. In the Jers Dungeon, after "In the Coin Hall, the hero always goes down the narrow plain stair." was forgotten, the next decision took the gold coins again, as it did before it was taught. delete removes the whole subject, its lines and its rules, from RAM and disk. Both are immediate. What they do not remove: the tenant's ledger keeps the subject id on each priced request, and batches and golden cases keep the requests that named it until you delete them.

Isolation

Inside the gateway every subject id is prefixed with your tenant, so acme at one tenant and acme at another are different memories, and no request can name another tenant's subject.

What recall is and is not

Recall matches words and short phrases. A fact worded very differently from the state is missed, so use the names and terms your states use. It returns lines to show the engine, and the answer says which ones. What the engine then does with a line is the subject of Rules in memory.