feat: add Cowork compatibility, /mode command, and make-mode skill by thedotmack · Pull Request #1309 · thedotmack/claude-mem

thedotmack · 2026-03-09T05:21:24Z

Summary

Lazy session init: Observation endpoint auto-initializes sessions in Cowork environments where UserPromptSubmit hook doesn't fire, unblocking the entire AI processing pipeline
Python version fallback: ChromaMcpManager probes Python 3.13→3.10 instead of hanging 30s on unavailable versions
/mode command: List and switch modes dynamically via /mode and /mode <name>
Cowork mode: 6 observation types (creation, research, transformation, decision, discovery, automation) and 7 concepts optimized for knowledge work
make-mode skill: Guided workflow for creating custom modes for any domain

Test plan

Start a Cowork session → perform tool uses → verify ai.lastInteraction is no longer null via curl localhost:37777/api/health
Verify Chroma doesn't timeout on systems without Python 3.13
/mode lists all modes including cowork
/mode cowork switches and updates settings
/mode code switches back without regressions
/make-mode walks through mode creation and produces valid JSON
All existing code--* language variants still load correctly

🤖 Generated with Claude Code

…mode skill - Add lazy session initialization in observation endpoint for Cowork environments where UserPromptSubmit hook doesn't fire - Add Python version auto-detection in ChromaMcpManager (probes 3.13→3.10) - Add matcher "*" to UserPromptSubmit hook for defense-in-depth - Add /mode slash command to list and switch modes via settings API - Add cowork.json mode with 6 knowledge-work observation types and 7 concepts - Add cowork--chill.json behavioral variant for selective recording - Add make-mode skill for guided custom mode creation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

claude · 2026-03-09T05:26:47Z

PR Review: feat/cowork-modes - see full review below

claude · 2026-03-09T05:28:22Z

Claude-Mem: AI Development Instructions

Claude-mem is a Claude Code plugin providing persistent memory across sessions. It captures tool usage, compresses observations using the Claude Agent SDK, and injects relevant context into future sessions.

Architecture

5 Lifecycle Hooks: SessionStart → UserPromptSubmit → PostToolUse → Summary → SessionEnd

