04 — 安装流程与多平台集成

1
2
3
4
5

// index.ts:10-14
const command =
  firstArg.startsWith('-') && !HELP_OR_VERSION_FLAGS.has(firstArg)
    ? 'install'       // 裸标志（如 --provider claude）直接触发 install
    : firstArg;       // 否则取第一个参数作为子命令

1
2
3
4
5

// install.ts:971-972
const alreadyInstalled = existsSync(
  join(marketplaceDir, 'plugin', '.claude-plugin', 'plugin.json')
);
// 同时读取现有版本号，区分 "重装" 还是 "升级" 提示

1
2
3
4
5
6
7
8
9

// install.ts:521-553: copyPluginToMarketplace
// 白名单复制，只拷贝必要目录
const allowedTopLevelEntries = [
  'plugin', 'package.json', 'dist', '.agents', '.mcp.json', 'README.md', ...
];

// install.ts:556-563: copyPluginToCache
// 只复制 plugin/ 目录到 cache/<version>/
cpSync(sourcePluginDirectory, cachePath, { recursive: true });

1
2
3

plugin/hooks/hooks.json  （仓库里的源文件）
    ↓ cpSync
~/.claude/plugins/marketplaces/thedotmack/plugin/hooks/hooks.json

1
2
3
4
5
6
7
8

