Claude-Mem

https://github.com/thedotmack/claude-mem
Admin
Claude-Mem is a persistent memory compression system for Claude Code that automatically captures...
Tokens:393,511
Snippets:3,186
Trust Score:7.8
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install with Provider and API Key

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

Pre-selects the AI provider and API key to skip interactive prompts during installation.

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

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

### Clone and Build

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

Clone the repository, install dependencies, and build all components.

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

# Install dependencies
npm install

# Build all components
npm run build
```

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

### Clone and Build from Source

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

For development or testing, clone the repository, install dependencies, build hooks and worker service, and optionally start the worker manually. The worker service auto-starts on the first Claude Code session.

```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
```

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

### Upgrade Existing Installation

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

Upgrades an existing installation while preserving settings and updating the plugin.

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

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

### Start worker from cloned repo

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

Starts the worker from the cloned repository when no Claude Code installation exists.

```bash
cd /opt/claude-mem  # wherever you cloned it
npm run worker:start
```

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

### Install bun

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

Installs bun via the official script. Required for the worker service.

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

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

### Install claude-mem for Antigravity CLI

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

Installs the plugin for Antigravity CLI. See the setup guide for more details.

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

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

### Start worker with custom port

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

Set a custom port and start the worker.

```bash
export CLAUDE_MEM_WORKER_PORT=38000
npm run worker:start
```

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

### Verify Plugin Installation

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

List the contents of the marketplace directory to verify the plugin was installed correctly.

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

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

### Clone and build claude-mem repository

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

Clones the claude-mem repository, installs dependencies, and builds the project. Requires bun for the worker service.

```bash
cd /opt  # or wherever you want to keep it
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
npm install
npm run build
```

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

### Check bun installation and port 37777

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

Verify bun is installed and check if port 37777 is occupied. Run the worker directly with `bun plugin/scripts/worker-service.cjs start`.

```bash
bun --version
```

```bash
lsof -i :37777
```

```bash
bun plugin/scripts/worker-service.cjs start
```

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

### Install claude-mem for Kimi Code

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

Installs the claude-mem adapter for Kimi Code using the kimi install command.

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

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

### Install native Pi extension and DeepSeek Harness plugin

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

Installs the native Pi extension and the DeepSeek Harness plugin. Both use the worker runtime. See the native harness setup documentation for capture, recall, and troubleshooting.

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

```bash
npx claude-mem install --ide dsh --dsh-profile tui
```

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

### Non-Interactive Install

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

Fully unattended installation. Defaults to Claude Max Plan and skips the observation feed configuration.

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

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

### Interactive example output

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

Example output from the interactive CLI tool showing queue summary and prompt.

```text
Worker is healthy ✓

Queue Summary:
  Pending: 12 messages
  Processing: 2 messages (1 stuck)
  Failed: 0 messages
  Recently Processed: 5 messages in last 30 minutes

Sessions with pending work: 3
  Session 44: 5 pending, 1 processing (age: 2m)
  Session 45: 4 pending, 1 processing (age: 7m - STUCK)
  Session 46: 2 pending

Would you like to process these pending queues? (y/n)
```

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

### Install notebooklm-py with Playwright and Chromium

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

One-time setup per machine. Required if `notebooklm auth check` does not return 0 or `command -v jq` does not resolve. Installs the CLI with Playwright and the Chromium browser. `jq` is also required for JSON parsing; install it separately if missing.

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

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

### Verify Bun installation

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

Check if Bun is installed and its version.

```bash
which bun
bun --version
```

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

### Install claude-mem Plugin

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

Install the claude-mem plugin after adding the marketplace. This is the second step in the installation process.

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

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

### Add Marketplace for Plugin Installation

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

Add the thedotmack/claude-mem marketplace before installing the plugin. This is required for /plugin install claude-mem to work.

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

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

### Check version marker

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

Display the install version marker and the package version to verify the installed version.

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

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

### Install and run the My Work wireframe

Source: https://github.com/thedotmack/claude-mem/blob/main/src/ui/my-work/README.md

Commands to install dependencies, start the dev server on localhost:5173, and run coverage checks that verify every UI requirement is on screen and write COVERAGE.md.

```bash
npm install
npm run dev        # http://localhost:5173
npm run coverage   # checks every UI requirement is on screen, writes COVERAGE.md
```

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

### New card component example

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

Example of creating a new card component in `src/ui/viewer/components/cards/YourCard.tsx` with a React functional component.

```tsx
import React from 'react';

