# Main Entry Point for thedotmack/claude-mem: Architecture and Execution Guide

> Discover the main entry point for thedotmack/claude-mem at src/services/worker-service.ts. Learn how the async main function orchestrates initialization for the Claude-Mem project.

- Repository: [Alex Newman/claude-mem](https://github.com/thedotmack/claude-mem)
- Tags: architecture
- Published: 2026-02-16

---

**The main entry point for thedotmack/claude-mem is [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts), which defines an async `main()` function that orchestrates system initialization, while the compiled `plugin/scripts/worker-service.cjs` serves as the physical runtime entry point executed by npm scripts.**

Understanding the main entry point for thedotmack/claude-mem is essential for developers contributing to this memory-augmented Claude Code plugin. The repository employs a dual-entry architecture where TypeScript source files provide the logical entry point during development, while a bundled CommonJS file handles production execution via Bun or Node.js.

## Locating the Main Entry Point Files

The claude-mem repository maintains two distinct entry points that serve different phases of the development lifecycle. The source file contains the raw initialization logic, while the compiled file provides the executable runtime artifact.

### The Source Entry Point: [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)

The primary logical entry point resides in [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts). At the bottom of this file, the `main()` function serves as the async initialization routine that orchestrates the entire application startup.

```typescript
// src/services/worker-service.ts
async function main() {
  // …initialisation, server start, health checks…
}

```

The file includes a conditional execution block that detects when the module runs as the top-level script using both ESM and CommonJS compatibility checks:

```typescript
if (import.meta.url === `file://${process.argv[1]}` || require.main === module || !module.parent) {
  // When the file is invoked directly (e.g. via `bun plugin/scripts/worker-service.cjs start`)
  main().catch(err => {
    logger.error('SYSTEM', 'Fatal startup error', { err });
    process.exit(1);
  });
}

```

### The Compiled Entry Point: `plugin/scripts/worker-service.cjs`

During the build process, the TypeScript source is bundled into `plugin/scripts/worker-service.cjs`, which serves as the physical runtime entry point. This CommonJS file is what the npm scripts actually execute when starting the service.

The compiled file maintains the same `main()` function logic but runs within a bundled context suitable for direct execution by Node.js or Bun without requiring TypeScript compilation at runtime.

## Initialization Architecture and Service Wiring

When the main entry point executes, the `main()` function performs a systematic initialization sequence that wires together all domain services.

The process begins by instantiating the **WorkerService** class, which acts as the central orchestrator. This service coordinates:

- **Database Management**: Initializes the `DatabaseManager` for persistent storage operations
- **Session Handling**: Configures the session manager for Claude Code integration
- **Search Capabilities**: Sets up vector search through Chroma integration
- **AI Agents**: Initializes agent systems for memory processing

Following service instantiation, the entry point starts the HTTP server defined in [`src/services/server/Server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/server/Server.ts), registering health check endpoints and API routes. Finally, it launches background helpers including the orphan process reaper and Chroma server integration before signaling readiness to the Claude Code hook framework.

## Practical Execution Methods

Developers can launch claude-mem through several entry point paths depending on their development phase and debugging needs.

### Using npm Scripts (Production Path)

The standard method for starting the service uses the provided npm scripts, which target the compiled entry point:

```bash

# Using Bun (the preferred runtime)

npm run worker:start

# → expands to: bun plugin/scripts/worker-service.cjs start

```

Additional script variants include:

- `npm run worker:restart` – Restarts the worker service
- `npm run worker:stop` – Stops the running worker

### Direct Source Execution (Development Path)

For debugging or development without rebuilding, run the TypeScript source directly:

```bash

# From the repository root

bun src/services/worker-service.ts

```

This method executes the `main()` function within the source file context, bypassing the compiled `worker-service.cjs` bundle.

### Programmatic Integration

For testing or custom implementations, import and instantiate the service directly:

```typescript
import { WorkerService } from './src/services/worker-service.js';

async function launch() {
  const service = new WorkerService();
  await service.start();   // internally calls the same init logic as main()
}
launch();

```

This approach bypasses the CLI entry point entirely while utilizing the same initialization sequence defined in the `main()` function.

## Summary

- The **main entry point for thedotmack/claude-mem** is [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts), which contains the async `main()` function that orchestrates system initialization.
- The **compiled runtime entry point** at `plugin/scripts/worker-service.cjs` is the physical file executed by npm scripts and production deployments.
- The entry point initializes the **WorkerService** class, which wires together database management, session handling, vector search, and AI agents before starting the HTTP server.
- Developers can launch the system via **npm scripts** (`worker:start`), **direct source execution** (`bun src/services/worker-service.ts`), or **programmatic integration** importing the WorkerService class.

## Frequently Asked Questions

### What is the difference between the source entry point and the compiled entry point in claude-mem?

The source entry point at [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts) is the TypeScript file containing the `main()` function and initialization logic used during development. The compiled entry point at `plugin/scripts/worker-service.cjs` is the bundled CommonJS output generated during the build process, which serves as the physical file executed by Node.js or Bun in production environments.

### How does the main entry point handle errors during startup?

The `main()` function in [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts) wraps its execution in a catch block that logs fatal errors using the system logger and exits the process with code 1. When the file runs as the top-level script, any unhandled promise rejections from `main()` trigger this error handler, ensuring the process terminates cleanly rather than hanging in a partial initialization state.

### Can I run the claude-mem entry point without using the compiled worker-service.cjs file?

Yes, you can execute the TypeScript source directly using Bun or ts-node. Running `bun src/services/worker-service.ts` from the repository root executes the `main()` function within the source context, bypassing the compiled bundle. This approach is useful for development and debugging but requires the TypeScript runtime environment, whereas the compiled `worker-service.cjs` file runs in standard Node.js or Bun without compilation steps.

### What services are initialized when the main entry point runs?

When the `main()` function executes, it instantiates the `WorkerService` class, which orchestrates several domain services: the `DatabaseManager` for persistent storage, the session manager for Claude Code integration, vector search capabilities through Chroma integration, and AI agent systems for memory processing. Following service initialization, the entry point starts the HTTP server defined in [`src/services/server/Server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/server/Server.ts) and launches background helpers including the orphan process reaper.