Development

Build from source, run tests, and contribute to Claude-Mem

​

Development Guide

​

Building from Source

​

Prerequisites

• Node.js satisfying ^20.19.0 || >=22.12.0 (see package.json)
• npm (comes with Node.js)
• Bun 1.1.31 or higher (required to run tests)
• Git

​

Clone and Build

# Clone repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# Install dependencies
npm install

# Build all components
npm run build

​

Build Process

The build process uses esbuild to compile TypeScript:

1. Compiles TypeScript to JavaScript
2. Creates standalone executables for each hook in plugin/scripts/
3. Bundles MCP search server to plugin/scripts/mcp-server.cjs
4. Bundles worker service to plugin/scripts/worker-service.cjs
5. Bundles web viewer UI to plugin/ui/viewer.html

Build Output:

• Hook executables: *-hook.js (ESM format)
• Setup version-check: version-check.js (ESM format, hand-written; installs missing plugin dependencies and records the install marker)
• Worker service: worker-service.cjs (CJS format)
• MCP server: mcp-server.cjs (CJS format)
• Viewer UI: viewer.html (self-contained HTML bundle)

​

Committed release bundles

Marketplace installs run the committed files in plugin/scripts/. When changing release versions or worker lifecycle code, regenerate and commit the affected runtime bundles with npm run build. A newer manifest paired with an older worker bundle can trigger repeated version-mismatch restarts.

CI checks committed bundle versions before rebuilding:

bun test tests/infrastructure/version-consistency.test.ts

If a replacement worker still reports a stale version, hooks remember the failed recycle in the data directory and skip further recycles of that unchanged bundle. Rebuild or reinstall the bundle to correct the version; a changed bundle allows another recycle attempt.

​

Build Scripts

# Build everything
npm run build

# Build only hooks
npm run build:hooks

# The build script is defined in scripts/build-hooks.js

​

Development Workflow

​

1. Make Changes

Edit TypeScript source files in src/:

src/
├── hooks/           # Hook implementations (entry points + logic)
├── services/        # Worker service and database
├── servers/         # MCP search server
├── sdk/             # Claude Agent SDK integration
├── shared/          # Shared utilities
├── ui/
│   └── viewer/      # React web viewer UI components
└── utils/           # General utilities

​

2. Build

npm run build

​

3. Test

# Run the fast test lane
npm test

# Run the integration test lane
npm run test:integration

# Run both test lanes
npm run test:all

# Check that every discovered test file belongs to exactly one lane
npm run test:lanes:check

# Run a specific test file with Bun
bun test ./tests/shared/settings-defaults-manager.test.ts

# Test context injection
npm run test:context

​

4. Manual Testing

# Start worker manually
npm run worker:start

# Check worker status
npm run worker:status

# View logs
npm run worker:logs

# Test hooks manually
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js

​

5. Iterate

Repeat steps 1-4 until your changes work as expected.

​

Viewer UI Development

​

Working with the React Viewer

The web viewer UI is a React application built into a self-contained HTML bundle.

Location: src/ui/viewer/

Structure:

src/ui/viewer/
├── index.tsx              # Entry point
├── App.tsx                # Main application component
├── components/            # React components
│   ├── Header.tsx         # Header with logo and actions
│   ├── Sidebar.tsx        # Project filter sidebar
│   ├── Feed.tsx           # Main feed with infinite scroll
│   ├── cards/             # Card components
│   │   ├── ObservationCard.tsx
│   │   ├── PromptCard.tsx
│   │   ├── SummaryCard.tsx
│   │   └── SkeletonCard.tsx
├── hooks/                 # Custom React hooks
│   ├── useSSE.ts          # Server-Sent Events connection
│   ├── usePagination.ts   # Infinite scroll pagination
│   ├── useSettings.ts     # Settings persistence
│   └── useStats.ts        # Database statistics
├── utils/                 # Utilities
│   ├── constants.ts       # Constants (API URLs, etc.)
│   ├── formatters.ts      # Date/time formatting
│   └── merge.ts           # Data merging and deduplication
└── assets/                # Static assets (fonts, logos)