export interface YourCardProps {
  // Your data structure
}

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

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

### Launch Antigravity CLI

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

Starts the Antigravity CLI normally. Claude-mem works in the background and injects context with recent observations and project history at session start.

```bash
agy
```

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

### Verify Bun version

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

Check the installed Bun version.

```bash
bun --version
```

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

### Manually install dependencies

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

Run these commands to manually install dependencies for the claude-mem plugin. This is a solution when the SessionStart hook fails with 'module not found' errors.

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

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

### Install claude-mem with default options

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

Runs the installer with default settings. It sets everything up first, then prompts you to sign in via browser (email magic link, no card required). Signing in provisions a memory key and unlocks the claude-mem observer with a 30-day free trial. After the trial, memory falls back to your Anthropic plan unless you subscribe.

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

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

### Build, run, inspect: quick start with claude-mem container

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

Quick start for building and running the claude-mem container, then launching Claude with the pre-staged pluginwildcard and inspecting the persistent SQLite DB on the host.

```bash
# From the repo root:
docker/claude-mem/build.sh
docker/claude-mem/run.sh
```

```bash
claude --plugin-dir /opt/claude-mem
```

```bash
sqlite3 .docker-claude-mem-data/claude-mem.db 'select count(*) from observations'
```

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

### Restart worker from Claude Code plugin

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

Starts the worker from an existing Claude Code plugin installation. Run from the plugin directory.

```bash
cd ~/.claude/plugins/marketplaces/thedotmack
npm run worker:restart
```

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

### Pre-select installation options with CLI flags

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

Use these commands to pre-select installation options. The --provider and --api-key flags specify an AI provider, --non-interactive runs fully unattended (defaults to Claude Max Plan), and --upgrade upgrades an existing installation.

```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
```

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

### OpenCode Zen Configuration Example

Source: https://github.com/thedotmack/claude-mem/blob/main/docs/public/usage/openai-compatible-provider.mdx

Example environment configuration for using the OpenCode Zen preset with the OpenAI-compatible provider. Sets the provider, preset, API key, and model. The model must be served on /chat/completions.

```json
{
  "CLAUDE_MEM_PROVIDER": "openai-compatible",
  "CLAUDE_MEM_OPENAI_COMPAT_PRESET": "opencode-zen",
  "CLAUDE_MEM_OPENAI_COMPAT_API_KEY": "<your OpenCode key>",
  "CLAUDE_MEM_OPENAI_COMPAT_MODEL": "deepseek-v4-flash"
}
```

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

### Install for Cursor separately with --ide

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

Run a second install for Cursor because --ide accepts a single string; do not stack --ide flags on one command. Cursor uses hooks and platformSource=cursor, while Grok Bot has no hooks.

```bash
npx claude-mem install --ide grok-bot
npx claude-mem install --ide cursor
```

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

### Start LiteLLM with config

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

Starts the LiteLLM proxy with the specified config, binding to 127.0.0.1 on port 4000. Requires the OPENAI_API_KEY environment variable.

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

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

### Test Context Retrieval

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

Run the npm script to test context retrieval.

```bash
npm run test:context
```

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

### Build and sync commands

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

Run these commands to build the project, sync the marketplace, and restart the worker before testing new features.

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

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

### GET /v1/usage response example

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

Response body returned by GET /v1/usage, showing the caller team's per-kind totals for the current month. The since field marks the start of the month in UTC.

