### Clone and Build Claude-Mem Project

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/openrouter-setup.mdx

This snippet shows how to clone the Claude-Mem repository, install its dependencies using Bun, and build the project. It's a prerequisite for setting up the integration.

```bash
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
bun install
bun run build
```

--------------------------------

### Install notebooklm-py and Playwright

Source: https://github.com/thedotmack/claude-mem/blob/main/plugin/skills/wowerpoint/SKILL.md

Run this one-time setup command to install the necessary Python package and browser binaries for Playwright.

```bash
uv tool install --with playwright --force notebooklm-py
$(uv tool dir)/notebooklm-py/bin/playwright install chromium
```

--------------------------------

### Add Marketplace and Install Plugin

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/troubleshooting.mdx

First, add the plugin marketplace, then install the plugin. Verify the installation by listing the plugin directory.

```bash
/plugin marketplace add thedotmack/claude-mem
```

```bash
/plugin install claude-mem
```

```bash
ls -la ~/.claude/plugins/marketplaces/thedotmack/
```

--------------------------------

### Installer Code - User Guidance

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-06-codex-plugin-version-mismatch.md

Installer code that guides the user to manually install plugins after marketplace registration. This indicates a gap in the automated installation process.

```typescript
src/npx-cli/commands/install.ts:271
```

```typescript
src/npx-cli/commands/install.ts:281
```

--------------------------------

### Import setup-runtime functions in install.ts

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-04-29-installer-streamline.md

Adds the necessary imports from the new `setup-runtime.ts` module to the `install.ts` file. This makes the runtime setup functions available for use in the installation command.

```typescript
import {
  ensureBun,
  ensureUv,
  installPluginDependencies,
  writeInstallMarker,
  isInstallCurrent,
} from '../install/setup-runtime.js';
```

--------------------------------

### Install Hooks and Start Claude-Mem Worker

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/openrouter-setup.mdx

Installs the necessary hooks for Cursor integration and starts the Claude-Mem worker process after manual configuration. These commands ensure the background service is running.

```bash
bun run cursor:install
bun run worker:start
```

--------------------------------

### Example Search Queries

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/usage/search-tools.mdx

Demonstrates how to refine search queries for better results. Start with broader terms and progressively narrow down the search.

```python
search(query="JWT authentication implementation with RS256")

search(query="authentication")
```

--------------------------------

### Installer Code - Register Marketplace

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-06-codex-plugin-version-mismatch.md

Example of the installer code that registers a plugin marketplace. This highlights that the current installer focuses on marketplace registration rather than direct plugin installation.

```typescript
src/services/integrations/CodexCliInstaller.ts:188
```

```typescript
src/services/integrations/CodexCliInstaller.ts:189
```

```typescript
src/services/integrations/CodexCliInstaller.ts:200
```

```typescript
src/services/integrations/CodexCliInstaller.ts:203
```

--------------------------------

### Quick Install and Build for Claude-Mem

Source: https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/README.md

This snippet outlines the steps to clone the Claude-Mem repository, install dependencies using bun, build the project, and initiate an interactive setup for configuring providers and installing hooks.

```bash
# Clone and build
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem && bun install && bun run build

# Interactive setup (configures provider + installs hooks)
bun run cursor:setup
```

--------------------------------

### Setup Hook Configuration for Version Check

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/hooks-architecture.mdx

This JSON configuration defines the 'Setup' hook to run a version check script. It ensures the plugin is up-to-date by comparing an install marker with the current plugin version. The hook is designed to be non-blocking and exits with code 0, even if a mismatch is found, providing repair instructions to stderr.

```json
{
  "hooks": {
    "Setup": [{
      "hooks": [{
        "type": "command",
        "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/version-check.js",
        "timeout": 60
      }]
    }]
  }
}
```

--------------------------------

### Install Claude-Mem CLI

Source: https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/QUICKSTART.md

Installs the Claude-Mem command-line interface globally or for the current project. Use 'user' for global installation. The 'status' command checks the installation.

