Context Budgets: What to Load at Session Start

Load enough to choose the next read

A session opening before the first user prompt cannot know whether the engineer wants a migration review, a failing test explained or a release note. Loading the deployment handbook and six months of remembered decisions makes that choice prematurely. The opening context should help the agent find the right material once the request arrives.

Anthropic’s context-engineering guidance describes retaining lightweight references and retrieving their contents just in time. Apply that idea to startup: include stable preferences, descriptions of available memories and descriptions of available skills. Keep incident transcripts, historical debugging sessions and complete procedures behind those references.

Use a concrete admission question for every proposed startup item: will this help select the next read across the sessions this bootstrap serves? A preferred response language might qualify. A workaround for one retired database driver probably needs a searchable entry instead. Required project instructions need their own allocation; optional remembered facts should not crowd them out.

Give the bootstrap a separate budget

Set a limit on the assembled startup payload before writing a loader. As an illustrative policy, allow 8,000 UTF-8 bytes for optional memory and skill discovery, allocated as follows. These numbers are a starting design to evaluate, not a vendor limit or a measured optimum.

• Profile: 1,000 bytes. Stable working preferences and the user’s relevant role, with links to longer records.
• Memory index: 3,000 bytes. Short descriptions and retrievable paths for the current project and person.
• Skill catalog: 3,000 bytes. Names, activation descriptions and locations for applicable skills.
• Routing and status: 1,000 bytes. How to search omitted entries, the payload revision and any unavailable category.

Measure the final serialized payload, including headings and paths. Count its tokens separately with the tokenizer used by the target model; bytes do not have a fixed conversion to tokens. Repeat that measurement for multilingual profiles and long identifiers.

This allocation covers only the optional bootstrap. Record the context already occupied by project instructions and tool definitions alongside it. Otherwise an 8,000-byte loader can look disciplined while another startup mechanism injects an entire handbook. Leave capacity for the first prompt, retrieved evidence and subsequent tool results.

Make each index entry earn its space

Recommend one compact memory entry containing a topic, a useful retrieval trigger, a path and a freshness marker. For example: “Billing migration: why invoice IDs remain strings; memory/billing-id-decision.md; reviewed 2026-10-20.” This points to a decision without loading its background discussion. The freshness marker reports review history; it does not prove the decision still applies.

Claude Code’s memory documentation provides an example of this separation: its startup memory index points to topic files that are read on demand. For your own index, prefer distinguishing descriptions over generic labels such as “project notes.” An agent needs to tell a schema decision apart from an incident timeline before spending a read.

The Agent Skills specification similarly separates startup metadata from activated instructions and supporting resources. Use the skill’s name and description to explain when it applies, then fetch its full SKILL.md when selected. Keep long examples and reference material behind further reads.

When the catalog exceeds its allowance, narrow it by workspace or project and expose a search route for the remainder. Report that the catalog is partial. Alphabetical truncation can silently remove the only relevant skill; relevance-based selection still needs a way to discover omitted entries. See organizing a shared skills repository for maintaining those retrievable procedures.

Attach one bounded payload to Claude Code

Claude Code’s hooks reference documents SessionStart, its startup matcher and plain-text stdout being added to context. For a macOS or Linux example, put this in the project’s .claude/settings.json. It reads a prepared local snapshot; generate that snapshot separately from the current profile, index and catalog.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "cat \"${CLAUDE_PROJECT_DIR}/.claude/session-bootstrap.txt\"",
            "timeout": 2
          }
        ]
      }
    ]
  }
}

The command only reads the file; it does not enforce the byte allowance. Have the snapshot generator reject oversized output before replacing the last valid file. Begin the snapshot with a plain-text heading, keep diagnostics out of stdout, and include its revision and generation time.

The timeout is in seconds. This matcher targets fresh sessions; the reference lists separate matchers for resume and compaction. Choose those deliberately to avoid duplicate injection. Keep static project instructions in CLAUDE.md, which the documentation recommends for static context. Budget for both inputs.

Fetch task evidence after the prompt arrives

Suppose the first request is to change invoice serialization. The startup index supplies a route to the billing decision. Read that decision and inspect the current serialization code; load a migration skill only if its activation description matches the work. Do not retrieve every billing memory because one billing term appeared.

Give deferred reads their own response limits. An index that saves startup space but opens a 50,000-word memory file simply postpones the overflow. Split records by decision or topic, return bounded excerpts for search and preserve paths for follow-up reads. Keep recalled records visibly separate from maintained project instructions.

Handle an unavailable optional memory service with an explicit status and a finite retrieval deadline. An outage should mean “memory unavailable,” rather than an empty result that implies no relevant history exists. Let the agent use the repository and ask for missing context when necessary. Treat any mandatory startup policy separately from optional personalization. The timing trade-offs belong in recall on every prompt; startup needs only the route into that process.

How SPYN3 bounds startup context

SPYN3’s optional Memory & skills layer includes a plugin for Claude Code and Codex. Its SessionStart hook loads the person’s profile, a memory index and the skill catalog, capped at 9,500 bytes. UserPromptSubmit recalls relevant memories with a short timeout and adds nothing if SPYN3 is slow or unavailable. Any MCP client can use context_list, context_read and context_search. Recalled memory is labelled as recorded data. Memory & skills is off by default; an admin enables it per workspace.

Test whether the smaller opening still finds the answer

Compare three startup variants on the same task set: no optional memory, the bounded bootstrap and full memory loading. Include a task needing a remembered decision, one needing a rarely used skill and one requiring no history. Judge whether the agent finds and uses the right record, not whether it repeats profile details.

Record startup bytes, startup tokens, time to the first useful action and the number of retrievals before the relevant evidence appears. Keep model and task inputs fixed during comparison. A smaller opening that repeatedly misses the billing decision needs better index descriptions or routing, rather than an automatic increase in its allowance.

Exercise overflow with long paths and multibyte text. Confirm that every included entry remains complete, omitted entries remain discoverable and a missing snapshot produces a visible diagnostic. Repeat after catalog growth or loader changes. Use evaluating agent memory recall to track whether saved startup space preserves useful retrieval.