项目简介

Claude-Mem 是一个为 Claude Code 设计的持久化记忆系统，能够在不同会话之间自动保存和恢复上下文信息。该项目使 Claude Code 能够在会话结束后保留对项目的理解和学习成果，从而在新的会话中继续利用这些知识。资料来源：README.md

核心功能

自动上下文保存

Claude-Mem 在用户使用 Claude Code 的过程中自动捕获工具使用和观察结果，生成语义摘要，并在后续会话中提供这些信息。这使得 AI 能够维持对项目的连续性理解，即使在会话结束或重新连接后也能保留关键知识。资料来源：README.md

观察记录系统

系统通过 Observation 数据模型记录每次重要的交互和发现。观察记录包含以下结构化字段：

资料来源：src/server/generation/providers/shared/prompt-builder.ts

摘要生成

系统支持生成会话级别的摘要（Summary），包含以下关键信息：

资料来源：src/sdk/prompts.ts

系统架构

Claude-Mem 采用模块化架构，主要包含以下核心模块：

graph TD
    A[Claude Code] <--> B[NPM CLI 模块]
    A <--> C[SDK 模块]
    B <--> D[Worker Service]
    C <--> D
    D <--> E[UI Viewer]
    D <--> F[存储层 ~/.claude-mem]

SDK 模块

SDK 模块负责生成 AI 可读的提示模板，支持观察记录和摘要的 XML 格式输出。该模块的核心功能包括：

• 观察提示构建：buildObservationPrompt() 函数生成用于引导 AI 生成观察记录的提示模板
• 摘要提示构建：buildSummaryPrompt() 函数生成用于生成会话摘要的提示模板
• 继续提示构建：buildContinuationPrompt() 函数处理跨会话的上下文延续

资料来源：src/sdk/prompts.ts

服务器端生成模块

服务器端负责实际调用 AI 模型生成观察记录和摘要，主要通过 prompt-builder.ts 实现：

• XML 格式的输出模式定义
• 私有内容检测与脱敏处理
• 活动模式（Mode）管理
• 观察类型的灵活配置

资料来源：src/server/generation/providers/shared/prompt-builder.ts

UI Viewer 模块

UI 模块提供了一个可视化界面，用于浏览和管理记忆内容：

资料来源：src/ui/viewer/App.tsx、src/ui/viewer/components/SummaryCard.tsx、src/ui/viewer/components/ObservationCard.tsx

NPM CLI 模块

命令行接口模块提供安装和管理功能：

• install 命令：安装插件到 Claude Code、设置 worker 服务
• start 命令：启动 worker 服务
• status 命令：检查服务状态

资料来源：src/npx-cli/commands/install.ts

安装与配置

安装方式

Claude-Mem 支持多种安装方式：

资料来源：README.md

上下文设置

用户可以通过 UI 的 ContextSettingsModal 配置以下参数：

资料来源：src/ui/viewer/components/ContextSettingsModal.tsx

首次使用流程

sequenceDiagram
    participant User as 用户
    participant CLI as Claude Code CLI
    participant Worker as Worker Service
    participant Viewer as UI Viewer
    participant Storage as ~/.claude-mem

    User->>CLI: 运行 npx claude-mem install
    CLI->>Worker: 启动 Worker Service
    Worker->>Viewer: 打开浏览器管理界面
    User->>CLI: 开始第一个会话
    CLI->>Storage: 捕获观察记录
    Storage->>Worker: 存储观察数据
    User->>CLI: 开始第二个会话
    Worker->>CLI: 注入历史上下文
    CLI->>User: 显示上下文增强的响应

资料来源：src/npx-cli/commands/install.ts

数据存储

所有数据默认存储在本地 ~/.claude-mem 目录中，确保用户对数据拥有完全控制权。存储内容包括：

• 观察记录（Observations）
• 会话摘要（Summaries）
• 用户设置
• 日志文件

技术栈

观察类型系统

系统支持可配置的观察类型，通过 observation_types 定义。不同模式下可以定义不同的观察类型以适应特定场景需求。资料来源：src/server/generation/providers/shared/prompt-builder.ts

相关资源

• 官方文档：https://docs.claude-mem.ai
• 项目主页：https://github.com/thedotmack/claude-mem
• X (Twitter)：@Claude_Memory

系统架构概览

Claude-Mem 采用客户端-服务端架构，包含以下核心组件：

graph TD
    A[Claude Code / Gemini CLI] --> B[Worker Service]
    B --> C[Memory Storage<br/>~/.claude-mem]
    B --> D[Context Compiler]
    D --> A
    C --> E[ObservationCompiler]
    E --> D

记忆项目（Memory Item）

Memory Item 是 Claude-Mem 中存储记忆的基本单位。

数据模型

// 资料来源：src/core/schemas/memory-item.ts
export type MemoryItemKind = z.infer<typeof MemoryItemKindSchema>;
export type MemoryItem = z.infer<typeof MemoryItemSchema>;
export type CreateMemoryItem = z.infer<typeof CreateMemoryItemSchema>;

记忆来源类型（Memory Source Type）

系统支持多种记忆来源类型：

核心字段

export type MemorySourceType = z.infer<typeof MemorySourceTypeSchema>;
export type MemorySource = z.infer<typeof MemorySourceSchema>;
export type CreateMemorySource = z.infer<typeof CreateMemorySourceSchema>;

观察记录（Observation）

Observation 是系统捕获的单个事件或活动记录。

观察记录结构

<observation>
  <type>[ implementation | debugging | research | planning ]</type>
  <title>观察标题</title>
  <subtitle>副标题</subtitle>
  <facts>
    <fact>具体事实1</fact>
    <fact>具体事实2</fact>
  </facts>
  <narrative>叙述性描述</narrative>
  <concepts>
    <concept>相关概念1</concept>
    <concept>相关概念2</concept>
  </concepts>
  <files_read>
    <file>读取的文件路径</file>
  </files_read>
  <files_modified>
    <file>修改的文件路径</file>
  </files_modified>
</observation>

观察类型

UI 展示组件

Observation 的 UI 展示由 ObservationCard.tsx 组件处理，支持以下功能：

• 按类型分组显示观察记录
• 展示关联的概念标签
• 显示涉及的文件（读取/修改）
• 显示观察记录的元数据（ID、日期）

// 资料来源：src/ui/viewer/components/ObservationCard.tsx
{showFacts && (concepts.length > 0 || filesRead.length > 0 || filesModified.length > 0) && (
  <div style={{ display: 'flex', flexWrap: 'wrap', gap: '8px', alignItems: 'center' }}>
    {concepts.map((concept: string, i: number) => (
      <span key={i}>{concept}</span>
    ))}
    {filesRead.length > 0 && (
      <span className="meta-files">
        <span className="file-label">read:</span> {filesRead.join(', ')}
      </span>
    )}
  </div>
)}

会话摘要（Summary）

Summary 是对整个会话的总结性描述。

摘要结构

<summary>
  <request>用户请求</request>
  <investigated>调查内容</investigated>
  <learned>学到的新知识</learned>
  <completed>完成的工作</completed>
  <next_steps>下一步计划</next_steps>
  <notes>备注信息</notes>
</summary>

摘要字段说明

UI 展示组件

// 资料来源：src/ui/viewer/components/SummaryCard.tsx
{sections.map((section, index) => (
  <section
    key={section.key}
    className="summary-section"
    style={{ animationDelay: `${index * 50}ms` }}
  >
    <div className="summary-section-header">
      <img src={section.icon} alt={section.label} />
      <h3 className="summary-section-label">{section.label}</h3>
    </div>
    <div className="summary-section-content">
      {section.content}
    </div>
  </section>
))}

上下文编译（Context Compilation）

Context Compiler 负责将存储的记忆转换为可注入到 Claude 会话的格式。

编译流程

graph LR
    A[Memory Storage] --> B[Query & Filter]
    B --> C[ObservationCompiler]
    C --> D[Format as XML]
    D --> E[Inject to Session]

上下文配置