```json
{ "since": "2026-06-01T00:00:00.000Z", "usage": { "request": 1280, "observation": 44 } }
```

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

### POST /v1/sessions/start

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

Start a new session.

```APIDOC
## POST /v1/sessions/start

### Description
Start a new session.

### Method
POST

### Endpoint
/v1/sessions/start

```

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

### Import command example output

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

Shows the expected output from the import command, including file details and import statistics.

```text
📦 Import file: windows-memories.json
📅 Exported: 2025-12-10T23:45:00.000Z
🔍 Query: "windows"
📊 Contains:
   • 54 observations
   • 12 sessions
   • 12 summaries
   • 7 prompts

🔄 Importing sessions...
   ✅ Imported: 12, Skipped: 0
🔄 Importing summaries...
   ✅ Imported: 12, Skipped: 0
🔄 Importing observations...
   ✅ Imported: 54, Skipped: 0
🔄 Importing prompts...
   ✅ Imported: 7, Skipped: 0

✅ Import complete!
📊 Summary:
   Sessions:     12 imported, 0 skipped
   Summaries:    12 imported, 0 skipped
   Observations: 54 imported, 0 skipped
   Prompts:      7 imported, 0 skipped
```

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

### Backup database and run tests for migration

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

Backup the database before testing the migration, then run the test suite.

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

# Run tests
npm test
```

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

### Check worker status from cloned repo

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

Navigate to the cloned repository and check worker status. Ensure dependencies are installed and built first.

```bash
cd /path/to/claude-mem && npm run worker:status
```

```bash
npm install && npm run build
```

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

### Run a backup immediately

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

Triggers an immediate backup snapshot. The first automatic snapshot occurs about five minutes after the worker starts; use this to take one now.

```bash
npx claude-mem backup run
```

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

### Manual testing commands

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

Commands to start the worker manually, check status, view logs, and test hooks with a sample JSON payload.

```bash
# 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
```

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

### Verify claude-mem installation

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

Checks that the worker is running, hooks are installed in `~/.gemini/config/hooks.json`, and MCP registration exists in either `~/.gemini/antigravity/mcp_config.json` or `~/.gemini/config/mcp_config.json`. Look for `claude-mem` entries in the grep output. The worker URL printed on startup opens the memory viewer.

```bash
# Check worker is running
npx claude-mem status

# Check hooks are installed — look for claude-mem entries
cat ~/.gemini/config/hooks.json | grep claude-mem

