Hooks 生命周期：触发时机、数据流向与 Worker 通信

1
2
3
4
5
6
7

Claude Code (宿主进程)
    ↓ stdio 管道（JSON payload）
bun-runner.js  ←→  worker-service.cjs (Bun 守护进程)
    ↓ HTTP 请求
Worker Express API (127.0.0.1:<port>)
    ↓
SQLite + Chroma

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// version-check.js:53-68
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);
}
const markerVersion = readInstallMarkerVersion(markerPath);
if (markerVersion !== pkg.version) {
  emitUpgradeHint(`claude-mem: upgraded to v${pkg.version} - run: npx claude-mem@latest install`);
}

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

// version-check.js:22-33
function emitUpgradeHint(message) {
  if (process.env.CLAUDE_MEM_CODEX_HOOK === '1') {
    // Codex 环境：用 hookSpecificOutput JSON 格式注入上下文
    console.log(JSON.stringify({
      hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: message }
    }));
  } else {
    // Claude Code 环境：直接打 stderr
    console.error(message);
  }
}

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

// bun-runner.js:96-118 — 收集 stdin，最多等 5 秒
async function collectStdin() {
  if (process.stdin.isTTY) { resolve(null); return; }
  const chunks = [];
  process.stdin.on('data', (chunk) => chunks.push(chunk));
  process.stdin.on('end', () => resolve(Buffer.concat(chunks)));
  setTimeout(() => resolve(chunks.length > 0 ? Buffer.concat(chunks) : null), 5000);
}

// bun-runner.js:138-193 — spawn bun 并转发 stdin
const child = spawn(bunPath, args, { stdio: ['pipe', 'inherit', 'inherit'] });
if (stdinData && stdinData.length > 0) {
  child.stdin.write(stdinData);
  child.stdin.end();
} else {
  // Issue #2188: 记录诊断，写 CAPTURE_BROKEN 标记，然后 exit(0)
  appendFileSync(join(logsDir, 'runner-errors.log'), diagnostic);
  writeFileSync(join(dataDir, 'CAPTURE_BROKEN'), diagnostic);
  process.exit(0);  // exit 0 防止 Windows Terminal tab 堆积
}

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

// hook-command.ts:74-116
export async function hookCommand(platform: string, event: string): Promise<number> {
  const adapter = getPlatformAdapter(platform);   // e.g. claudeCodeAdapter
  const handler = getEventHandler(event);         // e.g. observationHandler

  // 1. 读 stdin
  const rawInput = await readJsonFromStdin();
  // 2. 标准化（Claude Code 的 JSON 字段 → NormalizedHookInput）
  const input = adapter.normalizeInput(rawInput);
  input.platform = platform;
  // 3. 执行业务逻辑
  const result = await handler.execute(input);
  // 4. 格式化输出给 Claude Code
  const output = adapter.formatOutput(result);
  console.log(JSON.stringify(output));
  process.exit(result.exitCode ?? HOOK_EXIT_CODES.SUCCESS);
}

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

normalizeInput(raw) {
  return {
    sessionId:      r.session_id,       // Claude 会话 UUID
    cwd:            r.cwd,              // 工作目录（项目识别的关键）
    prompt:         r.prompt,           // UserPromptSubmit 的用户输入
    toolName:       r.tool_name,        // PostToolUse/PreToolUse 的工具名
    toolInput:      r.tool_input,       // 工具输入参数（JSON）
    toolResponse:   r.tool_response,    // 工具返回结果（JSON）
    transcriptPath: r.transcript_path,  // Stop hook 用于读取 JSONL 对话记录
    agentId:        r.agent_id,         // subagent 标识（防重复摘要）
    agentType:      r.agent_type,       // subagent 类型
  };
}

1
2
3
4
5
6

formatOutput(result) {
  if (r.hookSpecificOutput) {
    return { hookSpecificOutput: result.hookSpecificOutput, systemMessage: r.systemMessage };
  }
  return { systemMessage: r.systemMessage };  // 普通输出只带 systemMessage
}

1

node bun-runner.js worker-service.cjs start

1
2
3
4
5

case 'start': {
  const result = await ensureWorkerStarted(port);  // 检查是否已在运行，否则 spawnDaemon
  exitWithStatus(result === 'dead' ? 'error' : 'ready', ...);
  break;
}

1

node bun-runner.js worker-service.cjs hook claude-code context

 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

