# How to Configure the Token Budget for SessionStart Context Injection in agentmemory

> Configure agentmemory's token budget for SessionStart context injection using the TOKEN_BUDGET environment variable or pass a budget parameter to mem::context to optimize LLM token usage.

- Repository: [Rohit Ghumare/agentmemory](https://github.com/rohitg00/agentmemory)
- Tags: how-to-guide
- Published: 2026-05-10

---

**Set the `TOKEN_BUDGET` environment variable (default 2000) to control how many LLM tokens agentmemory consumes when injecting project context at the start of a Claude Code session, or pass a `budget` parameter to the `mem::context` function to override it for specific requests.**

The agentmemory library automatically injects project-level context into Claude Code sessions through SessionStart context injection. This process prepends an XML-like `<agentmemory-context>` block to your first interaction, consuming tokens from your Claude Pro quota. Configuring the token budget ensures you balance comprehensive memory retrieval with cost efficiency, as implemented in the rohitg00/agentmemory repository.

## Configuration Hierarchy

Agentmemory evaluates the token budget across three distinct scopes, checked in the following order of precedence:

- **Per-request override**: The `budget` field passed directly to the `mem::context` function or the `token_budget` query parameter on the REST endpoint
- **Session enablement**: The `AGENTMEMORY_INJECT_CONTEXT` environment variable must be set to `true` to activate injection in [`src/hooks/session-start.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/hooks/session-start.ts)
- **Global default**: The `TOKEN_BUDGET` environment variable (defaults to 2000) defined in [`src/config.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/config.ts)

## Setting the Global Token Budget

The `TOKEN_BUDGET` environment variable establishes the default ceiling for all context injection operations. According to [`src/config.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/config.ts), the `loadConfig()` function parses this value using `safeParseInt` and stores it in `config.tokenBudget`.

Create a configuration file at `~/.agentmemory/.env` to persist your settings:

```bash
mkdir -p ~/.agentmemory
cat > ~/.agentmemory/.env <<'EOF'

# Maximum tokens allocated for context injection (default: 2000)

TOKEN_BUDGET=1500

# Enable automatic injection at session start

AGENTMEMORY_INJECT_CONTEXT=true
EOF

```

## Enabling SessionStart Context Injection

Before the budget takes effect, you must opt into the SessionStart injection feature. In [`src/hooks/session-start.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/hooks/session-start.ts), the hook checks for `AGENTMEMORY_INJECT_CONTEXT=true` before calling the internal context builder.

When enabled, the hook executes this sequence:

1. Registers the session with zero token cost
2. Invokes `mem::context` with the global `tokenBudget` value
3. Respects any per-call `budget` argument passed to the function
4. Writes the generated `<agentmemory-context>` block to `stdout` for Claude Code to prepend

## Overriding the Budget Per Request

For granular control, bypass the global default by passing a `budget` field directly to the `mem::context` function. The `registerContextFunction` implementation in [`src/functions/context.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/context.ts) prioritizes this parameter over the environment configuration.

### Using the TypeScript SDK

```typescript
import { sdk } from "iii-sdk";

await sdk.trigger({
  function_id: "mem::context",
  payload: {
    sessionId: "ses_abc123",
    project: "/path/to/project",
    // Override global budget for this specific call
    budget: 800,
  },
});

```

### Using the REST API

```bash
curl -X POST http://localhost:3111/agentmemory/context \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"ses_abc123","project":"/path/to/project","budget":1200}'

```

## Verifying Token Consumption

After invoking the context function, verify actual consumption by examining the returned `tokens` field. This value represents the precise count deducted from your Claude Pro allocation.

```typescript
const { context, tokens } = await sdk.trigger({
  function_id: "mem::context",
  payload: { sessionId: "ses_abc123", project: "/path/to/project" },
});

console.log(`Injected ${tokens} tokens`);

```

The `tokens` returned by `registerContextFunction` reflects the final count after applying your specified budget ceiling, allowing you to audit usage across different sessions.

## Summary

- **Global configuration**: Set `TOKEN_BUDGET` in `~/.agentmemory/.env` to change the default from 2000 tokens as defined in [`src/config.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/config.ts)
- **Activation requirement**: Export `AGENTMEMORY_INJECT_CONTEXT=true` to enable SessionStart injection in [`src/hooks/session-start.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/hooks/session-start.ts)
- **Request-level control**: Pass `budget` to `mem::context` calls to override the global setting for specific queries, processed by `registerContextFunction` in [`src/functions/context.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/context.ts)
- **Consumption tracking**: Monitor the `tokens` return value from context requests to verify actual usage against your Claude Pro quota

## Frequently Asked Questions

### What happens if I set TOKEN_BUDGET higher than my Claude Pro allocation?

Agentmemory will generate the context block up to your specified budget, but Claude Code will truncate or reject the input if it exceeds your actual Claude Pro token limits. The library does not validate against your account quota; it only enforces the configured `TOKEN_BUDGET` ceiling during context assembly in [`src/functions/context.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/context.ts).

### Can I disable context injection entirely without changing the budget?

Yes. Set `AGENTMEMORY_INJECT_CONTEXT=false` or unset the variable entirely. When disabled, the SessionStart hook in [`src/hooks/session-start.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/hooks/session-start.ts) skips the `mem::context` invocation, resulting in zero token consumption for context injection regardless of your `TOKEN_BUDGET` value.

### Why does the default budget default to 2000 tokens?

The 2000-token default in [`src/config.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/config.ts) provides a balanced starting point that includes sufficient project context for most coding sessions without exhausting typical Claude Pro rate limits. You can adjust this via `safeParseInt`-parsed environment variables to accommodate larger codebases or stricter budget constraints.

### How does the budget parameter interact with the global TOKEN_BUDGET?

When you pass a `budget` parameter to `mem::context`, it completely replaces the global `config.tokenBudget` for that specific invocation. The `registerContextFunction` logic uses the per-request value as the hard ceiling for token generation, as implemented in [`src/functions/context.ts`](https://github.com/rohitg00/agentmemory/blob/main/src/functions/context.ts).