```bash
# Install globally for all projects (recommended)
claude-mem cursor install user

# Or install for current project only
claude-mem cursor install

# Check installation status
claude-mem cursor status
```

--------------------------------

### Runtime Installation and Management Functions

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-04-29-installer-streamline.md

These functions are exported from `src/npx-cli/install/setup-runtime.ts` and are used to manage the installation of Bun, uv, and plugin dependencies.

```APIDOC
## API Surface

### `ensureBun()`

#### Description
Ensures that Bun is installed and available. If not installed, it will attempt to install it.

#### Returns
- `Promise<{ bunPath: string; version: string }>` - An object containing the path to the Bun executable and its installed version.

### `ensureUv()`

#### Description
Ensures that the `uv` library is installed and available. If not installed, it will attempt to install it.

#### Returns
- `Promise<{ uvPath: string; version: string }>` - An object containing the path to the `uv` executable and its installed version.

### `installPluginDependencies(targetDir: string, bunPath: string)`

#### Description
Installs the dependencies for a plugin in the specified target directory using the provided Bun path.

#### Parameters
- **targetDir** (string) - Required - The directory where the plugin dependencies should be installed.
- **bunPath** (string) - Required - The path to the Bun executable to use for installation.

#### Returns
- `Promise<void>`

### `readInstallMarker(targetDir: string)`

#### Description
Reads the installation marker file from the target directory to check the current installation status and versions.

#### Parameters
- **targetDir** (string) - Required - The directory to read the marker file from.

#### Returns
- `{ version: string; bun?: string; uv?: string; installedAt?: string } | null` - An object containing installation details if the marker exists, otherwise null.

### `writeInstallMarker(targetDir: string, version: string, bunVersion: string, uvVersion: string)`

#### Description
Writes an installation marker file to the target directory with the specified version information.

#### Parameters
- **targetDir** (string) - Required - The directory to write the marker file to.
- **version** (string) - Required - The version of the plugin being installed.
- **bunVersion** (string) - Required - The version of Bun used for installation.
- **uvVersion** (string) - Required - The version of uv used for installation.

### `isInstallCurrent(targetDir: string, expectedVersion: string)`

#### Description
Checks if the current installation in the target directory matches the expected version.

#### Parameters
- **targetDir** (string) - Required - The directory to check the installation status in.
- **expectedVersion** (string) - Required - The expected version of the installation.

#### Returns
- `boolean` - True if the installation is current, false otherwise.
```

--------------------------------

### Bun Installation Scripts

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/architecture/worker-service.mdx

Install Bun globally on Windows, macOS, or Linux using provided scripts, or install manually via package managers.

```bash
# Windows:
powershell -c "irm bun.sh/install.ps1 | iex"

# macOS/Linux:
curl -fsSL https://bun.sh/install | bash
```

```bash
# Manual Install - Windows:
winget install Oven-sh.Bun

# Manual Install - macOS:
brew install oven-sh/bun/bun
```

--------------------------------

### Installation

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/openclaw-integration.mdx

Instructions for installing the Claude-Mem plugin using a one-liner script or manual configuration.

```APIDOC
## Installation

Run this one-liner to install everything automatically:

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```

The installer handles dependency checks (Bun, uv), plugin installation, memory slot configuration, AI provider setup, worker startup, and optional observation feed configuration.

You can also pre-select options:

```bash
# With a specific AI provider
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --provider=gemini --api-key=YOUR_KEY

# Fully unattended (defaults to Claude Max Plan)
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --non-interactive

# Upgrade existing installation
curl -fsSL https://install.cmem.ai/openclaw.sh | bash -s -- --upgrade
```

### Manual Configuration

Add `claude-mem` to your OpenClaw gateway's plugin configuration:

```json
{
  "plugins": {
    "claude-mem": {
      "enabled": true,
      "config": {
        "project": "my-project",
        "syncMemoryFile": true,
        "workerPort": 37777,
        "observationFeed": {
          "enabled": true,
          "channel": "telegram",
          "to": "your-chat-id"
        }
      }
    }
  }
}
```

