Session

The Session system provides SQLite-backed persistence for conversations, extensions, and metadata in Goose.

Overview

Sessions store:

Conversation history (messages)
Extension states (enabled MCP servers)
Token usage metrics
Working directory and metadata
Recipe configurations

Core Types

Represents a Goose conversation session.

pub struct Session {
    pub id: String,
    pub working_dir: PathBuf,
    pub name: String,
    pub user_set_name: bool,
    pub session_type: SessionType,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub extension_data: ExtensionData,
    pub total_tokens: Option<i32>,
    pub input_tokens: Option<i32>,
    pub output_tokens: Option<i32>,
    pub accumulated_total_tokens: Option<i32>,
    pub accumulated_input_tokens: Option<i32>,
    pub accumulated_output_tokens: Option<i32>,
    pub schedule_id: Option<String>,
    pub recipe: Option<Recipe>,
    pub user_recipe_values: Option<HashMap<String, String>>,
    pub conversation: Option<Conversation>,
    pub message_count: usize,
    pub provider_name: Option<String>,
    pub model_config: Option<ModelConfig>,
}

Source: crates/goose/src/session/session_manager.rs:70-96

String

required

Unique session identifier (format: YYYYMMDD_N)

working_dir

PathBuf

required

Directory where session tools execute

name

String

required

Human-readable session name

user_set_name

bool

required

Whether name was set by user (vs auto-generated)

session_type

SessionType

required

Type of session (User, Scheduled, SubAgent, Hidden, Terminal, Gateway)

extension_data

ExtensionData

required

JSON blob storing extension states

conversation

Option<Conversation>

Full message history (only loaded with include_messages=true)

total_tokens

Option<i32>

Tokens used in the last LLM call

accumulated_total_tokens

Option<i32>

Total tokens used across all LLM calls in this session

SessionType

pub enum SessionType {
    User,       // Standard user session
    Scheduled,  // Scheduled task session
    SubAgent,   // Sub-agent spawned session
    Hidden,     // Hidden from UI
    Terminal,   // Terminal-only session
    Gateway,    // Gateway session
}

Source: crates/goose/src/session/session_manager.rs:25-35

SessionManager

Manages session lifecycle and persistence.

pub struct SessionManager {
    storage: Arc<SessionStorage>,
}

Source: crates/goose/src/session/session_manager.rs:246-248

Constructor

instance()

Get the global SessionManager singleton.

pub fn instance() -> Self

Returns: Shared SessionManager instance Source: crates/goose/src/session/session_manager.rs:257-261 Example:

let session_manager = SessionManager::instance();

new()

Create a SessionManager with custom data directory.

pub fn new(data_dir: PathBuf) -> Self

data_dir

PathBuf

required

Directory for session database

Source: crates/goose/src/session/session_manager.rs:251-255

CRUD Operations

create_session()

Create a new session.

pub async fn create_session(
    &self,
    working_dir: PathBuf,
    name: String,
    session_type: SessionType,
) -> Result<Session>

working_dir

PathBuf

required

Initial working directory for tools

name

String

required

Initial session name

session_type

SessionType

required

Type of session to create

Returns: Newly created Session Source: crates/goose/src/session/session_manager.rs:267-276 Example:

let session = session_manager.create_session(
    PathBuf::from("/home/user/project"),
    "My Project".to_string(),
    SessionType::User,
).await?;

get_session()

Retrieve a session by ID.

pub async fn get_session(&self, id: &str, include_messages: bool) -> Result<Session>

&str

required

Session ID to retrieve

include_messages

bool

required

Whether to load full conversation history

Returns: Session with optional conversation Source: crates/goose/src/session/session_manager.rs:278-280 Example:

// Get session without messages (faster)
let session = session_manager.get_session("20260304_1", false).await?;

// Get session with full conversation
let session = session_manager.get_session("20260304_1", true).await?;
if let Some(conversation) = session.conversation {
    println!("Messages: {}", conversation.len());
}

list_sessions()

List all user and scheduled sessions.

pub async fn list_sessions(&self) -> Result<Vec<Session>>

Returns: Vector of sessions sorted by updated_at descending Source: crates/goose/src/session/session_manager.rs:298-300

list_sessions_by_types()

List sessions filtered by type.

pub async fn list_sessions_by_types(&self, types: &[SessionType]) -> Result<Vec<Session>>

types

&[SessionType]

required

Session types to include

Source: crates/goose/src/session/session_manager.rs:302-304 Example:

let sessions = session_manager.list_sessions_by_types(&[
    SessionType::User,
    SessionType::SubAgent,
]).await?;

delete_session()

Delete a session and all its messages.

pub async fn delete_session(&self, id: &str) -> Result<()>

&str

required

Session ID to delete

Source: crates/goose/src/session/session_manager.rs:306-308

Message Management

add_message()

Append a message to a session.

pub async fn add_message(&self, id: &str, message: &Message) -> Result<()>

&str

required

Session ID

message

&Message

required

Message to append

Source: crates/goose/src/session/session_manager.rs:290-292 Example:

