Server Beta Architecture

Relevant source files

• src/server/compat/SessionsObservationsAdapter.ts
• src/server/generation/ProviderObservationGenerator.ts
• src/server/generation/processGeneratedResponse.ts
• src/server/generation/providers/ClaudeObservationProvider.ts
• src/server/middleware/auth.ts
• src/server/middleware/postgres-auth.ts
• src/server/middleware/rate-limit.ts
• src/server/middleware/usage-metering.ts
• src/storage/postgres/agent-events.ts
• src/storage/postgres/rate-limit.ts
• src/storage/postgres/schema.ts
• src/storage/postgres/server-sessions.ts
• src/storage/postgres/usage.ts
• src/storage/sqlite/auth.ts
• tests/server/auth-api-key.test.ts
• tests/server/generation/process-generated-response.test.ts
• tests/server/paid-readiness.test.ts

The Server Beta architecture (Phase 9+) represents the high-scale, multi-tenant evolution of the claude-mem runtime. Unlike the legacy local worker, which uses SQLite and ChromaDB for single-user local development, the Server Beta runtime utilizes Postgres for structured storage and BullMQ (backed by Redis/Valkey) for asynchronous background generation tasks src/storage/postgres/schema.ts8-25

System Overview

The architecture is split into two distinct functional roles: the HTTP API Server and the Generation Worker. These can run in a single process or be scaled independently in a distributed environment.

The Identity Triad

Multi-tenancy and data isolation are enforced through a mandatory identity triad, ensuring that data is partitioned correctly across different users and organizations:

1. api_key_id: Identifies the calling service or user account (authenticated via Bearer or X-Api-Key token) src/server/middleware/postgres-auth.ts58-64
2. actor_id: Identifies the specific AI agent or user initiating the request, linked to the API key src/storage/postgres/schema.ts124
3. request_id: A unique identifier for the specific interaction, propagated from the HTTP middleware to the BullMQ payload for end-to-end traceability src/server/generation/ProviderObservationGenerator.ts75-76

High-Level Data Flow

Sources: src/server/middleware/postgres-auth.ts36-49 src/server/middleware/rate-limit.ts51-65 src/server/generation/ProviderObservationGenerator.ts38-54 src/server/generation/processGeneratedResponse.ts65-82

---

REST V1 API & Ingest Pipeline

The ServerV1PostgresRoutes class handles the core /v1 endpoints. It utilizes the IngestEventsService to handle incoming tool-use and message events.

Event Ingest and Job Creation

When an event is posted, the system performs the following:

1. Auth & Metering: Validates the API key, checks rate limits, and records usage src/server/middleware/rate-limit.ts24-48 src/server/middleware/usage-metering.ts7-15
2. Event Persistence: Stores the raw event in agent_events with a deterministic idempotency_key src/storage/postgres/agent-events.ts70-89
3. Job Enqueueing: Creates an observation_generation_job row and pushes a task to BullMQ src/server/generation/ProviderObservationGenerator.ts38-49

Legacy Compatibility

For clients still using the legacy /api/sessions/observations endpoint, the SessionsObservationsAdapter translates legacy payloads into the Server Beta event/job model src/server/compat/SessionsObservationsAdapter.ts5-18 It resolves the contentSessionId (Claude Code UUID) to a server_sessions row src/server/compat/SessionsObservationsAdapter.ts113-121

Sources: src/server/compat/SessionsObservationsAdapter.ts64-97 src/storage/postgres/agent-events.ts142-181

---

Generation Worker & Response Processing

The ProviderObservationGenerator is the BullMQ worker processor. It acts as a state machine for memory extraction src/server/generation/ProviderObservationGenerator.ts38-54

Processing Workflow

1. Reload & Lock: The worker reloads the canonical outbox row from Postgres and transitions the status to processing src/server/generation/ProviderObservationGenerator.ts104-153
2. Scope Validation: It verifies that the team_id and project_id in the BullMQ payload match the Postgres record to prevent cross-tenant leakage src/server/generation/ProviderObservationGenerator.ts112-128
3. LLM Generation: Calls the configured ServerGenerationProvider.
4. Transaction Persistence: processGeneratedResponse parses the XML and persists observations, source links, and job status updates within a single Postgres transaction src/server/generation/processGeneratedResponse.ts24-36

Idempotency and Deduplication

Idempotency is enforced at the database level:

• observations.generation_key: A unique index per team/project that collapses retry duplicates to a single row src/server/generation/processGeneratedResponse.ts28-29
• observation_sources: A unique index on (observation_id, source_type, source_id) ensures duplicate links are not created src/server/generation/processGeneratedResponse.ts30-31

Sources: src/server/generation/ProviderObservationGenerator.ts69-156 src/server/generation/processGeneratedResponse.ts65-98

---

Postgres Schema Architecture

The Server Beta Postgres schema provides the multi-tenant foundation, replacing the single-file SQLite database src/storage/postgres/schema.ts11-26

Table	Purpose	Code Entity
teams	Organization/Account level grouping.	teams src/storage/postgres/schema.ts91-97
projects	Scoped interaction area (e.g., a git repo).	projects src/storage/postgres/schema.ts99-107
api_keys	Authentication and scope enforcement.	api_keys src/storage/postgres/schema.ts119-132
server_sessions	Tracks interaction periods across reloads.	PostgresServerSession src/storage/postgres/server-sessions.ts8-25
agent_events	Raw log of tool uses and user prompts.	PostgresAgentEvent src/storage/postgres/agent-events.ts16-31
observations	Extracted memories (The "Memories").	PostgresObservation src/server/generation/processGeneratedResponse.ts9
usage_events	Metering for requests, tokens, and observations.	usage_events src/storage/postgres/schema.ts24

Usage Metering & Rate Limiting

The system includes "paid-readiness" primitives:

• Rate Limiting: Fixed-window per-key limiter using PostgresRateLimitRepository src/server/middleware/rate-limit.ts51-65
• Monthly Quotas: Checks month-to-date usage against a team cap src/server/middleware/rate-limit.ts88-102
• Usage Recording: recordUsageMetering tracks tokens spent and observations created after the generation transaction commits src/server/generation/processGeneratedResponse.ts100-113

Sources: src/storage/postgres/schema.ts84-205 src/server/middleware/rate-limit.ts1-48 tests/server/paid-readiness.test.ts90-100