{
"cells": [
{
"cell_type": "markdown",
"id": "72a873924b76",
"metadata": {},
"source": [
"# Chapter 15: What an Agent Should Remember: Retrieval, Compression, and Experience\n",
"\n",
"A controller remembers an earlier approval. The text is relevant, concise, and easy to retrieve. It can still be the wrong memory to use if the approval belongs to an older document version. Memory quality therefore includes authority and freshness, not only similarity or token efficiency.\n",
"\n",
"This notebook solves a small declared retrieval allocation. Records consume tokens and contribute additive decision value, but stale records and invalid version-bound authority are excluded first. A separate compression diagnostic checks whether the preferred action survives. The example intentionally gives an obsolete approval a very attractive value, making it impossible to confuse a high relevance score with current permission.\n",
"\n",
"**Outcome:** Choose fresh valid records and inspect action preservation under compression.\n",
"\n",
"- Inspect the declared input contract\n",
"- Predict the hand-checkable case\n",
"- Run the shared computation\n",
"- Change the critical assumption\n",
"- Apply the method to the transfer data\n",
"\n",
"**Guided route:** Run the worked calculation, inspect its figure, change the stated assumption, and try the transfer case. Read the explanations beside each result before opening the answers.\n",
"\n",
"**Deeper route:** First read the mathematics and canonical equation reference. Audit the input contract, predict the changed result, then inspect the shared chapter implementation and solve the questions independently. Both routes use the same calculations and preserve the equations."
]
},
{
"cell_type": "markdown",
"id": "a7781f3ee7dc",
"metadata": {},
"source": [
"## Technical Requirements\n",
"\n",
"Python 3.11 or later, the complete laboratory folder, and the notebook dependencies listed in `requirements-notebooks.txt` (the launcher's **Install notebook tools** choice installs them; see START-HERE). Standard-library chapter commands also support Python 3.10. No API key, model account or network call is used by this experiment.\n",
"\n",
"Prior knowledge:\n",
"\n",
"- Python lists and dictionaries\n",
"- The mapped chapter and its notation"
]
},
{
"cell_type": "markdown",
"id": "b383d4e2ae2e",
"metadata": {},
"source": [
"## The question and its mathematics\n",
"\n",
"For record i, let t_i be token cost, v_i declared decision value, and x_i in{0,1} retrieval status. The finite allocation maximizes sum_i v_i x_i subject to sum_i t_i x_i<=B. Freshness requires now-timestamp_i<=ttl_i. An authority-bearing record also requires its version to equal the current version.\n",
"\n",
"The code uses exact zero-one knapsack dynamic programming over integer budgets. Descending budget updates prevent the same record from being selected repeatedly. Its frontier gives the greatest eligible additive value at every budget from zero to B. These values are supplied judgments, not embedding similarity or empirically learned information gain.\n",
"\n",
"For compression, the implementation compares argmax_a Q_original(a) with argmax_a Q_compressed(a). Equal choices mean this particular decision is preserved. They do not imply the compressed memory retains every fact or supports every future task. Ties follow list order, so a genuine decision-preservation claim should also inspect whether a meaningful action gap remains."
]
},
{
"cell_type": "markdown",
"id": "fc0ecf647d2a",
"metadata": {},
"source": [
"## A calculation you can run\n",
"\n",
"Supply records with token counts, value, timestamps, time-to-live, authority flags, and version identifiers. The function checks numeric domains and rejects a timestamp later than now. It constructs freshness and authority validity before allocating budget. Invalid records remain visible in the returned table rather than disappearing without explanation.\n",
"\n",
"The plot shows the eligible retrieval frontier against token budget. The metrics identify selected and excluded records, used tokens, and compression choices. In the changed case reduce the budget and alter the compressed action values. Predict which record remains affordable and whether the action still matches. The two interventions address separate questions, so report both rather than attributing the entire change to memory quality.\n",
"\n",
"The next cell finds the bundle and imports the same computation used by the chapter skill. It does not change your system Python."
]
},