# Check MCP registration in either candidate config path
cat ~/.gemini/antigravity/mcp_config.json | grep claude-mem
cat ~/.gemini/config/mcp_config.json | grep claude-mem
```

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

### Check worker status from Claude Code install

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

Navigate to the plugin marketplaces directory and check worker status. Restart the worker if needed.

```bash
cd ~/.claude/plugins/marketplaces/thedotmack && npm run worker:status
```

```bash
npm run worker:restart
```

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

### Build viewer UI commands

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

Builds everything including the viewer, which is output to `plugin/ui/viewer.html` as a self-contained HTML file.

```bash
# 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
```

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

### Complete claude-mem plugin config with observation feed

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

Full OpenClaw plugin configuration for claude-mem, including project, syncMemoryFile, workerPort, and the observationFeed (Telegram example).

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

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

### Build and start only Postgres on the new image

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

Build the new Postgres image and start only the postgres service. This is step 2 of the upgrade process.

```bash
docker compose build postgres
```

```bash
docker compose up -d postgres
```

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

### hooks.json - Claude Code hook configuration

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

Defines all runtime hooks for the claude-mem plugin. Every hook uses exec form (command + args, no shell) except Setup, which still uses bash. The Setup hook runs only for claude --init, --init-only, and -p --maintenance, never on plugin install or normal session start. claude-mem is a compiled launcher placed by npx claude-mem install/update; ensure-launcher.cjs self-heals marketplace-only installs.

```json
{
  "hooks": {
    "Setup": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "shell": "bash",
        "command": "… resolve the plugin root …; node \"$_P/scripts/version-check.js\"",
        "timeout": 300
      }]
    }],
    "SessionStart": [{
      "matcher": "startup|resume|clear|compact",
      "hooks": [
        { "type": "command", "command": "claude-mem", "args": ["start"], "timeout": 60, "async": true }
      ]
    }, {
      "matcher": "startup|clear|compact",
      "hooks": [
        { "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "context"], "timeout": 60 }
      ]
    }, {
      "matcher": "startup",
      "hooks": [
        { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs"], "timeout": 180 }
      ]
    }],
    "UserPromptSubmit": [{
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "session-init"], "timeout": 15 }]
    }],
    "PreToolUse": [{
      "matcher": "Read|^Bash$|^Grep$|^Glob$|^memory_search$|^memory$|^mcp__.+__memory_search$",
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "file-context"], "timeout": 15 }]
    }],
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "observation"], "timeout": 120, "async": true }]
    }],
    "PostToolUseFailure": [{
      "matcher": "*",
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "observation"], "timeout": 120, "async": true }]
    }],
    "Stop": [{
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "summarize"], "timeout": 120, "async": true }]
    }],
    "SessionEnd": [{
      "hooks": [{ "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "session-end"], "async": true }]
    }]
  }
}
```

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

### GET /stream

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

Server-Sent Events stream for real-time updates. Emits events for processing status, session start, observation queued, summarize queued, observation created, summary created, and new prompt.

```APIDOC
## [GET] /stream

### Description
Server-Sent Events stream for real-time updates. Emits events for processing status, session start, observation queued, summarize queued, observation created, summary created, and new prompt.

### Method
GET

### Endpoint
/stream

### Response
#### Success Response (200)
- **type** (string) - Event type
- **data** (object) - Event data

#### Event Types
- `processing_status`: { type, isProcessing, queueDepth }
- `session_started`: { type, sessionDbId, project }
- `observation_queued`: { type, sessionDbId }
- `summarize_queued`: { type }
- `observation_created`: { type, observation }
- `summary_created`: { type, summary }
- `new_prompt`: { type, id, claude_session_id, project, prompt_number, prompt_text, created_at_epoch }
```

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

### Build command

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

Runs the build process for the project.

```bash
npm run build
```

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

### Install Dependencies with npm install

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

Install project dependencies to resolve 'Cannot find module' errors.

```bash
npm install
```

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

### Start Claude-Mem Server with Docker Compose

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

Starts the Claude-Mem Server beta with a persistent Valkey sidecar using the root docker-compose.yml, then checks the health endpoint at http://127.0.0.1:37777/healthz.

```sh
docker compose up --build
curl http://127.0.0.1:37777/healthz
```

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

### Open the room with standup.mjs open

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

Opens a new standup room with a goal and prompt that invite conversation. Uses --force to overwrite any existing room and --agent facilitator to set the agent role. The goal and prompt are passed as multi-line strings.

```bash
node "${CLAUDE_SKILL_DIR}/standup.mjs" open --force --agent facilitator \
  --goal "Collapse these branches/PRs into ONE consolidated worktree: what each changed, where they overlap, which becomes the target, and the merge order." \
  --prompt "Facilitated rounds. Round 1: introduce your branch and its state. Then resolve the conflicts the facilitator surfaces, round by round, until the room lands on one concrete plan (target worktree + merge order + conflict resolutions). Read-only: decide, don't merge. Register AGREE when you back the plan."
```

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

### Build, tag, and publish release

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

Build and sync, commit the version bump, tag the release, and push to main and the tag. Requires maintainer npm credentials and 2FA for the npm publish step.

```bash
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
```

```bash
npm publish
npm view claude-mem@NEW_VERSION version
```

```bash
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
```

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

### Clear install cache

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

Remove the install version marker to clear the cache for smart install caching issues.

```bash
rm ~/.claude/plugins/marketplaces/thedotmack/.install-version
```

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

### Start worker manually

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

Attempt to start the worker service manually.

```bash
npm run worker:start
```

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

### Build Scripts

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

Build everything, build only hooks, and the build script definition.

```bash
# Build everything
npm run build

