ClaudeCodeSDK.SessionStore (claude_code_sdk v0.2.2)

View Source

Persistent session storage and management.

Provides save/load/search capabilities for Claude conversation sessions, enabling multi-step workflows that survive application restarts.

Features

  • Save/load complete session message history
  • Tag sessions for organization
  • Search sessions by tags, date range, cost
  • Automatic cleanup of old sessions
  • Export/import session data
  • Session metadata tracking

Usage

# Start the store
{:ok, _pid} = ClaudeCodeSDK.SessionStore.start_link()

# Save a session
messages = ClaudeCodeSDK.query("Build a feature") |> Enum.to_list()
session_id = ClaudeCodeSDK.Session.extract_session_id(messages)

:ok = SessionStore.save_session(session_id, messages,
  tags: ["feature-dev", "important"],
  description: "Implemented user authentication"
)

# Load session later
{:ok, session_data} = SessionStore.load_session(session_id)

# Resume the conversation
ClaudeCodeSDK.resume(session_id, "Now add tests")

# Search sessions
sessions = SessionStore.search(tags: ["important"], after: ~D[2025-10-01])

Storage

Sessions are stored in ~/.claude_sdk/sessions/ by default. Each session is a JSON file with message history and metadata.

Configure storage location:

config :claude_code_sdk,
  session_storage_dir: "/custom/path/sessions"

Summary

Types

session_data()
session_metadata()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

cleanup_old_sessions(opts \\ [])

Cleans up sessions older than specified days.

delete_session(session_id)

Deletes a session.

list_sessions()

Lists all sessions.

load_session(session_id)

Loads a session by ID.

save_session(session_id, messages, opts \\ [])

Saves a session with messages and metadata.

search(criteria \\ [])

Searches sessions by criteria.

start_link(opts \\ [])

Starts the SessionStore GenServer.

Types

session_data()

@type session_data() :: %{
  session_id: String.t(),
  messages: [ClaudeCodeSDK.Message.t()],
  metadata: session_metadata()
}

session_metadata()

@type session_metadata() :: %{
  session_id: String.t(),
  created_at: DateTime.t(),
  updated_at: DateTime.t(),
  message_count: non_neg_integer(),
  total_cost: float(),
  tags: [String.t()],
  description: String.t() | nil,
  model: String.t() | nil
}

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

cleanup_old_sessions(opts \\ [])

@spec cleanup_old_sessions(keyword()) :: non_neg_integer()

Cleans up sessions older than specified days.

Examples

# Delete sessions older than 30 days
count = SessionStore.cleanup_old_sessions(max_age_days: 30)
# => 5 (number of sessions deleted)

delete_session(session_id)

@spec delete_session(String.t()) :: :ok

Deletes a session.

Examples

:ok = SessionStore.delete_session(session_id)

list_sessions()

@spec list_sessions() :: [session_metadata()]

Lists all sessions.

Returns metadata for all stored sessions, sorted by updated_at (newest first).

load_session(session_id)

@spec load_session(String.t()) :: {:ok, session_data()} | {:error, :not_found}

Loads a session by ID.

Examples

{:ok, session_data} = SessionStore.load_session(session_id)
# session_data.messages - List of messages
# session_data.metadata - Session metadata

save_session(session_id, messages, opts \\ [])

@spec save_session(String.t(), [ClaudeCodeSDK.Message.t()], keyword()) ::
  :ok | {:error, term()}

Saves a session with messages and metadata.

Parameters

  • session_id - Session identifier
  • messages - List of Message structs from query
  • opts - Keyword options:
    • :tags - List of tag strings
    • :description - Session description

Examples

:ok = SessionStore.save_session(session_id, messages,
  tags: ["code-review", "security"],
  description: "Security audit of auth module"
)

search(criteria \\ [])

@spec search(keyword()) :: [session_metadata()]

Searches sessions by criteria.

Parameters

  • criteria - Keyword options:
    • :tags - Match sessions with these tags (list)
    • :after - Sessions created after date (Date or DateTime)
    • :before - Sessions created before date
    • :min_cost - Minimum cost threshold
    • :max_cost - Maximum cost threshold

Examples

# Find all security review sessions
sessions = SessionStore.search(tags: ["security"])

# Find expensive sessions from last week
sessions = SessionStore.search(
  after: ~D[2025-10-01],
  min_cost: 0.10
)

start_link(opts \\ [])

@spec start_link(keyword()) :: GenServer.on_start()

Starts the SessionStore GenServer.