Model context

An agent's memory is a ModelContext: an ordered list of ContextItems the model is asked to reason over. createAgent starts one automatically and stores the instruction as a DeveloperMessageItem. You usually pass agent.getMemory().getContext() into runLoop.

runLoop also appends the user message itself during context_update (UserMessageItem.create(message)), so you do not wrap that string by hand in the typical handler.

import { ModelContext, DeveloperMessageItem, UserMessageItem } from '@mozaik-ai/core';

const context = ModelContext.create()
  .addItem(DeveloperMessageItem.create('You are a helpful assistant.'))
  .addItem(UserMessageItem.create('What is the capital of France?'));

ModelContext.create() assigns a UUID. Use addItem or addContextItems to append. rehydrate({ id, items }) rebuilds a context you previously persisted.

ContextItem taxonomy

A ContextItem is one atomic piece of that history. Concrete item types follow the OpenResponses vocabulary so your domain types stay stable across providers.

Client items (you produce these)

Model items (the model produces these)

Together, these items form an ordered transcript you can persist, trim, transform, or share.

Persistence

ModelContextRepository is an interface you implement:

interface ModelContextRepository {
  save(context: ModelContext): Promise<void>;
  get(id: string): Promise<ModelContext>;
  getByProjectId(projectId: string): Promise<ModelContext[]>;
}

There is no shipped in-memory implementation. Implement the interface against Postgres, Redis, or object storage, then save after a turn and rehydrate when a user returns.

Token usage

inference.completed may include a TokenUsage (inputTokens, outputTokens, totalTokens, plus InputTokenDetails / OutputTokenDetails). Use it for metering; it is not stored on ModelContext unless you copy it yourself.