# Build only hooks
npm run build:hooks

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

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

### OpenClaw Gateway lifecycle diagram

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

Shows how the plugin hooks into OpenClaw gateway events and communicates with the Claude-Mem worker via HTTP and SSE.

```text
OpenClaw Gateway
  │
  ├── before_agent_start ───→ Init session
  ├── before_prompt_build ──→ Inject context into system prompt
  ├── after_tool_call ──────→ Record observation
  ├── agent_end ────────────→ Summarize + Complete session
  └── gateway_start ────────→ Reset session tracking + context cache
                    │
                    ▼
         Claude-Mem Worker (localhost:37777)
           ├── POST /api/sessions/init
           ├── POST /api/sessions/observations
           ├── POST /api/sessions/summarize
           ├── POST /api/sessions/complete
           ├── GET  /api/context/inject ──→ System prompt context
           └── GET  /stream ─────────────→ SSE → Messaging channels
```

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

### Join a team with an invitation

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

Run this command to join a team using an invitation link. After running, approve the device and choose which projects to share.

```bash
npx claude-mem teambrain join <invite-link>
```

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

### Check database and run tests

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

Remove the database file and run tests to check for failures.

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

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

### Manual settings.json configuration

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

Creates the settings file with the Gemini provider and API key. After running this, re-run `npx claude-mem install` to set up Cursor hooks and the worker.

```bash
mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
EOF
```

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

### Install chromadb manually

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

Install chromadb in the plugin directory to resolve Chroma/Python dependency issues.

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

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

### Install claude-mem with remote worker and remote observer

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

Shows alternative install options: a remote worker using --runtime server and --server-url, and a remote observer using --provider openrouter.

```bash
# Remote worker
npx claude-mem install --ide grok-bot --runtime server --server-url https://YOUR_HOST

# Remote observer (cmem.ai or any OpenAI-compatible URL)
npx claude-mem install --ide grok-bot --provider openrouter
```

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

### GET /api/projects - Get Projects List

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

Returns a list of project names.

```http
GET /api/projects
```

```json
{
  "projects": ["claude-mem", "other-project", ...]
}
```

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

### Setup Hook Configuration (JSON)

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

Configuration for the Setup hook that runs a version check script. Uses bash shell and executes the version-check.js script with a 300-second timeout.

```json
{
  "hooks": {
    "Setup": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "shell": "bash",
        "command": "node \"$_P/scripts/version-check.js\"",
        "timeout": 300
      }]
    }]
  }
}
```

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

### Manual settings.json for OpenRouter provider

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

Creates ~/.claude-mem/settings.json with the OpenRouter provider and API key. Leave CLAUDE_MEM_OPENROUTER_BASE_URL unset for OpenRouter itself, then re-run npx claude-mem install to set up Cursor hooks and the worker.

```bash
mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
}
EOF
```

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

### Create notebook and add source document

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

Creates a new notebook and adds the source document. The notebook ID is extracted from `.notebook.id`; a wrong key yields an empty string and silent downstream failure. Title should be the H1 of the source doc or its filename stem, optionally with a date.

```bash
NOTEBOOK_ID=$(notebooklm create "<title>" --json | jq -r .notebook.id)
notebooklm source add "<doc-path>" --notebook "$NOTEBOOK_ID" --json
```

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

### Run Pro E2E with Miniflare options

Source: https://github.com/thedotmack/claude-mem/blob/main/services/sync-hub/DEPLOY.md

Example orchestrator command for running Pro-side E2E tests with the real Hub. Requires the Pro repository path and sets loopback URLs and a shared secret. The Pro-side command owns server lifecycle and supplies its relative Hub path to the helper.