用户可以通过环境变量配置上下文注入行为：

提示词构建

SDK 使用结构化的提示词模板生成记忆：

// 资料来源：src/sdk/prompts.ts
${mode.prompts.output_format_header}

<observation>
  <type>[ ${mode.observation_types.map(t => t.id).join(' | ')} ]</type>
  <title>${mode.prompts.xml_title_placeholder}</title>
  <subtitle>${mode.prompts.xml_subtitle_placeholder}</subtitle>
  <facts>
    <fact>${mode.prompts.xml_fact_placeholder}</fact>
  </facts>
  <narrative>${mode.prompts.xml_narrative_placeholder}</narrative>
  <concepts>
    <concept>${mode.prompts.xml_concept_placeholder}</concept>
  </concepts>
</observation>

数据持久化

存储位置

所有记忆数据存储在本地目录：

~/.claude-mem/
├── memories.db          # SQLite 数据库
├── transcripts/         # 会话转录
├── vector-index/       # 向量索引（如启用）
└── config/             # 配置文件

会话延迟处理

为避免并发问题，系统支持会话延迟处理：

模式（Mode）系统

Claude-Mem 支持多种工作模式，每种模式有不同的观察类型和提示词配置。

默认模式

// 资料来源：src/server/generation/providers/shared/prompt-builder.ts
const FALLBACK_OBSERVATION_TYPES = [
  { id: 'implementation' },
  { id: 'debugging' },
  { id: 'research' },
  { id: 'planning' },
];

模式配置结构

interface ModeConfig {
  prompts: {
    header_memory_continued: string;
    header_memory_start: string;
    continuation_instruction: string;
    output_format_header: string;
    // ... 其他提示词配置
  };
  observation_types: ReadonlyArray<{
    id: string;
  }>;
}

工作流程

记忆捕获流程

sequenceDiagram
    participant U as User
    participant C as Claude Code
    participant W as Worker Service
    participant M as Memory Storage

    U->>C: 执行任务
    C->>W: 发送工具使用事件
    W->>W: 生成观察记录
    W->>M: 存储记忆
    Note over C,M: 自动进行，无需用户干预

上下文注入流程

sequenceDiagram
    participant C as Claude Code
    participant W as Worker Service
    participant M as Memory Storage
    participant P as Prompt Builder

    C->>W: 请求上下文
    W->>M: 查询相关记忆
    M-->>W: 返回记忆列表
    W->>P: 构建提示词
    P-->>W: 格式化的上下文
    W-->>C: 注入上下文
    Note over C: 新会话开始

关键配置变量

相关文件索引

概述

Claude-Mem 是一个为 Claude Code 提供持久化记忆功能的插件系统，其核心目标是实现跨会话的上下文连续性。该系统通过自动捕获工具使用观察、生成语义摘要，使 Claude 能够在会话结束后或重新连接时保持对项目的知识连续性。 资料来源：README.md:1-10

系统架构采用插件化设计，支持多种 IDE 环境集成，包括 Claude Code、Gemini CLI 和 OpenCode。数据存储在本地文件系统（~/.claude-mem），确保用户对数据的完全控制。 资料来源：README.md:28-35

核心组件架构

Claude-Mem 的系统架构由以下核心层次组成：

graph TD
    subgraph "客户端层"
        IDE[IDE 插件集成]
        CLI[NPX CLI 工具]
    end
    
    subgraph "服务层"
        Worker[Worker Service]
        Server[Server 服务]
        PromptBuilder[Prompt Builder]
    end
    
    subgraph "SDK 层"
        PromptSDK[Prompts SDK]
        ObservationSDK[Observation SDK]
    end
    
    subgraph "UI 层"
        ViewerApp[Viewer 应用]
        SummaryCard[摘要卡片]
        ObservationCard[观察卡片]
        SettingsModal[设置模态框]
    end
    
    subgraph "数据层"
        Storage[本地存储 ~/.claude-mem]
        SessionData[会话数据]
        ObservationData[观察数据]
    end
    
    IDE --> Worker
    CLI --> Worker
    Worker --> Server
    Server --> PromptBuilder
    Server --> Storage
    PromptBuilder --> PromptSDK
    ViewerApp --> Server
    ViewerApp --> SettingsModal

组件职责矩阵

数据流架构

观察数据生命周期

graph LR
    A[工具调用] --> B[观察捕获]
    B --> C[输入解析]
    C --> D[Prompt 构建]
    D --> E[LLM 处理]
    E --> F[结构化输出]
    F --> G[存储]
    G --> H[摘要生成]
    H --> I[上下文注入]

1. 观察捕获阶段：系统监听 Claude Code 的工具调用事件，自动捕获工具输入和输出 资料来源：src/server/generation/providers/shared/prompt-builder.ts:1-30
2. 数据解析阶段：对捕获的工具调用进行解析，提取关键信息并处理私有数据边界 资料来源：src/server/generation/providers/shared/prompt-builder.ts:40-60
3. Prompt 构建阶段：根据活动模式（Mode）配置构建符合 XML 格式的观察输出 资料来源：src/sdk/prompts.ts:1-50
4. LLM 处理阶段：使用配置的 LLM 模型生成语义化的观察摘要
5. 存储阶段：将处理后的数据持久化到本地存储
6. 上下文注入阶段：在新的会话中自动注入相关记忆

上下文注入流程

graph TD
    A[新会话开始] --> B{检查记忆缓存}
    B -->|首次会话| C[不注入历史]
    B -->|非首次会话| D[查询历史观察]
    D --> E[加载最近 N 条观察]
    D --> F[加载最近 M 个会话]
    E --> G[构建上下文 Prompt]
    F --> G
    G --> H[注入到系统提示]
    H --> I[开始新会话]
    
    C --> I

上下文注入可通过环境变量进行配置： 资料来源：src/ui/viewer/components/ContextSettingsModal.tsx:30-60

提示词生成架构

Prompt SDK 结构

提示词生成采用模块化设计，支持多种模式配置： 资料来源：src/sdk/prompts.ts:50-100

interface ModeConfig {
  prompts: {
    continuation_instruction: string;
    output_format_header: string;
    xml_title_placeholder: string;
    xml_subtitle_placeholder: string;
    xml_fact_placeholder: string;
    xml_narrative_placeholder: string;
    xml_concept_placeholder: string;
    xml_file_placeholder: string;
    type_guidance: string;
    field_guidance: string;
    concept_guidance: string;
    format_examples: string;
    footer: string;
  };
  observation_types: ObservationType[];
}

输出模式构建

观察输出采用 XML 格式，包含以下结构化字段： 资料来源：src/server/generation/providers/shared/prompt-builder.ts:70-90

<observation>
  <type>[ observation | code_change | error_recovery | ... ]</type>
  <title>...</title>
  <subtitle>...</subtitle>
  <facts>
    <fact>...</fact>
  </facts>
  <narrative>...</narrative>
  <concepts>
    <concept>...</concept>
  </concepts>
  <files_read>
    <file>...</file>
  </files_read>
  <files_modified>
    <file>...</file>
  </files_modified>
</observation>

摘要生成 Prompt

系统支持生成会话级别的语义摘要，用于高层次的项目状态追踪： 资料来源：src/sdk/prompts.ts:80-120

<summary>
  <request>用户原始请求</request>
  <investigated>调查内容</investigated>
  <learned>学到的新知识</learned>
  <completed>完成的任务</completed>
  <next_steps>后续步骤</next_steps>
  <notes>备注</notes>
</summary>

UI 组件架构

组件层次结构

graph TD
    App --> Header
    App --> WelcomeCard
    App --> ObservationList
    App --> SummaryList
    App --> ContextSettingsModal
    App --> LogsDrawer
    
    ObservationList --> ObservationCard
    SummaryList --> SummaryCard
    
    ObservationCard --> ObservationType
    ObservationCard --> FactsList
    ObservationCard --> NarrativeView
    
    SummaryCard --> SummarySection
    SummarySection --> SectionHeader
    SummarySection --> SectionContent

