Simple memory system
Let Jev decide which requests and answers are worth remembering, then wrap the Jev call in a small function that adds memories to later calls.
Each Jev request sees only the state you send it. What a customer told your app last month, such as their edition or their plan, is not in their next request unless your code puts it there. The memory system here does that with one extra Jev request per call and a Python dict.
Our example routes support tickets. In August, a customer said they self-host on Windows Server. In September they write “Dashboards have been really slow since this morning”. Without memory, Jev sends that ticket to the cloud team instead of the self-hosted team. In the example below, adding memory sends all six later tickets to the expected teams. Routing each ticket alone gets two out of six correct.
The simple memory system has two parts:
- After each call, Jev sees the original request and its answer together. A
Noulquestion, which we call the gate, asks whether the request states an important fact about the customer that should be remembered. If P(yes) is at least 0.5, the ticket and Jev’s answer are saved as a memory for that customer. - A wrapper function,
ask_with_memory(), takes the samestateandquestionsarguments asask(), which is the TypeSafe Python SDKclient.system_onemethod with the model pinned and the call cached, and returns the Jev response. Before each call, it adds the customer’s saved tickets and Jev’s answers to them to the state.
That wrapper is a basic agent harness. A harness is the code around a model that gives it extra capabilities such as tool calls and running in loops. This basic toy one only gives it memory in a plain Python dict with one list per customer ID.
%%{init: {"fontFamily": "Inter, sans-serif", "flowchart": {"rankSpacing": 25, "wrappingWidth": 300, "subGraphTitleMargin": {"top": 8, "bottom": 20}}}}%%
flowchart TB
IN["ask_with_memory(state, questions)"]
subgraph R["Jev: answer the question"]
Q1["<b>Choice:</b> which support team?"]
end
subgraph G["Jev: judge the routed ticket"]
Q2["<b>Noul:</b> does the request state<br/>an important fact about the customer?"]
end
DEC{"P(yes) ≥ 0.5?<br/>your code"}
SAVE["save the memory<br/>under this customer's ID"]
OUT["handle the support ticket response in your code"]
MEM[("MEMORIES<br/>saved memories per customer")]
IN -- "state with memories<br/>+ routing question" --> R
R -- "original request + answer<br/>+ memory question" --> G
G -- "P(yes)" --> DEC
DEC -- "yes: save" --> SAVE
DEC -- "no: don't save" --> OUT
SAVE --> OUT
SAVE --> MEM
IN -. "added to the state<br/>on this customer's<br/>next support tickets" .- MEM
The wrapper makes two Jev requests, one after the other: the routing request, then the gate, which judges the ticket together with Jev’s answer. The wrapper returns the routing response whether or not anything is saved.
Because ask_with_memory() takes the same arguments as ask() and returns the same
response, you can swap one for the other without changing any other code. The wrapper
finds the customer’s memories, adds them to the state and saves new ones itself.
The example sends five earlier tickets from two customers through the wrapper, then routes three later messages from each customer twice: once with the memories it saved, once without. A table puts the two answers side by side for all six.
Setup
pip install ipython 'cooksafe>=0.2.0,<0.3.0'
Set TYPESAFE_API_KEY. Every API call is cached in
json_cache.json.
Download it into the folder you run this code from to replay the published numbers
instead of calling the API, or leave it out to run everything live.
Numbers below came from jev-1.13.0 on 2026-09-28.
The memory threshold of 0.5 is a starting point. You should evaluate it against
your own examples.
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.13.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"))
Define the tickets
Two customers, five earlier tickets and three later messages, all written for this cookbook. C-1042 (Harbor Logistics) runs the self-hosted edition on Windows Server under an Enterprise contract. C-2210 (Fernwood Studio) is on the cloud edition’s self-serve Team plan. Three of the earlier tickets state a lasting fact: an edition, a plan, a contract. Two don’t: a phone at the airport, a public holiday. No later message mentions the customer’s setup, so without memory Jev has to guess it.
Each ticket becomes a state with two parts: customer, who the customer is, and
ticket, the ticket thread. The ticket_state() function builds a
simplified ticket, like one from a helpdesk. In your app, the state is each ticket as
your helpdesk sends it, and ask_with_memory() adds the customer’s saved tickets to it.
The split into earlier tickets and later messages is only for this example.
DATA = {
"customers": {
"C-1042": {"id": "C-1042", "company": "Harbor Logistics"},
"C-2210": {"id": "C-2210", "company": "Fernwood 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))
2 customers, 5 earlier tickets, 3 later messages. The first ticket as Jev sees it:
{
"customer": {
"id": "C-1042",
"company": "Harbor Logistics"
},
"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?"
}
]
}
}
Route a ticket
One Choice question picks the support team. The none_suitable option gives Jev an
answer for when no team fits, and a ticket with too little context can end up there.
The helper ask() is client.system_one with the model version fixed and every call
cached. It takes a state and a dict of questions and returns the SDK’s own response
object, so code that already reads client.system_one responses works with it unchanged.
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}")
C-1042: 'Dashboards have been really slow since this morning.'
plain Jev -> cloud_ops 0.80
Plain Jev sends C-1042’s slow dashboards to the cloud team. This ticket alone gives it no reason to do anything else.
Ask Jev whether the ticket is worth remembering
First, as_memory() pairs the original state with Jev’s answer: the memory the wrapper
may save. The request key
holds the state before memories were injected, and jev_answered maps each question
to its answer. This keeps old memories from being nested inside every new memory.
A second Jev call reads that pair. The gate asks whether the request states an important fact about the customer, such as their edition, operating system, plan or contract. Jev’s answer is there as context, but a fact that appears only in the answer does not count. Without that rule, a generic answer such as “General product questions” can outweigh a real fact in the request, and an answer that relied on an earlier memory can be saved again as if it were new.
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`."
),
),
),
}
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"].noul
Wrap the call so it remembers
The wrapper, ask_with_memory(), has the same arguments and return value as ask(). The
memory store is a plain dict with one list per customer ID. The wrapper uses the ID in
the state to select the customer’s memories.
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 response
Adding memory this way has four consequences for your app:
- Every call makes two sequential requests, your call followed by the memory gate. The gate judges the ticket together with Jev’s answer, so it runs after the routing request. If your gate ignores the answer, it could instead be a second question in the routing request (see fan-out).
- Memory only grows. Every saved memory goes into every later call for that customer. There is no size limit, no check for relevance and no expiry date here. The Next steps section has ideas for each.
- Your questions never mention the memories. The memories go into the state under
earlier_tickets_from_this_customer, and Jev reads the whole state. Nothing inROUTEchanges. - The state needs
customer.id. Plain Jev also accepts a string as the state, but this wrapper needs the ID to find the customer’s list.
Send the earlier tickets and watch the answers change
Send the five earlier tickets through ask_with_memory(), in the order they arrived. The
same customer sends two of the later messages again: slow dashboards and 20 more seats.
That shows how each saved memory changes Jev’s answers. The repeated messages go through
the wrapper too, so the gate judges them as well.
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)
C-1042, memories: none
Slow dashboards -> cloud_ops 0.80
More seats -> enterprise_desk 0.62
C-2210, memories: none
Slow dashboards -> cloud_ops 0.75
More seats -> enterprise_desk 0.52
C-1042 T-101 selfhosted_windows P(remember) 0.91 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.44
C-2210 T-102 general P(remember) 0.91 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.91
More seats -> billing 0.98
C-1042 T-103 billing P(remember) 0.07 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.44
C-2210 T-104 general P(remember) 0.10 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.91
More seats -> billing 0.98
C-1042 T-105 enterprise_desk P(remember) 0.92 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.94
More seats -> enterprise_desk 0.99
The three tickets that state an edition, a plan or a contract are saved at 0.91 to 0.92. T-102 is saved even though Jev routed it to the general team, because the gate counts the customer’s words, not the answer. The airport and public-holiday tickets score 0.07 and 0.10 and are not saved, so the answers after them do not change.
Each saved memory changes the answers it is relevant to. For C-1042, the Windows ticket moves slow dashboards from the cloud team (0.80) to the Windows team (0.99). The Enterprise contract then settles seats at 0.99. For C-2210, the Team-plan ticket raises the cloud team from 0.75 to 0.91 and moves seats from the Enterprise desk (0.52) to billing (0.98). Adding the Enterprise memory lowers C-1042’s slow dashboards slightly, from 0.99 to 0.94, which is one reason to choose which memories to add (see Next steps). The gate saved none of the repeated messages.
Route the same messages for both customers
Each customer now sends the three later messages. Each message goes to plain ask() and
to ask_with_memory(), with the same state and the same question.
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.")
customer message expected plain Jev with memory
C-1042 Slow dashboards selfhosted_windows ✗ cloud_ops 0.80 ✓ selfhosted_windows 0.94
C-1042 Upgrade failing selfhosted_windows ✗ none_suitable 0.60 ✓ selfhosted_windows 1.00
C-1042 More seats enterprise_desk ✓ enterprise_desk 0.62 ✓ enterprise_desk 0.99
C-2210 Slow dashboards cloud_ops ✓ cloud_ops 0.75 ✓ cloud_ops 0.91
C-2210 Upgrade failing cloud_ops ✗ none_suitable 0.63 ✓ cloud_ops 0.86
C-2210 More seats billing ✗ enterprise_desk 0.52 ✓ billing 0.98
Expected routes: 2/6 without memory, 6/6 with memory.
With memory, all six messages reach the expected team, against two without. The same message now goes to a different team for each customer: slow dashboards go to the Windows team for C-1042 and stay with the cloud team for C-2210, and 20 more seats go to the Enterprise desk for C-1042 and to billing for C-2210. Where plain Jev was already right, memory raises the probability, from 0.62 to 0.99 for C-1042’s seats. The wrapper also judged the six later messages, and saved none: they state no important fact.
Each row’s expected team follows from the customer’s setup in the earlier tickets: C-1042’s self-hosted edition and Enterprise contract, C-2210’s cloud Team plan.
Open it in the playground
The link holds the exact routing state used for C-1042’s first slow-dashboards call, including its memories at that point, plus the routing question.
playground_link = make_playground_link(example_state, ROUTE, models=[TYPESAFE_MODEL])
display(Markdown(
f"🔗 [Open C-1042's ticket with its memories in the TypeSafe playground]({playground_link})"
))
Open C-1042’s ticket with its memories in the TypeSafe playground →
Next steps
- Choose what your app should remember. Edit
GATEto describe what is worth remembering for your own task, and testREMEMBER_ATagainst examples you have labelled. - Choose which memories to add. The wrapper adds every saved memory. A relevance question can select a smaller set once the list gets long.
- Replace outdated memories. Ask whether a new memory replaces an older one, then remove the old entry in code when appropriate.
- Keep memories between runs. Replace
MEMORIESwith a database keyed by customer ID. The in-memory dict disappears when the process exits. - Act on the route. Map each team to a handler in code, such as booking a call for Enterprise customers or sending a setup-specific article. See intent routing and confidence-based routing. Add your reply to the ticket thread as a support message, and the gate can remember what you did.
Appendix
Can a saved answer reinforce a mistake?
Yes. The gate ignores anything that appears only in Jev’s answer, so an answer can’t get a ticket saved by itself. Once a ticket is saved, though, its answer is saved with it, mistaken inference and all, and every later call for that customer reads it. A later answer can then repeat the mistake.
How should I choose the threshold?
The 0.5 in this wrapper is a starting value. To pick your own, label request-and-answer pairs from your traffic as worth remembering or not, and find the probability that best separates the two groups. Check it on pairs you didn’t use to pick it. Raise it if a misleading memory costs more than a missing one; lower it if the reverse. See Confidence and Confidence-Gated Routing for choosing thresholds and matching them to the risk of each action.