Octopus Database Overview
The Octopus database is the SQL Server persistence layer for the Octopus AI framework — storing agent definitions, conversation history, episodic memory, and procedural knowledge in a multi-tenant, query-friendly schema.
What Is the Octopus Database?
Every Octopus AI agent runs within a persistent data context. When an agent converses with a user, each turn of the conversation is recorded. When an agent learns a multi-step procedure, that procedure is saved. When an agent is configured, its full specification is stored. All of this structured data lives in the Octopus SQL Server database — a dedicated relational database that forms the core SQL tier of the Data Ocean for Octopus.
Unlike the vector store (Qdrant or PGVector) that holds embedding vectors and enables semantic similarity search, the Octopus SQL database holds structured, queryable, relational data. It is the source of truth for agent state, conversation history, and memory records.
The Octopus database is one of the SQL databases in the Data Ocean ecosystem. Data Ocean is BizFirstGO's unified data layer — a collection of purpose-built databases and query services that power workflow nodes, AI agents, and application data.
What Is Stored Here
Agent Definitions
System prompts, plugin references, configuration JSON, version, and lifecycle status for every registered Octopus agent.
Conversations
Session records linking a user to an agent — start/end timestamps, status (active, ended, timed-out), and session-level metadata.
Episodic Memory
Every message turn within a conversation — role, content, tool calls, and a reference pointer to the corresponding embedding in the vector store.
Procedural Memory
Named multi-step procedures that agents have learned — stored as structured JSON plans that can be retrieved and executed.
Relationship to the Vector Store
The Octopus memory system uses two complementary stores that work together:
| Store | Technology | What It Holds | Query Type |
|---|---|---|---|
| Octopus SQL Database | SQL Server | Structured records: agents, sessions, episode metadata, procedure plans | Exact lookups, joins, filters by agentId/sessionId/tenantId |
| Vector Store | Qdrant / PGVector | Embedding vectors + minimal payload metadata | Semantic similarity search (ANN nearest-neighbor) |
When an episode is stored, the text content goes into Octopus_Episodes.Messages (SQL), and the embedding vector goes into the vector store. The SQL row holds an EmbeddingRef that points to the vector store entry, allowing the system to retrieve full episode text after a semantic search identifies the relevant episode IDs.
All four Octopus tables include a TenantId column. Every query — whether in application code or manual SQL tooling — must include a WHERE TenantId = @tenantId clause. Cross-tenant data leakage is a security violation.
The Four Core Tables
Octopus_Agents
The registry of all AI agents in the tenant — their names, system prompts, plugin configurations, and operational status. An agent must exist here before it can run conversations.
Octopus_Conversations
Each time a user starts a chat session with an agent, a conversation record is created here. It groups all episodes (turns) in that session and tracks session lifecycle.
Octopus_Episodes
The episodic memory table — one row per conversation turn. Contains the message content (as compressed JSON), tool call records, timestamps, and an embedding reference.
Octopus_Procedures
Named multi-step plans that agents have stored as procedural memory — reusable action sequences with structured JSON steps.
Accessing the Database
Because the Octopus database is standard SQL Server, it can be accessed with any SQL tooling your team already uses:
- SQL Server Management Studio (SSMS) — for ad-hoc queries, schema inspection, and maintenance
- Azure Data Studio — lightweight cross-platform alternative to SSMS
- EF Core — the primary ORM used by the Octopus framework itself
- ADO.NET / Dapper — for high-performance read paths in application code
- Flow Studio SQL nodes — query Octopus data from within workflow automation
Unlike some AI memory systems that require a custom SDK to query, the Octopus SQL database is entirely standard SQL Server. Data engineers can inspect, report on, and manage it with familiar tools. The only requirement is that all queries include the tenant filter.
Multi-Tenancy Architecture
The Octopus database uses a shared-schema, tenant-column multi-tenancy model. All tenants share the same tables, but every row is tagged with a TenantId. The EF Core OctopusDbContext automatically applies a global query filter so that application-layer queries always scope to the current tenant.
For direct SQL access (SSMS, reporting tools), you must manually include the tenant filter. The database does not enforce row-level security at the SQL engine level — the filter is an application responsibility.