主要组件说明

#### Viewer 应用主容器 资料来源：src/ui/viewer/App.tsx:1-50

#### 观察卡片组件 资料来源：src/ui/viewer/components/ObservationCard.tsx:1-80

显示单个观察记录的详细信息，支持两种视图模式切换：

#### 摘要卡片组件 资料来源：src/ui/viewer/components/SummaryCard.tsx:1-50

展示会话级别的语义摘要，包含以下节：

• Request：用户请求
• Investigated：调查内容
• Learned：学到的知识
• Completed：完成的任务
• Next Steps：后续步骤

#### 设置模态框 资料来源：src/ui/viewer/components/ContextSettingsModal.tsx:1-100

提供交互式的上下文注入配置界面，包含：

• 观察数量配置（1-200）
• 会话数量配置（1-50）
• 实时终端预览

安装与部署架构

插件安装流程

graph LR
    A[npx claude-mem install] --> B{IDE 类型}
    B -->|Claude Code| C[Marketplace 安装]
    B -->|Gemini CLI| D[自动检测 ~/.gemini]
    B -->|OpenCode| E[特定路径配置]
    
    C --> F[Worker Service 启动]
    D --> F
    E --> F
    
    F --> G[注册插件钩子]
    G --> H[初始化本地存储]
    H --> I[系统就绪]

安装命令支持 资料来源：[src/npx-cli/commands/install.ts:1-50]()

首次使用引导 资料来源：[src/npx-cli/commands/install.ts:50-80]()

首次安装后，系统提供两种启动路径：

记忆存储架构

本地存储结构

所有数据存储在用户本地目录 ~/.claude-mem，包括：

• 会话记录
• 观察数据
• 生成的摘要
• 用户配置

数据隔离

系统通过以下机制保护数据隐私： 资料来源：src/server/generation/providers/shared/prompt-builder.ts:20-40

1. 私有数据检测：自动识别并标记包含敏感信息的内容
2. 数据边界控制：通过 docs/ip-boundary.md 定义数据处理边界
3. 本地优先：所有数据存储在用户本地，不上传至云端

多模式支持架构

系统支持可配置的操作模式（Mode），每种模式定义不同的：

模式管理器（ModeManager）提供活动模式的获取和切换功能。 资料来源：src/server/generation/providers/shared/prompt-builder.ts:35-45

扩展点与集成

IDE 插件钩子

系统通过插件钩子与 IDE 集成，支持：

• 工具调用拦截
• 会话状态监控
• 上下文注入

MCP 服务器集成

Claude-Mem 可作为 MCP（Model Context Protocol）服务器运行，提供：

• 记忆查询接口
• 观察记录接口
• 配置管理接口

国际化支持

系统内置多语言支持，包括简体中文（code--zh）等语言模式。 资料来源：README.md:80-90

安全与隐私

数据保护机制

许可证

项目采用 Apache License 2.0，该许可证允许在多种场景下使用，包括开发者工具、本地代理、MCP 服务器、企业系统、机器人栈和生产代理环境。 资料来源：README.md:100-110

总结

Claude-Mem 采用分层架构设计，核心包括：

1. 观察捕获层：通过 IDE 插件钩子自动捕获工具使用
2. 处理服务层：Worker Service 和 Server 处理数据转换和存储
3. 生成引擎层：Prompt Builder 构建 LLM 交互的提示词
4. 用户界面层：React 组件提供记忆查看和配置功能
5. 存储持久层：本地文件系统确保数据隐私和持久性

这种架构设计确保了系统具有良好的可扩展性、安全性和用户数据控制能力。

概述

Worker 服务是 claude-mem 系统中的核心后台处理组件，负责执行长期运行的任务队列、处理观察记录生成、以及管理会话上下文。该服务以独立进程方式运行，通过 BullMQ 与 Redis 进行进程间通信，实现高可靠性的任务处理能力。Worker 服务默认监听端口 37777，提供健康检查和状态监控接口。

Worker 服务的核心职责包括：

• 接收并处理来自主服务的任务队列请求
• 管理会话的上下文信息和历史记录
• 执行 LLM 响应处理和格式转换
• 维护任务执行状态和进度通知
• 处理失败任务的重试逻辑

资料来源：src/npx-cli/commands/install.ts:1-100

核心组件

Worker 服务由多个协同工作的子模块组成，每个模块承担特定的职责。

组件架构表

资料来源：src/services/worker/SessionManager.ts, src/services/worker/FormattingService.ts, src/services/worker/agents/ResponseProcessor.ts

任务队列架构

Worker 服务基于 BullMQ 构建企业级任务队列系统，支持分布式处理和跨进程事件通知。

队列工作流程

graph TD
    A[主服务提交任务] --> B[ServerJobQueue 入队]
    B --> C[Redis 队列存储]
    C --> D[Worker 进程轮询]
    D --> E{任务类型判断}
    E -->|生成任务| F[Generation Worker]
    E -->|处理任务| G[Processing Worker]
    F --> H[LLM 调用]
    G --> I[数据处理]
    H --> J[ResponseProcessor]
    I --> J
    J --> K[格式化输出]
    K --> L[结果存储]
    L --> M[QueueEvents 通知]

事件处理机制

Worker 服务通过 QueueEvents 订阅 Redis 发布/订阅通道，实现跨进程的可靠事件通知。

主要事件类型：

• stalled: 任务停滞检测，由 Worker 或 QueueEvents 触发
• progress: 任务进度更新
• error: 任务执行错误
• failed: 任务最终失败

graph LR
    A[Worker 进程] -->|w.on| B[stalled 事件]
    A -->|w.on| C[progress 事件]
    A -->|w.on| D[error 事件]
    A -->|w.on| E[failed 事件]
    F[QueueEvents] -->|events.on| G[跨进程 stalled 通知]
    G --> H[notifyStalled]

资料来源：src/server/jobs/ServerJobQueue.ts:50-80

任务重试策略

Worker 实现智能重试机制，在任务失败时根据配置自动重试：

// 伪代码示例，实际逻辑在 ServerJobQueue 中实现
{
  attempts: 3,           // 最大重试次数
  backoff: {
    type: 'exponential', // 指数退避
    delay: 2000          // 基础延迟 2 秒
  }
}

配置与端口

默认配置参数

健康检查流程

Worker 服务启动后通过端口 37777 提供健康检查端点：

sequenceDiagram
    participant CLI as Claude-Mem CLI
    participant Worker as Worker Service
    participant Redis as Redis
    
    CLI->>Worker: 检查端口 37777 连接
    alt 端口可达
        Worker-->>CLI: Worker 就绪
        CLI->>Worker: 启动完成提示
    else 端口不可达
        Worker-->>CLI: 仍在启动中
        CLI->>User: 提示等待 30 秒后重试
    end

资料来源：src/npx-cli/commands/install.ts:20-60

状态监控

队列深度监控

Worker 服务的 Header 组件持续监控队列状态，当存在待处理任务时显示队列气泡指示器：

// 队列气泡显示逻辑
{queueDepth > 0 && (
  <div className="queue-bubble">
    {queueDepth}
  </div>
)}

错误边界处理

Worker 服务的 UI 组件实现了 ErrorBoundary 错误边界机制，确保单个组件错误不会导致整个界面崩溃：

class ErrorBoundary extends Component {
  state = { error: null, errorInfo: null };
  
  componentDidCatch(error, errorInfo) {
    this.setState({ error, errorInfo });
  }
  
  render() {
    if (this.state.error) {
      return <ErrorFallback details={this.state.error} />;
    }
    return this.props.children;
  }
}

资料来源：src/ui/viewer/components/ErrorBoundary.tsx:1-50, src/ui/viewer/components/Header.tsx:1-40

启动与管理

安装命令

Worker 服务通过 npx 命令安装并自动配置：

npx claude-mem install

安装过程会：

1. 检查 Worker 服务状态
2. 等待服务在端口 37777 上就绪
3. 显示连接信息和后续操作指引

手动启动

如需手动启动 Worker 服务：

npx claude-mem start

服务将以后台进程方式运行，日志输出到标准输出。

资料来源：src/npx-cli/commands/install.ts:1-30

总结

Worker 服务是 claude-mem 架构中不可或缺的异步处理中枢，通过 BullMQ 和 Redis 实现高可靠性的分布式任务处理。服务支持事件驱动的进度监控、智能重试策略、以及完整的错误处理机制。SessionManager、FormattingService 和 ResponseProcessor 等子模块各司其职，共同完成从任务接收到结果输出的完整链路。

概述

claude-mem 的数据存储层是整个记忆系统的核心基础设施，负责持久化会话数据、观察记录和语义向量。该层采用混合存储架构，结合 SQLite 的事务性数据存储和 Chroma 向量数据库的语义搜索能力，实现高效的数据读写和智能检索功能。

数据存储层的主要职责包括：

• 会话管理：创建、更新和查询 Claude Code 会话记录
• 观察持久化：存储 AI 生成的观察条目（observations）
• 语义同步：将数据同步到向量数据库支持语义搜索
• 上下文注入：为新会话提供历史记忆上下文

资料来源：src/services/sqlite/Database.ts:1-50

架构设计

存储层组件

数据存储层由以下核心组件构成：

graph TD
    A[claude-mem SDK] --> B[SQLite 数据库]
    A --> C[Chroma 向量库]
    B --> D[sessions 表]
    B --> E[observations 表]
    B --> F[prompts 表]
    B --> G[summaries 表]
    C --> H[向量嵌入]
    E --> C
    I[Worker Service] --> B
    I --> C

资料来源：src/services/sqlite/schema.sql:1-20

数据模型

#### Sessions 表

会话表存储每次 Claude Code 交互会话的元数据：

CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    project TEXT NOT NULL,
    server_session_id TEXT,
    created_at_epoch INTEGER NOT NULL,
    updated_at_epoch INTEGER NOT NULL,
    summary_id TEXT,
    mode TEXT,
    event_count INTEGER DEFAULT 0
);

关键字段说明：

资料来源：src/services/sqlite/schema.sql:1-10

#### Observations 表

观察表是核心数据存储，记录 AI 生成的结构化观察：

CREATE TABLE observations (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL,
    project TEXT NOT NULL,
    type TEXT NOT NULL,
    title TEXT,
    subtitle TEXT,
    narrative TEXT,
    facts TEXT,  -- JSON array
    concepts TEXT,  -- JSON array
    files_read TEXT,  -- JSON array
    files_modified TEXT,  -- JSON array
    tool_name TEXT,
    tool_input TEXT,
    tool_output TEXT,
    occurred_at_epoch INTEGER NOT NULL,
    created_at_epoch INTEGER NOT NULL,
    is_summary_related INTEGER DEFAULT 0,
    FOREIGN KEY (session_id) REFERENCES sessions(id)
);

资料来源：src/services/sqlite/schema.sql:11-35

核心模块详解

Database 模块

Database.ts 是存储层的入口点，负责：

• 建立 SQLite 数据库连接
• 执行 schema 初始化
• 提供事务支持
• 管理数据库路径配置

// 典型初始化流程
const db = new Database(appDataPath);
await db.initialize();

资料来源：src/services/sqlite/Database.ts:1-30

Sessions 模块

Sessions.ts 实现会话管理的核心逻辑：

会话查询支持按项目名称、时间范围和模式类型过滤。

资料来源：src/services/sqlite/Sessions.ts:1-50

Observations 模块

Observations.ts 处理观察数据的读写操作：

graph LR
    A[工具调用事件] --> B[ObservationParser]
    B --> C[存储到SQLite]
    C --> D[ChromaSync]
    D --> E[生成向量嵌入]
    E --> F[Chroma向量库]

关键功能包括：

• 将工具输入/输出解析为结构化观察
• 支持批量插入和分页查询
• 维护观察与会话、摘要的关联关系

资料来源：src/services/sqlite/Observations.ts:1-60

向量同步机制

ChromaSync 模块

ChromaSync.ts 负责将 SQLite 中的观察数据同步到 Chroma 向量数据库：

graph TD
    A[SQLite observations] --> B[ChromaSync]
    B --> C{同步状态检查}
    C -->|已同步| D[跳过]
    C -->|需同步| E[提取文本内容]
    E --> F[调用Embedding API]
    F --> G[生成向量]
    G --> H[存储到Chroma]
    H --> I[更新同步标记]

同步策略包括：

• 增量同步：仅同步新增或更新的记录
• 批量处理：分批处理大量数据避免内存溢出
• 错误重试：失败时自动重试机制

资料来源：src/services/sync/ChromaSync.ts:1-80

向量搜索策略

搜索策略模块实现了多种检索算法：

资料来源：src/services/worker/search/strategies

数据流

写入流程

sequenceDiagram
    participant SDK as Claude SDK
    participant Worker as Worker Service
    participant SQLite as SQLite DB
    participant Chroma as Chroma
    
    SDK->>Worker: 发送工具调用事件
    Worker->>Worker: 解析为 Observation
    Worker->>SQLite: 存储观察记录
    Worker->>Chroma: 同步向量数据
    Chroma-->>Worker: 确认同步完成
    Worker-->>SDK: 返回处理结果

读取流程

当新会话启动时，数据存储层提供上下文注入：

1. 解析用户请求
2. 根据配置选择观察数量和会话数量
3. 执行向量相似度搜索
4. 按时间排序和去重
5. 注入到提示上下文

资料来源：src/services/sqlite/Observations.ts:60-100

配置与优化

存储路径

默认数据库存储路径为应用数据目录：

# macOS
~/Library/Application Support/claude-mem/

# Linux
~/.config/claude-mem/

# Windows
%APPDATA%/claude-mem/

性能考虑

• 索引优化：对 session_id、project、occurred_at_epoch 等字段建立索引
• 批量写入：使用事务批量提交减少 I/O
• 连接池：复用数据库连接减少开销

资料来源：src/services/sqlite/schema.sql:36-50

相关文档

• 安装指南
• API 参考
• 搜索功能

概述

搜索系统是 claude-mem 的核心功能模块，负责在历史观察记录、会话和提示词中进行语义检索。该系统通过混合搜索策略结合关键词匹配与语义理解，使用户能够快速定位跨越多个会话积累的项目知识。搜索结果不仅返回匹配的观察记录，还支持时间线构建、上下文预览和自动注入功能，使 AI 能够在新的会话中无缝利用历史上下文。

架构设计

系统组件

搜索系统由多个协同工作的组件构成，形成从请求处理到结果返回的完整管道。

数据流向

graph TD
    A[用户搜索请求] --> B[SearchOrchestrator]
    B --> C{HybridSearchStrategy}
    C --> D[关键词搜索]
    C --> E[语义向量搜索]
    D --> F[结果合并与排序]
    E --> F
    F --> G[TimelineBuilder]
    G --> H[搜索结果响应]
    H --> I[上下文预览/注入]

核心组件详解

SearchOrchestrator

SearchOrchestrator 作为搜索系统的协调器，负责接收和处理所有搜索请求。它根据请求类型分发到相应的搜索策略，并协调结果的聚合与格式化。

主要职责：

• 路由不同类型的搜索请求（观察记录、会话、提示词等）
• 管理搜索策略的执行顺序
• 处理搜索结果的缓存与去重
• 提供搜索帮助信息

HybridSearchStrategy

混合搜索策略是本系统的核心创新，它结合了传统关键词搜索的精确性与语义搜索的智能化理解能力。

graph LR
    A[查询字符串] --> B[分词处理]
    B --> C[关键词匹配]
    B --> D[语义向量化]
    C --> E[BM25 评分]
    D --> F[向量相似度]
    E --> G[分数融合]
    F --> G
    G --> H[Top-K 结果]

搜索模式支持：

• 全文搜索：对观察记录的标题、副标题、事实描述进行全文检索
• 标签搜索：按概念标签、文件路径、观察类型过滤
• 时间范围搜索：限定在特定时间段内的记录
• 项目隔离搜索：仅在指定项目中搜索

