# Store Types in the @openmaic/storage Package: A Complete Technical Guide

> Explore the seven store types in the @openmaic/storage package: KV, Asset, Document, Runtime, Session, Skill, and Material stores. Get a complete technical guide to unified TypeScript APIs.

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

---

**TLDR:** The `@openmaic/storage` package manages seven distinct store families—**KV Store**, **Asset Store**, **Document Store**, **Runtime Store**, **Agent Session Store**, **User Skill Store**, and **Agent Session Material Store**—each exposing unified TypeScript APIs with concrete implementations for browser, HTTP, and PostgreSQL backends.

The `@openmaic/storage` package manages the different types of stores required by the OpenMAIC framework, providing type-safe abstractions for every data storage need. According to the source code in `packages/@openmaic/storage/src/index.ts`, these storage families handle everything from simple key-value pairs to complex agent session materials across multiple runtime environments.

## KV Store (Key-Value)

The **KV Store** family provides the foundational key-value interface used throughout the OpenMAIC system. It includes scoped storage variants like `DeviceSafeKVStore` and `LocalKVStore` for client-side persistence, along with `KVScope` constants such as `DEFAULT_KV_SCOPE` for namespace isolation.

The package exports three primary backend implementations:

- **`BrowserKVStore`** – Located in `packages/@openmaic/storage/src/kv/browser.ts`, this implementation uses browser storage APIs to persist data client-side.
- **`HttpKVStore`** – Defined in `packages/@openmaic/storage/src/kv/http.ts`, this variant communicates with remote KV services via HTTP endpoints.
- **`PgKVStore`** – Found in `packages/@openmaic/storage/src/runtime/pg.ts`, this implementation persists key-value pairs in PostgreSQL tables for server-side reliability.

```typescript
import { BrowserKVStore } from '@openmaic/storage';

const kv = new BrowserKVStore(); 
await kv.set('myKey', { foo: 'bar' });
const value = await kv.get('myKey');
console.log(value);

```

## Asset Store

The **Asset Store** family handles binary data persistence, including images, documents, and other media files. It separates metadata management from byte storage through the `AssetStore` and `AssetByteStore` interfaces, and includes `AssetSignedReadHeaders` for secure URL generation.

Source files reveal three backend tiers:

- **`BrowserAssetStore`** – Implemented in `packages/@openmaic/storage/src/asset/browser-store.ts`, this uses browser Blob APIs and object URLs for temporary asset hosting.
- **`HttpAssetStore`** – Located in `packages/@openmaic/storage/src/asset/http.ts`, this client streams binary data to remote asset services.
- **`PgAssetStore` and `PgAssetByteStore`** – Defined in `packages/@openmaic/storage/src/asset/pg.ts` and `packages/@openmaic/storage/src/asset/pg-bytes.ts`, these store asset metadata and binary chunks in PostgreSQL. The package also supports `S3AssetByteStore` for cloud-native deployments.

```typescript
import { BrowserAssetStore, newAssetId } from '@openmaic/storage';

const assetStore = new BrowserAssetStore();
const assetId = newAssetId();

await assetStore.upload(assetId, new Blob(['binary data'], { type: 'image/png' }));
const url = await assetStore.getUrl(assetId);
console.log(url);

```

## Document Store

The **Document Store** family manages structured document hierarchies through `DocumentStore` and folder organization via `DocumentFolderStore`. It also includes `StageFreshnessManifestStore` for tracking synchronization state across environments.

Concrete implementations include:

- **`BrowserDocumentStore`** – Source in `packages/@openmaic/storage/src/document/browser.ts` provides client-side document management using browser storage.
- **`HttpDocumentStore`** – Located in `packages/@openmaic/storage/src/document/http.ts`, this implementation synchronizes documents with remote servers.
- **`PgDocumentStore`** – Found in `packages/@openmaic/storage/src/document/pg.ts`, offering durable document storage with full PostgreSQL ACID compliance.

```typescript
import { PgDocumentStore } from '@openmaic/storage';

const docStore = new PgDocumentStore({
  connectionString: process.env.PG_URL!,
});

await docStore.createFolder('myFolder');
await docStore.save('myFolder', 'doc1.md', '# Hello World');

```

## Runtime Store

The **Runtime Store** persists transient execution state and session histories during agent operations. The `RuntimeStore` interface supports append-only logs and state retrieval patterns critical for debugging agent chains, with associated error types like `HttpRuntimeStoreError`.

Available implementations:

- **`BrowserRuntimeStore`** – In `packages/@openmaic/storage/src/runtime/browser.ts`, suitable for client-side agent debugging tools.
- **`HttpRuntimeStore`** – Defined in `packages/@openmaic/storage/src/runtime/http.ts`, streaming runtime telemetry to centralized logging services.
- **`PgRuntimeStore`** – Also in `packages/@openmaic/storage/src/runtime/pg.ts` alongside the KV store, providing persistent runtime archives in PostgreSQL.

```typescript
import { BrowserRuntimeStore } from '@openmaic/storage';

const runtime = new BrowserRuntimeStore();
await runtime.append('session:123', { role: 'assistant', content: 'Welcome!' });
const history = await runtime.read('session:123');

```

## Agent Session Store

The **Agent Session Store** family manages conversational context and session metadata across the OpenMAIC platform. This specialized group includes `AgentSessionStore` as the base interface, supplemented by `AgentSessionAutomaticTitleStore` for AI-generated titles, `AgentSessionTitleStore` for user-defined names, and `AgentSessionUrlStore` for session routing information.

Currently, persistent implementations are server-side only:

- **`PgAgentSessionStore`** – Located in `packages/@openmaic/storage/src/material/pg.ts`, this PostgreSQL implementation handles session lifecycle management, automatic title generation, and URL persistence for multi-turn agent conversations.

Unlike browser-backed stores, agent session stores typically require durable server-side storage to maintain context across disconnections.

## User Skill Store

The **User Skill Store** persists per-user capability configurations and skill enablement states. The `UserSkillStore` interface defines methods for saving and retrieving skill metadata for capabilities like image generation.

Implementation:

- **`PgUserSkillStore`** – Source in `packages/@openmaic/storage/src/skill/pg.ts` implements user skill persistence in PostgreSQL, allowing the system to remember enabled skills across sessions.

```typescript
import { PgUserSkillStore } from '@openmaic/storage/src/skill/pg';

const skillStore = new PgUserSkillStore({ connectionString: process.env.PG_URL! });
await skillStore.saveSkill('user42', 'image-generation', { enabled: true });

```

## Agent Session Material Store

The **Agent Session Material Store** handles auxiliary data attachments linked to specific agent sessions, distinct from the core session store. The `AgentSessionMaterialStore` interface manages uploads, retrieval, and deletion of session-specific resources like reference documents or generated artifacts.

Implementation:

- **`PgAgentSessionMaterialStore`** – Defined in `packages/@openmaic/storage/src/material/pg.ts` alongside `PgAgentSessionStore`, this PostgreSQL implementation links binary materials to session records via foreign keys, ensuring referential integrity for session-linked attachments.

## Summary

The `@openmaic/storage` package provides a comprehensive storage architecture covering seven distinct persistence domains:

- **KV Store** – Key-value pairs with `BrowserKVStore`, `HttpKVStore`, and `PgKVStore` backends
- **Asset Store** – Binary asset management including `S3AssetByteStore` and PostgreSQL byte stores
- **Document Store** – Hierarchical document and folder management with `StageFreshnessManifestStore` for synchronization tracking
- **Runtime Store** – Ephemeral execution state and agent telemetry logging across browser and PostgreSQL
- **Agent Session Store** – Conversation context, automatic titles, and URL persistence via `PgAgentSessionStore`
- **User Skill Store** – Per-user capability configuration storage in `PgUserSkillStore`
- **Agent Session Material Store** – Session-linked attachment management through `PgAgentSessionMaterialStore`

Each family exposes consistent TypeScript interfaces while allowing runtime selection between browser-local, HTTP-remote, or PostgreSQL-durable implementations via the exports in `packages/@openmaic/storage/src/index.ts`.

## Frequently Asked Questions

### What is the difference between AssetStore and AssetByteStore?

**AssetStore** handles high-level asset metadata and signed URL generation using `AssetSignedReadHeaders`, while **AssetByteStore** manages the actual binary persistence layer. In the source code, `PgAssetStore` in `packages/@openmaic/storage/src/asset/pg.ts` manages metadata records, whereas `PgAssetByteStore` in `packages/@openmaic/storage/src/asset/pg-bytes.ts` handles the binary storage of file contents. This separation allows systems to store metadata in PostgreSQL while offloading heavy binary data to S3 via `S3AssetByteStore`.

### Can I use the Document Store in a browser-only OpenMAIC deployment?

Yes, the `BrowserDocumentStore` implementation in `packages/@openmaic/storage/src/document/browser.ts` provides full document and folder management capabilities using browser storage APIs. However, for multi-device synchronization, you should switch to `HttpDocumentStore` or `PgDocumentStore` to ensure documents persist across client sessions and devices.

### Which store should I use for temporary agent state that doesn't need to survive page reloads?

Use the **Runtime Store** with `BrowserRuntimeStore` for transient state that aids debugging but doesn't require durability. According to the implementation in `packages/@openmaic/storage/src/runtime/browser.ts`, this store is optimized for append-only logs and quick retrieval during single-page sessions. If you need persistence across reloads or server restarts, switch to `PgRuntimeStore` from `packages/@openmaic/storage/src/runtime/pg.ts`.

### How do I migrate from BrowserKVStore to PgKVStore in production?

Both implementations share the `KVStore` interface exported from `packages/@openmaic/storage/src/index.ts`, making migration straightforward. Replace `new BrowserKVStore()` with `new PgKVStore({ connectionString: 'postgresql://...' })` imported from `packages/@openmaic/storage/src/runtime/pg.ts`. Since both classes implement `get`, `set`, and `delete` methods with identical signatures, no other code changes are required beyond the constructor configuration.