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

The main entry point for thedotmack/claude-mem is 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

The primary logical entry point resides in 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.

// 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:

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, 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:

# 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:

# 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:

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, 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 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 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 and launches background helpers including the orphan process reaper.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}