// context.ts:15-81
export const contextHandler: EventHandler = {
  async execute(input: NormalizedHookInput): Promise<HookResult> {
    const context = getProjectContext(cwd);           // 从 cwd 推断项目名
    const projectsParam = context.allProjects.join(',');
    const apiPath = `/api/context/inject?projects=${encodeURIComponent(projectsParam)}`;

    // GET http://localhost:37700/api/context/inject?projects=xxx
    const contextResult = await executeWithWorkerFallback<string>(apiPath, 'GET');
    if (isWorkerFallback(contextResult)) {
      return emptyResult;  // Worker 不可达时优雅降级，返回空上下文
    }

    // 可选：检测 stale OAuth token 并追加提示（Issue #2215）
    const staleReason = readStaleMarker();
    if (staleReason) {
      additionalContext = `[claude-mem] Claude Desktop OAuth token is stale: ${staleReason}\n...`;
    }

    return {
      hookSpecificOutput: {
        hookEventName: 'SessionStart',
        additionalContext   // 注入到 Claude 的系统上下文
      }
    };
  }
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

GET /api/context/inject?projects=my-project
         │
         ▼ handleContextInject()
1. 判断是否有 observations（若无则返回欢迎提示）
2. 调用 generateContext({ projects, cwd, full: false })
3. 从 SQLite 拉取该项目历史 observations/session summaries
4. 格式化为带时间线的文本
         │
         ▼ res.setHeader('Content-Type', 'text/plain')
         ▼ res.send(contextText)

1
2
3
4
5
6

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "## Recent Activity\n...[历史记忆文本，包含 observation 摘要和 session 摘要]..."
  }
}

 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

// 1. 多 Agent 协议消息检测（<task-notification> 标签）
if (rawPrompt && isInternalProtocolPayload(rawPrompt)) {
  return { continue: true, suppressOutput: true };
}

// 2. 空 prompt 处理（语音/图片输入无文本）
const prompt = (!rawPrompt || !rawPrompt.trim()) ? '[media prompt]' : rawPrompt;

// 3. 调用 Worker
const initResult = await executeWithWorkerFallback<SessionInitResponse>(
  '/api/sessions/init', 'POST',
  { contentSessionId: sessionId, project, prompt, platformSource },
);

// 4. 可选语义检索注入（实验性功能）
const semanticInject = String(settings.CLAUDE_MEM_SEMANTIC_INJECT).toLowerCase() === 'true';
if (semanticInject && prompt.length >= 20 && prompt !== '[media prompt]') {
  const semanticResult = await executeWithWorkerFallback<SemanticContextResponse>(
    '/api/context/semantic', 'POST',
    { q: prompt, project, limit: settings.CLAUDE_MEM_SEMANTIC_INJECT_LIMIT || '5' },
  );
  if (!isWorkerFallback(semanticResult) && semanticResult?.context) {
    additionalContext = semanticResult.context;  // 相关历史 observations 文本
  }
}

1
2
3
4
5
6

const cleanedPrompt = stripMemoryTagsFromPrompt(prompt);
if (!cleanedPrompt || cleanedPrompt.trim() === '') {
  res.json({ sessionDbId, promptNumber, skipped: true, reason: 'private' });
  return;  // 整个 prompt 都是私有的，不保存
}
store.saveUserPrompt(contentSessionId, promptNumber, cleanedPrompt);

1
2
3
4

const FILE_READ_GATE_MIN_BYTES = 1_500;   // < 1.5KB 的文件不注入（太小没历史价值）
const FETCH_LOOKAHEAD_LIMIT = 40;          // 向 Worker 最多拉取 40 条原始记录
const DISPLAY_LIMIT = 15;                  // 去重+评分后最多展示 15 条
const MAX_FILE_CONTEXT_PATHS = 10;         // 批量 Read 时最多处理 10 个路径

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// file-context.ts:229-239
if (fileMtimeMs > 0) {
  const newestObservationMs = Math.max(...data.observations.map(o => o.created_at_epoch));
  if (fileMtimeMs >= newestObservationMs) {
    logger.debug('HOOK', 'File modified since last observation, skipping context injection', {
      filePath: relativePath, fileMtimeMs, newestObservationMs,
    });
    return null;  // 文件比最新 observation 还新 → 历史可能失效 → 跳过
  }
}

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

// Step 1: 每个 session 只保留一条（按时间最早的）
const seenSessions = new Set<string>();
const dedupedBySession = observations.filter(obs => {
  const key = obs.memory_session_id;
  if (!seenSessions.has(key)) { seenSessions.add(key); return true; }
  return false;
});