TimelineBuilder

TimelineBuilder 负责将搜索结果按时间顺序组织，帮助用户理解知识在项目演进过程中的累积过程。

时间线类型：

• timeline-by-query：基于搜索查询的时间线
• context-timeline：上下文注入时的时间线
• recent-context：最近上下文的综合视图

API 端点

搜索相关端点

上下文相关端点

观察记录检索

SQLite 数据模型

观察记录存储在 SQLite 数据库中，支持多种查询模式。资料来源：src/services/sqlite/observations/get.ts

支持的操作类型：

type ObservationKind = 'decision' | 'change' | 'how-it-works';

检索函数签名：

• getObservations(filters)：基础观察记录检索
• getObservationsBySession(sessionId)：按会话筛选
• getObservationsByProject(projectId)：按项目筛选
• getObservationsByType(type)：按类型筛选

查询参数

MCP 工具接口

MCP（Model Context Protocol）工具层为外部 AI 客户端提供搜索访问接口。资料来源：src/server/mcp/tools.ts

工具定义

// MCP 搜索工具结构
interface SearchTool {
  name: string;          // 工具名称
  description: string;  // 功能描述
  inputSchema: object;   // 输入参数模式
}

可用搜索工具

搜索策略实现

混合评分机制

混合搜索策略通过加权融合关键词匹配分数和语义相似度分数来生成最终排名。资料来源：src/services/worker/search/strategies/HybridSearchStrategy.ts

评分公式：

final_score = α × bm25_score + β × semantic_similarity

其中 α 和 β 为可配置的权重参数，默认 α = 0.4，β = 0.6。

结果重排序

搜索结果返回前会根据以下因素进行重排序：

• 时间衰减因子：新近记录优先
• 项目相关性：与当前项目关联度高的记录
• 使用频率：被引用次数多的记录

使用场景

场景一：跨会话知识检索

当开发者需要回顾之前实现某个功能的技术决策时，可以通过概念标签或文件路径快速定位相关观察记录。

场景二：上下文恢复

在长时间中断后重新开始工作时，系统可以将相关的历史观察打包为上下文预览，帮助 AI 快速恢复项目认知。

场景三：知识图谱构建

通过分析搜索结果中的概念标签和文件关联，系统可以自动构建项目的知识图谱结构。

配置选项

搜索配置参数

总结

搜索系统通过混合搜索策略、灵活的时间线构建和完整的 MCP 工具接口，为 claude-mem 提供了强大的知识检索能力。该系统使得跨会话的上下文保持和知识复用成为可能，显著提升了 AI 在长期项目中的工作效率。

概述

生命周期钩子系统（Lifecycle Hook System）是 claude-mem 的核心模块，负责在 Claude Code、Gemini CLI、OpenClaw Gateway 和 Cursor 等 IDE 的运行过程中自动捕获用户操作、生成语义摘要，并使历史上下文可供未来会话使用。该系统通过事件驱动的架构，在 IDE 的关键生命周期节点注入自定义逻辑，实现跨会话的持久记忆功能。 资料来源：README.md

架构设计

系统组件

graph TD
    subgraph "IDE 运行环境"
        CLI[Claude Code / Gemini CLI / Cursor / OpenClaw]
    end
    
    subgraph "钩子系统核心"
        HC[Hook Manager]
        EP[Event Processor]
        OBS[Observation Store]
        SUM[Summary Generator]
    end
    
    subgraph "存储层"
        DB[(SQLite/JSON)]
        FS[文件系统]
    end
    
    CLI -->|触发生命周期事件| HC
    HC -->|处理事件| EP
    EP -->|生成观测记录| OBS
    EP -->|触发摘要生成| SUM
    OBS -->|持久化| DB
    SUM -->|持久化| FS

事件流处理

钩子系统采用事件驱动模式，在 IDE 的生命周期各阶段触发相应的处理函数。每个事件都携带上下文数据，经处理器转换后存入持久化存储。 资料来源：openclaw/src/index.ts:1-50

钩子事件类型

OpenClaw Gateway 事件

OpenClaw Gateway 提供了完整的事件订阅接口，支持以下生命周期事件： 资料来源：openclaw/src/index.ts:15-27

事件回调接口定义

interface PluginInterface {
  on: ((
    event: "before_prompt_build",
    callback: PromptBuildCallback
  ) => void) &
    ((
      event: "before_agent_start",
      callback: EventCallback<BeforeAgentStartEvent>
    ) => void) &
    // ... 其他事件类型
    ((
      event: "after_compaction",
      callback: EventCallback<AfterCompactionEvent>
    ) => void);
}

资料来源：openclaw/src/index.ts:15-27

观测记录捕获机制

工具使用观测

系统通过 PostToolUse 钩子捕获所有工具调用，包括文件读取、编辑、执行命令等操作。 资料来源：cursor-hooks/README.md:1-20

sequenceDiagram
    participant User as 用户
    participant IDE as Claude Code
    participant Hook as 钩子系统
    participant Store as 观测存储
    
    User->>IDE: 执行操作
    IDE->>Hook: PostToolUse 事件
    Hook->>Hook: 提取工具参数和输出
    Hook->>Store: 保存观测记录
    Store-->>Hook: 确认保存
    Hook-->>IDE: 处理完成

文件编辑观测

针对文件修改操作，系统在 afterFileEdit 钩子中捕获变更详情，包括文件路径、修改内容和行号范围。 资料来源：cursor-hooks/README.md:1-20

Shell 命令观测

通过 afterShellExecution 钩子捕获命令行执行结果，记录命令内容、退出码和标准输出/错误。 资料来源：cursor-hooks/README.md:1-20

会话摘要系统

摘要生成流程

graph LR
    A[会话结束] --> B[收集观测记录]
    B --> C[生成摘要请求]
    C --> D[LLM 摘要生成]
    D --> E[解析 XML 格式]
    E --> F[存储摘要]
    
    G[新会话开始] --> H[加载历史摘要]
    H --> I[注入上下文]

摘要内容结构

摘要采用 XML 格式组织，包含以下关键字段： 资料来源：src/sdk/prompts.ts:1-30

摘要格式模板

<summary>
  <request>用户请求内容</request>
  <investigated>调查分析过程</investigated>
  <learned>学习到的内容</learned>
  <completed>完成的工作</completed>
  <next_steps>下一步计划</next_steps>
  <notes>备注信息</notes>
</summary>

资料来源：src/sdk/prompts.ts:1-30

多平台钩子配置

Claude Code 钩子

Claude Code 通过插件系统注册钩子，主要配置文件位于 plugin/hooks/hooks.json。系统支持 Stop 钩子用于会话结束时的摘要生成。 资料来源：cursor-hooks/README.md:1-20

Cursor IDE 钩子

Cursor 通过 shell 脚本实现钩子功能，配置文件包括： 资料来源：cursor-hooks/README.md:20-35

OpenClaw Gateway 钩子

OpenClaw Gateway 采用 TypeScript 接口定义钩子，支持通过 pluginConfig 进行自定义配置，并通过 registerService 注册后台服务。 资料来源：openclaw/src/index.ts:1-50

观测记录数据结构

观测记录模型

interface Observation {
  id: number;                    // 唯一标识符
  eventType: string;             // 事件类型
  tool_name?: string;            // 工具名称
  tool_input?: string;           // 工具输入
  tool_output?: string;          // 工具输出
  sourceAdapter: string;         // 来源适配器
  occurredAtEpoch: number;       // 发生时间戳
  payload?: string;              // 载荷数据
  facts?: string[];              // 提取的事实
  narrative?: string;           // 叙述文本
  concepts?: string[];           // 概念标签
  files_read?: string[];         // 读取的文件
  files_modified?: string[];     // 修改的文件
}

资料来源：src/server/generation/providers/shared/prompt-builder.ts:1-30

代码块去重机制