​

Building Viewer UI

# Build everything including viewer
npm run build

# The viewer is built to plugin/ui/viewer.html
# It's a self-contained HTML file with inlined JS and CSS

​

Testing Viewer Changes

1. Make changes to React components in src/ui/viewer/
2. Build: npm run build
3. Sync to installed plugin: npm run sync-marketplace
4. Restart worker: npm run worker:restart
5. Refresh the worker URL printed by npm run worker:status

Hot Reload: Not currently supported. Full rebuild + restart required for changes.

​

Adding New Viewer Features

Example: Adding a new card type

1. Create component in src/ui/viewer/components/cards/YourCard.tsx:

import React from 'react';

export interface YourCardProps {
  // Your data structure
}

export const YourCard: React.FC<YourCardProps> = ({ ... }) => {
  return (
    <div className="card">
      {/* Your UI */}
    </div>
  );
};

2. Import and use in Feed.tsx:

import { YourCard } from './cards/YourCard';

// In render logic:
{item.type === 'your_type' && <YourCard {...item} />}

3. Update types if needed in src/ui/viewer/types.ts

4. Rebuild and test

​

Viewer UI Architecture

Data Flow:

1. Worker service exposes HTTP + SSE endpoints
2. React app fetches initial data via HTTP (paginated)
3. SSE connection provides real-time updates
4. Custom hooks handle state management and data merging
5. Components render cards based on item type

Key Patterns:

• Infinite Scroll: usePagination hook with Intersection Observer
• Real-Time Updates: useSSE hook with auto-reconnection
• Deduplication: merge.ts utilities prevent duplicate items
• Settings Persistence: useSettings hook with localStorage
• Theme Support: CSS variables with light/dark/system themes

​

Adding New Features

​

Adding a New Hook

1. Create hook implementation in src/hooks/your-hook.ts:

#!/usr/bin/env node
import { readStdin } from '../shared/stdin';

async function main() {
  const input = await readStdin();

  // Hook implementation
  const result = {
    hookSpecificOutput: 'Optional output'
  };

  console.log(JSON.stringify(result));
}

main().catch(console.error);

Note: As of v4.3.1, hooks are self-contained files. The shebang will be added automatically by esbuild during the build process.

2. Add to plugin/hooks/hooks.json:

{
  "YourHook": [{
    "hooks": [{
      "type": "command",
      "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/your-hook.js",
      "timeout": 120
    }]
  }]
}

3. Rebuild:

npm run build

​

Modifying Database Schema

1. Add migration to src/services/sqlite/migrations.ts:

export const migration011: Migration = {
  version: 11,
  up: (db: Database) => {
    db.run(`
      ALTER TABLE observations ADD COLUMN new_field TEXT;
    `);
  },
  down: (db: Database) => {
    // Optional: define rollback
  }
};

2. Update types in src/services/sqlite/types.ts:

export interface Observation {
  // ... existing fields
  new_field?: string;
}

3. Update database methods in src/services/sqlite/SessionStore.ts:

createObservation(obs: Observation) {
  // Include new_field in INSERT
}

4. Test migration:

# Backup database first!
cp ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.backup

# Run tests
npm test

​

Extending SDK Prompts

1. Modify prompts in src/sdk/prompts.ts:

export function buildObservationPrompt(observation: Observation): string {
  return `
    <observation>

    </observation>
  `;
}

2. Update parser in src/sdk/parser.ts:

export function parseObservation(xml: string): ParsedObservation {
  // Parse new XML fields
}

3. Test:

npm test

​

Adding MCP Search Tools

1. Add tool definition in src/servers/mcp-server.ts:

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'your_new_tool') {
    // Implement tool logic
    const results = await search.yourNewSearch(params);
    return formatResults(results);
  }
});

2. Add search method in src/services/sqlite/SessionSearch.ts:

yourNewSearch(params: YourParams): SearchResult[] {
  // Implement FTS5 search
}

3. Rebuild and test:

npm run build
npm test

