Most analytics agents are stateless. You spin one up, it queries the warehouse, it gives you an answer, and everything it learned evaporates. The next session starts from scratch: the same schema discovery, the same freshness checks, the same stumbling over that column that was renamed in January. The difference between an agent that stays useful for a week and one that becomes indispensable over months is entirely about how it manages context. Not just what context it loads, but how that context is layered, budgeted, and persisted across sessions.

If you already have a specialized agent running with domain context in a CLAUDE.md file (the setup covered in Building specialized analytics agents), the patterns below will make it dramatically more effective. If you don't have that foundation yet, this guide will still make sense, but you'll get more out of it once you do.

The three layers of agent context

Context management determines whether your agent produces a useful answer or an expensive hallucination. Grounding LLMs with retrieved context dramatically reduces hallucination (Lewis et al., 2020). But treating "context" as a single blob is a mistake. The metric definitions your agent needs every session have nothing in common with the intermediate query results it accumulates during a single investigation. Conflating the two leads to bloated prompts, wasted tokens, and context windows that fill up before the agent finishes its work. There are three distinct layers, each with different lifetimes and management needs.

Context architecture
Three layers of agent context
1
Static context
Metric definitions, schema documentation, query conventions, business rules. Loaded at agent start. Changes rarely. Lives in CLAUDE.md or system prompts.
2
Session context
Schema samples, data freshness checks, table statistics. Gathered at the start of each investigation. Changes per session. Built by the agent's own queries.
3
Investigation context
Intermediate query results, hypotheses, dead ends. Accumulated during the investigation. Ephemeral. Managed within the agent's context window.

Static context is the easiest to get right. You write it once and update it occasionally. The real operational challenge starts with session context: the information your agent needs to gather fresh every time it spins up.

Session context: the warm-up phase

Before an agent starts investigating a question, it should orient itself to the current state of the data. A warm-up routine costs a few seconds and prevents the agent from confidently analyzing data that was last updated three days ago.

CLAUDE.md /session warm-up
## Session warm-up (run before every investigation)
Before answering any question, run these checks silently:
1. Check data freshness: SELECT MAX(date) FROM each primary table
2. Check row counts for the relevant time period
3. Verify that key joins still work (accounts ↔ subscriptions)
4. Note any anomalies (sudden drops in row counts, NULL spikes)

If any check fails, report the data issue BEFORE answering the
question. Do not proceed with stale or broken data.

A warm-up routine like this takes seconds and prevents entire categories of wrong answers. But once the agent passes warm-up and starts actually investigating, a different problem emerges: the context window itself becomes a scarce resource.

Investigation context: managing the window

Long investigations accumulate context: query results, intermediate tables, dead-end hypotheses. This is where agents start to degrade. The context window fills up, earlier findings get pushed out, and the agent starts repeating queries it already ran.

Two strategies work well:

CLAUDE.md /context management
## Context management rules
- After each query, summarize the key finding in 1-2 sentences
- Do NOT paste full query results into your reasoning. Extract
  the relevant numbers and discard the rest.
- For investigations with more than 5 queries, write a running
  summary to ./investigation-log.md with:
  - Question being investigated
  - Each step taken (query + finding)
  - Current hypothesis
  - Next planned step
- If you lose track of what you've already checked, read
  investigation-log.md before proceeding

Managing the window well keeps a single investigation on track. But the real leverage comes from what happens between investigations: carrying forward what the agent learned so it doesn't start cold next time.

Cross-session memory

The most impactful context pattern is cross-session memory: the agent remembers what it learned in previous investigations. This is where an agent transitions from a tool you re-train every session to one that compounds knowledge over time.

File-based persistence is the simplest implementation. The agent maintains a small set of memory files and reads them at the start of each session.

CLAUDE.md /cross-session memory
## Memory
- After completing an investigation, append a summary to
  ./memory/findings.md with the date, question, and key findings
- Before starting a new investigation, check ./memory/findings.md
  for relevant prior work
- Maintain ./memory/schema-notes.md with anything you learn about
  the data that isn't in the schema docs (quirks, gotchas, etc.)
- Maintain ./memory/metric-corrections.md if you discover that a
  metric definition in this file is wrong or incomplete

The findings.md file becomes the agent's institutional memory. The first investigation might take ten queries to orient itself. By the twentieth, the agent already knows that July EMEA numbers are low because of holidays, that the EU double-count bug affects March 2025, and that the segment_id column was replaced mid-year. None of that has to be rediscovered.

This is where file-based memory compounds. Each entry costs almost nothing to write, just a few sentences after an investigation completes, but the cumulative effect is dramatic. An agent with fifty entries in findings.md has absorbed weeks of analyst tribal knowledge. Its query count per investigation drops because it skips the exploratory queries that a fresh agent would need. It stops asking "why is March high?" because it already recorded the spring promo pattern. It stops joining on the wrong ID column because schema-notes.md documents the mid-year rename. The investment is front-loaded; the returns accelerate with every session.

