Simple memory system: let Jev decide what to remember
💡 One-sentence summary: use Jev to build an AI memory system — a Noul gate decides what to remember, memories are stored in a plain Python dictionary, and they are automatically merged into the state before each call.
Every Jev request only sees the state you send it. What the customer told you last month — which version they use, which plan, whether they signed a contract — is not in the next request unless your code puts it there.
The official cookbook (Simple memory system) takes a plain approach: one extra Jev request per call, plus a Python dictionary.
Its example scenario is support-ticket routing. In month 8, the customer says they self-host on Windows Server; in month 9, they write "Dashboards have been really slow since this morning". Without memory, Jev sends this ticket to the cloud team; with memory, all six follow-up tickets are routed to the expected team — each routed individually, and only three of them actually use memory.
This AI memory system has just two parts:
- After the call: Jev looks at the raw request and its own answer and answers one Noul — officially called the gate: does this request state a customer fact worth remembering? If P(yes) ≥ 0.5, the ticket is stored along with the answer as that customer's memory
- Before the call: add that customer's stored tickets (with Jev answers) into the state — wrapped in
ask_with_memory(), with parameters and return value identical toask()
ask_with_memory(state, questions)
│
▼ ① state + the customer's stored memories (sent as-is if there are none)
Jev request 1: answers your question (in this example: which team should take this ticket)
│ ② the raw request + the Jev answer, paired together
▼
Jev request 2: the gate (one Noul) — does this request state a customer fact worth remembering?
│
▼ ③ P(yes) ≥ REMEMBER_AT (0.5)? — your code decides
Yes ──┤── No ──┐
▼ │
Stored in MEMORIES │
(one list per customer ID)
└──────┬────────┘
▼
④ the answer to request 1 is returned as-is, and your code acts as usual
↺ stored memories go into that customer's next request (back to ①)This wrapper function, ask_with_memory(), is a minimal agent harness. Official definition: a harness is code around the model that gives it extra capabilities (tool calls, running in a loop). The harness on this page only provides memory — a plain Python dictionary, one list per customer ID. To see a harness that adds tool calls to the model, go to the previous lesson Agent decisions.
This lesson takes about 15 minutes. All numbers on this page come from the official cookbook's recorded data (jev-1.14.0, 2026-10-29): after deduplication, the official recording files contain 31 calls totaling 21,456 input tokens — at $42/Btok with free output, about $0.0009. The recording files ship with the official repository, so you can replay and verify them with zero keys.
What you'll be able to do after this lesson
- Add memory to any "Jev judgment + customer history" system: after each call, a Noul gate decides whether to remember; before each call, stored memories are merged into the state —
ask_with_memory()has the same parameters and return value asask(), so you can swap it in without changing other code - Make "what to remember" an explicit question (GATE) instead of scattered rules: persistent facts like version, plan, and contract are stored with 0.96–0.98; airport phone and public holiday get 0.02, 0.03 and are not stored
- Reproduce the official test yourself: the same "dashboards are slow" message — bare Jev routes to the cloud team 0.55, while with memory it goes to the Windows self-hosting team 0.98 — six follow-up tickets go from 3/6 to 6/6
- Explain the five limitations of this system (two serial requests per call, memory only grows and never shrinks...), and know the official next steps for upgrading memory (relevance-based selection, replacing old memories, switching databases)
Why use Jev instead of stuffing all history into the prompt?
| Capability | Stuff everything into the prompt / let a chat model remember on its own | Jev gate memory |
|---|---|---|
| Who decides what to remember | ❌ Store everything: airport phone and public holidays also take up context; chat model memory: what gets remembered depends on the model's mood, and the output can't be audited | ✅ A Noul gate gives a probability: what should be remembered 0.96–0.98, what shouldn't ≤ 0.04, with the threshold in your code |
| Are the probabilities trustworthy | ❌ Have the model write its confidence as text, then pray the parsing doesn't break | ✅ RLCD calibration training: probabilities are aligned with real outcomes, so the P ≥ 0.5 threshold actually means something |
| As history grows | ❌ Every request carries the entire history; tokens grow linearly with the number of tickets | ✅ Only tickets that pass the gate enter memory, and state grows with "facts worth remembering"; each call adds exactly one fixed extra gate request |
| Plugging into existing code | ❌ Change prompt templates, change the call chain | ✅ ask_with_memory() has the same parameters and same return value as ask()—in the official words: swap it in without changing any other code |
| What the gate looks at | ❌ Records the model's answer too: generic answers drown out the real facts in the request | ✅ Only counts what the customer/support staff wrote in the request; facts that appear only in the answer are never stored |
Your current predicament
- "The customer clearly stated back in 8 that they self-host on Windows Server, but when the dashboard slowed down in 9, the ticket still got routed to the cloud team—the customer had to explain their environment from scratch every time"
- "You ask a chat model to help 'remember customer information,' but what it remembers can't be audited: sometimes it treats 'posted from a phone at the airport today' as a long-term fact, other times it records its own inference from the previous turn all over again"
- "You tried stuffing the entire ticket history into every request: tokens burn faster and faster, and routing actually gets misled by irrelevant old tickets"
When to use this technique
Use this when you need:
- Your system already uses Jev to make judgments (routing, classification, verification), and the quality of those judgments depends on "who this customer is"—version, operating system, plan, contract, long-term preferences
- "What to remember" is one explicit question plus one explicit threshold—humans can audit it, check it into version control, and re-tune it at any time
- One independent memory per customer, automatically attached to new calls, without changing a single word of the question
And you don't want to:
- Stuff the entire history into every request, with tokens growing linearly with history
- Let a chat model freestyle its "remembering" and then parse the text it spits out
- Introduce a whole embedding-retrieval pipeline just for this—that's only needed once memory gets large (see advanced tips)
🎒 Prerequisites
- Completed Noul yes/no questions: the gate is a Noul—how to read 0–1 probabilities and how to set thresholds, used directly on this page
- Know that state is all Jev sees: memory is just one extra key in state, and the question doesn't need to change with it
- Got installation and the first request working:
.venvhastypesafe-sdk, andTYPESAFE_API_KEYis in the environment variables - Downloaded the official recorded cache: typesafe-public-examples repo,
cookbooks/basic_memorydirectory, filejson_cache.json, placed in the run directory—run the official code as-is, no key needed at all; delete it and everything goes through real calls - Know the cost ceiling: after deduplication the official recording makes 31 calls with 21,456 input tokens, about $0.0009 at $42/Btok, output free—see models and pricing for rates
Follow along
Step 1: Set up the environment, official cache, and five early tickets
Why: The memory system needs two kinds of tickets—early tickets that state persistent facts (to be remembered), and follow-up messages that only talk about the here and now (where memory pays off). All official data is hand-written for this example: 2 customers, 5 early tickets, 3 follow-up messages.
Create the directory, download the official recorded cache, and install dependencies:
mkdir jev-memory && cd jev-memory
curl -sLO https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks/basic_memory/json_cache.json
pip install ipython 'cooksafe>=0.2.0,<0.3.0' typesafe-sdkThe official pip line originally didn't include typesafe-sdk (the docs platform pre-installs it); we add it here.
The Setup cell (official as-is; make_playground_link and display are only used in the final Playground cell):
import json
import os
from pathlib import Path
from cooksafe import JsonCache, make_playground_link
from IPython.display import Markdown, display
from typesafe_sdk import Choice, Noul, NoulCriteria, SystemOneResponse, TypeSafeClient
TYPESAFE_MODEL = "jev-1.14.0"
REMEMBER_AT = 0.5 # save when P(lasting customer fact) reaches this starting threshold
MEMORY_KEY = "earlier_tickets_from_this_customer" # where saved tickets go in the state
client = TypeSafeClient(
api_key=os.environ.get("TYPESAFE_API_KEY", "cache-only"), # keyless kernels replay the cache
base_url=os.environ.get("TYPESAFE_ENDPOINT"),
timeout=120.0,
)
json_cache = JsonCache(Path("json_cache.json"))Three constants each handle one thing: TYPESAFE_MODEL pins the version (the official recording used jev-1.14.0 for the numbers); REMEMBER_AT = 0.5 is the gate's starting threshold for storing memory; MEMORY_KEY is the key name used when memory goes into state. "cache-only" is the default value the officials left for the key—when the cache hits, no request is sent at all, so every number on this page can be reproduced with zero keys.
Two customers, five early tickets, three follow-up messages (official DATA as-is; expected_team is hand-labeled based on what each customer said in their early tickets):
DATA = {
"customers": {
"C-1042": {"id": "C-1042", "company": "Acme Corp"},
"C-2210": {"id": "C-2210", "company": "Example Studio"},
},
"earlier_tickets": [
{"id": "T-101", "customer_id": "C-1042", "received_on": "2026-08-04",
"subject": "Adding an admin",
"text": "Hi, we run your self-hosted edition on Windows Server 2022 in our own data "
"centre. How do I add a new admin user?"},
{"id": "T-102", "customer_id": "C-2210", "received_on": "2026-08-11",
"subject": "Exporting to PDF",
"text": "We're a small design studio on your cloud edition, paying monthly on the "
"self-serve Team plan. How do I export a dashboard as a PDF?"},
{"id": "T-103", "customer_id": "C-1042", "received_on": "2026-08-19",
"subject": "Invoice download",
"text": "Sorry for the typos, typing this on my phone at the airport. Where can I "
"download last month's invoice?"},
{"id": "T-104", "customer_id": "C-2210", "received_on": "2026-09-02",
"subject": "Dark mode?",
"text": "Our whole team is out on Friday for a public holiday, so no rush on this "
"one. Is there a dark mode?"},
{"id": "T-105", "customer_id": "C-1042", "received_on": "2026-09-10",
"subject": "Sandbox environment",
"text": "For context, we signed an Enterprise contract with you in March. Can we get "
"a sandbox environment for testing?"},
],
"later_messages": [
{"subject": "Slow dashboards",
"text": "Dashboards have been really slow since this morning."},
{"subject": "Upgrade failing",
"text": "The upgrade to version 5.2 keeps failing halfway through."},
{"subject": "More seats",
"text": "We'd like to add 20 more seats before next quarter."},
],
"later_received_on": "2026-09-28",
# Labelled by hand from what each customer said in the earlier tickets.
"expected_team": {
"C-1042": {"Slow dashboards": "selfhosted_windows",
"Upgrade failing": "selfhosted_windows", "More seats": "enterprise_desk"},
"C-2210": {"Slow dashboards": "cloud_ops", "Upgrade failing": "cloud_ops",
"More seats": "billing"},
},
}
CUSTOMERS = DATA["customers"]
def ticket_state(customer_id: str, ticket_id: str, received_on: str, subject: str,
text: str) -> dict:
"""The state Jev sees for one ticket: a simplified ticket, like one from a helpdesk."""
return {
"customer": CUSTOMERS[customer_id],
"ticket": {
"id": ticket_id,
"received_on": received_on,
"subject": subject,
"messages": [{"from": "customer", "text": text}],
},
}
EARLIER = [
ticket_state(t["customer_id"], t["id"], t["received_on"], t["subject"], t["text"])
for t in DATA["earlier_tickets"]
]
print(f"{len(CUSTOMERS)} customers, {len(EARLIER)} earlier tickets, "
f"{len(DATA['later_messages'])} later messages. The first ticket as Jev sees it:\n")
print(json.dumps(EARLIER[0], indent=2))You should see (official release):
2 customers, 5 earlier tickets, 3 later messages. The first ticket as Jev sees it:
{
"customer": {
"id": "C-1042",
"company": "Acme Corp"
},
"ticket": {
"id": "T-101",
"received_on": "2026-08-04",
"subject": "Adding an admin",
"messages": [
{
"from": "customer",
"text": "Hi, we run your self-hosted edition on Windows Server 2022 in our own data centre. How do I add a new admin user?"
}
]
}
}Each ticket's state has just two parts (assembled by ticket_state()): customer is who's reporting, and ticket is a simplified ticket thread. The design intent of the data is spelled out by the officials: three early tickets state persistent facts—T-101 version (self-hosted Windows Server), T-102 plan (cloud self-serve Team), T-105 contract (Enterprise); two don't—T-103 airport phone, T-104 public holiday. None of the three follow-up messages mention the customer's environment, so without memory Jev can only guess.
2 customers, 5 earlier tickets, 3 later messagesprints without errors; I can point out which three tickets state persistent facts and which two don't
Step 2: First run the bare Jev router to see where it goes wrong without memory
Why: Establish the baseline first—without memory, where does this "slow dashboard" ticket get routed?
The routing question is a Choice with 7 options covering 7 support teams. Note none_suitable: the officials annotated its purpose—the destination when no team fits, where tickets with insufficient context land:
ROUTE = {
"team": Choice(
instructions="Which support team should handle `ticket`?",
criteria={
"cloud_ops": "Cloud team: problems with the hosted cloud edition, run by us",
"selfhosted_linux": "Self-hosted team, Linux: installs, upgrades and "
"performance of the self-hosted edition on Linux servers",
"selfhosted_windows": "Self-hosted team, Windows: installs, upgrades and "
"performance of the self-hosted edition on Windows Server",
"billing": "Billing: invoices, payments, seats and plan changes for "
"self-serve plans",
"enterprise_desk": "Enterprise desk: seats, contracts and account changes for "
"customers on an Enterprise contract (their technical problems go to the "
"technical teams)",
"general": "General product questions: features, how-to, settings",
"none_suitable": "None of these teams fits the ticket",
},
),
}
@json_cache
def _system_one(model: str, state: str, questions: str) -> dict:
response = client.system_one(
state=json.loads(state), questions=json.loads(questions), model=model
)
return response.model_dump(mode="json")
def ask(state: dict, questions: dict) -> SystemOneResponse:
"""client.system_one, with the model pinned and the call cached."""
as_json = {qid: q.model_dump(mode="json", exclude_none=True) for qid, q in questions.items()}
raw = _system_one(TYPESAFE_MODEL, json.dumps(state), json.dumps(as_json))
return SystemOneResponse.model_validate(raw)
def later_state(customer_id: str, message_index: int) -> dict:
"""One of the later messages, sent by this customer, with a fixed ticket ID."""
n = 201 + 3 * list(CUSTOMERS).index(customer_id) + message_index
message = DATA["later_messages"][message_index]
return ticket_state(customer_id, f"T-{n}", DATA["later_received_on"], message["subject"],
message["text"])
slow = later_state("C-1042", 0)
team = ask(slow, ROUTE).answers["team"]
print(f"C-1042: {slow['ticket']['messages'][0]['text']!r}")
print(f" plain Jev -> {team.choice} {team.probabilities[team.choice]:.2f}")ask() is just client.system_one with the model pinned on and the @json_cache cache attached; later_state() assigns fixed ticket numbers to follow-up messages (starting at T-201).
You should see (official release):
C-1042: 'Dashboards have been really slow since this morning.'
plain Jev -> cloud_ops 0.55Viewed on its own, this ticket's "slow dashboard" sounds like a cloud issue—Jev sends it to the cloud team with probability 0.55. The fact that C-1042 is self-hosted on Windows Server isn't mentioned anywhere in the ticket.
Step 3: Write the memory gate—a Noul that decides "is this worth remembering"
Why: "What to remember" must be one explicit question, not if-else branches scattered through the code. First, look at what's being stored—as_memory() pairs the raw state with Jev's answer:
def answer_text(question, answer):
"""The readable part of an answer: the chosen option's description, or the number."""
if answer.type == "choice":
return question.criteria[answer.choice]
return answer.noul if answer.type == "noul" else answer.score
def as_memory(state: dict, questions: dict, response: SystemOneResponse) -> dict:
return {
"request": state,
"jev_answered": {
q.instructions: answer_text(q, response.answers[qid])
for qid, q in questions.items()
},
}
def remember_probability(memory: dict) -> float:
"""P(the request states an important fact about the customer), with the answer as context."""
return ask(memory, GATE).answers["remember"].noulThe two key names are deliberate: request stores the raw state from before memory is added—old memory never nests into new memory; jev_answered maps each question to its answer text (for Choice answers, the selected option's description is stored).
The gate itself is a Noul (official GATE text verbatim). Pay attention to the two constraints in the instructions—only count what the customer/support staff wrote in request.ticket; jev_answered is context only, and nothing it says or implies counts:
GATE = {
"remember": Noul(
instructions=(
"In `request.ticket`, does the thread state a lasting fact about the customer that "
"should change how their future, unrelated tickets are handled? Count what the "
"customer or our support staff wrote in `request.ticket`. `jev_answered` shows how "
"the ticket was routed, which may rely on things learned earlier: do not count "
"anything it says or implies."
),
criteria=NoulCriteria(
true=(
"Yes: in `request.ticket` the customer or our support staff state something "
"about the customer that stays true after this ticket, such as the product "
"edition or operating system they run, their plan or contract, or a standing "
"preference."
),
false=(
"No: `request.ticket` only contains things specific to this one ticket or "
"moment, such as a one-off request, today's schedule, or the device they "
"happen to be typing on; or the lasting fact appears only in `jev_answered`."
),
),
),
}Why don't answers count? The officials give two reasons: first, generic answers—like "General product questions: features, how-to, settings," an answer anyone could match—drown out the real customer facts in the request; second, answers derived from old memory would get stored again as new facts, and memory would breed more of itself.
💡 Test Chinese-language tickets before going live
Official note: English is Jev's primary training language; other languages including Chinese work but with lower accuracy. Before switching GATE and ROUTE to Chinese, or gating Chinese tickets, run a batch with your own tickets first, check whether the "should remember / shouldn't remember" groups separate cleanly by probability, and only then set REMEMBER_AT.
Noul doesn't have a separate confidence—if you want a unified threshold with other question types, you can compute |2p − 1| yourself using the official formula (see Confidence).
You should see: no output in this step—remember_probability() isn't actually invoked until the next section.
Step 4: Wrap it in ask_with_memory()—the core of the AI memory system
Why: three small functions stitch the gate and the state together—this is the complete AI memory system, and the official code is just 18 lines:
MEMORIES: dict[str, list[dict]] = {} # customer ID -> that customer's saved memories
def customer_id(state: dict) -> str:
return state["customer"]["id"]
def ask_with_memory(state: dict, questions: dict) -> SystemOneResponse:
"""ask(), plus memory: same arguments, same return value."""
# 1. Answer the call with this customer's existing memories.
saved = MEMORIES.get(customer_id(state), [])
response = ask({**state, MEMORY_KEY: saved} if saved else state, questions)
# 2. Ask Jev whether the original request states an important fact worth keeping.
memory = as_memory(state, questions, response)
if remember_probability(memory) >= REMEMBER_AT:
MEMORIES.setdefault(customer_id(state), []).append(memory)
return responseRead these 18 lines three times: ① when memory exists, send {**state, MEMORY_KEY: saved}; when it doesn't, send as-is; ② only append after passing the gate with P ≥ 0.5; ③ the return value is identical to ask()—the caller never needs to know whether memory was stored.
The officials call out five consequences of this design, each worth remembering:
| # | Consequence | Details |
|---|---|---|
| 1 | Two serial requests per call | Route first, then gate—the gate needs to see the answer, so it can only run after the routing request; if your gate doesn't look at the answer, you can fold it into the routing request as a second question (parallel questions and speculative fan-out) |
| 2 | Memory only grows, never shrinks | Every memory enters every call for that customer from then on; no size limit, no relevance check, no expiry |
| 3 | The question never mentions memory | Memory goes into the earlier_tickets_from_this_customer key of the state, and Jev reads the whole state—ROUTE doesn't need a single word changed |
| 4 | The state must have customer.id | Bare Jev also accepts a string state, but the wrapper function needs the ID to find that customer's list |
| 5 | Stored answers can repeat mistakes | The gate doesn't count answers, so an answer alone can't get a ticket stored; but a stored ticket carries its answer, which is read on every subsequent call—a wrong inference persists forever |
💡 This is the unique value of Jev
"What to remember" isn't an instruction scattered in a prompt, nor a compromise of storing everything—it's a Noul with calibrated probabilities: in the official recording, the three tickets that should be remembered score 0.96–0.98 and the ones that shouldn't are all ≤ 0.04, with the two groups far apart; that's why REMEMBER_AT = 0.5 dares to draw the line in the middle. Changing "what to remember" = changing GATE's wording; changing "how certain before remembering" = changing one constant—neither touches the call chain.
You should see: no new output in this step either—the next section makes it run.
Step 5: Send the five early tickets and watch how each memory rewrites the answers
Why: the official probing experiment—send two follow-up messages before and after each early ticket (slow dashboard, add 20 seats) to see each memory's immediate impact. The repeated messages also pass through the gate, so the gate rules on them too:
PROBES = {"Slow dashboards": 0, "More seats": 2} # later messages to send after each ticket
def memory_ids(cid: str) -> str:
return ", ".join(m["request"]["ticket"]["id"] for m in MEMORIES.get(cid, [])) or "none"
def send_probes(cid: str) -> None:
for subject, i in PROBES.items():
team = ask_with_memory(later_state(cid, i), ROUTE).answers["team"]
print(f" {subject:<16} -> {team.choice:<19} {team.probabilities[team.choice]:.2f}")
for cid in CUSTOMERS:
print(f"{cid}, memories: {memory_ids(cid)}")
send_probes(cid)
for state in EARLIER:
cid = customer_id(state)
response = ask_with_memory(state, ROUTE)
p = remember_probability(as_memory(state, ROUTE, response)) # cached: the wrapper's call
verdict = "saved" if p >= REMEMBER_AT else "not saved"
text = state["ticket"]["messages"][0]["text"]
print(f"\n{cid} {state['ticket']['id']} {response.answers['team'].choice:<19} "
f"P(remember) {p:.2f} {verdict}")
print(f" {text[:84]}")
print(f"{cid}, memories: {memory_ids(cid)}")
send_probes(cid)That # cached: the wrapper's call comment line is worth noting: the wrapper already asked the gate once, so asking again here hits the cache and costs no new request.
You should see (official release, full probe table):
C-1042, memories: none
Slow dashboards -> cloud_ops 0.55
More seats -> enterprise_desk 0.53
C-2210, memories: none
Slow dashboards -> cloud_ops 0.68
More seats -> billing 0.58
C-1042 T-101 selfhosted_windows P(remember) 0.97 saved
Hi, we run your self-hosted edition on Windows Server 2022 in our own data centre. H
C-1042, memories: T-101
Slow dashboards -> selfhosted_windows 0.99
More seats -> enterprise_desk 0.53
C-2210 T-102 general P(remember) 0.98 saved
We're a small design studio on your cloud edition, paying monthly on the self-serve
C-2210, memories: T-102
Slow dashboards -> cloud_ops 0.98
More seats -> billing 0.98
C-1042 T-103 billing P(remember) 0.02 not saved
Sorry for the typos, typing this on my phone at the airport. Where can I download la
C-1042, memories: T-101
Slow dashboards -> selfhosted_windows 0.99
More seats -> enterprise_desk 0.53
C-2210 T-104 general P(remember) 0.03 not saved
Our whole team is out on Friday for a public holiday, so no rush on this one. Is the
C-2210, memories: T-102
Slow dashboards -> cloud_ops 0.98
More seats -> billing 0.98
C-1042 T-105 enterprise_desk P(remember) 0.96 saved
For context, we signed an Enterprise contract with you in March. Can we get a sandbo
C-1042, memories: T-101, T-105
Slow dashboards -> selfhosted_windows 0.98
More seats -> enterprise_desk 1.00Read this table (each item matches the official interpretation):
- The three tickets that should be stored are stored at 0.96–0.98: T-101 version 0.97, T-102 plan 0.98, T-105 contract 0.96
- T-102 is routed to the general team yet still stored—the gate counts what the customer wrote, not the routing answer; the "add 20 seats" verdict consequently jumps from billing 0.58 to 0.98
- Airport 0.02 and public holiday 0.03 are not stored—none of their subsequent probe answers changed
- Each memory only changes the answers related to it: C-1042's Windows ticket moves the slow dashboard from cloud team 0.55 to Windows team 0.99, and the Enterprise contract lifts the add-seats enterprise_desk from 0.53 to 1.00; C-2210's Team plan lifts cloud team 0.68 to 0.98 and billing 0.58 to 0.98
- The gate stored none of the repeated messages—sending the same probe ticket twice doesn't change the gate's verdict
You should see: your output matches the table above line by line (identical under cache replay; running live, probabilities will vary—follow the version you pinned).
- I can reproduce this table, and I can explain why T-102 was routed to general yet still stored
Step 6: Reconciliation—the same message routed once by bare Jev and once with memory
Why: the final reconciliation. Send all three follow-up messages for each customer, same state, same question, once through ask() and once through ask_with_memory(). The expected teams aren't guesses—the comments in DATA state it plainly: labeled by a human based on what each customer said in their early tickets (C-1042's self-hosted version + Enterprise contract, C-2210's cloud version Team plan):
EXPECTED = DATA["expected_team"]
plain_correct = memory_correct = total = 0
example_state = None
def cell(answer, expected: str) -> str:
mark = "✓" if answer.choice == expected else "✗"
return f"{mark} {answer.choice} {answer.probabilities[answer.choice]:.2f}"
print(f"{'customer':<9}{'message':<17}{'expected':<20}{'plain Jev':<27}{'with memory':<27}")
for cid in CUSTOMERS:
for i, message in enumerate(DATA["later_messages"]):
state = later_state(cid, i)
expected = EXPECTED[cid][message["subject"]]
plain = ask(state, ROUTE).answers["team"]
if example_state is None:
# Keep the exact state used for this call for the playground link.
saved = MEMORIES.get(cid, [])
example_state = json.loads(json.dumps({**state, MEMORY_KEY: saved} if saved else state))
response = ask_with_memory(state, ROUTE)
remembered = response.answers["team"]
plain_correct += plain.choice == expected
memory_correct += remembered.choice == expected
total += 1
print(f"{cid:<9}{message['subject']:<17}{expected:<20}{cell(plain, expected):<27}"
f"{cell(remembered, expected):<27}")
print(f"\nExpected routes: {plain_correct}/{total} without memory, "
f"{memory_correct}/{total} with memory.")example_state Those lines are reserved for the final Playground link—capturing the exact state of C-1042's first slow-dashboard call at that moment (including the memories stored by then).
You should see (official release):
customer message expected plain Jev with memory
C-1042 Slow dashboards selfhosted_windows ✗ cloud_ops 0.55 ✓ selfhosted_windows 0.98
C-1042 Upgrade failing selfhosted_windows ✗ none_suitable 0.64 ✓ selfhosted_windows 1.00
C-1042 More seats enterprise_desk ✓ enterprise_desk 0.53 ✓ enterprise_desk 1.00
C-2210 Slow dashboards cloud_ops ✓ cloud_ops 0.68 ✓ cloud_ops 0.98
C-2210 Upgrade failing cloud_ops ✗ none_suitable 0.58 ✓ cloud_ops 0.95
C-2210 More seats billing ✓ billing 0.58 ✓ billing 0.98
Expected routes: 3/6 without memory, 6/6 with memory.3/6 to 6/6. Four lines are worth watching:
- The same sentence goes to different teams: slow dashboard—C-1042 goes to the Windows team, C-2210 stays with the cloud team; add seats—C-1042 goes to enterprise_desk, C-2210 goes to billing—memory makes "how to route" follow the customer, not just the sentence
- Both
none_suitabletickets get rescued: the failed-escalation tickets don't mention the environment and lack context, so bare Jev can only answer "no suitable team"; with memory, they go to the Windows team 1.00 and the cloud team 0.95 respectively - Memory raises the probabilities on the three rows bare Jev already got right: C-1042 add-seats goes from 0.53 to 1.00—memory doesn't just change right or wrong, it changes confidence
- The gate stored none of these six follow-up messages—they don't state persistent facts, so nothing was added to memory
📋 Magic Prompt
The "Prompt" on this page is the question and wrapper template for the API—copy it, replace the 【】 placeholders (those with ? are optional), and it's ready to use.
📝 Memory Gate (Noul version)
Expected result: turn "what to remember" into an explicit yes/no question, get a 0–1 probability, and let a threshold in the code decide whether to store it.
GATE = {
"remember": Noul(
instructions=(
"【在 `request.ticket` 里,这个线程是否陈述了关于客户的一条持久事实——"
"它应该改变客户未来、与这张工单无关的工单的处理方式?只数客户或支持人员"
"在 `request.ticket` 里写下的话。`jev_answered` 显示这张工单被如何路由,"
"可能依赖早先学到的东西:它说的或暗示的任何内容都不要数。】"
),
criteria=NoulCriteria(
true="【是:客户或支持人员在 `request.ticket` 里陈述了这张工单之后仍然为真的东西——如产品版本、操作系统、套餐、合同、长期偏好】",
false="【否:`request.ticket` 只有属于这张工单或这一刻的内容——如一次性请求、当天日程、碰巧在用的设备;或持久事实只出现在 `jev_answered` 里】",
),
),
}
# 必填项:state = as_memory() 配好的 {"request": 加记忆前的原始 state, "jev_answered": {问题 instructions: 答案文本}}
# 选填项:true/false 里的例子换成你领域「值得记 / 不值得记」的清单?
# 输出规范:response.answers["remember"].noul → 0–1 概率(Noul 无单独 confidence)
# 约束条件:
# ✅ 一道 Noul 只问「该不该记」;记多久、给谁看,是代码的事
# ✅ 官方英文原文最稳(见第 3 步);中文化先用你自己的数据验证再上线
# ❌ 不要数 `jev_answered`——通用答案会压过真事实,靠旧记忆得出的答案会被当新事实再存✅ Memory wrapper and threshold (ask_with_memory version)
Expected result: automatically attach memory before the call and automatically run the gate after it; same parameters and same return value as ask(), so existing code can switch over with zero changes.
REMEMBER_AT = 【0.5】 # 多确定才记:官方给这道闸门的起点阈值
MEMORY_KEY = "【earlier_tickets_from_this_customer】" # 记忆放进 state 用的键名
MEMORIES: dict[str, list[dict]] = {} # 客户 ID -> 该客户的记忆列表
def ask_with_memory(state: dict, questions: dict) -> SystemOneResponse:
"""ask(), plus memory: same arguments, same return value."""
saved = MEMORIES.get(customer_id(state), [])
response = ask({**state, MEMORY_KEY: saved} if saved else state, questions)
memory = as_memory(state, questions, response)
if remember_probability(memory) >= REMEMBER_AT:
MEMORIES.setdefault(customer_id(state), []).append(memory)
return response
# 必填项:state 里必须有 customer.id——包装函数靠它找该客户的记忆列表
# 选填项:记忆长了加一道相关性问题,只挑子集并进 state?
# 输出规范:返回值与 ask() 完全相同——存没存记忆,调用方都不用管
# 约束条件:
# ✅ 先路由后闸门——闸门要看答案,只能在路由请求之后跑
# ✅ as_memory() 的 request 键存加记忆前的原始 state——旧记忆不会嵌套进新记忆
# ❌ 别把 MEMORIES 直接上线——内存字典进程退出就没了,官方 Next steps:换按客户 ID 键的数据库🔧 Your own routing question (Choice version)
Expected result: a single Choice dispatches tickets to a fixed set of teams; none_suitable gives tickets with insufficient context a place to go.
ROUTE = {
"team": Choice(
instructions="【这张工单该哪个支持团队接?判断 `ticket`】",
criteria={
"【选项 ID】": "【选项描述:什么情况归这个团队】",
"none_suitable": "【以上团队都不适合这张工单】",
},
),
}
# 必填项:选项 map——ID 是代码读的,描述是 Jev 读的
# 选填项:官方 7 选项全集见第 2 步(cloud_ops / selfhosted_linux / selfhosted_windows / billing / enterprise_desk / general / none_suitable)?
# 输出规范:answers["team"].choice + probabilities(每个选项)+ confidence
# 约束条件:
# ✅ 列表可能不全时留 none_suitable(或 other)——上下文不足的工单有地方去
# ✅ 记忆进 state 后,这道题一个字不用改——Jev 读整个 state
# ❌ 不要在 instructions 里提「记忆」——记忆是 state 的事,不是问题的事Checkpoint ✅
- I can name the two components of this AI memory system: after each call, a Noul gate decides whether to remember (store only when P ≥ 0.5); before each call, the customer's stored tickets, answers included, are merged into state
- I know why the gate counts only what is written in
request.ticket: generic answers would drown out real facts, and answers derived from old memories would get stored again as new facts - Of the five early tickets, three are stored and two are not: version / plan / contract 0.96–0.98 are stored; airport phone 0.02 and public holiday 0.03 are not—T-102, routed to general, is still stored
- Reconciliation experiment 3/6 → 6/6: for the same "dashboard is slow" sentence, C-1042 goes to the Windows team and C-2210 stays with the cloud team; bare Jev was already right on three lines, and memory pushed the probability from 0.53 up to 1.00
- Of the five consequences I can name three: two serial requests per call, memory only ever grows, state needs customer.id (the other two: the question never mentions memory, and stored answers repeat mistakes)
Pitfall warnings
❌ The gate counts Jev's answer too
If jev_answered is also factored into the "worth remembering" judgment, two things officially called out will happen: generic answers ("General product questions: features, how-to, settings") will drown out the real customer facts in the request—so T-102 might not get stored; and answers derived from old memories will be stored again as new facts, making memory self-propagate.
The official solution is hard-coded in the GATE's instructions: count only what the customer/support staff wrote in request.ticket; jev_answered is just context—nothing it says or implies counts.
❌ Trying to save a request by casually merging the gate into the routing request
The gate needs to see "the ticket + Jev's answer," and the answer only exists after the routing request—so in the five consequences of step 4, the first is "two serial requests per call." The official exception is explicit: if your gate doesn't look at the answer, it can become a second question inside the routing request (speculative fan-out, see parallel questions and speculative fan-out).
First figure out whether your gate needs to see the answer, then decide whether to merge.
❌ Switching to the wrapper function when state has no customer.id
Bare Jev accepts a string state of any shape; ask_with_memory(), however, relies on state["customer"]["id"] to find that customer's memory list. Before switching to the wrapper function, confirm your state carries the customer ID.
❌ Shipping the "only grows, never shrinks" demo memory straight to production
The three "no's" are stated plainly by the officials: no size limit, no relevance check, no expiration. Every memory enters every subsequent call for that customer—and "a large state full of irrelevant details" is exactly a known failure mode in Jev 1.13 pitfall handbook.
There are two more officially named risks: stored tickets carry their answers along, so wrong inferences persist; and MEMORIES is an in-memory dict that vanishes when the process exits. The official Next steps solutions are in the advanced techniques.
Advanced techniques (optional)
Tuning REMEMBER_AT: the official calibration method. The first item of the official Next steps is exactly this: from your traffic, label a batch of "request + answer" pairs, manually sort them into "worth remembering / not worth remembering" piles, pick the probability that separates them best as the threshold, then validate with a batch that took no part in the selection. Raise it if misleading memories are costly.
Why is the official starting point 0.5, looser than the "yes ≥ 0.7" in Noul's generic starting point? The code comment only says it's a starting threshold; the principle of Confidence is that thresholds scale with risk—storing a memory is a reversible, low-risk action, so 0.5 is good enough, and you raise it only when the costs are asymmetric. The officials also give a reference: confidence-based routing pattern.
When memory grows, the official four-step upgrade path. The remaining four Next steps items, adopted as needed: ① add a relevance question that picks a subset from the long memory list to merge into state; ② ask whether a new memory replaces an old one, and delete the replaced entry in code; ③ swap MEMORIES for a database keyed by customer ID; ④ add your app's replies to the ticket thread as support messages too, and have the gate judge them together.
Zero-key replay and the cost tally. All calls are recorded in the officially published json_cache.json: after deduplication, 31 calls (duplicate probe requests hit the same cache entry, which is why the entry count is lower than the logical call count)—19 routing calls and 12 gate calls; totaling 21,456 input tokens and 1,752 output tokens. At $42/Btok for input with free output, the whole page costs about $0.0009 to run.
If you only want to experience one memory-carrying routing call: the bottom of the official cookbook page has a ready-made Playground share link—loaded with the state at the time of C-1042's first slow-dashboard call (including the two memories already stored then, T-101 and T-105) + the routing question—open it and edit right in the browser:
Open C-1042's ticket and its memories in the TypeSafe playground →
It was generated by the official last cell: make_playground_link(example_state, ROUTE)—the exact state captured in step 6.
Wiring it into your app. GATE and ROUTE are now your own; copy the wrapper function as-is. If you use Claude Code, install the TypeSafe Agent Skill and hand this page to it:
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-aiThe officials recommend keeping the questions and threshold constants together in one file for easy human review—GATE's wording and REMEMBER_AT are your two pieces of "policy," and any change should go through code review.
Lesson summary
✅ An AI memory system = two components: after each call, a Noul gate (store only when P ≥ 0.5); before each call, the customer's stored tickets, answers included, are merged into state—ask_with_memory() and ask() share the same parameters and return values, so switching over requires no other code changes.
✅ "What to remember" is an explicit question: GATE counts only what the customer/support staff wrote in the request; what should be remembered gets 0.96–0.98, what shouldn't gets ≤ 0.04—the two groups sit far apart, which is why the 0.5 line can be drawn.
✅ Official measurements: with bare Jev, follow-up tickets got 3/6 right; with memory, 6/6 all reached the expected teams. Slow dashboard 0.55 cloud team → 0.98 Windows team; seat addition 0.53 → 1.00; both none_suitable tickets were rescued.
✅ Clear boundaries: two serial requests per call; memory only ever grows; the question never mentions memory; state needs customer.id; stored answers repeat mistakes.
Key configuration fields recap:
| Field | Value on this page | Description |
|---|---|---|
REMEMBER_AT | 0.5 | The starting threshold for the memory gate; the official comment says, verbatim, "starting threshold" |
MEMORY_KEY | earlier_tickets_from_this_customer | The key name under which memories enter state; Jev reads the whole state, so the question doesn't need to change |
TYPESAFE_MODEL | jev-1.14.0 | The version used for the official recorded numbers; when running live, lock in your own version ID |
MEMORIES | dict[str, list[dict]], keyed by customer ID | An in-memory dict; it's gone once the process exits; switch to a database for production |
| Gate question type | Noul (no separate confidence) | The threshold is set directly on P(yes); to put it on the same scale as other question types, compute "the absolute value of 2p − 1" yourself |
| State shape | customer (including id) + ticket | The wrapper function finds the memory list via customer.id |
Related tutorials:
- Agent decisions: picking skills, converting to function calls—Previous lesson: the same two-request structure of "the code must get the previous answer before sending the next request"
- RAG passage gating: only let relevant content into the context—Same family of problems: gating decides "what enters the context", this page decides "what enters state"; both are one question + a threshold in your code
- Confidence—Read before tuning REMEMBER_AT: the threshold scales with risk
Next lesson preview
This completes Line B (LLM and Agent applications). The next lesson starts Line C (documents and data): Value extraction: dates, emails, phone numbers, amounts.
You will learn:
- For dates, ask about the parts in the document (absolute or relative), parse and validate in code, double-check with confidence
- Emails, phone numbers, amounts: regex first to fish out candidates, Jev picks the right one, then code normalizes it
- The same habit as this page: whether extraction is right or wrong doesn't rely on the model's own judgment, but on typed questions + code validation