// Step 2: 按相关性评分排序
const scored = dedupedBySession.map(obs => {
  const inModified = filesModified.includes(targetPath);  // 修改过比仅读过更重要
  let score = 0;
  if (inModified) score += 2;
  if (totalFiles <= 3) score += 2;   // 只涉及少数文件的 obs 更精准
  else if (totalFiles <= 8) score += 1;
  return { obs, score };
});
scored.sort((a, b) => b.score - a.score);
return scored.slice(0, DISPLAY_LIMIT).map(s => s.obs);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

Current: 2026-05-08 10:30am PDT
This file has prior observations — supplementary context follows.
- **Need details?** get_observations([IDs])
- **Need structural map?** smart_outline("src/foo.ts")

### May 7, 2026
42 10:30a ⚖️ Refactored auth module to use JWT
58 2:15p 🔴 Fix null pointer in token validation
### May 8, 2026
71 9:00a ✅ Add refresh token expiry logic

1
2
3
4
5
6
7

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "Current: ...\n### May 8, 2026\n...",
    "permissionDecision": "allow"
  }
}

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

const result = await executeWithWorkerFallback<{ status?: string }>(
  '/api/sessions/observations',
  'POST',
  {
    contentSessionId: sessionId,
    platformSource,
    tool_name: toolName,
    tool_input: toolInput,    // 原始工具输入（未序列化，在 Worker 侧做）
    tool_response: toolResponse,
    cwd,
    agentId: input.agentId,   // 用于识别 subagent 的 observations
    agentType: input.agentType,
  },
);

1
2
3
4
5
6

const cleanedToolInput = payload.toolInput !== undefined
  ? stripMemoryTagsFromJson(JSON.stringify(payload.toolInput))
  : '{}';
const cleanedToolResponse = payload.toolResponse !== undefined
  ? stripMemoryTagsFromJson(JSON.stringify(payload.toolResponse))
  : '{}';

 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

// 跳过条件 1: Codex Stop hook 重入
if (input.stopHookActive === true) {
  return { continue: true, suppressOutput: true };
}

// 跳过条件 2: subagent（只有主 agent 才生成摘要）
if (input.agentId) {
  return { continue: true, suppressOutput: true };
}

// 提取最后一条 assistant 消息
let lastAssistantMessage = '';
if (input.lastAssistantMessage !== undefined) {
  lastAssistantMessage = stripMemoryTagsFromPrompt(input.lastAssistantMessage);
} else {
  // fallback: 从 JSONL transcript 文件中解析
  lastAssistantMessage = extractLastMessage(transcriptPath, 'assistant', true);
  lastAssistantMessage = stripMemoryTagsFromPrompt(lastAssistantMessage);
}

if (!lastAssistantMessage || !lastAssistantMessage.trim()) {
  return { continue: true, suppressOutput: true };  // 没有可摘要的内容
}

// 发送给 Worker 异步处理（不等待 AI 生成完成）
const queueResult = await executeWithWorkerFallback<{ status?: string }>(
  '/api/sessions/summarize', 'POST',
  { contentSessionId: sessionId, last_assistant_message: lastAssistantMessage, platformSource },
);

1
2
3
4
5
6
7
8
9

// tag-stripping.ts:4-11
const TAG_NAMES = [
  'private',            // 用户手写的隐私标记 —— 防止内容被记录
  'claude-mem-context', // 系统注入的历史上下文 —— 防止递归存储（存储后再次被存储）
  'system_instruction', // 系统指令（下划线版）
  'system-instruction', // 系统指令（连字符版）
  'persisted-output',   // 已持久化的输出
  'system-reminder',    // Claude Code 的 system-reminder 标签
] as const;

1
2
3
4
5

// tag-stripping.ts:14-17
const STRIP_REGEX = new RegExp(
  `<(${TAG_NAMES.join('|')})\\b[^>]*>[\\s\\S]*?</\\1>`,
  'g'
);

1
2
3
4
5
6
7
8

// tag-stripping.ts:48-54
export function stripMemoryTagsFromJson(content: string): string {
  return stripTags(content).stripped;  // 用于 tool_input/tool_response（JSON 字符串）
}

export function stripMemoryTagsFromPrompt(content: string): string {
  return stripTags(content).stripped;  // 用于 prompt/assistant message（自然语言）
}

1
2
3
4
5
6

// tag-stripping.ts:37-43
if (total > MAX_TAG_COUNT) {
  logger.warn('SYSTEM', 'tag count exceeds limit', undefined, {
    tagCount: total, maxAllowed: MAX_TAG_COUNT
  });
}

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

