# How Does OpenMAIC Handle Persistence? Workspace Session Storage Explained

> Discover how OpenMAIC handles persistence with workspace session storage. Explore options for browser storage, custom implementations, or disabling it entirely.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: internals
- Published: 2026-08-31

---

**OpenMAIC persists lightweight UI state using the browser's Web Storage API (`localStorage`) through a resilient abstraction layer in [`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-session-memory.ts), offering configurable storage options that support default browser persistence, custom implementations, or complete disablement for server-side rendering.**

The THU-MAIC/OpenMAIC repository implements client-side persistence specifically for workspace session recovery. Understanding how OpenMAIC handles persistence reveals a design that prioritizes runtime flexibility while maintaining simple key-value storage semantics for remembering conversation context.

## Storage Architecture and Key Definitions

The persistence logic lives primarily in [`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-session-memory.ts) and utilizes the **Web Storage API** to store minimal state. According to the OpenMAIC source code, three specific storage keys manage workspace navigation history:

| Storage Key | Purpose |
|-------------|---------|
| `openmaic:workspace:last-session` | Remembers the ID of the last conversation opened in the Pro workspace |
| `openmaic:workspace:home` | Sentinel value indicating the workspace home page was the last active view |
| `MAIC_DISCARDED_DB` | Defined in [`configs/storage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/configs/storage.ts) as a reserved flag for discarded database state (currently a placeholder) |

All operations wrap native `localStorage` calls in `try / catch` blocks to tolerate environments where storage is unavailable, such as private-mode browsers or server-side rendering contexts.

## Core Persistence API Functions

The module exports a focused API for session memory management. Each function handles specific lifecycle events for workspace navigation:

**Reading State** – `readLastWorkspaceSessionId()` retrieves the remembered session ID or returns `null` if the home sentinel is stored instead.

**Remembering Sessions** – `rememberWorkspaceSession(sessionId)` stores a normalized, trimmed session identifier for later recovery.

**Marking Home View** – `rememberWorkspaceHome()` stores the sentinel value `openmaic:workspace:home`, signaling that no specific session was active when the user left.

**Selective Forgetting** – `forgetWorkspaceSession(sessionId)` removes the stored ID only if it matches the provided value, preventing accidental deletion of newer state.

**Validation** – `validateRememberedWorkspaceSession(sessionId, existingSessionIds)` checks if a stored session still exists in the current session list; if not, it automatically clears the stale entry.

**URL Generation** – `workspaceResumeHref(sessionId)` constructs a safe resume link (`/workspace?session=…`) with proper URL encoding for the session identifier.

## Configurable Storage Options

The OpenMAIC persistence layer accepts an optional `SessionMemoryStorage` argument, enabling three distinct runtime configurations:

**Default Browser Storage** – Calling functions without arguments uses the native `window.localStorage` implementation.

**Custom Storage Implementation** – Developers can inject an object implementing `{ getItem, setItem, removeItem }` to redirect persistence to alternative layers such as IndexedDB wrappers, encrypted storage, or server-side session stores.

**Disabled Persistence** – Passing `undefined` or executing in environments where `window` is not defined (such as Next.js server components) effectively disables persistence without throwing errors, ensuring safe server-side rendering.

This dependency injection pattern, implemented in [`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-session-memory.ts), makes the module fully testable without mocking global browser APIs.

## Practical Implementation Example

Below are typical usage patterns for the OpenMAIC persistence API:

```typescript
import {
  readLastWorkspaceSessionId,
  rememberWorkspaceSession,
  rememberWorkspaceHome,
  forgetWorkspaceSession,
  validateRememberedWorkspaceSession,
  workspaceResumeHref,
} from '@/lib/workbench/workspace-session-memory';

// Store session when user opens a conversation
rememberWorkspaceSession('session-42');

// Generate a resumable link for navigation
const resumeLink = workspaceResumeHref('session-42');
// Returns: "/workspace?session=session-42"

// Retrieve remembered session on application mount
const lastId = readLastWorkspaceSessionId();
if (lastId) {
  console.log('Resuming session:', lastId);
}

// Clear storage after session deletion
forgetWorkspaceSession('session-42');

// Validate against current session list and auto-clear if stale
const existingIds = ['session-1', 'session-2'];
validateRememberedWorkspaceSession('session-42', existingIds);
// Returns false and removes the invalid entry

// Mark workspace home as the last viewed page
rememberWorkspaceHome();

```

## Summary

- OpenMAIC uses **Web Storage API** (`localStorage`) for lightweight client-side persistence of workspace session state.
- The core implementation resides in **[`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-session-memory.ts)**, with constants defined in **[`configs/storage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/configs/storage.ts)**.
- Five primary functions handle **reading**, **remembering**, **forgetting**, **validating**, and **linking** to workspace sessions.
- The API supports **dependency injection**, allowing default browser storage, custom implementations, or **disabled persistence** for SSR compatibility.
- All operations include **fault tolerance** for private browsing modes and restricted environments.

## Frequently Asked Questions

### What storage mechanism does OpenMAIC use for persistence?

OpenMAIC uses the browser's **Web Storage API**, specifically `window.localStorage`, to store workspace session identifiers. The implementation in [`lib/workbench/workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/workspace-session-memory.ts) wraps all storage calls in error handling to support environments where `localStorage` is unavailable, such as server-side rendering or private browsing modes.

### Can I replace localStorage with a custom storage solution in OpenMAIC?

Yes. Every exported function in [`workspace-session-memory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/workspace-session-memory.ts) accepts an optional `SessionMemoryStorage` argument. You can provide any object implementing `{ getItem(key: string): string | null, setItem(key: string, value: string): void, removeItem(key: string): void }` to redirect persistence to IndexedDB, encrypted storage, or a server-side backend.

### How does OpenMAIC handle invalid or deleted session IDs?

The **`validateRememberedWorkspaceSession()`** function checks a remembered ID against an array of existing session IDs. If the stored ID no longer exists in the current list, the function automatically clears the stale entry from storage and returns `false`, preventing navigation to non-existent conversations.

### Is persistence disabled during server-side rendering?

Persistence automatically disables itself in environments where `window` is undefined. By passing `undefined` as the storage argument or executing in Node.js contexts, the API returns safe defaults (typically `null`) without throwing errors, ensuring OpenMAIC applications render correctly during SSR.