Agents: read the raw Markdown of this page, or start at llms.txt.

Cookbook: Simple memory system

TL;DR Jev sees only the state you send, so memory lives in your code. After each call, a second request asks a Noul "gate" whether the original request states a lasting fact about the customer; at P(yes) ≥ 0.5 the request and Jev's answer are saved under the customer's ID, and a wrapper, ask_with_memory(), adds that customer's saved memories to every later state. In TypeSafe's support-routing example, all six later tickets reach the expected team with memory, two of six without. Two sequential requests per call; memory only grows; the 0.5 is a starting point to test on your own labels.

Goal

Carry facts from earlier requests into later ones. A customer said in August that they self-host on Windows Server; in September they write "Dashboards have been really slow since this morning". Each Jev request sees only its own state, so plain Jev routes that ticket to the cloud team. The cookbook calls its wrapper "a basic agent harness": the code around the model that gives it memory, here a Python dict with one list per customer ID.

When to use it: a repeated decision about the same entity (customer, account, device) where an earlier message changes how later ones should be read. When not to: facts you already hold in a database (put them in state directly), or anything where a wrong saved fact costs more than a missing one (see Gotchas).

Inputs / state shape

Two customers, written for the cookbook: C-1042 (Harbor Logistics, self-hosted edition on Windows Server, Enterprise contract) and C-2210 (Fernwood Studio, cloud edition, self-serve Team plan). Five earlier tickets, three of which state a lasting fact (an edition, a plan, a contract) and two of which do not (typing on a phone at the airport; a public holiday). Then three later messages per customer that never mention the setup: slow dashboards, a failing upgrade to version 5.2, 20 more seats. Expected teams were labelled by hand from the earlier tickets.

Each ticket's state is a dict with customer (id, company) and ticket (id, received_on, subject, messages as a list of {"from", "text"}). The wrapper adds saved memories under the key earlier_tickets_from_this_customer. A saved memory is {"request": <state before memories were added>, "jev_answered": {<question instructions>: <answer text>}}, so old memories are never nested inside new ones.

Numbers below came from jev-1.13.0 on 2026-09-28.

Questions asked

Routing (ROUTE), one Choice:

The none_suitable option gives Jev an answer when no team fits; a ticket with too little context can land there.

Gate (GATE), one Noul, verbatim:

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`."
            ),
        ),
    ),
}

The "fact only in jev_answered does not count" rule is deliberate: without it, the cookbook says, 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.

Combining logic in code

import json
import os
from pathlib import Path

from cooksafe import JsonCache
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"))

# ROUTE and GATE as above.


@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 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


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


# Usage: same call shape as ask().
# team = ask_with_memory(ticket_state, ROUTE).answers["team"]
# print(team.choice, team.probabilities[team.choice])

ask_with_memory() takes the same arguments and returns the same response as ask(), so it swaps in without changing the routing code; ROUTE never mentions memories, because Jev reads the whole state.

Results / what the cookbook reports

Earlier tickets through the wrapper (gate probability, saved or not):

T-102 was saved although it was routed to general: the gate counts the customer's words, not the answer.

Later messages, plain ask() vs ask_with_memory():

"Expected routes: 2/6 without memory, 6/6 with memory." The same message goes to different teams for different customers. Adding the Enterprise memory lowered C-1042's slow-dashboards answer from 0.99 to 0.94, which the cookbook gives as one reason to choose which memories to add. The gate saved none of the repeated or later messages.

Adapting it to a new domain

Per the cookbook's Next steps:

• Edit GATE to describe what is worth remembering for your task, and test REMEMBER_AT on examples you have labelled.
• Add a relevance question to pick a smaller set of memories once the list grows.
• Ask whether a new memory replaces an older one, and remove the old entry in code.
• Replace MEMORIES with a database keyed by customer ID; the dict disappears when the process exits.
• Map each team to a handler in code (Intent routing, Confidence-gated routing); add your reply to the ticket thread as a support message so the gate can remember what you did.

Choosing the threshold (appendix): label request-and-answer pairs from your traffic as worth remembering or not, find the probability that best separates the two groups, and check it on pairs you did not use to pick it. Raise it if a misleading memory costs more than a missing one; lower it if the reverse (Confidence vs probability).

Gotchas

• Two sequential requests per call. The gate reads the answer, so it runs after the routing request. If your gate ignores the answer, it can instead be a second question in the routing request (Speculative fan-out).
• Memory only grows. Every saved memory goes into every later call for that customer: no size limit, relevance check or expiry here. Long lists eventually press on the 32k limit for state plus the longest question (Models, aliases, pricing, rate limits, context) and add input tokens to every call (inferred).
• A saved answer can reinforce a mistake. The gate ignores facts that appear only in Jev's answer, but once a ticket is saved, its answer is saved with it, mistaken inference and all, and later calls read it (appendix).
• The state needs customer.id. Plain Jev accepts a string as the state; this wrapper does not.
• 0.5 is a starting point, not a tuned threshold; the published numbers are one synthetic example of two customers and six later messages.
• Install line. pip install ipython 'cooksafe>=0.2.0,<0.3.0'; set TYPESAFE_API_KEY. Every call is cached in json_cache.json in typesafe-ai/typesafe-public-examples; download it to replay the published numbers, or leave it out to run live. The cookbook also builds a playground share link with make_playground_link for C-1042's first slow-dashboards call.

Related

• State: what you send Jev — Jev sees only what you send; memory is code that adds to state
• Noul (yes/no) questions — the gate is one probability
• Cookbook: Classification using confidence — the routing Choice with confidence
• Intent routing — acting on the route
• Patterns: agent internals, routing, gates, context and memory — community memory and context patterns (P07 and others)
• Builder lessons: what changed the result — builders' results on putting context in state
• Cookbooks overview — the full cookbook catalog

Sources

• raw/docs/cookbooks__basic_memory.md (https://docs.typesafe.ai/cookbooks/basic_memory.md), first captured 2026-10-11