# 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 Jers's server and is flushed to disk in the background.

## What a subject is

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

| Subject | Lines you would write | A decision that uses them |
|---|---|---|
| a customer account | contract terms, who handles it, past incidents | which team, how urgent, escalate or not |
| a user of your app | preferences, opt-outs, plan | send this mail, show this offer |
| a player in a game | deeds, reputation, what killed them last time | how a character treats them, which way to go |
| a device or machine | normal ranges, last service, known faults | alert, ticket, stop |
| a case or claim | what is already known, who asked to be told | next step, escalate |

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

## Writing

```json
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.

```json
"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

```json
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.