<Note>
The claude-mem worker service must be running on the same machine as the OpenClaw gateway. The plugin communicates with it via HTTP on `localhost:37777`.
</Note>
```

--------------------------------

### Clone and Build Claude-Mem from Source

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/installation.mdx

For development or testing, clone the repository and build the project. This includes installing dependencies, building hooks and the worker service, and manually starting the worker if needed.

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

# Install dependencies
npm install

# Build hooks and worker service
npm run build

# Worker service will auto-start on first Claude Code session
# Or manually start with:
npm run worker:start

# Verify worker is running
npm run worker:status
```

--------------------------------

### Manually Install Plugin Dependencies

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/troubleshooting.mdx

Navigate to the plugin directory and run `npm install` to install missing dependencies.

```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm install
```

--------------------------------

### Install npm Dependencies

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/troubleshooting.mdx

Run `npm install` to install project dependencies, especially if encountering 'Cannot find module' errors.

```bash
npm install
```

--------------------------------

### Debugging Workflow Example

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/usage/search-tools.mdx

Demonstrates a 3-step workflow for debugging issues using the MCP tools. It involves searching for bugfixes, getting timeline context around a relevant observation, and fetching full details of specific fixes.

```workflow_example
Step 1: search(query="error database connection", type="bugfix", limit=10)
  → Review index, identify observations #245, #312, #489

Step 2: timeline(anchor=312, depth_before=3, depth_after=3)
  → See what was happening around the fix

Step 3: get_observations(ids=[312, 489])
  → Get full details on relevant fixes
```

--------------------------------

### Documentation Examples of Plugin Root Syntax

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/02-spawn-contract-templating.md

These are code examples found in documentation that teach users the raw syntax for referencing files using the CLAUDE_PLUGIN_ROOT environment variable. These examples are intended for direct copy-pasting by third-party users.

```plaintext
${CLAUDE_PLUGIN_ROOT}/scripts/my-hook.sh
```

--------------------------------

### Install Claude-Mem CLI

Source: https://github.com/thedotmack/claude-mem/blob/main/README.md

Use npx to install Claude-Mem. This command registers plugin hooks and sets up the worker service.

```bash
npx claude-mem install
```

```bash
npx claude-mem install --ide gemini-cli
```

```bash
npx claude-mem install --ide opencode
```

--------------------------------

### Simulate Fresh Install DB State

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/issue-2139-pending-messages-migration.md

Commands to move existing database files to simulate a fresh installation for testing migration.

```bash
mv ~/.claude-mem/claude-mem.db ~/.claude-mem/claude-mem.db.preissue2139
mv ~/.claude-mem/claude-mem.db-wal ~/.claude-mem/claude-mem.db-wal.preissue2139 2>/dev/null
mv ~/.claude-mem/claude-mem.db-shm ~/.claude-mem/claude-mem.db-shm.preissue2139 2>/dev/null
```

--------------------------------

### Install and Reset claude-mem

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-04-30-onboarding-ux-overhaul.md

Use these commands to perform a fresh installation of claude-mem. The first command removes any existing configuration, and the second installs the latest version.

```bash
rm -rf ~/.claude-mem
npx claude-mem install
```

--------------------------------

### Install Claude-Mem Plugin via Marketplace

Source: https://github.com/thedotmack/claude-mem/blob/main/README.md

Install Claude-Mem directly from the plugin marketplace within Claude Code.

```bash
/plugin marketplace add thedotmack/claude-mem

/plugin install claude-mem
```

--------------------------------

### Build and Verify Server-Beta Bundle

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-07-finish-bullmq-branch-ship-plan.md

Build the project and then list the contents of the plugin scripts directory to verify that the server-beta-service.cjs bundle has been produced.

```bash
npm run build-and-sync
ls -la plugin/scripts/server-beta-service.cjs
```

--------------------------------

### Windows Installation and Configuration for claude-mem

Source: https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/STANDALONE-SETUP.md

Step-by-step guide for installing and configuring claude-mem on Windows, including cloning the repository, installing dependencies, setting up the provider configuration, and initiating the interactive setup or manual installation.

