Session

Session management and persistence in Goose

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

Session

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

id · 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>

id · &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<()>

id · &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<()>

id · &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<()>

id · &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<'_>

id · &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>

id · &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

Related Types

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