# How Brave Browser Handles Sessions and Preferences: A Deep Dive into the Chromium-Based Architecture

> Discover how Brave browser manages sessions and preferences by extending Chromium's architecture. Learn about its unique settings and data storage.

- Repository: [Brave Software/brave-browser](https://github.com/brave/brave-browser)
- Tags: deep-dive
- Published: 2026-02-16

---

**Brave inherits Chromium’s `PrefService` and `SessionService` architecture to manage user settings and browsing state, extending it with Brave-specific preferences like shields and wallet settings while persisting data to JSON files in the user profile directory.**

The `brave/brave-browser` repository builds upon Chromium’s foundation to handle sessions and preferences, adding privacy-focused customizations while maintaining compatibility with the underlying storage mechanisms. Understanding this architecture is essential for developers contributing to Brave or building extensions that interact with user settings.

## Understanding the Preference Architecture in Brave

### The PrefService Hierarchy

At the core of Brave’s preference system is the `PrefService`, a singleton created for each `BrowserContext` (profile) in `chrome/browser/profiles/profile_impl.cc`. This service manages a layered hierarchy of preference stores:

- **Default store**: Read-only values shipped with the browser
- **User store**: A `PrefStore` backed by `JSONPrefStore` that persists to disk
- **Managed store**: Enterprise policy overrides

When code calls `Profile::GetPrefs()`, it receives the `PrefService` instance for that profile, which coordinates reads and writes across these layers.

### Brave-Specific Preference Keys

Brave extends the standard Chromium preference set by registering custom keys in [`components/brave_shields/common/pref_names.h`](https://github.com/brave/brave-browser/blob/main/components/brave_shields/common/pref_names.h) and `brave/browser/prefs/brave_browser_prefs.cc`. These include:

- `brave.shields.enabled`
- `brave.show_wallet_button`
- `brave.brave_ads.enabled`

Registration occurs during profile creation via `PrefRegistrySimple`, where each key is bound to a default value and type.

### Persistence and Storage Format

User-level preferences serialize to a JSON file located at `<profile>/Preferences` on disk. The `JSONPrefStore` class in [`components/prefs/json_pref_store.h`](https://github.com/brave/brave-browser/blob/main/components/prefs/json_pref_store.h) handles atomic read/write operations to prevent corruption during crashes.

Access in code follows this pattern:

```cpp
PrefService* prefs = profile->GetPrefs();
bool shields_enabled = prefs->GetBoolean(brave_shields::prefs::kShieldsEnabled);

```

## How Brave Manages User Sessions

### The SessionService Core

Brave uses Chromium’s `SessionService` (defined in [`chrome/browser/sessions/session_service.h`](https://github.com/brave/brave-browser/blob/main/chrome/browser/sessions/session_service.h)) to track the live state of browser windows and tabs. Each tab receives a unique `SessionID`, and the service maintains a mapping of `SessionID → TabNavigation` objects that capture:

- Current URL and title
- Scroll position
- Navigation history
- Session storage data

### Session Persistence Across Launches

When the browser shuts down, `SessionService::SaveLastSession()` serializes the current window and tab state to the profile directory. These files reside in `<profile>/Session Storage/` and include:

- `Last Session` files containing tab navigation data
- `Window` state descriptors
- `Tabs` metadata

On startup, `SessionRestore` (implemented in `chrome/browser/sessions/session_restore.cc`) reads these files through the `SessionService` and reconstructs the previous browsing session. The restore logic triggers via `Browser::SessionRestore()` when the preference `prefs::kRestoreOnStartup` indicates restoration is desired.

### Web-Level Session Storage

Separate from the UI session management, individual websites use `sessionStorage` for temporary data persistence. Brave handles this through `SessionStorageNamespace` (defined in [`content/browser/renderer_host/session_storage_namespace_impl.h`](https://github.com/brave/brave-browser/blob/main/content/browser/renderer_host/session_storage_namespace_impl.h)), which isolates storage per tab and clears it when the tab closes.

## Practical Code Examples

### Reading a Brave-Specific Preference

```cpp
// In any component that has a Profile* (e.g., a UI controller)

PrefService* prefs = profile->GetPrefs();
bool shields_enabled = prefs->GetBoolean(brave_shields::prefs::kShieldsEnabled);
// Use the value to conditionally show UI elements or adjust behavior

```

*Source:* `chrome/browser/ui/webui/settings/settings_localized_strings_provider.cc`

### Persisting a Custom Preference

```cpp
// Registration (usually done during profile creation in brave_browser_prefs.cc)
void RegisterBravePrefs(PrefRegistrySimple* registry) {
  registry->RegisterBooleanPref(brave::kMyFeatureEnabled, false);
}

// Later, toggling the flag based on user interaction
void SetMyFeatureEnabled(Profile* profile, bool enabled) {
  profile->GetPrefs()->SetBoolean(brave::kMyFeatureEnabled, enabled);
  // The JSONPrefStore automatically handles atomic writes to disk
}

```

*Source:* [`components/brave_shields/common/pref_names.h`](https://github.com/brave/brave-browser/blob/main/components/brave_shields/common/pref_names.h)

### Restoring the Last Session on Startup

```cpp
// Browser startup flow (simplified from chrome/browser/ui/browser.cc)
void Browser::Init() {
  // … other initialization …
  if (ShouldRestoreLastSession()) {
    SessionRestore::RestoreSession(profile_);
  }
}

// Helper that checks user preference
bool Browser::ShouldRestoreLastSession() {
  return !profile_->GetPrefs()->GetBoolean(prefs::kRestoreOnStartup);
}

```

*Source:* `chrome/browser/sessions/session_restore.cc`

### Saving the Current Session on Shutdown

```cpp
void Browser::Shutdown() {
  // … other shutdown work …
  profile_->GetSessionService()->SaveLastSession();
  // Serializes to <profile>/Session Storage/Last Session
}

```

*Source:* `chrome/browser/sessions/session_service.cc`

## Summary

- **Brave extends Chromium’s architecture** for sessions and preferences, using `PrefService` for settings and `SessionService` for browsing state.
- **Preferences** are stored in a layered hierarchy (default, user, managed) and persist to `<profile>/Preferences` as JSON via `JSONPrefStore`.
- **Brave-specific settings** like shields and wallet options are registered in [`components/brave_shields/common/pref_names.h`](https://github.com/brave/brave-browser/blob/main/components/brave_shields/common/pref_names.h) and accessed via `Profile::GetPrefs()`.
- **Sessions** track windows and tabs using `SessionID` mappings, serializing to `<profile>/Session Storage/` on shutdown and restoring via `SessionRestore` on startup.
- **Web-level session storage** is handled separately through `SessionStorageNamespace` for per-tab isolation.

## Frequently Asked Questions

### Where does Brave store user preferences on disk?

Brave stores user preferences in a JSON file located at `<profile>/Preferences` within your user data directory. This file is managed by the `JSONPrefStore` class, which ensures atomic writes to prevent corruption. The preferences include both Chromium defaults and Brave-specific settings like shields configuration and wallet preferences.

### How does Brave handle session restoration on startup?

When Brave starts, the `SessionRestore` mechanism checks the `prefs::kRestoreOnStartup` preference. If restoration is enabled, it reads the serialized session data from `<profile>/Session Storage/Last Session` and recreates the previous windows and tabs. This process uses the `SessionService` to map stored `SessionID` values back to live `TabNavigation` objects.

### What is the difference between SessionService and sessionStorage?

`SessionService` is a browser-level component that manages the UI state of windows and tabs, including navigation history and scroll positions, persisting across browser restarts. In contrast, `sessionStorage` is a Web API that provides temporary storage for individual websites, isolated per tab and cleared when the tab closes. Brave implements `sessionStorage` through `SessionStorageNamespace` in the content layer, separate from the `SessionService` in the browser layer.

### How can developers access Brave-specific preferences in code?

Developers can access Brave-specific preferences by obtaining the `PrefService` from the current profile using `Profile::GetPrefs()`, then calling typed getter methods like `GetBoolean()` or `SetBoolean()`. Brave defines its preference keys in headers such as [`components/brave_shields/common/pref_names.h`](https://github.com/brave/brave-browser/blob/main/components/brave_shields/common/pref_names.h) (e.g., `brave_shields::prefs::kShieldsEnabled`). Registration of new preferences should occur during profile initialization using `PrefRegistrySimple`.