```powershell
# Clone and build
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
bun install
bun run build

# Configure provider (Gemini example)
$settingsDir = "$env:USERPROFILE\.claude-mem"
New-Item -ItemType Directory -Force -Path $settingsDir

@"
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
"@ | Out-File -FilePath "$settingsDir\settings.json" -Encoding UTF8

# Interactive setup (recommended - walks you through everything)
bun run cursor:setup

# Or manual installation
bun run cursor:install
bun run worker:start
```

--------------------------------

### Create setup-runtime.test.ts

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-04-29-installer-streamline.md

Create a new test file for the setup-runtime module. This file should cover scenarios like missing install markers, correct marker production, and version checking logic.

```typescript
tests/setup-runtime.test.ts
```

--------------------------------

### Verify Claude-Mem Installation and Worker Status

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/openrouter-setup.mdx

Checks if the Claude-Mem worker is running and if the Cursor hooks have been successfully installed. These commands are used to confirm the integration is active.

```bash
bun run worker:status
bun run cursor:status
```

--------------------------------

### Add Setting up runtime task

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-04-29-installer-streamline.md

Replaces the deleted 'Setting up Bun and uv' task. This task ensures the runtime environment is ready by checking and potentially installing Bun and uv dependencies.

```typescript
{
  title: 'Setting up runtime (first install can take ~30s)',
  task: async (message) => {
    message('Checking Bun…');
    const { version: bunVersion } = await ensureBun();
    message('Checking uv…');
    const { version: uvVersion } = await ensureUv();
    const cacheDir = pluginCacheDirectory(version);
    if (!isInstallCurrent(cacheDir, version)) {
      message('Installing plugin dependencies…');
      const { bunPath } = await ensureBun();
      await installPluginDependencies(cacheDir, bunPath);
      writeInstallMarker(cacheDir, version, bunVersion, uvVersion);
    }
    return `Runtime ready (Bun ${bunVersion}, uv ${uvVersion}) ${pc.green('OK')}`;
  },
}
```

--------------------------------

### Example Export for Windows Compatibility

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/usage/export-import.mdx

This bash command exports memories related to 'windows compatibility installation', saving them to 'windows-fixes.json'. This is useful for collecting specific troubleshooting or setup information.

```bash
npx tsx scripts/export-memories.ts "windows compatibility installation" windows-fixes.json
```

--------------------------------

### Start Claude-Mem Server with Docker Compose

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/docker.md

Build the Docker image and start the Claude-Mem Server and its Valkey sidecar. Use this command to initiate the service.

```sh
docker compose up --build
```

```sh
curl http://127.0.0.1:37777/healthz
```

--------------------------------

### Worked Example: Corporate Gateway Configuration

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/configuration/custom-anthropic-backends.mdx

This example shows how to configure `~/.claude-mem/.env` and `~/.claude-mem/settings.json` to route traffic through a corporate Anthropic proxy. Ensure your proxy accepts the same protocol and model names.

```bash
# ~/.claude-mem/.env
ANTHROPIC_API_KEY=sk-corp-...
ANTHROPIC_BASE_URL=https://anthropic-proxy.internal.example.com
```

```json
{
  "CLAUDE_MEM_PROVIDER": "claude",
  "CLAUDE_MEM_MODEL": "claude-haiku-4-5-20251001"
}
```

--------------------------------

### Non-interactive claude-mem Installation with Redis

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-06-redis-dependency-strategy.md

These commands demonstrate non-interactive installation of claude-mem, specifying the queue engine and Redis setup.

```bash
npx claude-mem install --queue bullmq --install-redis
```

```bash
npx claude-mem install --queue bullmq --redis-url redis://127.0.0.1:6379
```

--------------------------------

### Build and Deploy Server Beta

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-07-claude-mem-13-server-beta-full-worker-parity.md

Build the project and bring up the server beta environment using Docker Compose. Ensure the build process is completed successfully before deployment.

```sh
npm run build
```

```sh
docker compose --profile server-beta up --build
```

--------------------------------

