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

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.

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.

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.

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.

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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}