
{
"cell_type": "code",
"execution_count": 1,
"id": "42ebefc0e5c1",
"metadata": {},
"outputs": [],
"source": [
"from pathlib import Path\n",
"import sys, json\n",
"LAB_ROOT = next((p for p in [Path.cwd(), *Path.cwd().parents] if (p / \"lab-manifest.json\").is_file()), None)\n",
"if LAB_ROOT is None:\n",
" raise RuntimeError(\"Open this notebook from the complete extracted laboratory folder.\")\n",
"sys.path.insert(0, str(LAB_ROOT / \"src\"))\n",
"from math_ai_agents.core import analyze, report_text\n",
"from math_ai_agents.plotting import figure_svg\n",
"from IPython.display import SVG, display\n"
]
},
{
"cell_type": "markdown",
"id": "7fffde8c0edb",
"metadata": {},
"source": [
"Set the declared inputs below. These are constructed teaching values, not measurements from a production agent. Change a value only after predicting what it should change."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "86212d08868b",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 15: memory-budget\n",
"Which memories deserve a limited retrieval budget, and does compression preserve the decision?\n",
"Evidence: constructed teaching example\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"retrieved_ids\": [\n",
" \"review-v2\",\n",
" \"summary\"\n",
" ],\n",
" \"retrieval_value\": 11.0,\n",
" \"tokens_used\": 6,\n",
" \"excluded_ids\": [\n",
" \"old-review\"\n",
" ],\n",
" \"compression_preserves_action\": true,\n",
" \"original_action\": 1,\n",
" \"compressed_action\": 1\n",
"}\n",
"\n",
"Interpretation:\n",
"Retrieval optimizes declared decision value among records that satisfy freshness and version-bound authority checks. Compression is checked by the action it preserves.\n",
"\n",
"Assumptions:\n",
"- Record values are additive and supplied, not inferred from text similarity.\n",
"- Exact finite subset search; no semantic embedding model.\n",
"\n",
"Limitations:\n",
"- Preserving one decision vector does not prove sufficiency for every future task.\n",
"- Retrieval relevance is not authority.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
}
],
"source": [
"chapter = 15\n",
"inputs = {'budget': 6,\n",
" 'now': 10,\n",
" 'current_version': 'v2',\n",
" 'records': [{'id': 'review-v2',\n",
" 'tokens': 4,\n",
" 'decision_value': 8,\n",
" 'timestamp': 9,\n",
" 'ttl': 3,\n",
" 'authority': True,\n",
" 'version': 'v2'},\n",
" {'id': 'summary',\n",
" 'tokens': 2,\n",
" 'decision_value': 3,\n",
" 'timestamp': 8,\n",
" 'ttl': 5,\n",
" 'authority': False,\n",
" 'version': 'v1'},\n",
" {'id': 'old-review',\n",
" 'tokens': 1,\n",
" 'decision_value': 100,\n",
" 'timestamp': 9,\n",
" 'ttl': 3,\n",
" 'authority': True,\n",
" 'version': 'v1'}],\n",
" 'original_action_values': [4, 6],\n",
" 'compressed_action_values': [3, 5]}\n",
"report = analyze(chapter, inputs)\n",
"# This input was explicitly taken from the teaching fixture.\n",
"report['evidence_kind'] = 'constructed teaching example'\n",
"print(report_text(report))"
]
},
{
"cell_type": "markdown",
"id": "fd5520949108",
"metadata": {},
"source": [
"At budget 6, review-v2 and summary fit exactly and contribute value 11. Old-review is excluded because its authority belongs to v1, despite its declared value 100 and low token cost. Its timestamp is fresh; freshness alone is therefore insufficient.\n",
"\n",
"Original action values [4,6] and compressed values [3,5] both prefer action 1. With changed budget 2, only summary is retrieved, giving value 3. Changed compressed values [6,5] prefer action 0, so compression no longer preserves the decision. That flag concerns this supplied value comparison; it does not infer which memory sentence caused the reversal.\n",
"\n",
"The plot below uses the calculated quantities. Read each panel's units before comparing its values."
]
},
{
"cell_type": "code",
"execution_count": 3,
"id": "590f57e74048",
"metadata": {},
"outputs": [
{
"name": "stderr",
"output_type": "stream",
"text": [
"Matplotlib is building the font cache; this may take a moment.\n"
]
},
{
"data": {
"image/svg+xml": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"display(SVG(figure_svg(report)))"
]
},
{
"cell_type": "markdown",
"id": "e3699acde71c",
"metadata": {},
"source": [
"**Figure 15.L1:** Calculated chapter experiment. Each panel labels its input and output units; interpret it under the assumptions printed in the report."
]
},
{
"cell_type": "markdown",
"id": "7dc80316f32d",
"metadata": {},
"source": [
"## Change the assumption\n",
"\n",
"Additive record values can overcount redundant memories. Two records that repeat the same fact may contribute less together than the sum of their isolated values. This implementation declares additivity rather than inventing a submodular or semantic model. If redundancy matters, provide a different valuation experiment.\n",
"\n",
"The authority boundary is equally important. A remembered instruction does not become authorized because it is recent, highly ranked, or compressed into a confident summary. Version checks preserve a limited current-state contract; broader permissions still need a live authority check.\n",
"\n",
"Compression can also preserve today's action while destroying tomorrow's distinction. The argmax diagnostic is task-relative. Test novel decisions and changed state before claiming sufficient memory. Keep excluded-record reasons in the report so token scarcity is not mistaken for intentional retention of unsafe evidence."
]
},
{
"cell_type": "code",
"execution_count": 4,
"id": "1bd9328523b6",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 15: memory-budget\n",
"Which memories deserve a limited retrieval budget, and does compression preserve the decision?\n",
"Evidence: constructed changed-assumption example\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"retrieved_ids\": [\n",
" \"summary\"\n",
" ],\n",
" \"retrieval_value\": 3.0,\n",
" \"tokens_used\": 2,\n",
" \"excluded_ids\": [\n",
" \"old-review\"\n",
" ],\n",
" \"compression_preserves_action\": false,\n",
" \"original_action\": 1,\n",
" \"compressed_action\": 0\n",
"}\n",
"\n",
"Interpretation:\n",
"Retrieval optimizes declared decision value among records that satisfy freshness and version-bound authority checks. Compression is checked by the action it preserves.\n",
"\n",
"Assumptions:\n",
"- Record values are additive and supplied, not inferred from text similarity.\n",
"- Exact finite subset search; no semantic embedding model.\n",
"\n",
"Limitations:\n",
"- Preserving one decision vector does not prove sufficiency for every future task.\n",
"- Retrieval relevance is not authority.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
},
{
"data": {
"image/svg+xml": [
""
],
"text/plain": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"changed_inputs = {'budget': 2,\n",
" 'now': 10,\n",
" 'current_version': 'v2',\n",
" 'records': [{'id': 'review-v2',\n",
" 'tokens': 4,\n",
" 'decision_value': 8,\n",
" 'timestamp': 9,\n",
" 'ttl': 3,\n",
" 'authority': True,\n",
" 'version': 'v2'},\n",
" {'id': 'summary',\n",
" 'tokens': 2,\n",
" 'decision_value': 3,\n",
" 'timestamp': 8,\n",
" 'ttl': 5,\n",
" 'authority': False,\n",
" 'version': 'v1'},\n",
" {'id': 'old-review',\n",
" 'tokens': 1,\n",
" 'decision_value': 100,\n",
" 'timestamp': 9,\n",
" 'ttl': 3,\n",
" 'authority': True,\n",
" 'version': 'v1'}],\n",
" 'original_action_values': [4, 6],\n",
" 'compressed_action_values': [6, 5]}\n",
"changed = analyze(chapter, changed_inputs)\n",
"changed['evidence_kind'] = 'constructed changed-assumption example'\n",
"print(report_text(changed))\n",
"display(SVG(figure_svg(changed)))"
]
},
{
"cell_type": "markdown",
"id": "ee8fda1f4718",
"metadata": {},
"source": [
"**Figure 15.L2:** The changed-assumption result. Compare the printed quantities and the stated assumptions with the first run. A different input need not imply a causal effect in a deployed agent."
]
},
{
"cell_type": "markdown",
"id": "97a5d9c17f6d",
"metadata": {},
"source": [
"## Try a new case\n",
"\n",
"The transfer case excludes expired even though it is cheap and valuable. Current is fresh, version-valid, and consumes the full budget 3, so it is selected with value 4. Both supplied decision vectors prefer action 0, preserving this action under compression.\n",
"\n",
"For local use, attach timestamps and document versions to records when those affect authority. Give decision values an explicit source, such as a constructed study or measured task benefit. A retrieval recommendation should name records to retain, records to exclude, and the evidence needed to justify their values. Use separate trace analysis when memory is trying to promote untrusted data into control."
]
},
{
"cell_type": "code",
"execution_count": 5,
"id": "feb4c2bdf9b0",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 15: memory-budget\n",
"Which memories deserve a limited retrieval budget, and does compression preserve the decision?\n",
"Evidence: constructed transfer example\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"retrieved_ids\": [\n",
" \"current\"\n",
" ],\n",
" \"retrieval_value\": 4.0,\n",
" \"tokens_used\": 3,\n",
" \"excluded_ids\": [\n",
" \"expired\"\n",
" ],\n",
" \"compression_preserves_action\": true,\n",
" \"original_action\": 0,\n",
" \"compressed_action\": 0\n",
"}\n",
"\n",
"Interpretation:\n",
"Retrieval optimizes declared decision value among records that satisfy freshness and version-bound authority checks. Compression is checked by the action it preserves.\n",
"\n",
"Assumptions:\n",
"- Record values are additive and supplied, not inferred from text similarity.\n",
"- Exact finite subset search; no semantic embedding model.\n",
"\n",
"Limitations:\n",
"- Preserving one decision vector does not prove sufficiency for every future task.\n",
"- Retrieval relevance is not authority.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
}
],
"source": [
"transfer_inputs = {'budget': 3,\n",
" 'now': 20,\n",
" 'current_version': 'doc-C',\n",
" 'records': [{'id': 'expired',\n",
" 'tokens': 1,\n",
" 'decision_value': 10,\n",
" 'timestamp': 10,\n",
" 'ttl': 2,\n",
" 'authority': False,\n",
" 'version': 'doc-C'},\n",
" {'id': 'current',\n",
" 'tokens': 3,\n",
" 'decision_value': 4,\n",
" 'timestamp': 19,\n",
" 'ttl': 3,\n",
" 'authority': True,\n",
" 'version': 'doc-C'}],\n",
" 'original_action_values': [1, 0],\n",
" 'compressed_action_values': [2, 1]}\n",
"transfer = analyze(chapter, transfer_inputs)\n",
"transfer['evidence_kind'] = 'constructed transfer example'\n",
"print(report_text(transfer))"
]
},
{
"cell_type": "markdown",
"id": "b6f027d12192",
"metadata": {},
"source": [
"## Apply the method to your inputs\n",
"\n",
"The example file below has the exact input shape the method accepts. Copy it to a new file, replace its values, then point `reader_file` at your copy. Run the cell again. Supplied inputs retain their stated provenance; the program cannot establish that they are representative observations.\n",
"\n",
"- **budget:** Nonnegative integer token budget up to 10000.\n",
"- **now:** Nonnegative current time.\n",
"- **current_version:** Current document or state version identifier.\n",
"- **records:** At most 20 records. Each has id,tokens:positive integer,decision_value:nonnegative number,timestamp,ttl:nonnegative numbers,authority:boolean,version:string.\n",
"- **original_action_values:** Finite values for each original decision alternative.\n",
"- **compressed_action_values:** Aligned values after compression."
]
},