### Install Claude-Mem on OpenClaw Gateway

Source: https://github.com/thedotmack/claude-mem/blob/main/README.md

Install Claude-Mem as a persistent memory plugin on OpenClaw gateways using a curl command. The installer handles dependencies, setup, configuration, and worker startup.

```bash
curl -fsSL https://install.cmem.ai/openclaw.sh | bash
```

--------------------------------

### Shell Expansion with Fallbacks

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/02-spawn-contract-templating.md

This example shows shell expansion for a single command, utilizing default values if environment variables are not set. It includes fallbacks for plugin root paths.

```json
{
  "command": "sh -c \"${VAR:-default}\""
}
```

--------------------------------

### Smart Install Caching with TypeScript

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/architecture-evolution.mdx

Implements version-based caching for npm installations to reduce session start time. It checks a version marker before installing dependencies, only running `npm install` if the version has changed. Dependencies include Node.js and npm.

```typescript
const currentVersion = getPackageVersion();
const installedVersion = readFileSync('.install-version', 'utf-8');

if (currentVersion !== installedVersion) {
  // Only install if version changed
  await runNpmInstall();
  writeFileSync('.install-version', currentVersion);
}
```

--------------------------------

### Start Claude-Mem Worker and Verify Status

Source: https://github.com/thedotmack/claude-mem/blob/main/cursor-hooks/README.md

Commands to start the Claude-Mem worker process and check its operational status. After installation and starting the worker, Cursor needs to be restarted for the hooks to be loaded and recognized.

```bash
# Start the worker:
claude-mem start

# Verify installation:
claude-mem cursor status
```

--------------------------------

### Start Gemini CLI

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/gemini-cli/setup.mdx

Launch Gemini CLI normally after installing and configuring claude-mem. The tool works in the background, injecting recent observations and project history at session start.

```bash
gemini
```

--------------------------------

### Start LiteLLM Gateway

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/configuration/litellm-gateway.mdx

This command starts the LiteLLM gateway with a specified configuration file and host/port. Ensure your OPENAI_API_KEY is set in the environment.

```bash
OPENAI_API_KEY=sk-your-openai-key \
litellm --config litellm-config.yaml --host 127.0.0.1 --port 4000
```

--------------------------------

### Verify Claude-Mem Installation Status

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/gemini-setup.mdx

These bash commands are used to check the status of the Claude-Mem worker and confirm that the Cursor hooks have been successfully installed.

```bash
# Check worker is running
bun run worker:status

# Check hooks are installed
bun run cursor:status
```

--------------------------------

### Manual Release Steps

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/development.mdx

Detailed manual steps for creating a release, including version updates, changelog, commits, tagging, and pushing.

```bash
# Manual version bump:
# 1. Update version in package.json
# 2. Update version in plugin/.claude-plugin/plugin.json
# 3. Update version at top of CLAUDE.md
# 4. Update version badge in README.md
# 5. Run: npm run build && npm run sync-marketplace

# Or use npm version command:
npm version 4.3.2

# Update changelog
# Edit CHANGELOG.md manually

# Commit
git add .
git commit -m "chore: Release v4.3.2"

# Tag
git tag v4.3.2

# Push
git push origin main --tags

# Publish to NPM
npm run release
```

--------------------------------

### Install Redis/Valkey via Docker

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-06-redis-dependency-strategy.md

When Docker is installed and running, this command launches a Redis or Valkey container. A named volume should be used for persistence.

```bash
docker run -d --name valkey -v valkey-data:/data valkey/valkey:<pinned>
```

```bash
docker run -d --name redis -v redis-data:/data redis:<pinned>
```

--------------------------------

### Checkout and Install Endless Mode (Bash)

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/endless-mode.mdx

This bash script guides users through checking out the beta branch for Endless Mode, installing its dependencies, and restarting the worker. It also provides instructions for returning to the stable version.

```bash
# Navigate to your claude-mem installation
cd ~/.claude/plugins/marketplaces/thedotmack/

# Checkout the beta branch
git checkout beta/endless-mode

# Install dependencies
npm install

# Restart the worker
npm run worker:restart

# To return to stable:
cd ~/.claude/plugins/marketplaces/thedotmack/
git checkout main
npm install
npm run worker:restart
```