​

Testing

​

Testing Philosophy

Claude-mem uses automated tests alongside manual verification in real host sessions.

The automated suite runs with Bun. scripts/test-lanes.ts divides discovered tests into two lanes: the fast lane is the default for npm test; the integration lane includes browser tests, tests under tests/integration/, and smart-file-read service tests. Use npm run test:all to run both lanes, and npm run test:lanes:check to check that the lanes are disjoint and cover every discovered test file.

Run tests relevant to your change during development. Manual verification can then check host integration, database state, logs, and worker health in a real session. It complements automated regression coverage; a manual check does not establish that the automated suite passes.

​

Manual Testing Workflow

When developing new features:

1. Build and sync:

   npm run build
   npm run sync-marketplace
   npm run worker:restart
   

2. Test in real session:

   • Start Claude Code
   • Trigger the feature you’re testing
   • Verify expected behavior

3. Check database state:

   sqlite3 ~/.claude-mem/claude-mem.db "SELECT * FROM your_table;"
   

4. Monitor worker logs:

   npm run worker:logs
   

5. Verify queue health (for recovery features):

   bun scripts/check-pending-queue.ts
   

​

Testing Tools

Health Checks:

# Worker status
npm run worker:status

# Queue inspection
WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
curl http://127.0.0.1:$WORKER_PORT/api/pending-queue

# Database integrity
sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"

Hook Testing:

# Test context hook manually
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js

# Test new hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","prompt":"test"}' | node plugin/scripts/new-hook.js

Data Verification:

# Check recent observations
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, tool_name, created_at
  FROM observations
  ORDER BY created_at_epoch DESC
  LIMIT 10;
"

# Check summaries
sqlite3 ~/.claude-mem/claude-mem.db "
  SELECT id, request, completed
  FROM session_summaries
  ORDER BY created_at_epoch DESC
  LIMIT 5;
"

​

Recovery Feature Testing

For manual recovery features specifically:

1. Simulate stuck messages:

   # Manually create stuck message (for testing only)
   sqlite3 ~/.claude-mem/claude-mem.db "
     UPDATE pending_messages
     SET status = 'processing',
         started_processing_at_epoch = strftime('%s', 'now', '-10 minutes') * 1000
     WHERE id = 123;
   "
   

2. Test recovery:

   bun scripts/check-pending-queue.ts
   

3. Verify results:

   WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   curl http://127.0.0.1:$WORKER_PORT/api/pending-queue | jq '.queue'
   

​

Regression Testing

Before releasing:

1. Test all hook triggers:

   • SessionStart: Start new Claude Code session
   • UserPromptSubmit: Submit a prompt
   • PostToolUse: Use a tool like Read
   • Summary: Let session complete
   • SessionEnd: Close Claude Code

2. Test core features:

   • Context injection (recent sessions appear)
   • Observation processing (summaries generated)
   • MCP search tools (search returns results)
   • Viewer UI (loads at the worker URL)
   • Manual recovery (stuck messages recovered)

3. Test edge cases:

   • Worker crash recovery
   • Database locks
   • Port conflicts
   • Large databases

4. Cross-platform (if applicable):

   • macOS
   • Linux
   • Windows

​

Code Style

​

TypeScript Guidelines

• Use TypeScript strict mode
• Define interfaces for all data structures
• Use async/await for asynchronous code
• Handle errors explicitly
• Add JSDoc comments for public APIs

​

Formatting

• Follow existing code formatting
• Use 2-space indentation
• Use single quotes for strings
• Add trailing commas in objects/arrays

​

Example

/**
 * Create a new observation in the database
 */
export async function createObservation(
  obs: Observation
): Promise<number> {
  try {
    const result = await db.insert('observations', {
      session_id: obs.session_id,
      tool_name: obs.tool_name,
      // ...
    });
    return result.id;
  } catch (error) {
    logger.error('Failed to create observation', error);
    throw error;
  }
}

​

Debugging

​

Enable Debug Logging

export DEBUG=claude-mem:*
npm run worker:restart
npm run worker:logs