export function disableClaudeAutoMemory(): boolean {
  const settings = readJsonSafe(claudeSettingsPath(), {});
  if (env.CLAUDE_CODE_DISABLE_AUTO_MEMORY === '1') return false; // 幂等

  settings.env = { ...env, CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1' };
  writeJsonFileAtomic(claudeSettingsPath(), settings);
  return true;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

export function detectInstalledIDEs(): IDEInfo[] {
  return [
    // 命令行工具：which/where 探测
    { id: 'claude-code', detected: isCommandInPath('claude'), ... },
    { id: 'copilot-cli', detected: isCommandInPath('copilot'), ... },
    // 桌面 IDE：检查配置目录
    { id: 'cursor',     detected: existsSync(join(home, '.cursor')), ... },
    { id: 'windsurf',   detected: existsSync(join(home, '.codeium', 'windsurf')), ... },
    // VS Code 扩展：扫描 extensions 目录
    { id: 'roo-code',   detected: hasVscodeExtension('roo-code'), ... },
    // 共 12 种 IDE
  ];
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

const makeHookCommand = (command: string) =>
  `"${escapedBunPath}" "${escapedWorkerPath}" hook cursor ${command}`;
//  ↑ 绝对路径               ↑ 同一个 worker-service.cjs     ↑ IDE 标识

const hooksJson: CursorHooksJson = {
  version: 1,
  hooks: {
    beforeSubmitPrompt: [
      { command: makeHookCommand('session-init') },  // 初始化 session
      { command: makeHookCommand('context') }         // 注入历史记忆
    ],
    afterMCPExecution:  [{ command: makeHookCommand('observation') }],
    afterShellExecution:[{ command: makeHookCommand('observation') }],
    afterFileEdit:      [{ command: makeHookCommand('file-edit') }],
    stop:               [{ command: makeHookCommand('summarize') }]
  }
};
// 写入 ~/.cursor/hooks.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

安装时：生成占位文件 .cursor/rules/claude-mem-context.mdc
         ↓ alwaysApply: true → Cursor 每次 chat 自动携带

每次 session 结束后：
  stop hook → summarize → Worker 压缩本次观测
  → Worker 调用 /api/context/inject
  → writeContextFile(workspacePath, context)
  → 更新 .cursor/rules/claude-mem-context.mdc

下次 session 开始时：
  Cursor 自动读取 rules/ 目录 → 携带最新记忆

1
2
3
4
5
6
7

// MDC 文件头（metadata）
const placeholder = `---
alwaysApply: true
description: "Claude-mem context from past sessions (auto-updated)"
---
# Memory Context from Past Sessions
*No context yet. Complete your first session...*`;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 三级安装 scope
type CursorInstallTarget = 'project' | 'user' | 'enterprise';
// project    → .cursor/              （只影响当前工程）
// user       → ~/.cursor/            （默认，影响所有项目）
// enterprise → /Library/.../Cursor   （macOS 企业级，需要 sudo）

// 额外配置 MCP server（~/.cursor/mcp.json）
config.mcpServers['claude-mem'] = {
  command: 'node',
  args: [mcpServerPath]   // plugin/scripts/mcp-server.cjs
};

1
2

CLAUDE_MEM_DATA_DIR    — 数据根目录（默认 ~/.claude-mem）
CLAUDE_MEM_WORKER_PORT — Worker HTTP 端口（默认 37700 + uid%100）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

// paths.ts:18-40 — resolveDataDir() 三层优先级
export function resolveDataDir(): string {
  // 1. 环境变量（最高优先级）
  if (process.env.CLAUDE_MEM_DATA_DIR) return process.env.CLAUDE_MEM_DATA_DIR;

  // 2. 默认路径下的 settings.json（持久化配置）
  const settingsPath = join(homedir(), '.claude-mem', 'settings.json');
  try {
    if (existsSync(settingsPath)) {
      const raw = JSON.parse(readFileSync(settingsPath, 'utf-8'));
      const settings = raw.env ?? raw;
      if (settings.CLAUDE_MEM_DATA_DIR) return settings.CLAUDE_MEM_DATA_DIR;
    }
  } catch { /* 文件缺失或损坏，回退默认值 */ }

  // 3. 硬编码默认值
  return join(homedir(), '.claude-mem');
}

export const DATA_DIR = resolveDataDir();  // 模块级常量，加载时固定

// 所有子路径全部从 DATA_DIR 派生：
export const DB_PATH = join(DATA_DIR, 'claude-mem.db');
export const LOGS_DIR = join(DATA_DIR, 'logs');
export const paths = {
  workerPid:         () => join(DATA_DIR, 'worker.pid'),
  settings:          () => join(DATA_DIR, 'settings.json'),
  database:          () => join(DATA_DIR, 'claude-mem.db'),
  chroma:            () => join(DATA_DIR, 'chroma'),
  transcriptsConfig: () => join(DATA_DIR, 'transcript-watch.json'),
  envFile:           () => join(DATA_DIR, '.env'),
  // ... 共 15 个路径
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

$CLAUDE_MEM_DATA_DIR  (默认 ~/.claude-mem)
├── claude-mem.db          # SQLite 数据库
├── settings.json          # 用户配置
├── .env                   # 敏感 env（ANTHROPIC_API_KEY 等）
├── worker.pid             # Worker 进程 PID
├── chroma/                # 向量数据库（Chroma）
├── logs/                  # 日志文件
├── archives/              # 归档数据
├── corpora/               # 知识语料库
├── modes/                 # 运行模式配置
├── transcript-watch.json  # Transcript 监视配置
├── supervisor.json        # Supervisor 注册表
└── cursor-projects.json   # Cursor 项目注册表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 工作账号 profile
export CLAUDE_MEM_DATA_DIR="$HOME/.claude-mem-work"
export CLAUDE_MEM_WORKER_PORT=37801
npx claude-mem start

# 个人 profile（另一个终端）
export CLAUDE_MEM_DATA_DIR="$HOME/.claude-mem-personal"
export CLAUDE_MEM_WORKER_PORT=37802
npx claude-mem start
# 两个 Worker 完全隔离，各自有独立的 DB、Chroma、日志

1
2

CLAUDE_MEM_WORKER_PORT: String(37700 + ((process.getuid?.() ?? 77) % 100)),
//                                       ↑ Windows 无 getuid，fallback 到 77 → 端口 37777

1
2
3
4
5
6

function resolveWorkerPort(): string {
  const fromEnv = process.env.CLAUDE_MEM_WORKER_PORT;
  if (Number.isInteger(parsed) && parsed >= 1 && parsed <= 65535) return String(parsed);
  const uid = typeof process.getuid === 'function' ? process.getuid() : 77;
  return String(37700 + (uid % 100));  // 完全相同的逻辑
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// version-check.js:53-69
const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
const markerPath = join(ROOT, '.install-version');

if (!existsSync(markerPath)) {
  emitUpgradeHint('claude-mem: runtime not yet set up - run: npx claude-mem@latest install');
  process.exit(0);  // ← 永远 exit 0，从不阻塞 session
}
const markerVersion = readInstallMarkerVersion(markerPath);
if (markerVersion !== pkg.version) {
  emitUpgradeHint(`claude-mem: upgraded to v${pkg.version} - run: npx claude-mem@latest install`);
}
process.exit(0);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// 安装完成后写入（setup-runtime.ts:262-274）
export function writeInstallMarker(targetDir, version, bunVersion, uvVersion) {
  const payload: MarkerSchema = {
    version,       // "13.1.0"
    bun: bunVersion, // "1.1.42"  ← 关键：记录安装时的 Bun 版本
    uv: uvVersion,
    installedAt: new Date().toISOString(),
  };
  writeFileSync(join(targetDir, '.install-version'), JSON.stringify(payload));
}

// 判断是否需要重新安装（setup-runtime.ts:277-287）
export function isInstallCurrent(targetDir: string, expectedVersion: string): boolean {
  if (!existsSync(join(targetDir, 'node_modules'))) return false;  // node_modules 被删了
  const marker = readInstallMarker(targetDir);
  if (!marker) return false;
  if (marker.version !== expectedVersion) return false;            // 版本变了

  // 关键检查：Bun 版本变了也要重装
  const currentBun = getBunVersion();
  if (currentBun && marker.bun && currentBun !== marker.bun) return false;
  return true;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 简化版本，原版更复杂（处理 Cygwin/WSL 路径转换）
_C="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
_P=$({
  # 优先查 cache 目录（按时间倒序，取最新版本）
  ls -dt "$_C/plugins/cache/thedotmack/claude-mem"/[0-9]*/ 2>/dev/null
  # 降级到 marketplace 目录
  printf '%s\n' "$_C/plugins/marketplaces/thedotmack/plugin"
} | while IFS= read -r _R; do
  _R="${_R%/}"
  [ -d "$_R/plugin/scripts" ] && _Q="$_R/plugin" || _Q="$_R"
  [ -f "$_Q/scripts/bun-runner.js" ] && { printf '%s\n' "$_Q"; break; }
done)
node "$_P/scripts/bun-runner.js" "$_P/scripts/worker-service.cjs" hook claude-code observation

1
2
3
4
5
6
7

// 实际读取：env var > settings.json > 代码默认值
static get(key: keyof SettingsDefaults): string {
  return process.env[key] ?? this.DEFAULTS[key];
}

// loadFromFile() 在文件加载后再调用 applyEnvOverrides()
// 确保 env var 始终覆盖文件配置

1
2
3

1. process.env[KEY]                  # Shell 级，每次进程生效
2. ~/.claude-mem/settings.json       # 用户持久配置（UI 可写）
3. SettingsDefaultsManager.DEFAULTS  # 代码硬编码默认值