MemGPT tiers, Voyager skill library, Agent Workflow Memory

What you'll learn

• Explain how MemGPT splits memory into an always-visible core, a message window and a searchable archive.
• Measure what a bigger window costs per call against what it keeps in view, using the lab's numbers.
• Diagnose an archived fact that never comes back because of the words in the agent's own query.
• Compare remembering facts with remembering skills (Voyager) and workflows (Agent Workflow Memory).

Lessons 1 to 4 of T10.2 decided in code what to remember and when to read it. This lesson hands part of that decision to the agent, then looks at memories that are capabilities rather than facts.

Dana opens a Larkspur chat by saying her shop is on an annual business plan. In her second message she adds that they bought it 12 days ago and have used 80 GB of outbound traffic. Three unrelated questions later she asks whether she can still get a full refund. The handbook's rule needs both numbers: a full refund within 30 days of purchase if the account used less than 100 GB. By then the traffic message has scrolled out of a short context window.

MemGPT (Packer et al., 2023; the framework is now called Letta) treats the context window the way an operating system treats RAM. A small main context is always in the prompt. An unbounded archival memory sits outside it, like disk. The agent moves information between the two with tools, so the agent decides what stays close, where the earlier lessons used a fixed rule:

Table 1: MemGPT's three tiers as the notebook implements them.

The model gets four tools. Two edit core memory (core_memory_append, core_memory_replace), and two move things to and from the archive (archival_memory_insert, archival_memory_search). Every turn rebuilds the system prompt from the current core memory, runs any tool calls for at most MAX_TOOL_ROUNDS = 5 rounds, and then appends the answer to the window, which evicts the oldest messages once the window is full:

Figure 1: Paging. Overflow moves the oldest messages to the archive, and only a search the model makes brings them back.

The notebook runs the same pattern on a trip planner whose $2,500 budget is evicted before a sixth turn asks for it. Its system prompt has to keep one-off details out of core memory: without that rule gpt-4o-mini tends to store every detail there, and the archive stops mattering.

The window is a budget

The lab replays Dana's six turns through the notebook's own window and archive classes, ported to JavaScript and checked against the Python classes on every window size from 1 to 12 and 408 queries (4,932 comparisons, 0 mismatches). It reports the conversation at turn 6 for each window size:

Table 2: Window size against what the model sees, from the lab. Tokens are characters of core memory plus the window, divided by four.

A window of 9 keeps the traffic message in view at about 156 tokens of conversation per call, against 117 at the notebook's window of 6. Those 39 extra tokens are paid on every call of every turn, whether or not the next question needs the old message.

Recall depends on the query

At a window of 6 the traffic message is in the archive, and the answer depends on a search the model must decide to make and on the words it chooses. The notebook's search lower-cases both sides, splits on spaces and counts shared words, so punctuation stays attached:

Table 3: Four archive queries at a window of 6, from the lab.

We call the last two rows the wrong-words miss: the fact is stored, the agent searched, and the answer still lacks it. Open the tiered memory lab, set the window to 6 and switch between outbound traffic and how much traffic?, then slide the window to 9:

Three costs of letting the agent page

Three separate things can fail Dana here:

• The window is paid on every call. A bigger window removes the search at the price of tokens on every turn.
• Recall depends on the agent asking. The notebook checks in code whether the model called archival_memory_search in turn 6. If it did not, the answer comes without the figure, a failure we call the unasked search.
• The search is part of memory quality. Keyword overlap keeps punctuation and ties easily. A real system embeds archive entries and searches by meaning, the same retrieval choices as any RAG index (T5.4).

The earlier layers, tiers included, remember facts and events. The next two architectures remember capabilities.

A skill library stores capabilities that worked: code in Voyager, tool-call sequences in Agent Workflow Memory. Both follow one loop: look in the library first, build something new only when nothing fits, check it, and store only what passed:

Figure 2: The skill-library loop shared by Voyager and Agent Workflow Memory.

