# `ClaudeAgentSDK.SessionStore`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L1)

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} = ClaudeAgentSDK.SessionStore.start_link()

    # Save a session
    messages = ClaudeAgentSDK.query("Build a feature") |> Enum.to_list()
    session_id = ClaudeAgentSDK.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
    ClaudeAgentSDK.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_agent_sdk,
      session_storage_dir: "/custom/path/sessions"

# `session_data`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L75)

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

# `session_metadata`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L64)

```elixir
@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
}
```

# `child_spec`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L51)

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `cleanup_old_sessions`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L189)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L175)

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

Deletes a session.

## Examples

    :ok = SessionStore.delete_session(session_id)

# `list_sessions`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L163)

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

Lists all sessions.

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

# `load_session`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L125)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L111)

```elixir
@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"
    )

# `search`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L153)

```elixir
@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`
[🔗](https://github.com/nshkrdotcom/claude_agent_sdk/blob/v0.9.2/lib/claude_agent_sdk/session_store.ex#L87)

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

Starts the SessionStore GenServer.

---

*Consult [api-reference.md](api-reference.md) for complete listing*