系统内置代码块去重逻辑，避免重复记录相同的代码段： 资料来源：src/services/smart-file-read/parser.ts:30-50

graph TD
    A[遍历符号] --> B{是代码块?}
    B -->|否| E[跳过]
    B -->|是| C{范围已存在?}
    C -->|否| F[添加到映射]
    C -->|是| D{是匿名块?}
    D -->|是| G[标记为重复]
    D -->|否| H[替换现有块]
    F --> E
    G --> E
    H --> E

上下文注入机制

上下文加载配置

用户可通过环境变量配置上下文加载行为： 资料来源：src/ui/viewer/components/ContextSettingsModal.tsx:1-30

提示词构建

上下文信息通过专门的提示词构建器注入到新会话中： 资料来源：src/sdk/prompts.ts:30-60

graph TD
    A[新会话开始] --> B[加载历史摘要]
    B --> C[构建摘要上下文]
    C --> D[注入 system_identity]
    D --> E[添加 observer_role]
    E --> F[注入 spatial_awareness]
    F --> G[应用 recording_focus]
    G --> H[生成完整提示词]

服务注册与生命周期

后台服务注册

OpenClaw Gateway 支持通过 registerService 注册后台服务，每个服务可以定义启动和停止逻辑： 资料来源：openclaw/src/index.ts:1-15

registerService({
  id: string;
  start: (ctx: PluginServiceContext) => void | Promise<void>;
  stop?: (ctx: PluginServiceContext) => void | Promise<void>;
});

命令注册

插件可以注册自定义命令供用户在 IDE 中调用：

registerCommand({
  name: string;           // 命令名称
  description: string;   // 命令描述
  acceptsArgs?: boolean; // 是否接受参数
  requireAuth?: boolean; // 是否需要认证
  handler: (ctx: PluginCommandContext) => PluginCommandResult;
});

资料来源：openclaw/src/index.ts:1-15

配置管理

钩子设置存储

钩子配置通过 hook-settings.ts 集中管理，支持运行时修改和持久化。 资料来源：cursor-hooks/README.md:20-35

检测机制

系统提供 detectClaudeCode() 函数检测 Claude CLI 是否可用：

export async function detectClaudeCode(): Promise<boolean> {
  // 检查 PATH 中是否存在 claude 命令
  // 或检查 ~/.claude/plugins 目录
}

资料来源：src/services/integrations/CursorHooksInstaller.ts:40-65

最佳实践

观测记录优化

1. 避免重复捕获：利用代码块去重机制减少冗余数据
2. 控制观测数量：通过 CLAUDE_MEM_CONTEXT_OBSERVATIONS 限制注入量
3. 定期清理：配置自动清理策略，避免存储膨胀

性能考虑

1. 异步处理：钩子回调应尽可能异步执行，避免阻塞主流程
2. 批量写入：多个观测记录可批量写入存储
3. 延迟初始化：非关键服务采用延迟加载策略

安全性

1. 数据隔离：确保用户数据存储在隔离目录（如 ~/.claude-mem）
2. 敏感信息过滤：在 tool_result_persist 钩子中过滤敏感输出
3. 访问控制：合理配置 requireAuth 参数

相关文档

• 主项目文档
• Cursor 钩子参考
• 架构概览

概述

Claude-Mem 通过 Model Context Protocol (MCP) 实现与多种 AI Agent 平台的深度集成。MCP 作为连接 AI 助手与外部工具、资源的标准协议，使 claude-mem 能够作为统一的知识记忆层，为不同 IDE 环境（如 Claude Code、OpenClaw、OpenCode 等）提供跨会话的持久化上下文能力。

MCP 集成模块位于 src/server/mcp/ 目录，包含工具注册、资源管理、提示词模板和 MCP 服务器核心实现等组件。资料来源：src/servers/mcp-server.ts:1

架构设计

模块结构

MCP 集成系统由以下核心模块组成：

graph TD
    A[MCP 客户端<br/>Claude Code / OpenClaw / OpenCode] --> B[MCP 服务器<br/>mcp-server.ts]
    B --> C[tools.ts<br/>工具定义]
    B --> D[resources.ts<br/>资源提供]
    B --> E[prompts.ts<br/>提示词模板]
    B --> F[register.ts<br/>注册与生命周期]
    C --> G[记忆存储<br/>SQLite + claude.md]
    D --> G

核心职责

工具系统 (tools.ts)

工具定义

MCP 工具系统允许 AI Agent 通过标准化接口查询和操作记忆数据。工具定义遵循 MCP 协议规范，每个工具包含：

• 名称 (name): 工具的唯一标识符
• 描述 (description): 工具用途说明，供 AI Agent 理解何时调用
• 输入模式 (inputSchema): 工具参数的 JSON Schema 定义

可用工具类型

典型的 MCP 工具包括：

1. 记忆查询工具: 根据时间范围、项目或关键词检索历史观察记录
2. 摘要生成工具: 请求生成特定会话的语义摘要
3. 上下文注入工具: 将检索到的记忆注入到当前会话上下文
4. 项目状态工具: 查询当前项目的已知信息和状态

资料来源：src/server/mcp/tools.ts:1

资源系统 (resources.ts)

资源模型

MCP 资源系统将 claude-mem 的记忆数据以 URI 形式暴露给 AI Agent，支持按需读取：

graph LR
    A[AI Agent] -->|请求资源 URI| B[MCP 服务器]
    B --> C[resources.ts]
    C --> D[SQLite 数据库]
    C --> E[claude.md 文件]

资源 URI 格式

资源使用统一资源标识符进行寻址：

资源缓存策略

资源系统实现了智能缓存机制，避免重复读取相同数据。缓存失效策略与记忆更新事件联动，确保数据一致性。

资料来源：src/server/mcp/resources.ts:1

提示词集成 (prompts.ts)

提示词模板系统

MCP 提示词模块负责生成与记忆相关的上下文模板，帮助 AI Agent 理解如何与记忆系统交互：

• 系统级提示词: 定义 AI Agent 对记忆系统的认知角色
• 查询提示词: 生成结构化的记忆查询指令
• 响应格式提示词: 指定记忆数据的返回格式规范

模板变量

提示词系统支持动态变量注入：

资料来源：src/server/mcp/prompts.ts:1

注册与生命周期 (register.ts)

初始化流程

sequenceDiagram
    participant Host as MCP Host
    participant Server as MCP Server
    participant Registry as register.ts
    participant Store as 记忆存储
    
    Host->>Server: 连接请求
    Server->>Registry: 初始化注册
    Registry->>Registry: 注册工具定义
    Registry->>Registry: 注册资源提供器
    Registry->>Registry: 订阅生命周期事件
    Registry->>Store: 验证连接
    Server-->>Host: 连接就绪

生命周期管理

注册模块负责管理以下生命周期事件：

1. 连接建立: 验证客户端权限，初始化会话上下文
2. 工具调用: 路由工具请求到对应的处理器
3. 资源订阅: 管理资源变更通知
4. 连接断开: 清理会话状态，持久化临时数据

错误处理

注册系统实现了健壮的错误处理机制：

• 工具调用超时自动重试
• 资源不可用时的优雅降级
• 连接异常时的自动重连策略

资料来源：src/server/mcp/register.ts:1

MCP 服务器核心 (mcp-server.ts)

服务器架构

MCP 服务器是整个集成系统的核心入口点，负责：

1. 传输层管理: 处理 STDIO 或 HTTP 传输
2. 协议实现: 遵循 MCP 规范进行消息编解码
3. 请求路由: 将入站请求分发到对应模块
4. 响应序列化: 将处理结果格式化为 MCP 协议格式

启动配置

与其他集成方式的对比

Claude-Mem 支持多种集成方式，MCP 是其中最标准化的方案：

资料来源：src/servers/mcp-server.ts:1

使用场景

跨会话上下文保持

当 AI Agent 在新会话中处理项目时，可以通过 MCP 接口获取历史会话中积累的项目知识：

1. Agent 连接 MCP 服务器
2. 通过资源接口获取项目历史
3. 工具调用检索相关观察记录
4. 上下文注入当前会话

