plans/2026-05-07-claude-mem-13-server-beta-full-worker-parity.md
Status: implementation plan
Date: 2026-05-07
Release target: claude-mem 13
Primary goal: add server (beta) as an installer-selectable runtime while leaving the existing worker in place
Relationship to prior plan: follows plans/2026-05-07-claude-mem-server-apache-bullmq-team-auth.md, but narrows the release strategy to full worker parity plus additive team features
Claude-Mem 13 should ship Server (beta) as an opt-in runtime, not as a worker replacement.
The existing worker remains:
Server beta must reach feature parity by wrapping or copying worker behavior behind shared services before it claims to be a viable runtime. New team features are additive and must not break single-user local worker flows.
plans/2026-05-07-claude-mem-server-apache-bullmq-team-auth.md/Users/alexnewman/Downloads/claude-mem-handoff-docs/claude-mem-server-plan.md/Users/alexnewman/Downloads/claude-mem-handoff-docs/apache-2-plan.mdsrc/npx-cli/index.tssrc/npx-cli/commands/install.tssrc/npx-cli/commands/runtime.tssrc/services/worker-service.tssrc/services/worker-spawner.tssrc/services/server/Server.tssrc/services/worker/http/middleware.tssrc/services/worker/http/routes/ViewerRoutes.tssrc/services/worker/http/routes/SessionRoutes.tssrc/services/worker/http/routes/DataRoutes.tssrc/services/worker/http/routes/SearchRoutes.tssrc/services/worker/http/routes/SettingsRoutes.tssrc/services/worker/http/routes/LogsRoutes.tssrc/services/worker/http/routes/MemoryRoutes.tssrc/services/worker/http/routes/CorpusRoutes.tssrc/services/worker/http/routes/ChromaRoutes.tssrc/services/worker/http/shared.tssrc/services/worker/SessionManager.tssrc/services/sqlite/PendingMessageStore.tssrc/services/queue/SessionQueueProcessor.tssrc/services/worker/agents/ResponseProcessor.tssrc/servers/mcp-server.tsplugin/hooks/hooks.jsondocker/claude-mem/Dockerfiledocker/claude-mem/entrypoint.shdocker/claude-mem/run.sh@clack/prompts through p.select, p.confirm, p.tasks, and p.note in src/npx-cli/commands/install.ts.spawnBunWorkerCommand(command, extraArgs) in src/npx-cli/commands/runtime.ts.ensureWorkerStarted(port, workerScriptPath) from src/services/worker-spawner.ts.RouteHandler.setupRoutes(app) and Server.registerRoutes(handler).zod plus validateBody(schema).ingestObservation, ingestPrompt, and ingestSummary in src/services/worker/http/shared.ts.PendingMessageStore, SessionQueueProcessor, and SessionManager.getMessageIterator.@modelcontextprotocol/sdk Server, ListToolsRequestSchema, and CallToolRequestSchema, with hand-written tool schemas in src/servers/mcp-server.ts.Queue.add, with custom job IDs or dedupe IDs for duplicate suppression.express.json(). Express 5 catch-all docs use /api/auth/*splat.express.json().Server beta is not parity-complete until every item below is implemented or explicitly routed to the worker compatibility path.
npx claude-mem installnpx claude-mem repairnpx claude-mem updatenpx claude-mem uninstallnpx claude-mem startnpx claude-mem stopnpx claude-mem restartnpx claude-mem statusnpx claude-mem search <query>npx claude-mem adopt [--dry-run] [--branch <name>]npx claude-mem cleanup [--dry-run]npx claude-mem transcript watchplugin/scripts/worker-service.cjs start|stop|restart|status|cursor|gemini-cli|hook|generate|clean|adopt|cleanup|--daemoncontinue: true and suppressOutput: trueGET /, GET /health, GET /streamGET /api/health, GET /api/readiness, GET /api/version, GET /api/instructionsPOST /api/admin/restart, POST /api/admin/shutdown, GET /api/admin/doctorPOST /api/sessions/init, POST /api/sessions/observations, POST /api/sessions/summarize, GET /api/sessions/statusGET /api/observations, GET /api/summaries, GET /api/prompts, GET /api/observation/:id, GET /api/observations/by-file, POST /api/observations/batch, GET /api/session/:id, POST /api/sdk-sessions/batch, GET /api/prompt/:id, GET /api/stats, GET /api/projects, GET /api/processing-status, POST /api/processing, POST /api/importGET /api/search, GET /api/timeline, GET /api/decisions, GET /api/changes, GET /api/how-it-works, GET /api/search/observations, GET /api/search/sessions, GET /api/search/prompts, GET /api/search/by-concept, GET /api/search/by-file, GET /api/search/by-type, GET /api/context/recent, GET /api/context/timeline, GET /api/context/preview, GET /api/context/inject, POST /api/context/semantic, GET /api/onboarding/explainer, GET /api/timeline/by-query, GET /api/search/helpGET /api/settings, POST /api/settings, GET /api/mcp/status, POST /api/mcp/toggle, GET /api/branch/status, POST /api/branch/switch, POST /api/branch/updateGET /api/logs, POST /api/logs/clearPOST /api/memory/savePOST /api/corpus, GET /api/corpus, GET /api/corpus/:name, DELETE /api/corpus/:name, POST /api/corpus/:name/rebuild, POST /api/corpus/:name/prime, POST /api/corpus/:name/query, POST /api/corpus/:name/reprimeGET /api/chroma/status__IMPORTANTsearchtimelineget_observationssmart_searchsmart_unfoldsmart_outlinebuild_corpuslist_corporaprime_corpusquery_corpusrebuild_corpusreprime_corpus<private> and excluded projectssession-memory meta skip rulesWhat to implement:
Worker (stable, recommended)Server (beta)--runtime worker--runtime server-beta--queue sqlite|bullmq--redis-url <url>--no-server-beta-autostartCLAUDE_MEM_RUNTIME=worker|server-betaCLAUDE_MEM_SERVER_BETA_ENABLED=true|falseCLAUDE_MEM_SERVER_PORTCLAUDE_MEM_SERVER_HOSTCLAUDE_MEM_QUEUE_ENGINE=sqlite|bullmqDocumentation references:
promptProvider() and promptClaudeModel() in src/npx-cli/commands/install.ts.mergeSettings(...) in src/npx-cli/commands/install.ts.Starting worker daemon task.Verification checklist:
--runtime worker, --runtime server-beta, unknown runtime values, and default behavior.npx claude-mem install --no-auto-start still skips worker/server startup.Anti-pattern guards:
What to implement:
src/npx-cli/commands/server-runtime.ts or extend runtime command helpers with server-aware variants.claude-mem server start|stop|restart|status|doctor|logs.claude-mem start|stop|restart|status mapped to the selected runtime, but in claude-mem 13 default that selection is worker.claude-mem worker startclaude-mem worker stopclaude-mem worker restartclaude-mem worker status.server.pid.server.portserver-YYYY-MM-DD.logensureWorkerStarted(...).Documentation references:
spawnBunWorkerCommand from src/npx-cli/commands/runtime.ts.src/services/worker-spawner.ts and src/services/infrastructure/ProcessManager.ts.Verification checklist:
claude-mem worker status works with existing worker.claude-mem server status does not lie when server beta is not installed.Anti-pattern guards:
.worker.pid or .worker.port for server beta./api/*What to implement:
src/server/compat/worker-api-routes.ts./api/*, /, /health, and /stream routes in Server beta.Documentation references:
src/services/worker/http/routes.Server.registerRoutes(...) usage from WorkerService.registerRoutes().src/services/worker-service.ts for initialization readiness.Verification checklist:
tests/server/parity/routes.test.ts that asserts every route from the parity matrix is registered.Anti-pattern guards:
/v1 routes as a substitute for /api/* parity.What to implement:
WorkerService as the stable wrapper.ServerBetaService as a parallel wrapper that composes the same service graph.Documentation references:
WorkerService.constructor.WorkerService.initializeBackground().WorkerService server options.Verification checklist:
Anti-pattern guards:
What to implement:
ObservationQueueEngine interface.BullMqObservationQueueEngine for Server beta._persistentId;_originalTimestamp;tool_use_id;Documentation references:
PendingMessageStore, SessionQueueProcessor, and SessionManager.getMessageIterator.Verification checklist:
CLAUDE_MEM_REDIS_URL or Docker Compose.Anti-pattern guards:
What to implement:
usersorganizationsteamsteam_membersprojects.team_idmemory_items.team_idagent_events.team_idaudit_log.team_idlocal-userlocal-orgpersonalDocumentation references:
src/services/sqlite/migrations/runner.ts.src/services/sqlite/SessionStore.ts.Verification checklist:
Anti-pattern guards:
What to implement:
/v1/* and team admin routes./api/* compatibility routes in local-dev mode by default for current hooks.claude-mem server api-key createclaude-mem server api-key listclaude-mem server api-key revokeclaude-mem server team createclaude-mem server team listclaude-mem server team inviteclaude-mem server team membersclaude-mem server team switchmemories:readmemories:writememories:forgetevents:writeprojects:readprojects:writeadmin:readadmin:writeDocumentation references:
Verification checklist:
Anti-pattern guards:
What to implement:
/v1/* routes for Server beta:
GET /v1/infoGET /v1/meGET /v1/teamsPOST /v1/teamsGET /v1/projectsPOST /v1/projectsPOST /v1/eventsPOST /v1/events/batchPOST /v1/memoriesGET /v1/memories/:idPATCH /v1/memories/:idPOST /v1/searchPOST /v1/contextPOST /v1/forgetGET /v1/auditPOST /v1/exportPOST /v1/import/v1 route team-aware through authContext.teamId./api/* as compatibility routes and do not force team scoping into their public response shape.Documentation references:
claude-mem-server-plan.md.Verification checklist:
/v1 write requires auth./v1 read is scoped to the active team./api/search still behaves like worker for local compatibility.Anti-pattern guards:
/v1 silently fall back to unscoped global reads./v1.What to implement:
searchtimelineget_observationsmemory_addmemory_searchmemory_contextmemory_forgetmemory_list_recentmemory_record_decisionteam_listteam_switchDocumentation references:
src/servers/mcp-server.ts.tests/servers/mcp-tool-schemas.test.ts.Verification checklist:
Anti-pattern guards:
What to implement:
worker-service.cjs in claude-mem 13 by default.CLAUDE_MEM_RUNTIME=server-beta and have hook handlers route to server beta only after server beta health is confirmed./api/health and /v1/info:
runtime: worker|server-betacompatWorkerAvailable: booleanserverBetaEnabled: booleanDocumentation references:
plugin/hooks/hooks.json.src/services/worker-service.ts cases hook, generate, and daemon startup.Verification checklist:
Anti-pattern guards:
What to implement:
Documentation references:
ViewerRoutes.src/ui/viewer.Verification checklist:
/ in worker./ in server beta.Anti-pattern guards:
What to implement:
claude-mem-server-betavalkeychromadocker/claude-mem harness available.GET /healthzPINGDocumentation references:
docker/claude-mem/entrypoint.sh and run.sh.plans/2026-05-06-redis-dependency-strategy.md.Verification checklist:
docker compose --profile server-beta up --build/v1/info works.Anti-pattern guards:
What to implement:
docs/server-beta.md.docs/server-beta-parity.md with the parity matrix and test commands.docs/team-features.md.Documentation references:
docs/public/*.mdx.Verification checklist:
rg -n "server beta|Server \\(beta\\)|worker stable|team features" README.md docsAnti-pattern guards:
Run:
npm run typecheck:root
bun test tests/server/ tests/services/queue/ tests/services/sqlite/ tests/servers/
bun test tests/integration/worker-api-endpoints.test.ts
bun test tests/hook-lifecycle.test.ts tests/worker-spawn.test.ts tests/services/worker-spawner.test.ts
npm run build
docker compose --profile server-beta up --build
Parity acceptance:
npx claude-mem install.Server (beta).claude-mem worker start|status|stop works.claude-mem server start|status|stop works./api/* compatibility router and route parity tests./v1 team-aware API.The key release rule: claude-mem 13 can ship Server beta only when worker remains fully intact and Server beta has an explicit parity test report.