```sh
CMEM_PRO_REPO_PATH=../../../../claude-mem-pro \
INTERNAL_PROJECTOR_URL=http://127.0.0.1:3005/api/internal/sync/project \
TOKEN_VERIFY_URL=http://127.0.0.1:3005/api/pro/sync/verify \
CMEM_INTERNAL_PROJECTOR_SECRET=local-e2e-projector-secret-32-chars \
npm run test:pro-sync-e2e --prefix "$CMEM_PRO_REPO_PATH"
```

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

### Example Memory Search Prompts

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

Example questions you can ask Claude Desktop to trigger the auto-activated skill, such as "What did we do last session?" or "How did we implement authentication?"

```plaintext
"What did we do last session?"
"Did we fix this bug before?"
"How did we implement authentication?"
"What decisions did we make about the API?"
"Show me changes to worker-service.ts"
```

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

### GET /api/prompt/:id - Get Prompt by ID

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

Retrieves a single prompt by its ID.

```http
GET /api/prompt/:id
```

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

### GET /api/session/:id - Get Session by ID

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

Retrieves a single session by its ID.

```http
GET /api/session/:id
```

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

### Rebuild and test MCP search tools

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

Build the project and run tests after adding MCP search tools.

```bash
npm run build
npm test
```

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

### GET /api/observation/:id - Get Observation by ID

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

Retrieves a single observation by its ID.

```http
GET /api/observation/:id
```

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

### CLI usage with options

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

Translate with verbose output, custom output directory, and custom filename pattern.

```bash
translate-readme -v -o ./i18n --pattern docs.{lang}.md README.md es fr de ja zh
```

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

### Check npm availability

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

Verify that npm is installed and accessible by running these commands. This helps diagnose dependency installation issues.

```bash
which npm
npm --version
```

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

### Clean node_modules and reinstall

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

First step when build fails: remove node_modules and reinstall dependencies.

```bash
rm -rf node_modules
npm install
```

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

### Install claude-mem for Windsurf

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

Installs the claude-mem adapter for Windsurf using the --ide windsurf flag.

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

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

### Runtime hooks configuration in hooks.json

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

Defines SessionStart and PostToolUse hooks as exec-form commands without a shell key. SessionStart includes startup, resume, clear, and compact matchers, plus a self-heal launcher check. PostToolUse captures observations asynchronously.

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume|clear|compact",
        "hooks": [
          { "type": "command", "command": "claude-mem", "args": ["start"], "timeout": 60, "async": true }
        ]
      },
      {
        "matcher": "startup|clear|compact",
        "hooks": [
          { "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "context"], "timeout": 60 }
        ]
      },
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs"], "timeout": 180 }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "claude-mem", "args": ["hook", "claude-code", "observation"], "timeout": 120, "async": true }
        ]
      }
    ]
  }
}
```

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

### Install claude-mem for Cursor

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

Installs the claude-mem adapter for Cursor using the --ide cursor flag.

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

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

### Export command example output

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

Shows the expected output from the export command, including search results and export statistics.

```text
🔍 Searching for: "windows"
✅ Found 54 observations
✅ Found 12 sessions
✅ Found 12 summaries
✅ Found 7 prompts

📦 Export complete!
📄 Output: windows-memories.json
📊 Stats:
   • 54 observations
   • 12 sessions
   • 12 summaries
   • 7 prompts
