Returns a specification to start this module under a supervisor.

See Supervisor.

@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)

@spec delete_session(String.t()) :: :ok | {:error, :invalid_session_id}

Deletes a session.

Examples

:ok = SessionStore.delete_session(session_id)

@spec delete_session_via_store(String.t(), term(), keyword()) ::
  :ok | {:error, term()}

Deletes a SessionStore-backed session when the adapter implements delete.

@spec file_path_to_session_key(String.t(), String.t()) ::
  ClaudeAgentSDK.SessionStore.Key.t() | nil

Converts a Claude transcript file path under a projects directory into a SessionStore key.

@spec fold_session_summary(map() | nil, ClaudeAgentSDK.SessionStore.Key.input(), [
  map()
]) :: map()

Folds appended SessionStore entries into a summary sidecar.

@spec fork_session_via_store(String.t(), term(), keyword()) ::
  ClaudeAgentSDK.Session.ForkResult.t() | {:error, term()}

Forks a SessionStore-backed session into a new session.

@spec get_session_info_from_store(String.t(), term(), keyword()) ::
  ClaudeAgentSDK.Session.SessionInfo.t() | nil

Looks up one SessionStore-backed session.

@spec get_session_messages_from_store(String.t(), term(), keyword()) :: [
  ClaudeAgentSDK.Session.SessionMessage.t()
]

Reads visible messages from a SessionStore-backed session.

@spec get_subagent_messages_from_store(String.t(), String.t(), term(), keyword()) :: [
  ClaudeAgentSDK.Session.SessionMessage.t()
]

Reads visible messages from a SessionStore-backed subagent transcript.

@spec import_session_to_store(String.t(), term(), keyword()) :: :ok | {:error, term()}

Imports a local Claude JSONL session transcript into a SessionStore adapter.

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

Lists all sessions.

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

@spec list_sessions_from_store(
  term(),
  keyword()
) :: [ClaudeAgentSDK.Session.SessionInfo.t()]

Lists sessions backed by a SessionStore adapter.

@spec list_subagents_from_store(String.t(), term(), keyword()) :: [String.t()]

Lists subagent IDs for a SessionStore-backed session.

@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

@spec project_key_for_directory(String.t() | nil) :: String.t()

Derives the SessionStore project key for a directory.

@spec rename_session_via_store(String.t(), String.t(), term(), keyword()) ::
  :ok | {:error, term()}

Appends a custom title entry to a SessionStore-backed session.

@spec save_session(String.t(), [ClaudeAgentSDK.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"
)

@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
)

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

Starts the SessionStore GenServer.

@spec tag_session_via_store(String.t(), String.t() | nil, term(), keyword()) ::
  :ok | {:error, term()}

Appends or clears a tag on a SessionStore-backed session.