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

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
• Global default: The TOKEN_BUDGET environment variable (defaults to 2000) defined in 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, 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:

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, 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 prioritizes this parameter over the environment configuration.

Using the TypeScript SDK

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

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.

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
• Activation requirement: Export AGENTMEMORY_INJECT_CONTEXT=true to enable SessionStart injection in 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
• 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.

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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}