```

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

### GET /api/summaries - Get Paginated Summaries

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

Retrieves paginated summaries. Query parameters: offset, limit, project.

```http
GET /api/summaries?offset=0&limit=20&project=my-project
```

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

### GET /api/observations - Get Paginated Observations

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

Retrieves paginated observations. Query parameters: offset, limit, project.

```http
GET /api/observations?offset=0&limit=20&project=my-project
```

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

### Install claude-mem for Codex CLI

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

Installs the claude-mem adapter for Codex CLI using the --ide codex-cli flag.

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

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

### Initialization flow for session IDs

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

Shows the four-step initialization flow: hook creates SDK session, SDKAgent checks for a real memory session ID, first SDK message registers the real ID, and subsequent prompts may use resume. The diagram includes database state transitions and the resume condition.

```text
┌─────────────────────────────────────────────────────────────┐
│ 1. Hook creates session                                     │
│    createSDKSession(contentSessionId, project, prompt)      │
│                                                              │
│    Database state:                                          │
│    ├─ content_session_id: "user-session-123"               │
│    └─ memory_session_id: NULL (not yet captured)           │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. SDKAgent starts, checks hasRealMemorySessionId           │
│    const hasReal = !!memorySessionId                        │
│    → FALSE (it's NULL)                                      │
│    → Resume NOT used (fresh SDK session)                    │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. First SDK message arrives with session_id                │
│    ensureMemorySessionIdRegistered(sessionDbId, "sdk-gen-abc123") │
│                                                              │
│    Database state:                                          │
│    ├─ content_session_id: "user-session-123"               │
│    └─ memory_session_id: "sdk-gen-abc123" (real!)          │
└─────────────────────────────────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Subsequent prompts may use resume                        │
│    const shouldResume =                                      │
│      !!memorySessionId && lastPromptNumber > 1 && !forceInit│
│    → TRUE only for continuation prompts in the same runtime │
│    → Resume parameter: { resume: "sdk-gen-abc123" }         │
└─────────────────────────────────────────────────────────────┘
```

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

### Test SDK prompt changes

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

Run the test suite to verify prompt and parser changes.

```bash
npm test
```

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

### Back up the database with pg_dumpall

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

Run this command while the old stack is still running to create a backup file named claude-mem-backup.sql. A copy of the volume is also acceptable.

```bash
docker compose exec postgres pg_dumpall -U "$POSTGRES_USER" > claude-mem-backup.sql
```

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

### GET /v1/usage response JSON

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

Response from GET /v1/usage returning the caller team's per-kind usage totals for the current month. The example shows request and observation counts.

```json
{ "since": "2026-06-01T00:00:00.000Z", "usage": { "request": 1280, "observation": 44 } }
```

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

### POST /v1/projects

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

Create a new project.

```APIDOC
## POST /v1/projects

### Description
Create a new project.

### Method
POST

### Endpoint
/v1/projects

```

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

### GET /api/prompts - Get Paginated User Prompts

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

Retrieves paginated user prompts. Query parameters: offset, limit, project.

```http
GET /api/prompts?offset=0&limit=20&project=my-project
```

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

### Install local worker with npx claude-mem install --ide cursor

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

Starts the local worker. Hooks already ship with this plugin. MCP `claude-mem-local` talks to it. For remote inference, leave provider as openrouter / cmem.ai (`CLAUDE_MEM_OPENROUTER_BASE_URL=https://cmem.ai/api/inference/v1`). For local host-login, use `--provider host` (loopback shim; never bind the worker port — on macOS the worker is often 37777, so the shim uses 37778).

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

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

### GET /api/projects

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

Retrieves the list of projects.

```APIDOC
## GET /api/projects

### Description
Retrieves the list of projects.

### Method
GET

### Endpoint
/api/projects

### Response
#### Success Response (200)
- **projects** (array of strings) - List of project names

#### Request Example
```http
GET /api/projects
```

#### Response Example
```json
{
  "projects": ["claude-mem", "other-project", ...]
}
```
```

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

### Manual settings.json configuration for context injection

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

Settings are stored in `~/.claude-mem/settings.json`. This JSON example shows all available context injection settings with their values. The Context Settings Modal in the web viewer is the recommended way to configure these settings, as it provides live preview of changes.

```json
{
  "CLAUDE_MEM_CONTEXT_OBSERVATIONS": "100",
  "CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true",
  "CLAUDE_MEM_CONTEXT_SESSION_COUNT": "20",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_TYPES": "bugfix,decision,discovery",
  "CLAUDE_MEM_CONTEXT_OBSERVATION_CONCEPTS": "how-it-works,gotcha",
  "CLAUDE_MEM_CONTEXT_FULL_COUNT": "10",
  "CLAUDE_MEM_CONTEXT_FULL_FIELD": "narrative",
  "CLAUDE_MEM_CONTEXT_SHOW_READ_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_WORK_TOKENS": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_SAVINGS_AMOUNT": "true",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_SUMMARY": "false",
  "CLAUDE_MEM_CONTEXT_SHOW_LAST_MESSAGE": "false"
}
```

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

### GET /

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

Returns the HTML for the React viewer UI.

```APIDOC
## [GET] /

### Description
Returns the HTML for the React viewer UI.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **body** (string) - HTML content
```

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

### Install claude-mem from Claude Code plugin marketplace

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

Adds the claude-mem plugin from the marketplace and installs it. Restart Claude Code after installation; context from previous sessions will automatically appear in new sessions.

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

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

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

### Load launchd plist

Source: https://github.com/thedotmack/claude-mem/blob/main/services/sync-hub/DEPLOY.md

Loads the launchd plist to start the canary service.

```sh
launchctl load ~/Library/LaunchAgents/ai.cmem.sync-canary.plist
```

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

### GET /api/mcp/status

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

Retrieves the MCP server status.

```APIDOC
## [GET] /api/mcp/status

### Description
Retrieves the MCP server status.

### Method
GET

### Endpoint
/api/mcp/status

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether the MCP server is enabled

#### Response Example
```json
{ "enabled": boolean }
```
```

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

### Gateway configuration example: CLAUDE_MEM_PROVIDER stays claude

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

Example configuration showing the required settings for using LiteLLM as a gateway. The provider must remain 'claude' to ensure the worker uses ClaudeProvider, not native Gemini or OpenRouter providers.

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

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

### GET /api/settings

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

Retrieves the current user settings.

```APIDOC
## [GET] /api/settings

### Description
Retrieves the current user settings.

### Method
GET

### Endpoint
/api/settings

### Response
#### Success Response (200)
- **sidebarOpen** (boolean) - Whether the sidebar is open
- **selectedProject** (string | null) - The selected project

#### Response Example
```json
{
  "sidebarOpen": boolean,
  "selectedProject": string | null
}
```
```

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

### GET /api/stats

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

Retrieves database and worker statistics.

```APIDOC
## GET /api/stats

### Description
Retrieves database and worker statistics.

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
- **worker** (object) - Worker statistics
  - **version** (string) - Worker version
  - **uptime** (number) - Uptime in seconds
  - **activeSessions** (number) - Number of active sessions
  - **sseClients** (number) - Number of SSE clients
  - **port** (number) - Port number
- **database** (object) - Database statistics
  - **path** (string) - Path to the database file
  - **size** (number) - Size in bytes
  - **observations** (number) - Number of observations
  - **sessions** (number) - Number of sessions
  - **summaries** (number) - Number of summaries

#### Request Example
```http
GET /api/stats
```

#### Response Example
```json
{
  "worker": {
    "version": "7.0.0",
    "uptime": 12345,
    "activeSessions": 2,
    "sseClients": 1,
    "port": 37742
  },
  "database": {
    "path": "~/.claude-mem/claude-mem.db",
    "size": 1048576,
    "observations": 500,
    "sessions": 50,
    "summaries": 25
  }
}
```
```

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

### Useful Commands for Development

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

Commands to check TypeScript types, lint, format, and clean build artifacts.

```bash
# 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
```

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

### Verify node_modules Exists

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

List the contents of node_modules to confirm dependencies are installed.

```bash
ls -la node_modules/
```

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

### smart_outline Example

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

Returns a complete structural skeleton of a file, including all functions, classes, methods, properties, and imports (~1-2k tokens per file).

```text
smart_outline(file_path="services/worker-service.ts")
```
Tokens:
Raw