Build Tools & Compiling
Relevant source files
The following files were used as context for generating this wiki page:
The build system in Claude-mem is designed to transform TypeScript source files into standalone, executable scripts and services compatible with the Claude Code plugin architecture. The process involves bundling multiple lifecycle hooks, a worker service, and a React-based viewer UI into a distributable plugin/ directory.
The orchestration of these tasks is primarily handled by Node.js scripts using esbuild for high-performance bundling and Bun for runtime execution. This system ensures that all dependencies are either bundled or managed through a "smart install" process that auto-configures the environment (including Bun and Python/uv for vector search) on the user's machine.
Sources: scripts/build-hooks.js:8-12, CLAUDE.md:10-18, plugin/scripts/smart-install.js:7-12
Core Build Architecture
The build process is divided into several discrete phases that target different components of the system. The primary entry point for developers is npm run build, which triggers the comprehensive hook and service build script.
Build Orchestration Flow
The build script prepares the plugin/scripts and plugin/ui directories, ensuring the output structure is ready for the plugin marketplace.
Sources: scripts/build-hooks.js:33-50, package.json:52
Component Compilation Details
1. Hooks Bundling
Claude-mem utilizes five primary lifecycle hooks: context-hook, new-hook, save-hook, summary-hook, and user-message-hook. These are bundled from src/hooks/*.ts into individual standalone ESM scripts in plugin/scripts/.
- Engine: esbuild
- Target: Node18 / ESM
- External:
bun:sqlite(injected at runtime by Bun) - Banner:
#!/usr/bin/env bun(shebang for Bun execution)
Sources: scripts/build-hooks.js:15-22, scripts/build-hooks.js:141-160
2. Worker Service and MCP Server
The worker-service (Express API) and mcp-server (Model Context Protocol) are bundled as CommonJS (.cjs) files. They include the package version defined in package.json through the __DEFAULT_PACKAGE_VERSION__ definition.
| Component | Source Path | Output Path | Format | Shebang |
|---|---|---|---|---|
| Worker Service | src/services/worker-service.ts | plugin/scripts/worker-service.cjs | CJS | #!/usr/bin/env bun |
| MCP Server | src/servers/mcp-server.ts | plugin/scripts/mcp-server.cjs | CJS | #!/usr/bin/env node |
| Context Generator | src/services/context-generator.ts | plugin/scripts/context-generator.cjs | CJS | N/A |
Sources: scripts/build-hooks.js:24-37, scripts/build-hooks.js:86-136
3. Viewer UI
The React-based web viewer is compiled via scripts/build-viewer.js. The output is a single viewer.html file placed in plugin/ui/, providing a real-time memory stream interface.
Sources: CLAUDE.md:18, scripts/build-hooks.js:72-84
Runtime Dependency Management (Smart Install)
A critical part of the build and deployment toolchain is plugin/scripts/smart-install.js. This script runs during the first hook execution to ensure the environment is correctly configured without requiring manual user intervention.
Dependency Verification Logic
The "Smart Install" system handles:
- Bun Runtime: Auto-installs Bun for high-performance JS execution and SQLite support.
- uv Manager: Auto-installs
uvto provide a Python environment for the Chroma vector database. - CLI Aliases: Configures
.bashrc,.zshrc, or PowerShell profiles to provide theclaude-memcommand.
Sources: plugin/scripts/smart-install.js:15-132, plugin/scripts/smart-install.js:254-288
Build Commands Summary
| Command | Script / File | Description |
|---|---|---|
npm run build | scripts/build-hooks.js | Compiles all TypeScript hooks and services. |
npm run build-and-sync | scripts/sync-marketplace.cjs | Full pipeline: build, sync to local marketplace, restart worker. |
npm run build:binaries | scripts/build-worker-binary.js | Generates standalone native binaries for the worker service. |
npm run changelog:generate | scripts/generate-changelog.js | Generates CHANGELOG.md by fetching GitHub release data. |
Sources: package.json:52-60, scripts/generate-changelog.js:58-94
Conclusion
The build system of Claude-mem leverages esbuild to minimize startup latency for lifecycle hooks while ensuring cross-platform compatibility through a robust Smart Install mechanism. By bundling the core logic into standalone scripts with precise shebangs, the project maintains a seamless integration with Claude Code and Cursor IDE environments.