let message = Message::user().with_text("Hello, Goose!");
session_manager.add_message("20260304_1", &message).await?;

replace_conversation()

Replace entire conversation history (used for compaction).

pub async fn replace_conversation(&self, id: &str, conversation: &Conversation) -> Result<()>

&str

required

Session ID

conversation

&Conversation

required

New conversation to store

Source: crates/goose/src/session/session_manager.rs:294-296

truncate_conversation()

Delete messages after a timestamp.

pub async fn truncate_conversation(&self, session_id: &str, timestamp: i64) -> Result<()>

session_id

&str

required

Session ID

timestamp

i64

required

Unix timestamp (seconds) - messages >= this timestamp are deleted

Source: crates/goose/src/session/session_manager.rs:326-330

Update Operations

update()

Get a builder for updating session fields.

pub fn update(&self, id: &str) -> SessionUpdateBuilder<'_>

&str

required

Session ID to update

Returns: Builder for chaining updates Source: crates/goose/src/session/session_manager.rs:282-284

SessionUpdateBuilder

Builder pattern for updating sessions. Source: crates/goose/src/session/session_manager.rs:98-117

user_provided_name()

Set user-provided name.

pub fn user_provided_name(mut self, name: impl Into<String>) -> Self

Source: crates/goose/src/session/session_manager.rs:154-161

system_generated_name()

Set auto-generated name.

pub fn system_generated_name(mut self, name: impl Into<String>) -> Self

Source: crates/goose/src/session/session_manager.rs:163-170

extension_data()

Update extension state.

pub fn extension_data(mut self, data: ExtensionData) -> Self

Source: crates/goose/src/session/session_manager.rs:182-185

apply()

Execute the update.

pub async fn apply(self) -> Result<()>

Source: crates/goose/src/session/session_manager.rs:150-152 Example:

session_manager
    .update("20260304_1")
    .user_provided_name("My Renamed Session")
    .total_tokens(Some(1500))
    .apply()
    .await?;

Import/Export

export_session()

Export session to JSON.

pub async fn export_session(&self, id: &str) -> Result<String>

&str

required

Session ID to export

Returns: JSON string representation Source: crates/goose/src/session/session_manager.rs:314-316

import_session()

Import session from JSON.

pub async fn import_session(&self, json: &str) -> Result<Session>

json

&str

required

JSON session data

Returns: Newly created Session Source: crates/goose/src/session/session_manager.rs:318-320

copy_session()

Duplicate a session.

pub async fn copy_session(&self, session_id: &str, new_name: String) -> Result<Session>

session_id

&str

required

ID of session to copy

new_name

String

required

Name for the new session

Source: crates/goose/src/session/session_manager.rs:322-324

Analytics

get_insights()

Get aggregated session statistics.

pub async fn get_insights(&self) -> Result<SessionInsights>

Returns: Session insights with token totals Source: crates/goose/src/session/session_manager.rs:310-312

SessionInsights

pub struct SessionInsights {
    pub total_sessions: usize,
    pub total_tokens: i64,
}

Source: crates/goose/src/session/session_manager.rs:119-124

Chat History Search

search_chat_history()

Search messages across all sessions.

pub async fn search_chat_history(
    &self,
    query: &str,
    limit: Option<usize>,
    after_date: Option<DateTime<Utc>>,
    before_date: Option<DateTime<Utc>>,
    exclude_session_id: Option<String>,
) -> Result<ChatRecallResults>

query

&str

required

Search query string

limit

Option<usize>

Maximum results to return

after_date

Option<DateTime<Utc>>

Only include messages after this date

before_date

Option<DateTime<Utc>>

Only include messages before this date

exclude_session_id

Option<String>

Session ID to exclude from results

Source: crates/goose/src/session/session_manager.rs:357-368

Agent - Main agent orchestrator
Conversation - Message history
Config - Configuration system

Core Library

Providers

Extensions

CLI Commands

Server API

​Overview

​Core Types

​Session

​SessionType

​SessionManager

​Constructor

​instance()

​new()

​CRUD Operations

​create_session()

​get_session()

​list_sessions()

​list_sessions_by_types()

​delete_session()

​Message Management

​add_message()

​replace_conversation()

​truncate_conversation()

​Update Operations

​update()

​SessionUpdateBuilder

​user_provided_name()

​system_generated_name()

​extension_data()

​apply()

​Import/Export

​export_session()

​import_session()

​copy_session()

​Analytics

​get_insights()

​SessionInsights

​Chat History Search

​search_chat_history()

​Related Types

Build docs developers (and LLMs) love

Overview

Core Types

Session

SessionType

SessionManager

Constructor

instance()

new()

CRUD Operations

create_session()

get_session()

list_sessions()

list_sessions_by_types()

delete_session()

Message Management

add_message()

replace_conversation()

truncate_conversation()

Update Operations

update()

SessionUpdateBuilder

user_provided_name()

system_generated_name()

extension_data()

apply()

Import/Export

export_session()

import_session()

copy_session()

Analytics

get_insights()

SessionInsights

Chat History Search

search_chat_history()

Related Types