memory/findings.md — example entry
## 2026-04-07: Q1 revenue variance
Question: Why did Q1 revenue miss plan by $1.2M?
Finding: 73% of the shortfall came from two non-renewals in
Enterprise EMEA (accounts acct_4821 and acct_7203). Both had
flagged low health scores since January.
Note: The revenue.quarterly_plan table uses fiscal quarters
(FY starts Feb 1), not calendar quarters. Always check which
quarter definition the stakeholder means.

## 2026-03-22: March spike investigation
Question: Why is March MRR 18% above February?
Finding: Expected. Spring promo campaign runs March 1-15.
See business calendar in CLAUDE.md.
Note: Trial conversions from the promo inflate new business ARR
for about 6 weeks after the campaign ends.

Cross-session memory assumes that the underlying data stays consistent enough for past findings to remain valid. In practice, it doesn't. That brings us to one of the harder problems in long-lived agents.

Handling schema drift

Data schemas change. Columns get renamed, tables get deprecated, new fields appear with different semantics. An agent that was accurate in January can silently start producing wrong answers in April if it hasn't been updated.

Three patterns help:

Version-stamp your context. Include a "last validated" date in your table context files. Add a check to the agent's warm-up that flags when the table's actual schema doesn't match what's documented.

CLAUDE.md /schema validation
## Schema validation (run during warm-up)
For each primary table, run:
  SELECT column_name, data_type
  FROM INFORMATION_SCHEMA.COLUMNS
  WHERE table_name = '{table}'

Compare against the columns documented in context/tables/{table}.md.
If any column in the docs doesn't exist in the table, or if a
column's type has changed, STOP and report the discrepancy before
proceeding. Do not guess at alternative column names.

Write schema notes to memory. When the agent discovers an undocumented column, a renamed field, or a deprecated table, it should add the finding to memory/schema-notes.md immediately. This creates a running changelog of discovered schema changes that can be reviewed and folded into the formal documentation.

Date your metric definitions. When a metric definition changes (a new ARR calculation that excludes a newly created contract type, for example), add a date to the definition rather than replacing it. Agents need to know which formula applied when for historical analysis.

CLAUDE.md /versioned metric definitions
## Metric definitions

### MRR (current: from 2026-01-01)
SUM of active subscription monthly amounts, excluding trials
AND excluding month-to-month contracts under $500 (added 2026-01-01)

### MRR (legacy: before 2026-01-01)
SUM of active subscription monthly amounts, excluding trials only

When analyzing periods that span the 2026-01-01 boundary, note
which definition applies to which portion of the analysis.

Schema drift handling adds more context to manage: validation queries, schema notes, versioned definitions. All of this is valuable, but it has a cost in tokens. The question becomes how to fit everything into a finite context window without losing the information that matters.

Context budgeting

Context windows are finite. A detailed table context file, a full findings.md, and a running investigation log can together consume a significant fraction of the available context before the agent writes a single query. Left unmanaged, this leads to truncation: the agent silently loses earlier context and starts making errors it would have avoided if the window were clear.

A practical budget for a specialized analytics agent:

CLAUDE.md /context loading rules
## Context loading

### Always load
- This file (CLAUDE.md)
- context/relationships.md
- memory/findings.md (last 20 entries only)
- memory/schema-notes.md

### Load on demand
- context/tables/{table}.md — load when you first query that table
- memory/metric-corrections.md — load if you're calculating metrics
- memory/findings-archive.md — load only if asked about historical work

### Never load into active context
- Raw query results (summarize instead)
- Full CSV files (sample 5 rows max, then describe the rest)

The goal is to keep the agent's working context focused on what it actually needs for the current investigation. Everything else should be on disk and readable on demand, not pre-loaded into every session. Get the budget right, and you have an agent that stays sharp across long investigations without drowning in its own history.

Putting it together

The core principle is straightforward: layer your context by lifetime. Permanent context (metric definitions, schema docs, business rules) lives in static files and changes rarely. Per-session context (freshness checks, row counts, current schema state) is gathered at warm-up and discarded when the session ends. Per-investigation context (intermediate results, hypotheses, dead ends) is managed within the context window and summarized aggressively to avoid filling it up.

The investment in getting these layers right pays off exponentially. A well-structured agent doesn't just perform better on its next investigation; it performs better on every subsequent investigation, because cross-session memory compounds. By the time your agent has run thirty or forty investigations, it has accumulated a body of institutional knowledge that would take a new analyst weeks to build. The query count drops, the accuracy improves, and the agent starts catching data quality issues before you even ask about them.

Once you have structured context flowing through your agent, the natural next question is: how do you observe what it's actually doing with that context? Which memory entries is it using? Where is it spending tokens? The observability and traceability guide covers logging, cost tracking, and debugging patterns for agents in production.

If you haven't yet set up a specialized agent with domain context, start with Building specialized analytics agents. It covers the foundation that the patterns in this guide build on.

References & further reading