# What Store Types Are Available in the OpenMAIC Persistence Layer?

> Explore the OpenMAIC persistence layer's store types: InMemoryStore, IndexedDBStore, and ServerStore. Discover how they manage data efficiently for your projects.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: api-reference
- Published: 2026-09-03

---

**The OpenMAIC persistence layer exposes three primary store types—InMemoryStore, IndexedDBStore, and ServerStore—along with specialized variants for binary assets and key-value data, all implementing a unified Store interface.**

The THU-MAIC/OpenMAIC repository provides a modular persistence layer that abstracts storage operations behind a common interface. This architecture allows developers to swap between in-memory caching, browser-based IndexedDB, and remote server storage without changing application logic. Understanding the available store types is essential for configuring the optimal data persistence strategy across development, testing, and production environments.

## Primary Store Types in OpenMAIC

The persistence layer defines three core implementations in `lib/persistence/`, each targeting a specific runtime environment or durability requirement.

### InMemoryStore (Non-Durable Fallback)

The **InMemoryStore** serves as the default fallback when no durable storage is available, such as during server-side rendering or unit testing. Located in [`lib/persistence/in-memory-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/in-memory-store.ts), this implementation stores data in plain JavaScript objects that persist only for the duration of the process.

### IndexedDBStore (Client-Side Browser Storage)

For browser environments, the **IndexedDBStore** provides durable client-side persistence using the Dexie wrapper around IndexedDB. Defined in [`lib/persistence/indexeddb-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/indexeddb-store.ts), this store handles scenes, assets, and metadata locally within the browser's storage quota.

### ServerStore (Remote API Persistence)

The **ServerStore** enables centralized, remote persistence by communicating with backend endpoints under `api/persistence/*`. Implemented in [`lib/persistence/server-provider.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/server-provider.ts), this store supports custom server configurations including S3-compatible backends or traditional databases.

## Specialized Store Types

Beyond the primary storage interface, OpenMAIC provides specialized stores for specific data shapes and access patterns.

### AssetByteStore (Binary Asset Handling)

The **AssetByteStore** manages raw binary payloads such as images, audio, and video files. Located in [`lib/persistence/asset-byte-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/asset-byte-store.ts), this store isolates large binary objects from JSON document storage to optimize retrieval performance and memory usage.

### KVStore (Key-Value Persistence)

For configuration flags and short-lived caches, the **KVStore** offers lightweight key-value operations. Defined in [`lib/persistence/kv-persist.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/kv-persist.ts), this implementation supports simple string-based storage without the overhead of full document serialization.

## Runtime Store Selection

The persistence layer uses a factory pattern to instantiate the appropriate store type based on environment configuration.

The `createPersistenceStore` function in [`lib/persistence/store-factory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/store-factory.ts) selects implementations dynamically:

```typescript
import { createPersistenceStore } from '@/lib/persistence/store-factory';

const persistence = createPersistenceStore({
  type: process.env.NEXT_PUBLIC_PERSISTENCE === '1' ? 'server' :
        typeof window !== 'undefined' ? 'indexeddb' : 'memory',
});

```

## Working with Store Implementations

All store implementations conform to the same interface, enabling consistent CRUD operations regardless of the underlying storage mechanism.

Saving documents to any active store:

```typescript
await persistence.saveDocument({
  id: 'stage-42',
  content: JSON.stringify(sceneData),
});

```

Storing binary assets via the specialized byte store:

```typescript
import { getAssetByteStore } from '@/lib/persistence/asset-byte-store';

await getAssetByteStore().put('image-123', blob);

```

Managing configuration flags with the key-value store:

```typescript
import { kvPersist } from '@/lib/persistence/kv-persist';

await kvPersist.set('hasSeenTutorial', true);
const seen = await kvPersist.get('hasSeenTutorial');

```

## Summary

- The OpenMAIC persistence layer provides **InMemoryStore**, **IndexedDBStore**, and **ServerStore** as primary implementations.
- **InMemoryStore** in [`lib/persistence/in-memory-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/in-memory-store.ts) serves non-durable fallback scenarios such as SSR and testing.
- **IndexedDBStore** in [`lib/persistence/indexeddb-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/indexeddb-store.ts) handles browser-based client storage via the Dexie wrapper.
- **ServerStore** in [`lib/persistence/server-provider.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/server-provider.ts) routes data to remote APIs supporting S3 or custom backends.
- Specialized stores include **AssetByteStore** for binary data in [`lib/persistence/asset-byte-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/asset-byte-store.ts) and **KVStore** for key-value pairs in [`lib/persistence/kv-persist.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/kv-persist.ts).
- The factory pattern in [`lib/persistence/store-factory.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/store-factory.ts) enables runtime selection based on environment variables like `NEXT_PUBLIC_PERSISTENCE`.

## Frequently Asked Questions

### What is the default store type when running OpenMAIC in a browser?

When `typeof window` is defined and `NEXT_PUBLIC_PERSISTENCE` is not set to server mode, the factory automatically instantiates **IndexedDBStore** to provide durable client-side storage.

### How does OpenMAIC handle binary assets differently from JSON documents?

Binary assets utilize the **AssetByteStore** defined in [`lib/persistence/asset-byte-store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/asset-byte-store.ts), which operates separately from document stores to optimize memory usage and supports direct Blob operations rather than JSON serialization.

### Can I configure OpenMAIC to use a custom S3-compatible storage backend?

Yes. The **ServerStore** implementation in [`lib/persistence/server-provider.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/persistence/server-provider.ts) communicates via HTTP to `api/persistence/*` endpoints, allowing the backend to route requests to S3, MinIO, or any custom storage provider without modifying client-side code.

### Is the InMemoryStore suitable for production workloads?

No. The **InMemoryStore** is designed exclusively for testing and server-side rendering fallback scenarios, as data persists only for the duration of the JavaScript process and is lost on page reload.