主动记忆增强

通过 MCP 工具， AI Agent 可以在处理复杂任务时主动查询记忆库：

用户请求: 重构 authentication 模块
  ↓
Agent 调用 MCP 工具: search_observations(project, "auth")
  ↓
获取历史修改记录、设计决策
  ↓
生成重构方案时参考历史上下文

多 Agent 知识共享

在 OpenClaw 等多 Agent 环境中，MCP 服务器可作为共享记忆中枢：

• 多个 Agent 实例共享同一记忆存储
• 通过 MCP 资源接口实现跨 Agent 知识传递
• 保持团队协作的上下文连续性

配置与调试

环境变量

状态检查

npx claude-mem status

该命令可验证 MCP 服务器运行状态和连接状态。

安全考虑

数据隔离

• 每个项目的记忆数据相互隔离
• MCP 连接使用项目路径作为会话标识
• 资源访问遵循最小权限原则

敏感信息处理

记忆系统会自动过滤敏感信息（如 API Key、环境变量值），确保只记录语义内容而非凭证数据。

相关文档

• 快速开始指南 - MCP 集成的入门配置
• SDK 文档 - 编程接口参考
• 开发指南 - MCP 模块开发说明

支持的 IDE 环境

claude-mem 支持以下集成目标：

资料来源：src/npx-cli/commands/install.ts

集成架构概览

┌─────────────────────────────────────────────────────────────┐
│                      claude-mem                             │
├─────────────────────────────────────────────────────────────┤
│  CLI 适配层 (src/cli/adapters)                              │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐         │
│  │ ClaudeCode  │ │    Cursor    │ │  GeminiCLI   │         │
│  │   Adapter    │ │   Adapter    │ │   Adapter    │         │
│  └──────┬───────┘ └──────┬───────┘ └──────┬───────┘         │
├─────────┴────────────────┴────────────────┴─────────────────┤
│  集成服务层 (src/services/integrations)                      │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           HookInstaller 抽象工厂                      │   │
│  │  ┌────────────────┐  ┌────────────────┐               │   │
│  │  │ ClaudeHooks    │  │ CursorHooks    │               │   │
│  │  │ Installer      │  │ Installer      │               │   │
│  │  └────────────────┘  └────────────────┘               │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

CLI 适配层

适配层负责检测目标 IDE 环境并提供统一的安装接口。

Claude Code 适配器

Claude Code 通过插件机制集成：

# 通过插件市场安装
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

# 或通过命令行安装
npx claude-mem install

资料来源：README.md

检测机制

集成系统通过多层次检测确定 IDE 环境：

export async function detectClaudeCode(): Promise<boolean> {
  // 1. 检测 CLI 命令是否在 PATH 中
  try {
    const { stdout } = await execAsync('which claude || where claude', { timeout: 5000 });
    if (stdout.trim()) {
      return true;
    }
  } catch (error) {
    logger.debug('WORKER', 'Claude CLI not in PATH', {}, error);
  }

  // 2. 检测插件目录是否存在
  const pluginDir = path.join(CLAUDE_CONFIG_DIR, 'plugins');
  if (existsSync(pluginDir)) {
    return true;
  }

  return false;
}

资料来源：src/services/integrations/CursorHooksInstaller.ts:60-79

Cursor 集成

Cursor IDE 支持通过 Cursor Hooks 机制注入记忆功能：

npx claude-mem install --ide cursor

集成流程包括：

1. 检测 Cursor 安装路径
2. 创建项目级规则目录
3. 生成 claude-mem-context.mdc 上下文文件
4. 注册会话钩子

钩子系统

Claude Code 插件钩子

Claude Code 通过插件系统实现钩子注册，支持以下事件：

Cursor Hooks

Cursor 的钩子系统位于 cursor-hooks 目录，提供项目级别的上下文注入：

interface CursorHook {
  name: string;
  trigger: 'project' | 'session' | 'command';
  handler: (context: HookContext) => void;
}

资料来源：cursor-hooks

模式系统

claude-mem 支持通过模式（Mode）自定义集成行为，不同模式可配置不同的观测类型和提示模板。

内置模式

模式配置

模式定义位于 plugin/modes 目录，每个模式包含：

plugin/modes/
├── code/
│   ├── config.json       # 模式配置
│   ├── prompts.ts        # 提示模板
│   └── observation-types.ts  # 观测类型定义
└── ...

资料来源：plugin/modes

安装流程

统一安装命令

npx claude-mem install [options]

安装状态检测

安装完成后，系统会执行状态检测：

// 检测 worker 服务是否就绪
workerAlive
  ? 显示成功消息 + 访问 URL
  : 显示等待提示 + 手动启动命令

资料来源：src/npx-cli/commands/install.ts

运行时交互

首次使用流程

┌─────────────────────────────────────────────────────────────┐
│ 1. 用户首次启动 IDE                                          │
├─────────────────────────────────────────────────────────────┤
│ 2. 插件检测到新会话                                           │
├─────────────────────────────────────────────────────────────┤
│ 3. 加载历史观测记录 (最近 50 条)                               │
├─────────────────────────────────────────────────────────────┤
│ 4. 显示欢迎提示卡片                                           │
├─────────────────────────────────────────────────────────────┤
│ 5. 用户开始交互，实时生成新观测                                 │
└─────────────────────────────────────────────────────────────┘

记忆注入机制

graph TD
    A[用户会话开始] --> B{检测历史观测}
    B -->|有记录| C[加载最近 N 条观测]
    B -->|无记录| D[显示欢迎卡片]
    C --> E[注入到上下文]
    E --> F[用户交互]
    F --> G[实时生成观测]
    G --> H[存储到本地数据库]
    H --> F
    D --> F
    I[会话结束] --> J[生成摘要]
    J --> H

平台兼容性

macOS / Linux

• 支持 Claude Code、Cursor、Gemini CLI、OpenCode
• 钩子安装到用户目录 ~/.claude-mem
• 使用 Unix socket 通信

Windows

故障排除

常见问题

1. IDE 未检测到

检查 CLI 命令是否在 PATH 中： ``bash which claude # Claude Code which cursor # Cursor ``

1. 钩子未生效

重启 IDE 会话，或手动触发： ``bash npx claude-mem install --force ``

1. 记忆未注入

检查 worker 服务状态： ``bash npx claude-mem status ``

诊断命令

# 检测已安装的钩子
npx claude-mem cursor status

# 重新安装
npx claude-mem install --force