Voyager: executable skills behind tests

Voyager (Wang et al., 2023) played Minecraft without fine-tuning by saving each working piece of code as a named skill. The notebook moves the idea to small Python text tasks:

Table 4: The notebook's four tasks and the decisions it expects; a live model makes them. The library starts with two seeds, count_vowels and reverse_string.

Before generating, a model call reads the library's descriptions and decides whether to reuse. Every new skill, and every reuse, runs against test cases before it counts, and the tests must be able to fail. When every expected answer is True, a function that always returns True passes and the library stores a skill that checks nothing. We call that the vacuous test. Task 4's tests mix both answers; run against them, an always-True candidate fails on its second case, "Voyager", which expects False.

Generated code is untrusted. The notebook screens it with a denylist of 21 tokens, runs it with 25 permitted builtins in a child python -I process with an empty environment, and kills it after 5 seconds. It also says plainly that a denylist is not a sandbox: code from a model you do not control belongs in a container or a hosted sandbox with no network and no secrets.

Agent Workflow Memory: templates from successful runs

Agent Workflow Memory (Wang et al., 2024) stores procedures instead of code:

Figure 3: Workflow memory. Only successful trajectories become templates.

A small ReAct loop logs every tool call. After a success, a model call turns the trajectory into a template with placeholders: look up {entity}, then multiply by {factor}. For a new task, one model call picks the structurally similar template, a second fills in the placeholders, and the executor runs the plan, filling {step_1} from the first observation. A task with a new shape matches no template and falls back to planning from scratch. Templates can also overfit to the first task's wording, or go stale when the tools change.

The payoff is in the call count: adapting costs a fixed two calls, and planning from scratch costs one per step plus the final answer:

Table 5: LLM calls per task, from the notebook's stated call counts. Rows past 2 steps extend its formula.

Three kinds of procedural memory

All three store "how to do it", with different writers and checks:

Table 6: Procedures, skills and workflows compared.

Both notebooks retrieve with a model call over a short list, which works at their size. With hundreds of skills or workflows, embed the descriptions and retrieve by similarity, as lesson 4 of T10.2 does for facts.

For a MemGPT-style Larkspur assistant answering Dana's refund question, the choices become four settings:

1. Put the plan in core memory. "Annual business plan" is durable and identity-level; it stays in every prompt.
2. Size the window from cost. A window of 6 keeps about 117 tokens of conversation; 9 keeps the traffic message for 39 more on every call.
3. Check the search in code. Log whether turn 6 called the archive search, and alert when a question about past numbers answers without one.
4. Replace the keyword search. Embed archive entries, so how much traffic? and data usage this month both find the 80 GB message.

Interview tip: when asked how an agent remembers, separate what it knows (facts), what happened (episodes) and what it can do (skills and workflows). Each needs its own writer and its own check.

1. Packer, C. et al. (2023). MemGPT: Towards LLMs as Operating Systems. arXiv:2310.08560.
2. Wang, G. et al. (2023). Voyager: An Open-Ended Embodied Agent with Large Language Models. arXiv:2305.16291.
3. Wang, Z. Z. et al. (2024). Agent Workflow Memory. arXiv:2409.07429.

The code for this lesson is in these notebooks. Colab runs one in your browser: install the packages its first cell imports and set the API keys it reads. To run every notebook as written, clone the repository and use its uv environment.

• MemGPT keeps core memory and a short message window in the prompt and moves everything else to an archive the agent searches with tools. The window is a budget paid on every call: 117 tokens at 6 messages, 156 at 9, in the lab.
• Archived facts come back only if the agent searches, with words that match. At a window of 6, Dana's 80 GB message ranked first for outbound traffic and was missed for how much traffic? and data usage this month.
• Voyager and Agent Workflow Memory store what worked, as code or tool-call templates. Check the library first, store only what passed tests that can fail, and treat generated code as untrusted.