Token-Aware Context

medium10 mincontext-builder.ts

You assemble prompts yourself and need the most recent history that fits a token budget, with the system prompt always included.

What it shows

  • Store messages with InMemoryAdapter and countTokens()
  • Build the context with ContextBuilder for different budgets and read the truncation metadata

The code

context-builder.ts
import { ContextBuilder, InMemoryAdapter, countTokens } from '@cogitator-ai/memory';

const memory = new InMemoryAdapter();
await memory.connect();

const agentId = 'travel-agent';
const threadId = 'trip-to-japan';
await memory.createThread(agentId, {}, threadId);

const conversation = [
  { role: 'user' as const, content: 'I want to plan a trip to Japan in April. Budget is $3000.' },
  { role: 'assistant' as const, content: 'April is cherry blossom season. Split two weeks between Tokyo, Kyoto, Osaka and Hakone.' },
  { role: 'user' as const, content: 'Is the Japan Rail Pass worth it?' },
  { role: 'assistant' as const, content: 'Yes. A 14-day pass covers the Shinkansen and pays off on this route. Buy it before you travel.' },
  { role: 'user' as const, content: 'Any food recommendations?' },
  { role: 'assistant' as const, content: 'Ramen in Tokyo, okonomiyaki in Osaka, matcha desserts in Kyoto. Budget $30-50 a day.' },
];

for (const message of conversation) {
  await memory.addEntry({ threadId, message, tokenCount: countTokens(message.content) });
}

for (const maxTokens of [120, 150, 220]) {
  const builder = new ContextBuilder(
    { maxTokens, strategy: 'recent', includeSystemPrompt: true },
    { memoryAdapter: memory }
  );
  const context = await builder.build({
    threadId,
    agentId,
    systemPrompt: 'You are a travel planning assistant.',
  });
  console.log(
    `${maxTokens} tokens: ${context.metadata.includedMessageCount}/${context.metadata.originalMessageCount} messages, ` +
      `${context.tokenCount} tokens, truncated=${context.truncated}`
  );
}

await memory.disconnect();

Run it

install · bash
pnpm add @cogitator-ai/memory
run · bash
npx tsx context-builder.ts

Or run the full example from a clone of the repository (keys in .env):

repository · bash
npx tsx examples/memory/02-context-builder.ts

Learn more