Memory Storage Overview
Octopus uses two persistence backends — SQL Server and a vector database — to store three of its four memory types. This guide covers where each memory type is stored, the complete table schemas, tenant isolation, retention policies, backup strategies, and migration procedures.
Storage Architecture
SQL Server
Stores episodic memory (conversation episodes), procedural memory (procedure steps), and agent configuration. Managed via EF Core with multi-tenant global query filters.
Vector Database
Stores semantic memory (knowledge chunk embeddings). Qdrant for production, PGVector for PostgreSQL-first teams. One collection per agent.
In-Process RAM
Working memory exists only in RAM for the duration of a single request. Rebuilt from the other stores on every turn. Never persisted to disk.
Storage Map
| Memory Type | Storage System | Table / Collection | Plugin |
|---|---|---|---|
| Working | In-process RAM | N/A | Core (no plugin needed) |
| Episodic | SQL Server | Octopus_Episodes, Octopus_EpisodeMessages | SqlServerPlugin |
| Semantic | Qdrant or PGVector | agent_{agentId} collection | SemanticKernelPlugin |
| Procedural | SQL Server | Octopus_Procedures | SqlServerPlugin |
| Agent Config | SQL Server | Octopus_Agents, Octopus_AgentMemoryConfig | SqlServerPlugin |
SqlServerPlugin Responsibilities
The SqlServerPlugin manages all SQL-backed storage. It registers EF Core services, runs migrations on startup, and applies multi-tenant query filters globally:
public class SqlServerPlugin : IOctopusPlugin
{
public void OnRegister(IServiceCollection services, OctopusConfig config)
{
services.AddDbContext<OctopusDbContext>(opt =>
opt.UseSqlServer(config.SqlConnectionString,
sql => sql.MigrationsAssembly("BizFirst.Octopus.SqlServerPlugin")));
services.AddScoped<IEpisodicMemoryStore, EpisodicMemoryStore>();
services.AddScoped<IProceduralMemoryStore, ProceduralMemoryStore>();
services.AddScoped<IAgentStore, AgentStore>();
}
public async Task OnStartAsync(IServiceProvider sp, CancellationToken ct)
{
// Apply pending EF Core migrations on startup
var db = sp.GetRequiredService<OctopusDbContext>();
await db.Database.MigrateAsync(ct);
}
}Key Design Decisions
| Decision | Rationale |
|---|---|
| SQL for relational + vector DB for embeddings | Relational queries (by userId, agentId, date) are naturally SQL; vector similarity is naturally a vector store concern |
| One vector collection per agent | Enforces knowledge isolation without any query-time filtering overhead |
| EF Core global query filters for TenantId | Every SQL query automatically scoped to the tenant — no risk of cross-tenant data leakage |
| Soft delete before hard purge | Episodic memory is soft-deleted at TTL expiry; a background job hard-purges after a grace period |
| Schema migrations in plugin assembly | Self-contained — deploying the plugin is sufficient to create all required tables |