
{
"cell_type": "code",
"execution_count": 6,
"id": "1b68936bf048",
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Chapter 15: memory-budget\n",
"Which memories deserve a limited retrieval budget, and does compression preserve the decision?\n",
"Evidence: supplied local inputs; provenance not independently verified\n",
"\n",
"Calculated quantities:\n",
"{\n",
" \"retrieved_ids\": [\n",
" \"current\"\n",
" ],\n",
" \"retrieval_value\": 4.0,\n",
" \"tokens_used\": 3,\n",
" \"excluded_ids\": [\n",
" \"expired\"\n",
" ],\n",
" \"compression_preserves_action\": true,\n",
" \"original_action\": 0,\n",
" \"compressed_action\": 0\n",
"}\n",
"\n",
"Interpretation:\n",
"Retrieval optimizes declared decision value among records that satisfy freshness and version-bound authority checks. Compression is checked by the action it preserves.\n",
"\n",
"Assumptions:\n",
"- Record values are additive and supplied, not inferred from text similarity.\n",
"- Exact finite subset search; no semantic embedding model.\n",
"\n",
"Limitations:\n",
"- Preserving one decision vector does not prove sufficiency for every future task.\n",
"- Retrieval relevance is not authority.\n",
"\n",
"Execution: completed locally; constructed inputs are not deployment measurements.\n"
]
}
],
"source": [
"reader_file = LAB_ROOT / 'data/examples/ch15.json'\n",
"reader_inputs = json.loads(reader_file.read_text())\n",
"reader_report = analyze(chapter, reader_inputs)\n",
"print(report_text(reader_report))"
]
},
{
"cell_type": "markdown",
"id": "793db50da629",
"metadata": {},
"source": [
"## Questions\n",
"\n",
"1. Why exclude old-review?\n",
"\n",
"2. What is default retrieval value?\n",
"\n",
"3. Does action preservation prove all future information survives?\n",
"\n",
"Answers: [separate solutions](../solutions/ch15.md). Try the calculation before opening them."
]
},
{
"cell_type": "markdown",
"id": "4a939bdb7eb7",
"metadata": {},
"source": [
"## Summary\n",
"\n",
"Memory selection is a decision under cost, freshness, and authority. Exact knapsack allocation chooses among eligible records; action comparison checks a limited compression property. The obsolete approval is excluded despite its high value, the changed budget reduces retrieval, and changed compression reverses the action. These calculations do not perform semantic retrieval or establish universal sufficiency. Preserve the valuation and version contract whenever memory influences an action.\n",
"\n",
"Limits of this experiment:\n",
"\n",
"- This is a local calculation under declared inputs, not an empirical claim about a deployed agent.\n",
"- Read the returned assumptions and limitations before applying the numerical result.\n",
"\n",
"The assistant skill is [`maa-15-memory-budget`](../skills/maa-15-memory-budget/SKILL.md). It uses this notebook's tested computation and input contract."
]
},
{
"cell_type": "markdown",
"id": "9cc9f25ba898",
"metadata": {},
"source": [
"## Equations from the chapter\n",
"\n",
"These are the unchanged display equations and their explanations from the canonical chapter. They are a reference for the experiment, not a claim that every equation is numerically implemented by this one method."
]
},
{
"cell_type": "markdown",
"id": "c5c902c8502c",
"metadata": {},
"source": [
"### Equation 15.1\n",
"\n",
"\n",
"\n",
"Equation (15.1) selects records by expected decision value under a stated context budget.\n",
"\n",
"Include records only when expected decision improvement exceeds the decision-value-priced token cost within budget.\n",
"\n",
"LaTeX source, preserved for inspection:\n",
"\n",
"```latex\n",
"R^\\star\\in\\arg\\max_{R:\\,\\sum_{m\\in R}c(m)\\le B}\n",
"\\left\\{\\operatorname E[\\text{decision value}\\mid R]-\\lambda\\sum_{m\\in R}c(m)\\right\\}.\n",
"\\tag{15.1}\n",
"```"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Mathematics of AI Agents",
"language": "python",
"name": "maa-lab"
},
"lab_chapter": 15,
"lab_execution": {
"code_cells": 6,
"created_utc": "2026-10-02T05:15:09.957858+00:00",
"elapsed_seconds": 8.917202083976008,
"method": "fresh process; new ipykernel InProcessKernelManager; cells submitted as Jupyter execute requests",
"network_transport_tested": false,
"python": "3.11.15",
"source_sha256": "1fef17b53eeb38382eab888047ae3be60894bd9e930c97dfd839f2b19316fdd0"
},
"language_info": {
"name": "python"
}
},
"nbformat": 4,
"nbformat_minor": 5
}