# 查看日志
tail -f ~/.claude-mem/logs/*.log

相关文档

• 快速开始指南
• 故障排除
• 开发指南

概述

Claude-Mem 提供多种安装方式，支持在不同集成环境中部署本插件。安装过程会自动配置后台运行服务（Worker）、数据存储目录以及与 Claude Code 的集成钩子。

安装方式

Claude-Mem 支持以下几种安装途径：

1. NPX 一键安装（推荐）

通过 npx 命令直接安装，这是最简单的方式：

npx claude-mem install

安装完成后，系统会显示欢迎提示，包含以下信息：

• Worker 服务状态（启动中或已就绪）
• 访问本地查看器的 URL
• 后续操作指引

资料来源：README.md:1-30

2. Claude Code 插件市场安装

对于 Claude Code 用户，可以通过内置的 /plugin 命令安装：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

安装完成后需要重启 Claude Code。

资料来源：README.md:30-35

3. Gemini CLI 安装

针对 Gemini CLI 用户，可以指定 --ide 参数：

npx claude-mem install --ide gemini-cli

该命令会自动检测 ~/.gemini 目录并完成配置。

资料来源：README.md:18-22

4. OpenCode 安装

针对 OpenCode 编辑器用户：

npx claude-mem install --ide opencode

资料来源：README.md:25-28

5. OpenClaw Gateway 安装

在 OpenClaw 网关上安装持久化内存插件：

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

资料来源：README.md:45-50

安装流程架构

graph TD
    A[用户执行安装命令] --> B{安装方式}
    B -->|npx claude-mem install| C[初始化配置文件]
    B -->|/plugin install| D[检测 Claude Code 环境]
    B -->|OpenClaw| E[下载安装脚本]
    
    C --> F[启动 Worker 服务]
    D --> F
    E --> G[配置 Gateway]
    
    F --> H[创建 ~/.claude-mem 目录]
    H --> I[注册集成钩子]
    I --> J[安装完成，显示提示]
    
    J --> K[首次启动建议]
    K --> L["方式A: 直接开始工作"]
    K --> M["方式B: 运行 /learn-codebase"]

Worker 服务配置

默认配置

启动状态检测

安装完成后，系统会检查 Worker 服务状态：

workerAlive
  ? [workerHeadline, firstSuccessMessage, twoPathsMessage]
  : [waitMessage, manualStartHint]

资料来源：src/npx-cli/commands/install.ts:10-30

手动启动

如果 Worker 未自动启动，可手动启动：

npx claude-mem start

环境变量配置

安装后提示控制

首次安装后，系统会显示欢迎提示。可通过环境变量禁用：

CLAUDE_MEM_WELCOME_HINT_ENABLED=false

资料来源：src/npx-cli/commands/install.ts:20-25

查看器配置

通过 ContextSettingsModal.tsx 可以配置以下参数：

资料来源：src/ui/viewer/components/ContextSettingsModal.tsx:40-60

卸载说明

卸载前需要关闭所有 Claude Code 会话，否则活动钩子会重新创建配置目录：

npx claude-mem uninstall

注意：关闭所有 Claude Code 会话后再执行卸载，否则 ~/.claude-mem 目录会被重新创建。

资料来源：src/npx-cli/commands/install.ts:15-18

快速验证安装

安装完成后按以下步骤验证：

1. 启动 Claude Code
2. 确认控制台无错误信息
3. 在新项目中输入测试提示
4. 第二次会话时应能看到历史上下文注入

安装方式对比

常见问题

Q: npm install -g claude-mem 是否可行？

不行。通过 npm install -g 安装的是 SDK/库版本，不会注册插件钩子或设置 Worker 服务。必须使用 npx claude-mem install 或 /plugin 命令安装。

资料来源：README.md:36-40

Q: 如何检查服务状态？

npx claude-mem status

Q: Worker 启动后显示等待状态怎么办？

这是正常现象，Worker 启动需要约 30 秒。等待完成后刷新浏览器即可。

资料来源：src/npx-cli/commands/install.ts:35-40

后续步骤

安装完成后，推荐以下两种初始化方式：

方式 A（推荐）：直接开始工作，记忆会从第一次提示中被动构建。

方式 B：运行 /learn-codebase 命令预加载整个代码仓库（约 5 分钟，可选）。

资料来源：src/npx-cli/commands/install.ts:22-28

相关文档

• 使用指南
• 配置选项
• 故障排除

Pitfall Log / 踩坑日志

项目：thedotmack/claude-mem

摘要：发现 24 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Bug: /api/search ignores platformSource, causing Codex MCP search to return Claude/Cursor/null-source memories。

1. 安装坑 · 来源证据：Bug: `/api/search` ignores `platformSource`, causing Codex MCP search to return Claude/Cursor/null-source memories

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: /api/search ignores platformSource, causing Codex MCP search to return Claude/Cursor/null-source memories
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_28646536cf7d499aadab2346c2666f89 | https://github.com/thedotmack/claude-mem/issues/2389 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows: cmd.exe /c uvx wrapper breaks Chroma MCP stdio on WinGet uv installs (regression after #1190 / #1199) --> FIX attacched
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a6c844000d9b4adead4a2fdb73660c8d | https://github.com/thedotmack/claude-mem/issues/2426 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：[Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug] 13.x worker fails with "Cannot find module 'zod/v3'" — package-lock.json missing zod entry
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9e74ac48a1744106a07ff519ad2d2773 | https://github.com/thedotmack/claude-mem/issues/2437 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v13: merged_into_project migration silently skipped on pre-existing DBs (schema_versions ≤ 23)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_510ecb03a1de412f940987e370c68fac | https://github.com/thedotmack/claude-mem/issues/2433 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：Use node to run mcp for windows environment

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Use node to run mcp for windows environment
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_95d37c5d34a749f7a25fdd5fe1dc7969 | https://github.com/thedotmack/claude-mem/issues/2446 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

6. 配置坑 · 来源证据：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：chroma-mcp fails to connect on Windows: cmd.exe misinterprets protobuf<7 as I/O redirection
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_77fdc7c371f042eeb70fbeb52a7a2788 | https://github.com/thedotmack/claude-mem/issues/2438 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 运行坑 · 来源证据：自动运行时突然报下图所示内容，然后插件就不能用了

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：自动运行时突然报下图所示内容，然后插件就不能用了
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2d5aa43a4c5a4e46a0f2122dea46947a | https://github.com/thedotmack/claude-mem/issues/2441 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安全/权限坑 · 来源证据：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Codex CLI plugin hooks consume Claude Code session quota via Claude Code SDK
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8b77cb6420d845a9bd38852571b6adbd | https://github.com/thedotmack/claude-mem/issues/2431 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

9. 安装坑 · 来源证据：Codex CLI: PreToolUse hook returned unsupported suppressOutput

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex CLI: PreToolUse hook returned unsupported suppressOutput
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9022a732f6e54ba39309c5377cf2d8fa | https://github.com/thedotmack/claude-mem/issues/2360 | 来源类型 github_issue 暴露的待验证使用条件。

10. 安装坑 · 来源证据：[feat] Option to load only memory-related skills

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[feat] Option to load only memory-related skills
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_efa30fc4873343aea26f804c8d1113ec | https://github.com/thedotmack/claude-mem/issues/2448 | 来源类型 github_issue 暴露的待验证使用条件。

11. 安装坑 · 来源证据：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：server-beta: ModeManager not initialized — generation jobs fail with 'No mode loaded'
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_757115889024465dbafb2f4ffcbe8356 | https://github.com/thedotmack/claude-mem/issues/2443 | 来源类型 github_issue 暴露的待验证使用条件。

12. 安装坑 · 来源证据：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with "Module not found"

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v12.1.1: hooks/hooks.json references removed scripts/worker-service.cjs — all hooks fail with "Module not found"
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_0e29da4de6004faea2de867f758794f8 | https://github.com/thedotmack/claude-mem/issues/1835 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

13. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | host_targets=claude, claude_code

14. 配置坑 · 来源证据：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：server-beta: runServerBetaCli() default command exits immediately — unusable with systemd
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2613a65b36064bfeb5bbaf9fed69672d | https://github.com/thedotmack/claude-mem/issues/2444 | 来源类型 github_issue 暴露的待验证使用条件。

15. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | README/documentation is current enough for a first validation pass.

16. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | last_activity_observed missing

17. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium

18. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | No sandbox install has been executed yet; downstream must verify before user use.

19. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | no_demo; severity=medium

20. 安全/权限坑 · 来源证据：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Daemon survives plugin disable, burns 500M+ tokens/week with no observable user-facing benefit
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a4e91994a3834fc4a64f07b31ce17242 | https://github.com/thedotmack/claude-mem/issues/2451 | 来源类型 github_issue 暴露的待验证使用条件。

21. 安全/权限坑 · 来源证据：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Long-running Worker endpoints share health-check timeout (HEALTH_TIMEOUT_MS); should use per-endpoint timeouts
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8b61a79c5ae144fcbd7cb8737397dbee | https://github.com/thedotmack/claude-mem/issues/2447 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

22. 安全/权限坑 · 来源证据：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：claude-mem v13.2.0: transcript-watcher.cjs missing from NPM bundle
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c23b4f1758454233a20f5c0653d69d51 | https://github.com/thedotmack/claude-mem/issues/2450 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

23. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | issue_or_pr_quality=unknown

24. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1048065319 | https://github.com/thedotmack/claude-mem | release_recency=unknown