Hooks (src/hooks/*.ts) - TypeScript → ESM, built to plugin/scripts/*-hook.js

Worker Service (src/services/worker-service.ts) - Express API on port 37777, Bun-managed, handles AI processing asynchronously

Database (src/services/sqlite/) - SQLite3 at ~/.claude-mem/claude-mem.db

Search Skill (plugin/skills/mem-search/SKILL.md) - HTTP API for searching past work, auto-invoked when users ask about history

Planning Skill (plugin/skills/make-plan/SKILL.md) - Orchestrator instructions for creating phased implementation plans with documentation discovery

Execution Skill (plugin/skills/do/SKILL.md) - Orchestrator instructions for executing phased plans using subagents

Chroma (src/services/sync/ChromaSync.ts) - Vector embeddings for semantic search

Viewer UI (src/ui/viewer/) - React interface at http://localhost:37777, built to plugin/ui/viewer.html

Privacy Tags

<private>content</private> - User-level privacy control (manual, prevents storage)

Implementation: Tag stripping happens at hook layer (edge processing) before data reaches worker/database. See src/utils/tag-stripping.ts for shared utilities.

Build Commands

npm run build-and-sync        # Build, sync to marketplace, restart worker

Configuration

Settings are managed in ~/.claude-mem/settings.json. The file is auto-created with defaults on first run.

File Locations

Source: <project-root>/src/
Built Plugin: <project-root>/plugin/
Installed Plugin: ~/.claude/plugins/marketplaces/thedotmack/
Database: ~/.claude-mem/claude-mem.db
Chroma: ~/.claude-mem/chroma/

Exit Code Strategy

Claude-mem hooks use specific exit codes per Claude Code's hook contract:

Exit 0: Success or graceful shutdown (Windows Terminal closes tabs)
Exit 1: Non-blocking error (stderr shown to user, continues)
Exit 2: Blocking error (stderr fed to Claude for processing)

Philosophy: Worker/hook errors exit with code 0 to prevent Windows Terminal tab accumulation. The wrapper/plugin layer handles restart logic. ERROR-level logging is maintained for diagnostics.

See private/context/claude-code/exit-codes.md for full hook behavior matrix.

Requirements

Bun (all platforms - auto-installed if missing)
uv (all platforms - auto-installed if missing, provides Python for Chroma)
Node.js

Documentation

Public Docs: https://docs.claude-mem.ai (Mintlify)
Source: docs/public/ - MDX files, edit docs.json for navigation
Deploy: Auto-deploys from GitHub on push to main

Pro Features Architecture

Claude-mem is designed with a clean separation between open-source core functionality and optional Pro features.

Open-Source Core (this repository):

All worker API endpoints on localhost:37777 remain fully open and accessible
Pro features are headless - no proprietary UI elements in this codebase
Pro integration points are minimal: settings for license keys, tunnel provisioning logic
The architecture ensures Pro features extend rather than replace core functionality

Pro Features (coming soon, external):

Enhanced UI (Memory Stream) connects to the same localhost:37777 endpoints as the open viewer
Additional features like advanced filtering, timeline scrubbing, and search tools
Access gated by license validation, not by modifying core endpoints
Users without Pro licenses continue using the full open-source viewer UI without limitation

This architecture preserves the open-source nature of the project while enabling sustainable development through optional paid features.

Important

No need to edit the changelog ever, it's generated automatically.

claude · 2026-03-09T05:29:22Z

#!/usr/bin/env node

/**

Generate CHANGELOG.md from GitHub releases
Fetches all releases from GitHub and formats them into Keep a Changelog format.
*/

import { execSync } from 'child_process';
import { writeFileSync } from 'fs';

function getReleases() {
console.log('📋 Fetching releases from GitHub...');
const releasesJson = exec('gh release list --limit 1000 --json tagName,publishedAt,name');
const releases = JSON.parse(releasesJson);

// Fetch body for each release
console.log(📥 Fetching details for ${releases.length} releases...);
for (const release of releases) {
const body = exec(gh release view ${release.tagName} --json body --jq '.body').trim();
release.body = body;
}

return releases;
}

function formatDate(isoDate) {
const date = new Date(isoDate);
return date.toISOString().split('T')[0]; // YYYY-MM-DD
}

function cleanReleaseBody(body) {
// Remove the "Generated with Claude Code" footer
return body
.replace(/🤖 Generated with [Claude Code].$/s, '')
.replace(/---\n$/s, '')
.trim();
}

function extractVersion(tagName) {
// Remove 'v' prefix from tag name
return tagName.replace(/^v/, '');
}

function generateChangelog(releases) {
console.log(📝 Generating CHANGELOG.md from ${releases.length} releases...);

const lines = [
'# Changelog',
'',
'All notable changes to this project will be documented in this file.',
'',
'The format is based on Keep a Changelog.',
'',
];

// Sort releases by date (newest first)
releases.sort((a, b) => new Date(b.publishedAt) - new Date(a.publishedAt));

for (const release of releases) {
const version = extractVersion(release.tagName);
const date = formatDate(release.publishedAt);
const body = cleanReleaseBody(release.body);

// Add version header
lines.push(`## [${version}] - ${date}`);
lines.push('');

// Add release body
if (body) {
  // Remove the initial markdown heading if it exists (e.g., "## v5.5.0 (2025-11-11)")
  const bodyWithoutHeader = body.replace(/^##?\s+v?[\d.]+.*?\n\n?/m, '');
  lines.push(bodyWithoutHeader);
  lines.push('');
}

}

return lines.join('\n');
}

function main() {
console.log('🔧 Generating CHANGELOG.md from GitHub releases...\n');

const releases = getReleases();

if (releases.length === 0) {
console.log('⚠️ No releases found');
return;
}

const changelog = generateChangelog(releases);

writeFileSync('CHANGELOG.md', changelog, 'utf-8');

console.log('\n✅ CHANGELOG.md generated successfully!');
console.log( ${releases.length} releases processed);
}

main();

- New set-mode skill: full mode activation (settings + project instructions + worker restart) in one command - Updated make-mode skill: added Step 6 for creating mode CLAUDE.md files focused on human-primary agent relationship - Mode CLAUDE.md files are standalone project instructions with no claude-mem internal references - set-mode installs mode instructions via <claude-mem-mode> tags in the project's CLAUDE.md (idempotent on mode switches) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

claude · 2026-03-09T05:35:46Z

REVIEW PART 1/4 - Bugs

Race condition in lazy session init (SessionRoutes.ts): Two concurrent observations arriving milliseconds apart could both pass the getSession check and both call initializeSession, resulting in a duplicate session or overwritten state. Consider using a Set of in-flight session IDs as a lightweight lock, or check-and-init inside the session manager atomically.
createSDKSession called unconditionally: createSDKSession is called on every observation request regardless of whether the session already exists. If not idempotent (inserts a new DB row each call), phantom DB records will accumulate. Confirm this is safe or gate the DB call behind the session check.
Synthetic prompt saved to the DB: The string [auto-initialized from observation] is stored via saveUserPrompt and will appear in memory search results and session history. Consider skipping saveUserPrompt for auto-init sessions, or using a flag so search/UI can filter it out.

claude · 2026-03-09T05:35:58Z

REVIEW PART 2/4 - Performance and Security

Performance:

Blocking execSync loop in detectPythonVersion() (ChromaMcpManager.ts): With 4 versions x 5s timeout each, worst-case startup cost is 20 seconds of blocking the event loop. The PR description says it fixes the 30s hang, but 20s is still significant. Consider: (a) reducing per-probe timeout to 1-2s since a python --version call that takes more than a second is almost certainly unavailable, or (b) running probes in parallel with Promise.all + execAsync.
detectPythonVersion() result not cached: If ChromaMcpManager is instantiated more than once, it will re-probe Python each time. Cache at the module level or as a private static field (e.g. private static cachedPythonVersion: string | undefined).

Security:

Path traversal risk in /mode command (plugin/commands/mode.md): The validation step constructs a filesystem path from raw user input: plugin/modes/ARGUMENTS.json. A value like ../../.ssh/id_rsa would traverse the directory. Since this is a command spec for Claude to follow, add an explicit sanitization instruction -- verify the argument contains only alphanumeric characters, hyphens, and underscores before any filesystem or network use.

claude · 2026-03-09T05:36:10Z

REVIEW PART 3/4 - Code Quality and Nits

Code Quality / Minor:

hooks.json matcher change needs clearer documentation: Adding matcher: star to UserPromptSubmit should be explicitly called out. If the hook previously fired without a matcher this is a no-op and should be noted. If not, it is a meaningful behavioral change that warrants its own test step.
/mode command next-session caveat buries the lede: The note that a mode change only takes effect after /clear or a new conversation is critical UX info. Consider surfacing it more prominently in the confirmation message template.
make-mode skill requires 33 prompt fields -- fragile: If even one field is omitted, the generated mode JSON will be invalid. This is a high bar for AI-generated output. Consider providing a JSON schema or template that modes inherit from, with only domain-specific fields requiring generation.

Nits:

cowork--chill.json intentionally omits observation_types/observation_concepts (delegating to parent), but this pattern is not documented in the make-mode skill. Worth adding a note that behavioral variants can omit these fields.
getProjectName(cwd) is newly imported -- confirm it handles undefined/empty cwd gracefully for environments where cwd is not passed in the observation payload.

claude · 2026-03-09T05:36:18Z

REVIEW PART 4/4 - Overall Summary

The feature set is solid and the Cowork mode design is thoughtful. The lazy session init is the most impactful fix and the core logic is clear.

Main asks before merge:

Address the race condition in lazy session init (SessionRoutes.ts)
Confirm createSDKSession idempotency before the lazy-init guard
Reduce the Python probe timeout in detectPythonVersion() -- 20s worst-case is still too long
Add input sanitization note to the /mode command to prevent path traversal

Lower priority:

Cache detectPythonVersion() result
Filter synthetic [auto-initialized from observation] prompts from search/history
Document the behavioral variant (--chill) pattern in make-mode skill
Clarify that hooks.json matcher change is intentional/no-op

claude · 2026-03-09T05:41:16Z

test

claude · 2026-03-09T05:41:34Z