Skip to main content

Memory management options

Orbis Studio provides flexible memory management options for storage and retrieval of data relevant to your flows and your Orbis Studio server. This includes essential Orbis Studio database tables, file management, and caching, as well as chat memory.

Storage​

Orbis Studio uses a PostgreSQL database for all storage. This is pre-configured during platform installation. You can also selectively use external storage for chat memory only — see Store chat memory.

Orbis Studio database tables​

The following tables are stored in the Orbis Studio database:

• ApiKey: Manages Orbis Studio API authentication keys. Component API keys are stored in the Variables table. For more information, see API keys and authentication.

• Deployment: Tracks deployments of Orbis Studio flows to external providers, including the deployment name, provider resource key, and associated project and provider account.

• DeploymentProviderAccount: Stores configured connections to external deployment providers, including provider URL, tenant settings, and encrypted credentials.

• File: Stores metadata for files uploaded to Orbis Studio's file management system, including file names, paths, sizes, and storage providers. For more information, see Manage files.

• Flow: Contains flow definitions, including nodes, edges, and components, stored as JSON or database records. For more information, see Build flows.

tip

Orbis Studio can be configured to automatically remove API keys and tokens from flow data before saving to the database. Contact your administrator to enable this setting.

• FlowVersion: Stores numbered snapshots of flow definitions, enabling version history. Each row captures a complete flow data snapshot linked to a flow and identified by a sequential version number. For more information, see Save and restore flow versions.

• FlowVersionDeploymentAttachment: Links specific flow versions to provider deployments, tracking which flow version is deployed where and the provider's opaque snapshot identifier for that version.

• Folder: Provides a structure for flow storage, including single-user folders and shared folders accessed by multiple users. For more information, see Manage flows in projects.

• IngestionRun: Records knowledge base ingestion run history, including aggregate counters (chunks created, bytes processed, files succeeded/failed/skipped) and per-file outcome details for each ingestion job. For more information, see Knowledge bases.

• Job: Background job queue for asynchronous tasks including flow workflow execution and knowledge base ingestion. Tracks job type (workflow, ingestion, evaluation), status (queued, in_progress, completed, failed), timestamps, and per-job progress metadata.

• KnowledgeBase: Stores knowledge base configurations, including the embedding model, chunking settings, backend type, status, and cached statistics (chunk count, word count, total size). For more information, see Knowledge bases.

• MemoryBase: Stores memory base configurations for flows, including the associated knowledge base name, embedding model, auto-capture threshold, and optional preprocessing settings.

• MemoryBasePreprocessingOutput: Captures LLM-distilled preprocessing output before knowledge base writes. Each row represents one preprocessing batch and tracks the status (processed, ingested, or skipped) to support resumable two-phase commit (LLM call → knowledge base write).

• MemoryBaseSession: Tracks per-session state for each memory base, including the sync cursor position and total count of processed messages.

• MemoryBaseWorkflowRun: Records workflow job runs per memory base and session to support threshold-based ingestion, linking each workflow job to its resulting ingestion job.

• Message: Stores chat messages and interactions that occur between components. For more information, see Message objects and Store chat memory.

• MessageIngestionRecord: Records which messages have been ingested into a memory base and by which job. Serves as a join table between messages and memory bases, ensuring each message is not re-ingested.

• Trace and Span: Stores traces and spans for flows and components. For more information, see Traces.

• Transactions: Records execution history and results of flow runs. This information is used for logging.

• User: Stores user account information including credentials, permissions, profiles, and user management settings. For more information, see API keys and authentication.

• Variables: Stores global encrypted values and credentials. For more information, see Global variables and Component API keys.

• VertexBuild: Tracks the build status of individual nodes within flows. For more information, see Test flows in the Playground.

For more information, see the database models in the source code.

Store chat memory​

Chat-based flows with a Chat Input or Chat Output component produce chat history that is stored in the Orbis Studio messages table. At minimum, this serves as a chat log, but it isn't functionally the same as chat memory that provides historical context to an LLM.

To store and retrieve chat memories in flows, you can use a Message History component or the Agent component's built-in chat memory.

How does chat memory work?

Chat memory is a cache for an LLM or agent to preserve past conversations to retain and reference that context in future interactions. For example, if a user has already told the LLM their name, the LLM can retrieve that information from chat memory rather than asking the user to repeat themselves in future conversations or messages.

Chat memory is distinct from vector store memory because it is built specifically for storing and retrieving chat messages from databases.

Components that support chat memory (such as the Agent and Message History components) provide access to their respective databases as memory. Retrieval as memory is an important distinction for LLMs and agents because this storage and retrieval mechanism is specifically designed to recall context from past conversations. Unlike vector stores, which are designed for semantic search and retrieval of text chunks, chat memory is designed to store and retrieve chat messages in a way that is optimized for conversation history.

Session ID and chat memory​

Chat history and memories are grouped by session ID (session_id).

The default session ID is the flow ID, which means that all chat messages for a flow are stored under the same session ID as one large chat session.

For better segregation of chat memory, especially in flows used by multiple users, consider using custom session IDs. For example, if you use user IDs as session IDs, then each user's chat history is stored separately, isolating the context of their chats from other users' chats.

Chat memory options​

Where and how chat memory is stored depends on the components used in your flow:

  • Agent component: This component has built-in chat memory that is enabled by default. This memory allows the agent to retrieve and reference messages from previous conversations associated with the same session ID. All messages are stored in Orbis Studio storage, and the component provides minimal memory configuration options, such as the number of messages to retrieve.

    The Agent component's built-in chat memory is sufficient for most use cases.

    If you want to use external chat memory storage, retrieve memories outside the context of a chat, or use chat memory with a language model component (not an agent), you must use the Message History component (with or without a third-party chat memory component).

  • Message History component: By default, this component stores and retrieves memories from Orbis Studio storage, unless you attach a third-party chat memory component. It provides a few more options for sorting and filtering memories, although most of these options are also built-in to the Agent component as configurable or fixed parameters.

    You can use the Message History component with or without a language model or agent. For example, if you need to retrieve data from memories outside of chat, you can use the Message History component to fetch that data directly from your chat memory database without feeding it into a chat.

  • Third-party chat memory components: Use one of these components only if you need to store or retrieve chat memories from a dedicated external chat memory database. Typically, this is necessary only if you have specific storage needs that aren't met by Orbis Studio storage. For example, if you want to manage chat memory data by directly working with the database, or if you want to use a different database than the default Orbis Studio storage.

For more information and examples, see Message History component and Agent memory.

See also​