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

# Sessions

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

Import these **6 exports** from `@agentium/core`. Read the [sessions guide](/memory/sessions) 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.

## AppendResult

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

```typescript theme={null}
export interface AppendResult {
    /** Messages that were trimmed from the session because maxMessages was exceeded. */
    overflow: ChatMessage[];
}
```

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

## IncrementalSessionConfig

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

```typescript theme={null}
/**
 * Like `SessionManager` but writes each message as an individual entry instead
 * of re-serializing the whole conversation on every turn. Periodically rolls up
 * the loose entries into a snapshot to bound read latency.
 *
 * Storage layout (per sessionId):
 *
 *   ns="sessions:meta"       key=<sessionId>           -> Session minus messages
 *   ns="sessions:snapshot"   key=<sessionId>           -> { messages, nextSeq } (collapsed)
 *   ns="sessions:msg"        key=<sessionId>:<seq>     -> ChatMessage (incremental)
 *
 * `seq` is a zero-padded monotonically increasing integer so that
 * `list(ns, sessionId + ":")` returns entries in chronological order.
 */
export interface IncrementalSessionConfig {
    /** Take a full snapshot every N message appends. Default: 25. */
    snapshotFrequency?: number;
    /** Soft message limit applied to whole turns at snapshot time. Default: unlimited. */
    maxMessages?: number;
}
```

## IncrementalSessionManager

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

```typescript theme={null}
export declare class IncrementalSessionManager {
    constructor(storage: StorageDriver, config?: IncrementalSessionConfig);
    getOrCreate(sessionId: string, userId?: string): Promise<Session>;
    appendMessage(sessionId: string, msg: ChatMessage): Promise<void>;
    appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<void>;
    /**
     * Force an immediate snapshot. Useful for graceful drains.
     */
    snapshotNow(sessionId: string): Promise<void>;
    getHistory(sessionId: string, limit?: number): Promise<ChatMessage[]>;
    updateState(sessionId: string, patch: Record<string, unknown>): Promise<void>;
    getState(sessionId: string): Promise<Record<string, unknown>>;
    deleteSession(sessionId: string): Promise<void>;
}
```

Related: [`ChatMessage`](/api-reference/core/models#chatmessage), [`IncrementalSessionConfig`](/api-reference/core/session#incrementalsessionconfig), [`Session`](/api-reference/core/session#session), [`StorageDriver`](/api-reference/core/storage#storagedriver).

## Session

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

```typescript theme={null}
export interface Session {
    sessionId: string;
    userId?: string;
    messages: ChatMessage[];
    state: Record<string, unknown>;
    createdAt: Date;
    updatedAt: Date;
}
```

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

## SessionManager

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

```typescript theme={null}
export declare class SessionManager {
    constructor(storage: StorageDriver, config?: SessionManagerConfig);
    getOrCreate(sessionId: string, userId?: string): Promise<Session>;
    appendMessage(sessionId: string, msg: ChatMessage): Promise<AppendResult>;
    appendMessages(sessionId: string, msgs: ChatMessage[]): Promise<AppendResult>;
    getHistory(sessionId: string, limit?: number): Promise<ChatMessage[]>;
    updateState(sessionId: string, patch: Record<string, unknown>): Promise<void>;
    getState(sessionId: string): Promise<Record<string, unknown>>;
    deleteSession(sessionId: string): Promise<void>;
    /** List stored sessions, optionally filtered by user. */
    listSessions(opts?: {
        userId?: string;
    }): Promise<Session[]>;
    /**
     * Search message text across sessions. Returns short snippets.
     * This is a simple substring search, not embeddings.
     */
    searchSessions(query: string, opts?: {
        userId?: string;
        limit?: number;
    }): Promise<Array<{
        sessionId: string;
        snippet: string;
    }>>;
}
```

Related: [`AppendResult`](/api-reference/core/session#appendresult), [`ChatMessage`](/api-reference/core/models#chatmessage), [`Session`](/api-reference/core/session#session), [`SessionManagerConfig`](/api-reference/core/session#sessionmanagerconfig), [`StorageDriver`](/api-reference/core/storage#storagedriver).

## SessionManagerConfig

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

```typescript theme={null}
export interface SessionManagerConfig {
    /** Soft message limit. Oldest whole turns are trimmed; the latest turn stays intact. Default: unlimited. */
    maxMessages?: number;
}
```


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