--------------------------------

### Run Claude-mem Setup Wizard (Bash)

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/index.mdx

Executes the interactive setup wizard for claude-mem, which helps configure AI providers (like Gemini) and automatically installs necessary hooks for Cursor IDE users without a Claude Code subscription.

```bash
bun run cursor:setup
```

--------------------------------

### Install Valkey on Ubuntu/Debian

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-06-redis-dependency-strategy.md

Use the package manager to install Valkey on Ubuntu/Debian systems. The `valkey-redis-compat` package provides compatibility symlinks.

```bash
apt install valkey
```

--------------------------------

### Example buildShellCommand for claude-code-setup

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/02-spawn-contract-templating.md

Generates a shell command for the 'claude-code-setup' host, requiring 'version-check.js' and providing a specific not-found message. This matches a specific line in 'plugin/hooks/hooks.json'.

```typescript
buildShellCommand({ host: 'claude-code-setup', requireFile: 'version-check.js', trailingCommand: ['node', '"$_P/scripts/version-check.js"'], notFoundMessage: 'claude-mem: version-check.js not found' })
```

--------------------------------

### Check Version Markers

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/troubleshooting.mdx

Compare the `.install-version` file with the `package.json` version to ensure dependency caching is accurate. This helps diagnose issues with outdated installations.

```bash
cat ~/.claude/plugins/marketplaces/thedotmack/.install-version
cat ~/.claude/plugins/marketplaces/thedotmack/package.json | grep version
```

--------------------------------

### Build Project

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/troubleshooting.mdx

Run the build script to compile project assets, including potentially the MCP search server. Use when tools are missing or not working.

```bash
npm run build
```

--------------------------------

### MCP Search Workflow: Initial Search

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/troubleshooting.mdx

Start the MCP search process by performing an initial search to get an index of relevant items. This is the first step in the recommended 3-layer workflow.

```bash
# Start with search to get index
search(query="...", limit=10)
```

--------------------------------

### Run Server-Beta Service Tests

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-07-finish-bullmq-branch-ship-plan.md

Execute the test suite for the server-beta service using Bun. This ensures the core functionality of the server-beta runtime is working correctly.

```bash
bun test tests/server/server-beta-service.test.ts
```

--------------------------------

### Baking Absolute Paths (TypeScript)

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/02-spawn-contract-templating.md

This TypeScript example demonstrates baking absolute paths directly into the code, without relying on environment variables or dynamic resolution. This is used for specific installer types.

```typescript
const mcpServerPath = `${MARKETPLACE_ROOT}/path/to/server`;
const workerServicePath = `${MARKETPLACE_ROOT}/path/to/worker`;
```

--------------------------------

### Reset Stuck Messages (sqlite3)

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/usage/manual-recovery.mdx

Resets messages that are stuck in the 'processing' state back to 'pending'. This involves clearing the processing start time and resetting the status.

```bash
sqlite3 ~/.claude-mem/claude-mem.db "
  UPDATE pending_messages
  SET status = 'pending', started_processing_at_epoch = NULL
  WHERE status = 'processing';
"
```

--------------------------------

### Check Claude-Mem Settings File Content

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/openrouter-setup.mdx

Displays the content of the `settings.json` file for Claude-Mem, which is useful for troubleshooting configuration issues, particularly related to the OpenRouter API key.

```bash
cat ~/.claude-mem/settings.json
```

--------------------------------

### Switch Claude-Mem Provider to Gemini

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/openrouter-setup.mdx

Shows how to change the AI provider for Claude-Mem to Gemini by updating the `CLAUDE_MEM_PROVIDER` setting in the configuration. This change takes effect on the next observation without requiring a restart.

```json
{
  "CLAUDE_MEM_PROVIDER": "gemini"
}
```

--------------------------------

### HTTP API Call for Search - TypeScript

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/architecture/search-architecture.mdx

