The Server Beta Runtime is a high-performance, multi-tenant implementation of the claude-mem architecture. While the legacy worker service is optimized for local-first single-user environments using SQLite and local subprocesses, the Server Beta runtime is designed for cloud-scale deployments. It replaces the local storage and process model with a robust stack comprising Postgres for relational data, Redis/Valkey for coordination, and BullMQ for distributed job processing.
The Server Beta runtime provides a scalable alternative to the standard worker service, specifically targeting multi-user environments where isolation and high availability are required. It decouples the HTTP API (request handling) from the heavy lifting of observation extraction and summarization (generation).
It introduces a hardened security posture by emitting mandatory security headers (e.g., X-Content-Type-Options, X-Frame-Options) when running in server mode plugin/scripts/server-service.cjs3 The runtime uses a versioned API mounted under /v1, providing stable integration points for external agents and MCP clients docs/api.md3
For details on the underlying system design and the multi-tenant identity model, see Server Beta Architecture.
The runtime is orchestrated through the ServerV1PostgresRoutes which links the HTTP surface to the Postgres storage layer and the background job queue src/server/routes/v1/ServerV1PostgresRoutes.ts118-131
| Component | Role | Code Entity |
|---|---|---|
| HTTP Server | Handles REST V1 API requests and authentication. | Server tests/server/runtime/server-mcp-http-routes.test.ts19 |
| Route Handler | Manages /v1 routes for sessions, events, and memories. | ServerV1PostgresRoutes src/server/routes/v1/ServerV1PostgresRoutes.ts118 |
| Ingest Service | Handles event entry and job enqueuing. | IngestEventsService src/server/routes/v1/ServerV1PostgresRoutes.ts123-126 |
| Storage Repos | Postgres-backed repositories for all entities. | PostgresStorageRepositories src/storage/postgres/index.ts32-44 |
| Remote MCP | Authenticated recall tools for Claude Code. | createRecallMcpServer src/server/mcp/recall-mcp-server.ts140-142 |
For a full reference of available endpoints and authentication modes, see Server Beta REST V1 API.
The following diagram bridges the conceptual "Natural Language Space" of user requests to the "Code Entity Space" of the Server Beta runtime.
Diagram: Request to Memory Pipeline
Sources: src/server/routes/v1/ServerV1PostgresRoutes.ts146-167 src/storage/postgres/agent-events.ts67-70 src/storage/postgres/schema.ts11-26 src/server/mcp/recall-mcp-server.ts101-112
The Server Beta runtime uses a centralized Postgres schema that must be bootstrapped before service start src/storage/postgres/schema.ts28-49 It includes a sophisticated migration system to manage table structures like api_keys, audit_log, and observation_generation_jobs src/storage/postgres/schema.ts84-203
Diagram: Bootstrapping and Validation
Sources: src/storage/postgres/schema.ts28-49 src/server/routes/v1/ServerV1PostgresRoutes.ts146-158 src/server/compat/SessionsObservationsAdapter.ts57-64
| Feature | Legacy Worker | Server Beta |
|---|---|---|
| Concurrency | Single-process (SQLite) | Multi-process / Distributed (Postgres) src/storage/postgres/schema.ts11-26 |
| Tenancy | Single User | Multi-tenant (team_id x project_id) src/storage/postgres/schema.ts99-107 |
| Reliability | Local process supervision | BullMQ with persistence and retries src/storage/postgres/schema.ts188-203 |
| API Version | Legacy /api | Versioned /v1 docs/api.md3-5 |
| Auth Storage | Settings file | Postgres api_keys table src/storage/postgres/schema.ts119-132 |
| MCP Access | Local Stdio | Remote Authenticated HTTP src/server/mcp/recall-mcp-server.ts136-140 |
Sources: src/storage/postgres/schema.ts11-26 docs/api.md3-5 src/server/routes/v1/ServerV1PostgresRoutes.ts46-50 src/server/compat/SessionsObservationsAdapter.ts3-18