​

Inspect Database

sqlite3 ~/.claude-mem/claude-mem.db

# View schema
.schema observations

# Query data
SELECT * FROM observations LIMIT 10;

​

Trace Observations

Use correlation IDs to trace observations through the pipeline:

sqlite3 ~/.claude-mem/claude-mem.db
SELECT correlation_id, tool_name, created_at
FROM observations
WHERE session_id = 'YOUR_SESSION_ID'
ORDER BY created_at;

​

Debug Hooks

Run hooks manually with test input:

# Test context hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","source":"startup"}' | node plugin/scripts/context-hook.js

# Test new hook
echo '{"session_id":"test-123","cwd":"'$(pwd)'","prompt":"test"}' | node plugin/scripts/new-hook.js

​

Publishing

Releases ship from main only, and pull requests target main.

​

Version Bump

Update every manifest that carries the package version:

• package.json
• plugin/package.json
• .claude-plugin/marketplace.json
• .claude-plugin/plugin.json
• plugin/.claude-plugin/plugin.json
• .codex-plugin/plugin.json
• plugin/.codex-plugin/plugin.json
• openclaw/openclaw.plugin.json

Verify the old version is gone and the new version appears everywhere expected:

git grep -n '"version": "NEW_VERSION"'
git grep -n '"version": "OLD_VERSION"'

​

Build, Tag, and Publish

npm run build-and-sync
git add -A
git commit -m "chore: bump version to NEW_VERSION"
git tag -a vNEW_VERSION -m "Version NEW_VERSION"
git push origin main
git push origin vNEW_VERSION

Publishing to npm requires the maintainer’s npm credentials and 2FA:

npm publish
npm view claude-mem@NEW_VERSION version

Only after npm resolves the version, create the GitHub release and regenerate the changelog:

gh release create vNEW_VERSION --title "vNEW_VERSION" --notes "..."
npm run changelog:generate
git add docs/CHANGELOG.md
git commit -m "docs: regenerate changelog for vNEW_VERSION"
git push origin main

Do not hand-edit docs/CHANGELOG.md; it is generated from GitHub releases.

​

Contributing

​

Contribution Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Write tests
5. Update documentation
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

​

Pull Request Guidelines

• Clear title: Describe what the PR does
• Description: Explain why the change is needed
• Tests: Include tests for new features
• Documentation: Update docs as needed
• Changelog: Do not hand-edit docs/CHANGELOG.md; it is generated during release
• Commits: Use clear, descriptive commit messages

​

Code Review Process

1. Automated tests must pass
2. Code review by maintainer
3. Address feedback
4. Final approval
5. Merge to main

​

Development Tools

​

Recommended VSCode Extensions

• TypeScript
• ESLint
• Prettier
• SQLite Viewer

​

Useful Commands

# Check TypeScript types
npx tsc --noEmit

# Lint code (if configured)
npm run lint

# Format code (if configured)
npm run format

# Clean build artifacts
rm -rf plugin/scripts/*.js plugin/scripts/*.cjs

​

Troubleshooting Development

​

Build Fails

1. Clean node_modules:

   rm -rf node_modules
   npm install
   

2. Check Node.js version:

   node --version  # Should be >= 20.0.0
   

3. Check for syntax errors:

   npx tsc --noEmit
   

​

Tests Fail

1. Check database:

   rm ~/.claude-mem/claude-mem.db
   npm test
   

2. Check worker status:

   npm run worker:status
   

3. View logs:

   npm run worker:logs
   

​

Worker Won’t Start

1. Kill existing process:

   npm run worker:stop
   

2. Check port:

   WORKER_PORT=$(jq -r .CLAUDE_MEM_WORKER_PORT ~/.claude-mem/settings.json)
   lsof -i :$WORKER_PORT
   

3. Try custom port:

   export CLAUDE_MEM_WORKER_PORT=38000
   npm run worker:start
   

​

Next Steps

• Architecture Overview - Understand the system
• Configuration - Customize Claude-Mem
• Troubleshooting - Common issues