Glossary
85 terms from “Agent Memory and State.” Hover the first occurrence in the lesson for its definition.
| Term | Definition | Source |
|---|---|---|
| stateless | The property that the server keeps no private per-session state between one API call and the next, so every request must carry the full conversation history itself. | Using the Messages API |
| context window | The container holding everything the model can actually see in one request: the system prompt, every message in the messages array, the tool definitions, and the model's own output for the turn. | Context windows |
| system prompt | Text sent with the request that sets the model's role and behavior; the official docs list it as one of the components that counts toward the context window. | Context windows |
| tool definitions | The name, description, and input_schema you pass to the model to describe each available tool; the docs state they count toward the same request's context window. | Context windows |
| extended thinking | The reasoning content the model produces while generating this turn's reply; the docs state it counts toward this turn's context window usage. | Context windows |
| usage | The field in the API response that reports how many input and output tokens the request actually consumed. | Context windows |
| context rot | The phenomenon named in the official docs where accuracy and recall degrade as the token count in the window grows. | Context windows |
| accumulation | The default behavior in which conversation history piles up in the context window turn after turn, growing and never shrinking unless something actively clears it. | Context windows |
| resend | The real mechanism behind the word "memory" — every request re-sends the earlier history messages to the model verbatim, rather than the model storing or recalling anything itself. | Using the Messages API |
| multiple sessions | The scope of information that has to outlive a single conversation and survive across independent sessions, which stuffing it into the current messages array cannot achieve. | Context windows |
| Messages API | The API this course builds on; its official docs state plainly that it is stateless and that you always send the full conversational history with each request. | Using the Messages API |
| append | The plainest way to manage conversation history — after each turn, tack the new messages onto the end of the existing messages array and send the whole array again next turn. | Context windows |
| truncation | Cutting the oldest batch of messages outright when the window is nearly full and keeping only the most recent N — simple to implement, but what it drops is gone irreversibly. | Context windows |
| compaction | The official mechanism that distills the contents of a context window into a high-fidelity summary, letting the agent continue with minimal performance degradation once the conversation gets long. | Context engineering: memory, compaction, and tool clearing |
| high-fidelity summary | What compaction produces — a distilled version that replaces the long run of raw history and sits at the front of the window, keeping what happened and what was concluded while dropping word-for-word detail. | Context engineering: memory, compaction, and tool clearing |
| trigger threshold | The window-usage level at which an official mechanism automatically starts compacting or clearing tool results. | Context engineering: memory, compaction, and tool clearing |
| tool-result clearing | The official mechanism aimed at bloat from tool use itself — it drops old, re-fetchable results while keeping the record that the call happened. | Context engineering: memory, compaction, and tool clearing |
| re-fetchable | The qualifier that decides what clearing may drop — content the tool returned that has gone stale and can be obtained again by calling the same tool with the same arguments. | Context engineering: memory, compaction, and tool clearing |
| 150K tokens | Compaction's default trigger threshold — compaction fires automatically once window usage reaches this level. | Context engineering: memory, compaction, and tool clearing |
| 100K tokens | Tool-result clearing's default trigger threshold, lower than compaction's 150K, reflecting its role of stepping in earlier against the single bloat source of tool output. | Context engineering: memory, compaction, and tool clearing |
| 50K tokens | The server-enforced floor for compaction's trigger threshold — the configured value must be at least this large, so the threshold cannot be lowered arbitrarily. | Compaction |
| the most recent 3 tool calls | Tool-result clearing's default retention policy — the full results of the last three tool calls stay intact, and older tool results get cleared. | Context engineering: memory, compaction, and tool clearing |
| mental model | The Cookbook's three-way division of labor for handling context bloat — compaction for a window that's grown too large, clearing for stale re-fetchable data inside it, memory for surviving across sessions. | Context engineering: memory, compaction, and tool clearing |
| window usage | The measure of how much context-window capacity the current conversation history occupies; it's what you check to decide whether to truncate, compact, or clear. | Context engineering: memory, compaction, and tool clearing |
| whole-transcript | The scope of compaction — user messages, assistant messages, tool calls, tool results, and even prior compaction blocks all get flattened into the new summary. | Context engineering: memory, compaction, and tool clearing |
| round-trip | One complete tool-calling exchange — the assistant message carrying tool_use plus the user message carrying the matching tool_result — the smallest unit history slicing may treat as atomic. | Handle tool calls |
| tool_use_id | The identifier binding a tool_result block back to the tool_use block that produced it; clearing replaces the result's content but leaves this id in place. | Handle tool calls |
| external memory | Storage that isn't bound to a single conversation's lifecycle — usually a file on disk — so information written there can still be read after the session ends. | Context engineering: memory, compaction, and tool clearing |
| memory file | A file kept on disk to carry information across sessions — CLAUDE.md being the representative case — which may be loaded into context in full or in part when a session begins. | How Claude remembers your project |
| loaded into the context window | The process by which a memory file's contents are read from disk and injected into a specific request, making them visible to the model for that turn. | How Claude remembers your project |
| block-level HTML comments | Content wrapped in <!-- --> inside a CLAUDE.md file; the docs state it is stripped before the content is injected into the agent's context. | How Claude remembers your project |
| Auto memory | Memory written by the model itself as the conversation goes, structured as an index file plus on-demand topic files, complementing the human-written CLAUDE.md. | How Claude remembers your project |
| index file | The first layer of Auto memory's two-layer structure — MEMORY.md, for instance — which stores per-topic entry summaries rather than the full content of each topic. | How Claude remembers your project |
| retrieval on demand | Loading only the index's entry summaries at session start, and reading a specific topic memory file only when the current task actually needs it. | How Claude remembers your project |
| MEMORY.md | Auto memory's index file; the official rule is that only its first 200 lines or first 25KB, whichever comes first, load at the start of each conversation. | How Claude remembers your project |
| CLAUDE.md | A human-written project memory file loaded in full into context at the start of every session; the official size target is under 200 lines, with a hard limit of 4 MiB. | How Claude remembers your project |
| 200 lines | The official size target recommended for a CLAUDE.md file; going past it consumes more context and lowers the agent's adherence to instructions. | How Claude remembers your project |
| 4 MiB | The genuine hard limit for CLAUDE.md — a file up to this size is loaded in full, and anything larger is skipped entirely. | How Claude remembers your project |
| /compact | The compaction command in Claude Code; the docs note a project-root CLAUDE.md survives it, being re-read from disk and re-injected into the session afterward. | How Claude remembers your project |
| boundary check | Path-checking logic added to a memory file's read/write tool so the tool cannot be talked into reading or writing files outside the memory directory. | How Claude remembers your project |
| same-prefix sibling directory | The directory that defeats a bare string-prefix path check — /project/memory-evil shares the prefix /project/memory and so passes startsWith, even though it sits entirely outside the memory root. | How Claude remembers your project |
| path.sep | Node's constant for the platform's path separator, used in the safe boundary condition abs.startsWith(ROOT + path.sep) so only paths beginning with "root plus separator" match. | How Claude remembers your project |
| structured state | Task progress expressed through fixed fields — a todo list with explicit status markers — that host code can parse reliably, as opposed to progress described in prose. | Track todos |
| todo list | A multi-step task broken into a set of items, each carrying an explicit status field, so the agent and the host code can track progress together. | Track todos |
| lifecycle | The four stages a todo moves through from the moment it is identified until it is no longer needed: created, activated, completed, removed. | Track todos |
| pending | The first state in a todo's lifecycle — the item has been identified and added to the list, but work on it hasn't started. | Track todos |
| in_progress | The second state in a todo's lifecycle — when the work actually begins, the status moves from pending to this value. | Track todos |
| completed | The third state in a todo's lifecycle — the status set when the task finishes successfully. | Track todos |
| deleted | The fourth state in a todo's lifecycle — a todo that's no longer needed is removed by setting its status to this value in a TaskUpdate call. | Track todos |
| task-tracking tool | The tool that lets an agent create and update todo statuses, so task progress appears in the message stream as structured tool calls. | Track todos |
| structured tool call | The form in which a task-tracking status change appears in the message stream — an identifiable, independently parseable call rather than a line of prose. | Track todos |
| checkpoint | A task's state at a point in time written out as data and persisted somewhere outside the session's lifetime, so execution can resume after an interruption. | Track todos |
| recoverability | The ability, after a process restart, to read the most recent checkpoint and continue from where the work stopped instead of starting over. | Track todos |
| idempotent | The property of an operation that produces the same result no matter how many times it runs, so re-running it causes no extra side effects. | Track todos |
| TaskUpdate | The tool call used to change a todo's status; every step of the lifecycle, removal included, goes through it. | Track todos |
| MemoryTrap | A real vulnerability disclosed by Cisco researchers describing how a seemingly harmless routine — clone a repo, approve a dependency install — turns into persistent prompt injection. | Memory Is a Feature. It Is Also an Attack Surface |
| ASI06 | OWASP's risk-category identifier for agent security covering Memory & Context Poisoning, the class MemoryTrap maps to. | Memory Is a Feature. It Is Also an Attack Surface |
| persistent memory | Storage an agent reads and trusts across sessions; because it is loaded automatically and repeatedly, anything written there shapes future behavior, not just one response. | Memory Is a Feature. It Is Also an Attack Surface |
| persistent prompt injection | What a routine developer workflow turned into in MemoryTrap — injected content that isn't confined to one turn but is written where it will be reloaded and re-trusted in future sessions. | Memory Is a Feature. It Is Also an Attack Surface |
| stale memory | Content in persistent memory that was once correct but no longer applies, and is still executed as a currently valid rule simply because it's sitting in memory. | Memory Is a Feature. It Is Also an Attack Surface |
| trusted surfaces | Places like memory, hooks, and configuration that the system loads repeatedly as a trusted source, so malicious content reaching them can be exploited over and over. | Memory Is a Feature. It Is Also an Attack Surface |
| future reasoning | What an attacker actually influences once malicious content reaches a trusted surface — not this one response, but the model's reasoning across many future sessions. | Memory Is a Feature. It Is Also an Attack Surface |
| hooks configuration | The global configuration that, alongside persistent memory, malicious content also reached in the MemoryTrap case — another store the system loads and trusts repeatedly. | Memory Is a Feature. It Is Also an Attack Surface |
| highly trusted instruction layer | The layer MemoryTrap's malicious content influenced through the system prompt — a source of instructions the system grants a high degree of trust. | Memory Is a Feature. It Is Also an Attack Surface |
| memory poisoning | Malicious content actively written into persistent memory or another trusted surface, so storage that should be trustworthy instead carries an attacker's payload. | Memory Is a Feature. It Is Also an Attack Surface |
| Credentials | Keys, passwords, and access tokens — content that, once written into an automatically loaded memory file, gets re-exposed in the window every session for no matching benefit. | Memory Is a Feature. It Is Also an Attack Surface |
| untrusted raw text | File contents, web text, and dependency output an agent reads while doing a task — input data for that one task, not something to be copied verbatim into persistent memory. | Memory Is a Feature. It Is Also an Attack Surface |
| Stable, confirmed rules and facts | Content from a clearly trustworthy source that a human has confirmed — code-style conventions, a root cause established by real investigation — the kind worth writing to persistent memory. | Memory Is a Feature. It Is Also an Attack Surface |
| memory read/write tools | The pair of tools (read_memory / write_memory) that let an agent write content worth keeping out beyond the window and retrieve what it stored earlier. | How Claude remembers your project |
| memory root | The directory dedicated to memory files (MEMORY_ROOT in the code); every operation the memory read/write tools perform is confined to it. | How Claude remembers your project |
| write_memory | The tool that writes text into a file under the memory root; its description spells out the "what to store" boundary that Lesson 5 established. | How Claude remembers your project |
| prompt-level guidance | A rule expressed only in a tool's description, which steers the model's behavioral tendency but is not enforced by code the way a path check is. | Memory Is a Feature. It Is Also an Attack Surface |
| cross-session memory backfill | Logic that actively reads memory files when a new session starts and injects their contents as an initial message, so memory is in the window from the very first turn. | How Claude remembers your project |
| hand-written compaction | This course's simplified teaching implementation of compaction — trigger on a character budget, split history on complete round-trip boundaries, then make one model call to generate the summary. | Context engineering: memory, compaction, and tool clearing |
| compact_20260112 | The identifier for Anthropic's native compaction feature, triggering at 150K tokens by default — the mechanism the lesson's hand-written version merely imitates. | Context engineering: memory, compaction, and tool clearing |
| clear_tool_uses_20250919 | The identifier for Anthropic's native tool-result clearing feature, triggering at 100K tokens by default and keeping the last 3 calls' results. | Context engineering: memory, compaction, and tool clearing |
| character budget | A crude teaching approximation that gauges token usage by character count to decide whether history needs compacting; it is not a precise token count. | Context engineering: memory, compaction, and tool clearing |
| splitKeepingToolPairs | The helper that decides where to cut history for compaction, backing the cut point up until a tool_use / tool_result pair is no longer split across the summary and the kept portion. | Handle tool calls |
| summary message | The single message a hand-written compaction produces to replace the earlier history, spliced in at the front of the messages array. | Context engineering: memory, compaction, and tool clearing |
| summarization call | The extra model call a hand-written compaction makes to generate the summary — one of the concrete costs of compacting. | Context engineering: memory, compaction, and tool clearing |
| placeholder content | The stand-in text a hand-written clearing function swaps in for old tool_result content beyond the keep count, leaving the tool_use_id untouched. | Context engineering: memory, compaction, and tool clearing |
| keep count | The number of most recent tool calls whose full results are preserved by clearing; results beyond it get replaced with placeholder content, echoing the native default of 3. | Context engineering: memory, compaction, and tool clearing |
| history-trimming | The capability this lesson adds to the execution loop so a long conversation doesn't balloon forever, covering both hand-written compaction and tool-result clearing. | Context engineering: memory, compaction, and tool clearing |
| TOOLS | The single table registering each tool's schema alongside its implementation function; the loop derives toolSchemas and toolHandlers from it. | How tool use works |
| memory-augmented loop | The finished loop this lesson builds — the execution loop from the tool-calling course with memory read/write, memory backfill, hand-written compaction, and tool-result clearing all fitted in. | How tool use works |