> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Context

> Public context signatures and configuration in @agentium/core 4.0.0.

Import these **17 exports** from `@agentium/core`. Read the [context guide](/knowledge/context-providers) for setup and behavior, or return to the [package reference](/api-reference/core).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## ContextCompactionError

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-compactor.ts)

```typescript theme={null}
/** An indivisible live exchange cannot fit. The caller must increase its budget or bound tool results. */
export declare class ContextCompactionError extends Error {
    readonly requiredTokens: number;
    readonly budget: number;
    constructor(requiredTokens: number, budget: number);
}
```

## ContextCompactor

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-compactor.ts)

```typescript theme={null}
export declare class ContextCompactor {
    constructor(config: ContextCompactorConfig);
    compact(messages: ChatMessage[]): Promise<ChatMessage[]>;
}
```

Related: [`ChatMessage`](/api-reference/core/models#chatmessage), [`ContextCompactorConfig`](/api-reference/core/agent#contextcompactorconfig).

## ContextFile

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-files.ts)

```typescript theme={null}
export interface ContextFile {
    name: string;
    path: string;
    content: string;
    blocked?: string;
}
```

## ContextProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

````typescript theme={null}
/**
 * `ContextProvider` is a pre-fetched data source attached to an Agent.
 *
 * Unlike Tools (which the LLM explicitly invokes), context providers run
 * automatically before every turn and inject their output into the system
 * prompt. Good for "the agent should always know X" data: my calendar, recent
 * Slack messages, current SQL row counts, file contents the agent referenced.
 *
 * Typical usage:
 *
 * ```ts
 * const calendar = new FilesystemContextProvider({ basePath: "./notes", glob: "*.md" });
 * const agent = new Agent({ context: [calendar], ... });
 * ```
 */
export interface ContextProvider {
    readonly name: string;
    /**
     * Fetch the current context. Called once per agent run before the LLM is invoked.
     * Returning an empty string causes the provider to contribute nothing.
     */
    fetchContext(query: string, ctx: RunContext): Promise<string>;
}
````

Related: [`RunContext`](/api-reference/core/agent#runcontext).

## countConversationTokens

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-compactor.ts)

```typescript theme={null}
export declare function countConversationTokens(messages: ChatMessage[]): number;
```

Related: [`ChatMessage`](/api-reference/core/models#chatmessage).

## DatabaseContextProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

```typescript theme={null}
export declare class DatabaseContextProvider implements ContextProvider {
    readonly name: string;
    constructor(cfg: DatabaseContextProviderConfig);
    fetchContext(_query: string, ctx: RunContext): Promise<string>;
}
```

Related: [`ContextProvider`](/api-reference/core/context#contextprovider), [`DatabaseContextProviderConfig`](/api-reference/core/context#databasecontextproviderconfig), [`RunContext`](/api-reference/core/agent#runcontext).

## DatabaseContextProviderConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

```typescript theme={null}
export interface DatabaseContextProviderConfig {
    /**
     * Function called on every run to produce the context string. The agent's
     * `RunContext` is passed in so you can scope queries to the current user/tenant.
     */
    fetch: (ctx: RunContext) => Promise<string>;
    /** Provider name for logs (e.g. `"postgres-users"`). */
    label?: string;
}
```

Related: [`RunContext`](/api-reference/core/agent#runcontext).

## FilesystemContextProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

```typescript theme={null}
export declare class FilesystemContextProvider implements ContextProvider {
    readonly name = "filesystem";
    constructor(cfg: FilesystemContextProviderConfig);
    fetchContext(_query: string, _ctx: RunContext): Promise<string>;
}
```

Related: [`ContextProvider`](/api-reference/core/context#contextprovider), [`FilesystemContextProviderConfig`](/api-reference/core/context#filesystemcontextproviderconfig), [`RunContext`](/api-reference/core/agent#runcontext).

## FilesystemContextProviderConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

```typescript theme={null}
export interface FilesystemContextProviderConfig {
    /** Base directory all paths are read from. */
    basePath: string;
    /** Files to include (relative paths, optionally with `**` wildcards expanded by `glob`). */
    files?: string[];
    /** Optional glob pattern (uses `node:fs.glob` when available). */
    glob?: string;
    /** Per-file character cap. Default 4000. */
    maxCharsPerFile?: number;
    /** Overall character cap. Default 16000. */
    maxTotalChars?: number;
}
```

## formatContextFiles

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-files.ts)

```typescript theme={null}
export declare function formatContextFiles(files: ContextFile[]): string;
```

Related: [`ContextFile`](/api-reference/core/context#contextfile).

## groupConversationTurns

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-compactor.ts)

```typescript theme={null}
/** A user turn, all its tool rounds and the concluding assistant form one atomic group. */
export declare function groupConversationTurns(messages: ChatMessage[]): ChatMessage[][];
```

Related: [`ChatMessage`](/api-reference/core/models#chatmessage).

## HttpContextProvider

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

```typescript theme={null}
export declare class HttpContextProvider implements ContextProvider {
    readonly name = "http";
    constructor(cfg: HttpContextProviderConfig);
    fetchContext(_query: string, _ctx: RunContext): Promise<string>;
}
```

Related: [`ContextProvider`](/api-reference/core/context#contextprovider), [`HttpContextProviderConfig`](/api-reference/core/context#httpcontextproviderconfig), [`RunContext`](/api-reference/core/agent#runcontext).

## HttpContextProviderConfig

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

```typescript theme={null}
export interface HttpContextProviderConfig {
    url: string;
    /** Headers forwarded with the fetch. */
    headers?: Record<string, string>;
    /** Optional SSRF allowlist. */
    allowedHosts?: string[];
    /** Optional response transformer. */
    transform?: (rawBody: string) => string;
    /** Char cap. */
    maxChars?: number;
}
```

## loadContextFiles

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-files.ts)

```typescript theme={null}
/**
 * Load project instruction files (AGENTS.md and friends).
 *
 * Walks from `cwd` up to the git root and merges matching files.
 * Only one project-file type is used (first match in PROJECT_FILES order).
 */
export declare function loadContextFiles(opts?: LoadContextFilesOptions): Promise<ContextFile[]>;
```

Related: [`ContextFile`](/api-reference/core/context#contextfile), [`LoadContextFilesOptions`](/api-reference/core/context#loadcontextfilesoptions).

## LoadContextFilesOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-files.ts)

```typescript theme={null}
export interface LoadContextFilesOptions {
    /** Working directory to start from. Default: process.cwd() */
    cwd?: string;
    /** Max characters kept per file. Default: 20000 */
    maxChars?: number;
    /** Skip the prompt-injection scan. Default: false */
    skipScan?: boolean;
}
```

## resolveContextProviders

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/context-providers.ts)

```typescript theme={null}
/**
 * Resolve all configured providers in parallel, label each block, and join
 * them into a single context string suitable for the system prompt.
 */
export declare function resolveContextProviders(providers: ContextProvider[], query: string, ctx: RunContext): Promise<string>;
```

Related: [`ContextProvider`](/api-reference/core/context#contextprovider), [`RunContext`](/api-reference/core/agent#runcontext).

## validateConversationTransform

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/core/src/context/conversation-transform.ts)

```typescript theme={null}
/**
 * Host messages are immutable. Closed historical tool/replay groups may be removed
 * atomically; a retained or current group must keep every opaque/call/result item.
 */
export declare function validateConversationTransform(before: readonly ChatMessage[], after: readonly ChatMessage[]): void;
```

Related: [`ChatMessage`](/api-reference/core/models#chatmessage).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.