// tag-stripping.ts:56-68
const PROTOCOL_ONLY_TAGS = ['task-notification'] as const;
const PROTOCOL_ONLY_REGEX = new RegExp(
  `^\\s*<(${PROTOCOL_ONLY_TAGS.join('|')})\\b[^>]*>(?:(?!<\\1\\b|</\\1\\b)[\\s\\S])*</\\1>\\s*$`,
);
const MAX_PROTOCOL_PAYLOAD_BYTES = 256 * 1024;  // 256KB 上限

export function isInternalProtocolPayload(text: string): boolean {
  if (!text) return false;
  if (text.length > MAX_PROTOCOL_PAYLOAD_BYTES) return false;
  return PROTOCOL_ONLY_REGEX.test(text);
}

 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

export async function executeWithWorkerFallback<T = unknown>(
  url: string,
  method: 'GET' | 'POST' | 'PUT' | 'DELETE',
  body?: unknown,
  options: WorkerFallbackOptions = {},
): Promise<WorkerCallResult<T>> {
  // 1. 懒启动检查（每个 hook 进程只检查一次，有缓存）
  const alive = await ensureWorkerAliveOnce();
  if (!alive) {
    recordWorkerUnreachable();  // 持久化失败计数器
    return { continue: true, reason: 'worker_unreachable', [WORKER_FALLBACK_BRAND]: true };
  }

  // 2. 发送 HTTP 请求
  const response = await workerHttpRequest(url, init);

  // 3. 处理非 2xx 响应
  if (!response.ok) {
    resetWorkerFailureCounter();  // 注意：非 2xx 也重置计数器（worker 在线，只是业务错误）
    if (response.status === 429 || response.status >= 500) {
      return { continue: true, reason: `worker_api_${response.status}`, [WORKER_FALLBACK_BRAND]: true };
    }
    return parsed as T;  // 4xx 等返回原始响应（业务层判断）
  }

  resetWorkerFailureCounter();  // 成功后重置连续失败计数
  return JSON.parse(await response.text()) as T;
}

 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

// worker-utils.ts:277-329
async function ensureWorkerRunning(): Promise<boolean> {
  if (await isWorkerPortAlive()) {  // 先检查健康和 PID 文件
    await checkWorkerVersion();     // 版本不匹配时记录 debug log（不自动重启）
    const ready = await waitForWorkerReadiness();  // 等待 DB/Chroma 初始化
    return ready;
  }

  // Worker 不在 → 找 Bun 运行时和 worker-service.cjs
  const proc = spawnHidden(runtimePath, [scriptPath, '--daemon'], { detached: true });
  proc.unref();  // 父进程（hook）退出后子进程继续运行

  // 轮询 /api/health，指数退避：250ms → 500ms → 1000ms
  const alive = await waitForWorkerPort({ attempts: 3, backoffMs: 250 });
  const ready = await waitForWorkerReadiness();  // 再等 DB/Chroma ready
  return ready;
}

// 每个 hook 进程缓存结果，避免重复探活
let aliveCache: boolean | null = null;
export async function ensureWorkerAliveOnce(): Promise<boolean> {
  if (aliveCache !== null) return aliveCache;
  aliveCache = await ensureWorkerRunning();
  return aliveCache;
}

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

// worker-utils.ts:425-437
const WORKER_FALLBACK_BRAND: unique symbol = Symbol.for('claude-mem/worker-fallback');

export type WorkerFallback =
  | { continue: true; [WORKER_FALLBACK_BRAND]: true }
  | { continue: true; reason: string; [WORKER_FALLBACK_BRAND]: true };

export function isWorkerFallback<T>(result: WorkerCallResult<T>): result is WorkerFallback {
  return typeof result === 'object'
    && result !== null
    && (result as any)[WORKER_FALLBACK_BRAND] === true;
}

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

// worker-utils.ts:401-416
function recordWorkerUnreachable(): number {
  const state = readHookFailureState();  // 从 ~/.claude-mem/state/hook-failures.json 读取
  const next = { consecutiveFailures: state.consecutiveFailures + 1, lastFailureAt: Date.now() };
  writeHookFailureStateAtomic(next);  // 原子写（tmp → rename）

  const threshold = getFailLoudThreshold();  // 默认 3，可配置 CLAUDE_MEM_HOOK_FAIL_LOUD_THRESHOLD
  if (next.consecutiveFailures >= threshold) {
    process.stderr.write(`claude-mem worker unreachable for ${next.consecutiveFailures} consecutive hooks.\n`);
    process.exit(HOOK_EXIT_CODES.BLOCKING_ERROR);  // exit(2)：Claude Code 把 stderr 喂给 Claude
  }
  return next.consecutiveFailures;
}