Shows how the MCP server translates a tool call into an HTTP GET request to the Worker Service. This example constructs the URL for a search operation, including query parameters.

```typescript
const url = `http://localhost:37777/api/search?query=authentication%20bug&type=bugfix&limit=10`;
const response = await fetch(url);
```

--------------------------------

### Configure Specific OpenRouter Model in Claude-Mem

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/cursor/openrouter-setup.mdx

Demonstrates how to specify a particular OpenRouter model (e.g., a free Gemini model) within the Claude-Mem settings file. This allows for fine-tuning the AI model used for processing.

```json
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "your-key",
  "CLAUDE_MEM_OPENROUTER_MODEL": "google/gemini-2.0-flash-exp:free"
}
```

--------------------------------

### Build and Sync Project

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/development.mdx

Build the project and sync marketplace extensions before restarting the worker service. This ensures all changes are deployed.

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

```

--------------------------------

### Rewrite SessionStart Welcome Hint Template

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-04-30-onboarding-ux-overhaul.md

This template defines the new welcome hint message for the SessionStart event. It uses third-person narration and clarifies the memory seeding and injection process.

```text
# claude-mem status

This project has no memory yet. The current session will seed it; subsequent sessions will receive auto-injected context for relevant past work.

Memory injection starts on your second session in a project.

`/learn-codebase` is available if the user wants to front-load the entire repo into memory in a single pass (~5 minutes on a typical repo, optional). Otherwise memory builds passively as work happens.

Live activity: {viewer_url}
How it works: `/how-it-works`

This message disappears once the first observation lands.
```

--------------------------------

### GitHub Actions Workflow for README Translation

Source: https://github.com/thedotmack/claude-mem/blob/main/scripts/translate-readme/README.md

A GitHub Actions workflow that automatically translates the README.md file on changes to the main branch. It requires setting the `ANTHROPIC_API_KEY` secret and includes steps for checkout, Node.js setup, installation, translation, and committing/pushing the translated files.

```yaml
name: Translate README
on:
  push:
    branches: [main]
    paths: [README.md]

jobs:
  translate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      
      - run: npm install -g readme-translator
      
      - name: Translate README
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          translate-readme -v -o ./i18n README.md es fr de ja zh
      
      - name: Commit translations
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add i18n/
          git diff --staged --quiet || git commit -m "chore: update README translations"
          git push
```

--------------------------------

### Basic Session Interaction with V1 SDK

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/context/agent-sdk-v2-preview.md

This V1 SDK example shows how a basic prompt is handled using an async generator, which is the pattern that V2 aims to simplify for multi-turn conversations.

```typescript
import { query } from '@anthropic-ai/claude-agent-sdk'

const q = query({
  prompt: 'Hello!',
  options: { model: 'claude-sonnet-4-6-20250929' }
})

for await (const msg of q) {
  if (msg.type === 'assistant') {
    const text = msg.message.content
      .filter(block => block.type === 'text')
      .map(block => block.text)
      .join('')
    console.log(text)
  }
}
```

--------------------------------

### Codex CLI Installer - Install Flow

Source: https://github.com/thedotmack/claude-mem/blob/main/plans/2026-05-06-codex-plugin-version-mismatch.md

The core logic for the Codex CLI installer, handling the process of registering and verifying plugin installations.

```typescript
async function installFlow(pluginName: string, marketplaceName: string) {
  // ... install logic ...
  // Registers marketplace
  // Verifies installability
  // Detects stale caches and provides remediation messages
  // ...
}
```

--------------------------------

### Example Usage of MCP Search Tools

Source: https://github.com/thedotmack/claude-mem/blob/main/README.md

Demonstrates the 3-step workflow for searching memory using Claude-Mem's MCP tools: first searching for an index, then identifying relevant IDs, and finally fetching full details for those IDs.

```typescript
// Step 1: Search for index
search(query="authentication bug", type="bugfix", limit=10)

// Step 2: Review index, identify relevant IDs (e.g., #123, #456)

// Step 3: Fetch full details
get_observations(ids=[123, 456])
```