核心定位

memsearch 旨在解决 AI 编码代理在长时间任务中的记忆缺失问题。传统的编码代理每次对话都是全新的上下文窗口，无法主动回忆之前解决过的问题、做过的决策或积累的项目知识。

memsearch 通过三层渐进式检索机制，使代理能够：

• 快速定位历史讨论中的相关片段
• 展开查看完整的 Markdown 段落上下文
• 在必要时回溯原始会话记录

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

核心概念

Markdown 作为事实来源（Source of Truth）

memsearch 坚持 Markdown 文件优先 的设计哲学。所有记忆内容都以 Markdown 格式存储在本地目录中，Milvus 仅作为可重建的影子索引（shadow index）存在。

┌──────────────────────────────────────────────────────────────┐
│                     Memsearch 架构                            │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   Plugins ──→ Markdown 文件 (.memsearch/memory/)             │
│                     │                                       │
│                     ▼                                       │
│              memsearch index → Milvus                       │
│                     │                                       │
│                     ▼                                       │
│              memsearch search ←──── CLI / API                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

这种设计的优势包括：

• 可读性：记忆内容可被人类直接阅读和编辑
• 可移植性：无需依赖专有数据库即可迁移
• 可重建性：Milvus 索引损坏时可通过重新索引完全恢复

资料来源：README.md:65-72

项目级内存隔离

memsearch 默认采用项目级作用域的内存模型。每个项目拥有独立的 .memsearch/memory/ 目录，集合名称从项目路径派生，确保不同项目的记忆相互隔离。

~/.memsearch/memory/
└── ms_project_abc12345/
    ├── memory/
    │   ├── 2026-03-27.md
    │   ├── 2026-03-26.md
    │   └── ...
    └── config.yaml

这种设计使用户能够明确预测和理解记忆的归属范围。资料来源：README.md:75-85

插件生态

memsearch 通过插件层与主流 AI 编码代理集成，目前已支持的平台包括：

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

核心模块

MemSearch 核心类

MemSearch 是库的公共 API 入口，位于 src/memsearch/__init__.py。该类封装了索引、搜索、监控等核心功能。

from memsearch import MemSearch

ms = MemSearch(["./docs", "./memory"])
ms.index()
results = ms.search("如何配置 Milvus")

资料来源：src/memsearch/__init__.py:5-9

文档分块器（Chunker）

分块器负责将 Markdown 文件拆分为语义上有意义的块，便于嵌入和检索。核心策略包括：

• 按标题层级拆分：H1-H6 标题作为自然分界点
• 最小有意义长度：过滤过短的标题段落（_MIN_MEANINGFUL_LEN = 2）
• HTML 注释清理：移除会话 UUID 和转录路径等元数据噪声

def clean_content_for_embedding(text: str) -> str:
    """Strip metadata noise from chunk content before embedding."""
    cleaned = _HTML_COMMENT_RE.sub("", text)
    cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
    return cleaned.strip()

资料来源：src/memsearch/chunker.py:1-30

文件扫描器（Scanner）

scan_paths() 函数递归扫描指定路径，收集 Markdown 文件元数据（路径、修改时间、大小），并支持隐藏文件过滤。

@dataclass(frozen=True)
class ScannedFile:
    """Metadata for a discovered markdown file."""
    path: Path
    mtime: float
    size: int

资料来源：src/memsearch/scanner.py:1-30

文件监控器（Watcher）

基于 watchdog 库实现，支持目录变化监控和防抖（debounce）处理：

资料来源：src/memsearch/watcher.py:1-50

CLI 命令

memsearch CLI 提供以下核心命令：

资料来源：src/memsearch/cli.py:1-50

检索流程

memsearch 采用三层渐进式搜索策略：

graph TD
    A[用户提问] --> B[L1: memsearch search]
    B --> C{需要更多细节?}
    C -->|是| D[L2: memsearch expand]
    D --> E{需要原始对话?}
    E -->|是| F[L3: 解析 transcript]
    C -->|否| G[返回排序结果]
    E -->|否| G
    F --> H[原始对话对话]
    D --> G

第一层：语义搜索

结合向量相似度和 BM25 关键词匹配，返回相关性排序的块列表。

第二层：段落展开

通过 chunk_hash 获取完整 Markdown 段落，可能包含会话锚点注释：

<!-- session:UUID turn:ID db:PATH -->

第三层：原始回溯

解析锚点指向的会话转录文件，返回原始对话记录（含工具调用）。

资料来源：README.md:90-110

配置选项

memsearch 支持丰富的配置项，主要分为以下类别：

嵌入模型配置

Milvus 后端配置

插件配置

各插件支持独立的摘要模型配置：

# 使用原生摘要模型
memsearch config set plugins.codex.summarize.provider native

# 使用外部 LLM 提供者
memsearch config set plugins.codex.summarize.provider openai
memsearch config set plugins.codex.summarize.model gpt-4o-mini

资料来源：plugins/codex/README.md:1-40

已知限制与社区问题

已识别的技术债务

社区功能请求

• 全局/个人记忆（#337）：在项目级内存之外增加跨项目共享的个人知识库
• 自动记忆精炼（#523）：防止文档腐烂，将流水账式日记转化为结构化知识

资料来源：README.md:120-140

快速开始

安装

# 通过 uv 安装
uv tool install memsearch

# 或通过 pip 安装
pip install memsearch

初始化

# 全局配置
memsearch config init

# 项目级配置
memsearch config init --project

基本使用

# 索引当前目录
memsearch index .

# 搜索记忆
memsearch search "上次如何解决 CORS 问题"

# 监控变化
memsearch watch ./memory ./docs

版本历史

资料来源：mkdocs.yml:1-10

系统要求

安装

通过 uv 安装（推荐）

uv tool install memsearch

通过 pip 安装

pip install memsearch

安装完成后，验证版本：

memsearch --version

资料来源：pyproject.toml

核心概念

架构概览

graph TD
    subgraph 用户层
        A[Markdown 文件] --> B[memsearch CLI]
        B --> C[搜索结果]
    end
    
    subgraph 处理层
        D[scanner.py 扫描文件] --> E[chunker.py 分块]
        E --> F[嵌入模型生成向量]
    end
    
    subgraph 存储层
        G[Milvus Lite .db 文件] --> H[向量索引]
        G --> I[集合管理]
    end
    
    F --> G

memsearch 的核心数据流：

1. 扫描：scanner.py 递归扫描指定路径下的 .md 和 .markdown 文件
2. 分块：chunker.py 按标题层级将文件切分为语义块
3. 嵌入：使用 ONNX 本地模型（默认 bge-m3）或 OpenAI API 生成向量
4. 索引：将分块内容及其向量存储到 Milvus 集合

资料来源：src/memsearch/scanner.py:1-50

分块机制

chunker.py 实现基于标题层级的智能分块：

• 支持 # 到 ###### 六级标题作为分块边界
• 自动移除 HTML 注释（包含会话 UUID 和转录路径）
• 过滤无意义内容（如仅有标题无正文的章节）
• 可配置最大分块大小

_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)
_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)

资料来源：src/memsearch/chunker.py:1-30

交互式配置

首次使用前，运行配置向导：

memsearch config init

配置向导将依次询问：

项目级配置

在当前目录初始化项目级配置：

memsearch config init --project

项目级配置存储在 .memsearch/config.toml，自动以目录名为基础派生集合名称。

手动配置命令

# 设置单个配置项
memsearch config set embedding.provider openai
memsearch config set milvus.uri http://localhost:19530

# 查看当前配置
memsearch config list

# 获取特定配置
memsearch config get embedding.provider

资料来源：src/memsearch/cli.py:1-100

基础使用

索引操作

#### 索引当前目录

memsearch index .

该命令扫描当前目录及子目录中的所有 Markdown 文件，将内容分块并写入 Milvus。

#### 索引指定路径

memsearch index ./docs ./memory

#### 索引单个文件

memsearch index ./README.md

搜索操作

#### 语义搜索

memsearch search "如何配置嵌入模型"

返回与查询语义最相关的分块列表，按相关性排序。

#### 展开分块

获取分块的完整上下文：

memsearch expand <chunk_hash>

chunk_hash 来自搜索结果。

查看统计信息

memsearch stats

显示当前集合的索引块数量。

注意：如果集合名称仅在配置文件中设置，stats 命令可能显示 0 块。请显式使用 -c 参数指定集合。

文件监控

启动实时监控，自动增量索引变更：

memsearch watch . --debounce-ms 1500

监控器使用 watchdog 检测文件变化，经过指定延迟后触发增量索引。

sequenceDiagram
    participant U as 用户
    participant W as Watcher
    participant M as Milvus
    participant FS as 文件系统
    
    U->>W: memsearch watch .
    W->>FS: 监控目录变化
    U->>FS: 修改 memory/2026-03-27.md
    FS->>W: 文件变更事件
    W->>W: 延迟 1500ms
    W->>M: 增量索引变更

资料来源：src/memsearch/watcher.py:1-60

插件集成

memsearch 提供针对主流 AI 编码代理的插件支持：

Claude Code 插件

Claude Code 插件在每次会话结束时自动捕获记忆摘要：

graph LR
    A[用户提问] --> B[Agent 响应]
    B --> C[Stop Hook 触发]
    C --> D[解析最后对话轮次]
    D --> E[LLM 摘要 haiku]
    E --> F[追加到 memory/日期.md]
    F --> G[memsearch index]

插件使用会话锚点标记记忆位置，支持后续精确召回原始对话。

安装后需要重启 Claude Code 会话以加载新状态。

资料来源：README.md

配置摘要模型

插件的摘要模型可独立配置：

# 使用 Codex 原生摘要模型
memsearch config set plugins.codex.summarize.model gpt-5.1-codex-mini

# 使用 OpenAI 模型
memsearch config set plugins.codex.summarize.provider openai
memsearch config set plugins.codex.summarize.model gpt-5-mini

常见问题

Milvus Lite 集合状态问题

使用 Milvus Lite（本地 .db 文件）时，memsearch search 可能失败并提示集合处于 released 状态：

pymilvus.exceptions.MilvusException: Collection 'xxx' is in state 'released'

解决方案：启动 memsearch watch 进程保持集合加载状态，或使用远程 Milvus 服务器。

索引内存泄漏

使用 ONNX 提供商索引大型语料库时，可能出现内存线性增长。每个分块约消耗 9MB 内存。建议对大型语料库分批处理或重启进程。

配置优先级

命令行参数 > 项目配置（.memsearch/config.toml）> 全局配置（~/.memsearch/config.toml）

下一步

核心文件速查

资料来源：src/memsearch/__init__.py:1-10

概述

MemSearch 是一个跨平台的语义记忆系统，专为 AI 编码代理设计，采用 Markdown 文件作为核心存储，Milvus 作为可重建的向量索引后端。项目仓库位于 zilliztech/memsearch。

核心设计理念：Markdown 是唯一的事实来源（Source of Truth），Milvus 仅作为可重建的影子索引存在。当 Milvus 数据丢失时，可通过重新索引 Markdown 文件完整恢复所有数据。

资料来源：docs/architecture.md

核心架构分层

MemSearch 采用清晰的分层架构，从下到上依次为：

    subgraph 插件层["插件层 (Plugins)"]
        A1[Claude Code 插件]
        A2[Codex 插件]
        A3[OpenClaw 插件]
        A4[OpenCode 插件]
    end
    
    subgraph CLI_API层["CLI / Python API 层"]
        B1[memsearch CLI 命令]
        B2[MemSearch Python 类]
    end
    
    subgraph 核心功能层["核心功能层 (src/memsearch/)"]
        C1[core.py - 核心编排]
        C2[chunker.py - Markdown 分块]
        C3[scanner.py - 文件扫描]
        C4[watcher.py - 文件监控]
    end
    
    subgraph 存储层["存储层 (Storage)"]
        D1[Markdown 文件系统]
        D2[Milvus 向量数据库]
    end
    
    subgraph 向量模型层["向量模型层"]
        E1[ONNX (bge-m3)]
        E2[OpenAI Embeddings]
    end
    
    A1 --> B1
    A2 --> B1
    A3 --> B1
    A4 --> B1
    B1 <--> B2
    B2 --> C1
    C1 --> C2
    C1 --> C3
    C1 --> C4
    C2 --> D1
    C3 --> D1
    C4 --> D1
    C2 --> E1
    C2 --> E2
    C2 --> D2

资料来源：docs/architecture.md

核心模块详解

核心编排 (core.py)

MemSearch 类是系统的核心编排器，负责协调文件扫描、分块、嵌入生成和 Milvus 存储操作。

资料来源：src/memsearch/core.py

Markdown 分块 (chunker.py)

chunker.py 负责将 Markdown 文件语义化拆分为可索引的块。

核心流程：

    A[Markdown 文件] --> B[按标题层级解析]
    B --> C{标题级别变化?}
    C -->|是| D[创建新块]
    C -->|否| E[追加到当前块]
    D --> F{块大小超限?}
    E --> F
    F -->|是| G[拆分块]
    F -->|否| H[验证内容质量]
    G --> H
    H --> I{内容有意义?}
    I -->|否| J[丢弃块]
    I -->|是| K[生成块哈希]
    K --> L[准备索引]

关键函数：

资料来源：src/memsearch/chunker.py

文件扫描 (scanner.py)

scanner.py 实现多路径递归扫描，发现需要索引的 Markdown 文件。

@dataclass(frozen=True)
class ScannedFile:
    """发现的 Markdown 文件元数据"""
    path: Path
    mtime: float  # 修改时间
    size: int     # 文件大小

扫描特性：

• 支持目录递归遍历
• 可配置扩展名过滤（默认 .md、.markdown）
• 可选忽略隐藏文件/目录（以 . 开头）
• 基于路径的去重机制

资料来源：src/memsearch/scanner.py

文件监控 (watcher.py)

使用 watchdog 库实现文件系统监控，支持增量索引更新。

class _MarkdownHandler(FileSystemEventHandler):
    """调度 Markdown 文件事件到回调函数，带防抖机制"""

工作原理：

1. 监听文件系统的 created、modified、deleted 事件
2. 对同一文件的连续事件进行防抖合并
3. 触发回调时携带事件类型和文件路径

资料来源：src/memsearch/watcher.py

数据流架构

索引流程

    A[文件扫描] --> B[文件读取]
    B --> C[Markdown 解析]
    C --> D[语义分块]
    D --> E[内容清理]
    E --> F[嵌入生成]
    F --> G[块哈希计算]
    G --> H[Milvus 存储]
    H --> I[Markdown 源文件]

搜索流程

    A[用户查询] --> B[查询嵌入]
    B --> C[Milvus 向量搜索]
    A --> D[BM25 关键词匹配]
    C --> E[混合排序]
    D --> E
    E --> F[结果排名]
    F --> G[返回 chunk_hash]

资料来源：docs/architecture.md

存储模型

Markdown 文件组织

.memsearch/
└── memory/
    └── YYYY-MM-DD.md    # 按日期组织的记忆文件

每个记忆文件包含带锚点注释的会话记录：

## Session 14:32

- User asked about X
- Claude did Y

<!-- session:UUID db:PATH -->

Milvus 集合结构

集合名称通过项目目录名派生，格式为 ms_<项目标识>。

资料来源：src/memsearch/core.py

向量模型层

# 切换到 OpenAI 嵌入
memsearch config set embedding.provider openai

# 切换回本地 ONNX
memsearch config set embedding.provider onnx

资料来源：plugins/codex/README.md

CLI 命令体系

资料来源：src/memsearch/cli.py

插件架构

通用插件结构

    subgraph 插件类型["插件类型"]
        P1[Claude Code]
        P2[Codex]
        P3[OpenClaw]
        P4[OpenCode]
    end
    
    subgraph 组件["每个插件包含"]
        C1[Stop Hook - 会话总结]
        C2[Start Hook - 会话开始]
        C3[Memory Tools - 搜索/展开/对话]
        C4[Skills - 配置引导]
        C5[Prompts - 项目回顾模板]
    end
    
    P1 --> C1
    P1 --> C2
    P1 --> C3
    P1 --> C4
    P1 --> C5

捕获流程（以 Claude Code 为例）

用户提问 → Agent 响应 → Stop Hook 触发
                          │
         ┌────────────────┴────────────────┐
         ▼                                    
    解析最后对话轮次                        
         │                                    
    LLM 总结 (haiku 模型)                   
    "- User asked about X."                
    "- Claude did Y."                       
         │                                    
    追加到 memory/YYYY-MM-DD.md             
    (带 <!-- session:UUID --> 锚点)         
         │                                    
    memsearch index → Milvus               

三层召回机制

资料来源：README.md

配置系统

配置层级

graph TD
    A[默认配置] --> B[全局配置 ~/.memsearch/config.toml]
    B --> C[项目配置 ./.memsearch/config.toml]
    C --> D[CLI 参数覆盖]

关键配置项

资料来源：src/memsearch/cli.py

已知限制与社区问题

资料来源：社区问题追踪

扩展阅读

• 设计理念 - 深入了解项目的核心设计决策
• Python API - MemSearch 类的详细 API 参考
• CLI 参考 - 命令行工具完整文档
• 平台对比 - 各代理插件的功能对比

概述

memsearch 是一个跨平台的语义记忆搜索系统，专为 AI 编程代理设计，采用 Markdown 文件作为数据源，Milvus 作为向量检索后端。系统采用分层架构，底层是 CLI/API 核心层，上层是插件生态层。

graph TB
    subgraph 插件层
        CLAUDE[Claude Code 插件]
        CODEX[Codex 插件]
        OPENCLAW[OpenClaw 插件]
        OPENCODE[OpenCode 插件]
    end
    
    subgraph 核心层
        CLI[CLI 模块]
        CORE[MemSearch 核心类]
        CONFIG[配置管理]
    end
    
    subgraph 索引层
        SCANNER[文件扫描器]
        CHUNKER[Markdown 分块器]
        WATCHER[文件监视器]
    end
    
    subgraph 存储层
        MILVUS[Milvus Store]
        MARKDOWN[Markdown 文件]
    end
    
    CLAUDE --> CLI
    CODEX --> CLI
    OPENCLAW --> CLI
    OPENCODE --> CLI
    CLI --> CORE
    CORE --> CONFIG
    CORE --> SCANNER
    CORE --> CHUNKER
    CORE --> WATCHER
    SCANNER --> MARKDOWN
    CHUNKER --> MILVUS
    WATCHER --> MARKDOWN

MemSearch 核心类

类定义与职责

MemSearch 是整个系统的核心入口类，封装了索引、搜索、配置等核心功能：

"""memsearch — semantic memory search for markdown knowledge bases."""

from .core import MemSearch

__all__ = ["MemSearch"]

资料来源：src/memsearch/__init__.py:1-5

核心类提供了统一的 API 接口，负责：

• 加载和合并配置（全局配置 + 项目配置）
• 管理 Milvus 集合的生命周期
• 协调扫描、分块、嵌入、存储等流程
• 提供搜索和查询接口

配置管理架构

memsearch 采用多层配置合并策略：

graph LR
    GLOBAL[全局配置<br/>~/.memsearch/config.toml] --> MERGE[配置合并]
    PROJECT[项目配置<br/>.memsearch/config.toml] --> MERGE
    ENV[环境变量] --> MERGE
    MERGE --> FINAL[最终配置]
    FINAL --> CORE[MemSearch 实例]

配置系统支持以下配置项：

文件扫描器 (Scanner)

功能定位

scanner.py 模块负责递归扫描指定路径，收集 Markdown 文件元数据：

@dataclass(frozen=True)
class ScannedFile:
    """Metadata for a discovered markdown file."""

    path: Path
    mtime: float
    size: int

资料来源：src/memsearch/scanner.py:10-14

扫描函数签名

def scan_paths(
    paths: list[str | Path],
    *,
    extensions: tuple[str, ...] = (".md", ".markdown"),
    ignore_hidden: bool = True,
) -> list[ScannedFile]:

扫描流程

graph TD
    START[scan_paths 调用] --> FOR_LOOP[遍历 paths 列表]
    FOR_LOOP --> IS_DIR{根路径是<br/>目录?}
    IS_DIR -->|是| WALK[os.walk 递归遍历|
    IS_DIR -->|否| IS_FILE{是文件?}
    IS_FILE -->|是| CHECK_EXT{扩展名匹配?}
    CHECK_EXT -->|是| ADD[添加到结果列表]
    CHECK_EXT -->|否| SKIP[跳过]
    WALK --> CHECK_HIDDEN{忽略隐藏?}
    CHECK_HIDDEN -->|是| FILTER_DIRS[过滤隐藏目录]
    CHECK_HIDDEN -->|否| KEEP_ALL[保持原样]
    FILTER_DIRS --> FOR_FILES[遍历目录文件]
    FOR_FILES --> CHECK_HIDDEN_FILES{忽略隐藏文件?}
    CHECK_HIDDEN_FILES -->|是| FILTER_FILES[过滤隐藏文件]
    CHECK_HIDDEN_FILES -->|否| CHECK_EXT2[检查扩展名]
    FILTER_FILES --> CHECK_EXT3[检查扩展名]
    CHECK_EXT2 --> ADD2[添加到结果]
    CHECK_EXT3 --> ADD3[添加到结果]
    ADD --> SORT[按路径排序]
    ADD2 --> SORT
    ADD3 --> SORT
    SKIP --> END{遍历完成?}
    SORT --> END
    END --> RETURN[返回结果列表]

关键特性：

• 使用 seen 集合进行去重，防止同一文件被多次添加
• 支持自定义扩展名过滤
• 可选择性忽略 . 开头的隐藏文件/目录
• 按文件路径排序返回结果

Markdown 分块器 (Chunker)

功能定位

chunker.py 模块负责将 Markdown 文件按语义结构拆分为可索引的分块：

"""Markdown chunking — split markdown files into semantic chunks by headings."""

资料来源：src/memsearch/chunker.py:1-2

核心正则表达式

内容清洗

def clean_content_for_embedding(text: str) -> str:
    """Strip metadata noise from chunk content before embedding.

    Removes HTML comments (<!-- ... -->), which often contain session/turn
    UUIDs and transcript paths that dilute embedding quality.  The original
    content stored in Milvus is unchanged — this only affects the text
    sent to the embedding model.
    """
    cleaned = _HTML_COMMENT_RE.sub("", text)
    # Collapse runs of blank lines left behind by removed comments
    cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
    return cleaned.strip()

资料来源：src/memsearch/chunker.py:15-24

内容质量过滤

_MIN_MEANINGFUL_LEN = 2

def _has_meaningful_content(text: str) -> bool:
    """Return True if *text* has enough substance to be worth indexing."""

资料来源：src/memsearch/chunker.py:10-11

系统会丢弃符合以下条件的分块：

• 仅包含标题无正文内容
• HTML 注释、标题行、空白字符剥离后剩余长度不足 2 字符
• 无实质语义内容

分块策略

graph LR
    MD[Markdown 文件] --> PARSE[解析标题结构]
    PARSE --> TREE[构建嵌套树]
    TREE --> SPLIT[按 H1-H6 层级拆分]
    SPLIT --> FILTER[过滤无意义分块]
    FILTER --> CLEAN[清理 HTML 注释]
    CLEAN --> CHUNKS[语义分块列表]

文件监视器 (Watcher)

功能定位

watcher.py 模块使用 watchdog 库监控文件系统变化，实现增量索引：

"""File watcher — monitors directories for markdown changes using watchdog."""

资料来源：src/memsearch/watcher.py:1-2

核心类设计

class _MarkdownHandler(FileSystemEventHandler):
    """Dispatch markdown file events to a callback with debounce."""

    def __init__(
        self,
        callback: Callable[[str, Path], None],
        extensions: tuple[str, ...] = (".md", ".markdown"),
        debounce_ms: int = DEFAULT_DEBOUNCE_MS,
    ) -> None:

防抖机制

sequenceDiagram
    participant FS as 文件系统事件
    participant WH as WatchHandler
    participant Timer as 定时器
    participant CB as 回调函数

    FS->>WH: on_modified(file.md)
    WH->>Timer: 创建/重置 Timer
    Note over Timer: 等待 debounce_ms
    Timer->>CB: 触发回调
    Note over CB: 处理文件变化

默认防抖延迟为 1500ms，用于：

• 避免同一文件的连续修改触发多次处理
• 等待文件写入完成后再处理

线程安全

self._timers: dict[str, threading.Timer] = {}
self._pending: dict[str, str] = {}  # path -> latest event_type
self._lock = threading.Lock()

使用 threading.Lock 保护共享状态，防止竞态条件。

CLI 模块

命令行接口结构

cli.py 模块提供完整的命令行界面，支持交互式配置初始化：

# 交互式配置示例
result["plugins"]["claude-code"]["summarize"]["enabled"] = click.confirm(
    "  Claude Code summarization enabled",
    default=current.plugins.claude_code.summarize.enabled,
)
result["plugins"]["codex"]["summarize"]["provider"] = click.prompt(
    "  Codex summarize provider",
    default=current.plugins.codex.summarize.provider,
)

主要命令

配置项详情

系统支持对各平台插件的摘要模型进行独立配置：

数据模型

ScannedFile 数据类

@dataclass(frozen=True)
class ScannedFile:
    """Metadata for a discovered markdown file."""

    path: Path        # 文件绝对路径
    mtime: float      # 修改时间戳
    size: int         # 文件大小（字节）

配置数据模型

已知问题与限制

根据社区反馈，以下问题值得关注：

内存泄漏问题

Issue #533 报告使用 ONNX 提供者索引时存在内存泄漏，每分块约消耗 9MB 内存，在 15GB 内存主机上会导致 OOM。

Milvus Lite 集合状态

Issue #540 报告在非活跃会话中使用 Milvus Lite 时，memsearch search 可能因集合处于 "released" 状态而失败，需要手动调用 load()。

重复主键

Issue #539 报告批量索引时可能出现 "duplicate primary keys" 错误。

配置继承

Issue #538 报告 memsearch stats 在仅设置配置文件中的 collection name 时显示 0 分块，需显式传递 -c 参数。

模块依赖关系

graph TD
    INIT["__init__.py<br/>MemSearch 导出"]
    CORE["core.py<br/>MemSearch 核心类"]
    CONFIG["config.py<br/>配置管理"]
    SCANNER["scanner.py<br/>文件扫描"]
    CHUNKER["chunker.py<br/>Markdown 分块"]
    WATCHER["watcher.py<br/>文件监视"]
    CLI["cli.py<br/>命令行界面"]
    STORE["store.py<br/>Milvus 存储"]

    INIT --> CORE
    CORE --> CONFIG
    CORE --> SCANNER
    CORE --> CHUNKER
    CORE --> WATCHER
    CORE --> STORE
    CLI --> CORE

扩展指南

添加新的嵌入提供者

1. 在 config.py 中添加新提供者的配置项
2. 在 core.py 中实现提供者初始化逻辑
3. 更新 embedding/ 目录下的提供者实现

自定义分块策略

修改 chunker.py 中的分块逻辑：

• 调整 _HEADING_RE 正则以改变标题层级
• 修改 _MIN_MEANINGFUL_LEN 以过滤不同长度阈值
• 在 clean_content_for_embedding 中添加额外的清洗规则

核心架构概览

graph TD
    A[Markdown 文件] --> B[scanner.py 扫描文件]
    B --> C[chunker.py 按标题分块]
    C --> D[clean_content_for_embedding 清洗内容]
    D --> E[生成向量嵌入]
    E --> F[MilvusStore 写入 Milvus]
    F --> G[向量数据库索引]
    
    H[搜索请求] --> I[向量检索 + BM25 混合搜索]
    I --> J[返回排序结果]

文件扫描模块

ScannedFile 数据结构

文件扫描由 scanner.py 中的 ScannedFile 数据类定义元数据：

@dataclass(frozen=True)
class ScannedFile:
    path: Path
    mtime: float
    size: int

scan_paths 扫描函数

scan_paths() 函数支持多路径递归扫描，核心参数如下：

关键行为：

• 支持文件和目录混合输入
• 目录递归遍历时自动过滤以 . 开头的隐藏文件/目录
• 通过 seen 集合实现去重，避免同一文件被多次处理
• 结果按文件路径排序返回

def scan_paths(
    paths: list[str | Path],
    *,
    extensions: tuple[str, ...] = (".md", ".markdown"),
    ignore_hidden: bool = True,
) -> list[ScannedFile]:

资料来源：src/memsearch/scanner.py:12-47

Markdown 分块机制

分块策略

chunker.py 实现基于标题层级的语义分块，使用正则表达式识别 Markdown 标题：

_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)

分块逻辑遵循以下原则：

1. 按标题层级切分：每个 H1-H6 标题下方的内容成为一个独立的语义块
2. 保留层级结构：包含标题本身的文本片段作为块的起始内容
3. 过滤无意义内容：标题后无实际内容的空块被丢弃

内容清洗与过滤

#### clean_content_for_embedding 函数

在生成向量嵌入前，内容需要经过清洗以提高嵌入质量：

def clean_content_for_embedding(text: str) -> str:
    """Strip metadata noise from chunk content before embedding."""
    cleaned = _HTML_COMMENT_RE.sub("", text)
    cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
    return cleaned.strip()

清洗步骤：

注意：此函数仅影响发送给嵌入模型的内容，存储在 Milvus 中的原始内容不受影响。

#### _has_meaningful_content 函数

分块前会验证内容是否有足够的信息量：

_MIN_MEANINGFUL_LEN = 2

def _has_meaningful_content(text: str) -> bool:
    """Return True if text has enough substance to be worth indexing."""
    stripped = _HTML_COMMENT_RE.sub("", text)
    # ... further processing

判断标准：

• 移除 HTML 注释后
• 过滤标题行和空白
• 剩余正文长度需超过 _MIN_MEANINGFUL_LEN（默认 2 字符）

例如：

• ## Session 03:16 → 标题后无正文 → 拒绝
• ## Title\nSome real content → 有实际内容 → 保留

分块数据流

flowchart LR
    A[原始 Markdown] --> B[解析标题层级]
    B --> C{内容有意义?}
    C -->|是| D[生成 Chunk 对象]
    C -->|否| E[丢弃]
    D --> F[clean_content_for_embedding]
    F --> G[生成向量嵌入]
    G --> H[Upsert 到 Milvus]

索引存储机制

MilvusStore 数据存储

索引数据通过 MilvusStore 类管理，关键字段包括：

向量生成与写入流程

1. 文件扫描：递归发现 .md 和 .markdown 文件
2. 增量检测：基于 mtime 字段判断文件是否变更
3. 分块处理：按标题切分为语义块
4. 内容清洗：移除 HTML 注释和噪声
5. 向量生成：调用嵌入模型生成向量表示
6. 批量写入：通过 upsert 写入 Milvus

async def upsert(self, chunks: list[dict[str, Any]]) -> int:
    """Upsert chunks and return count of successfully indexed chunks."""

资料来源：src/memsearch/store.py

已知限制与社区问题

#### 内存泄漏问题（Issue #533）

大规模语料库索引时存在内存泄漏：

indexing a multi-MB markdown corpus with the ONNX provider walks anon-rss to ~11.5 GB and the kernel OOM-kills the process

现象：

• 每个 chunk 约泄漏 9 MB anon-rss
• 单进程内内存线性增长
• 进程重启后内存正常释放

#### 重复主键错误（Issue #539）

同一批次内不允许重复的主键：

duplicate primary keys are not allowed in the same batch: invalid parameter

当索引过程中同一文件被多次扫描或 chunk hash 冲突时触发。

#### 写入持久性问题（Issue #534）

远程 Milvus 2.5+ 的写入可能未真正持久化：

MilvusStore.upsert() reports success but writes are not durable on remote Milvus 2.5+

upsert 返回成功计数，但底层写入可能未真正持久化到 Milvus。

维护与压缩

compact_chunks 压缩机制

compact.py 提供了 LLM 驱动的块压缩功能：

async def compact_chunks(
    chunks: list[dict[str, Any]],
    *,
    llm_provider: str = "openai",
    model: str | None = None,
    prompt_template: str | None = None,
    base_url: str | None = None,
    api_key: str | None = None,
) -> str:

支持的 LLM 提供商：

默认压缩提示词：

You are a knowledge compression assistant. Given the following chunks of text \
from a knowledge base, create a concise but comprehensive summary that preserves \
all key facts, decisions, code patterns, and actionable insights.

compaction 状态标记

压缩前的转录内容可能在压缩后丢失（Issue #537）：

Pre-compaction transcript not captured by Stop hook?

Stop 钩子的 parse-transcript.sh 在压缩完成后运行，导致压缩前的转录被 isCompactSummary 标记替代，原始对话细节丢失。

配置与调优

CLI 索引选项

memsearch index <paths> [options]

watch 模式

持续监控文件变更并自动重索引：

memsearch watch <paths> --debounce-ms 5000

变更检测基于 ScannedFile 中的 mtime 字段，实现增量更新。

故障排查

相关文档

• memsearch 架构 - 系统整体架构
• 配置指南 - 嵌入和 Milvus 配置
• 故障排查 - 常见问题解决方案
• 插件系统 - Claude Code 等平台的集成

概述

MemSearch 的检索系统是一个混合检索引擎，结合了向量语义搜索和关键词 BM25 搜索，以提供高质量的语义记忆召回能力。系统以 Markdown 文件为数据源，通过语义分块将内容切分为可索引的 chunk，然后存储到 Milvus 向量数据库中进行高效检索。

检索流程遵循三层递进架构：L1 语义检索获取候选 chunk，L2 展开完整段落，L3 解析原始会话转录。资料来源：README.md

核心检索流程

搜索执行流程

用户查询 → 查询向量生成 → 混合检索 → 重排序 → 结果返回

MemSearch 支持两种后端模式：

已知限制：当使用 Milvus Lite 时，collection 默认处于 released 状态，需调用 load() 后才能执行搜索/查询操作。CLI search 在非活跃会话/watch 进程外执行时会失败。资料来源：社区 issue #540

配置文件解析流程

检索系统依赖配置解析来确定 collection 名称和连接参数：

def _safe_resolve_config(overrides: dict[str, Any] | None) -> Config:
    """解析配置，优先使用命令行覆盖值"""

已知问题：当 collection 名称仅在配置文件中设置时，memsearch stats 可能报告 0 chunks，即使数据已成功索引。必须显式传递 -c 参数才能正确识别 collection。资料来源：社区 issue #538

数据模型与索引结构

Chunk 数据结构

@dataclass
class Chunk:
    chunk_hash: str      # 内容 SHA256 哈希
    content: str        # 原始 Markdown 内容
    path: Path          # 来源文件路径
    mtime: float        # 文件修改时间
    start_line: int     # 起始行号
    end_line: int       # 结束行号

分块算法

Markdown 分块器 (chunker.py) 负责将文档切分为语义连贯的块：

_HEADING_RE = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)
_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
_MIN_MEANINGFUL_LEN = 2  # 最小有意义内容长度

关键处理逻辑：

1. 标题识别：使用正则 ^(#{1,6})\s+(.+)$ 匹配 1-6 级标题作为分块边界
2. HTML 注释过滤：移除 <!-- ... --> 注释块，防止会话 UUID 等噪声干扰嵌入质量
3. 内容验证：_has_meaningful_content() 检查块是否有足够的实质内容

def clean_content_for_embedding(text: str) -> str:
    """为嵌入模型清理内容 - 移除元数据噪声"""
    cleaned = _HTML_COMMENT_RE.sub("", text)
    cleaned = re.sub(r"\n{3,}", "\n\n", cleaned)
    return cleaned.strip()

资料来源：src/memsearch/chunker.py:1-45

嵌入向量生成

嵌入模块负责将文本 chunk 转换为高维向量：

# 配置嵌入提供商
memsearch config set embedding.provider onnx   # 本地默认
memsearch config set embedding.provider openai  # 需要 OPENAI_API_KEY

资料来源：plugins/codex/README.md

文件扫描与索引

扫描器架构

@dataclass(frozen=True)
class ScannedFile:
    path: Path    # 文件路径
    mtime: float  # 修改时间
    size: int     # 文件大小

扫描策略：

• 递归遍历指定路径，收集 .md 和 .markdown 文件
• 默认跳过隐藏文件/目录（以 . 开头）
• 支持多路径同时扫描

def scan_paths(
    paths: list[str | Path],
    *,
    extensions: tuple[str, ...] = (".md", ".markdown"),
    ignore_hidden: bool = True,
) -> list[ScannedFile]:

资料来源：src/memsearch/scanner.py:1-45

增量索引机制

MemSearch 支持增量索引，仅处理自上次索引后修改的文件：

class _MarkdownHandler(FileSystemEventHandler):
    def __init__(self, callback, debounce_ms=1500):
        self._debounce_s = debounce_ms / 1000.0
        self._timers: dict[str, threading.Timer] = {}

资料来源：src/memsearch/watcher.py:1-45

向量存储与查询

MilvusStore 实现

MilvusStore 负责向量数据的持久化和查询：

class MilvusStore:
    def upsert(self, chunks: list[Chunk]) -> int:
        """写入 chunks，返回成功数量"""
    
    def search(self, query_vector: list[float], top_k: int) -> list[SearchResult]:
        """向量相似度搜索"""
    
    def get_collection_stats(self) -> dict:
        """获取 collection 统计信息"""

已知问题：在远程 Milvus 2.5+ 环境中，upsert() 可能报告成功但数据未真正持久化，缺少 flush() 调用。memsearch index 报告的 chunk 数量可能与 get_collection_stats() 返回的 row_count 不一致。资料来源：社区 issue #534

搜索结果格式

@dataclass
class SearchResult:
    chunk_hash: str    # 用于 expand 命令的标识符
    content: str       # 匹配的 chunk 内容
    score: float       # 相似度分数
    path: Path          # 来源文件路径
    start_line: int     # 起始行
    end_line: int       # 结束行

CLI 检索命令

search 子命令

memsearch search <query> [options]

# 常用选项
-c, --collection    # 指定 collection 名称
--limit            # 返回结果数量（默认 10）
--output           # 输出格式 (json/text)

expand 子命令

根据 search 返回的 chunk_hash 展开完整段落：

memsearch expand <chunk_hash> [options]

# 示例
memsearch expand abc123def456 --collection my_collection

三层递进检索模式

用户: "我们讨论过关于批处理大小的问题吗？"
         │
         ▼
┌─────────────────────────────────────┐
│ L1: memsearch search "批处理大小"    │
│     → 返回语义相关 chunks            │
└─────────────────────────────────────┘
         │ (需要更多详情？)
         ▼
┌─────────────────────────────────────┐
│ L2: memsearch expand <chunk_hash>   │
│     → 返回完整 .md 段落              │
└─────────────────────────────────────┘
         │ (需要原始对话？)
         ▼
┌─────────────────────────────────────┐
│ L3: 解析 session.jsonl 原始转录     │
│     → 返回原始对话内容               │
└─────────────────────────────────────┘

性能优化与限制

内存管理

已知问题：使用 ONNX 提供者索引时，每个 chunk 泄漏约 9MB anon-rss 内存。索引多 MB 的 Markdown 语料库时，内存可能线性增长至 11.5GB，导致 OOM。资料来源：社区 issue #533

CJK 分词支持

当前检索系统在中文（CJK）语境下存在 tokenization 缺陷，影响信息检索效果。建议使用 jieba-next 等专业中文分词工具增强健壮性。资料来源：社区 issue #102

配置参考

# 初始化配置
memsearch config init              # 全局交互式配置
memsearch config init --project    # 项目级配置

# 查看/修改配置
memsearch config list
memsearch config set embedding.provider openai

故障排除

概述

MemSearch 采用分层架构设计，CLI/API 层负责索引、搜索和 Milvus 同步，而插件层则构建在 CLI/API 层之上，为不同的 AI 编码代理提供深度集成。插件系统的核心理念是：Markdown 文件始终是数据源的真实来源，Milvus 仅作为可重建的影子索引。

graph TB
    subgraph "用户交互层"
        User[用户/开发者]
    end
    
    subgraph "插件层 (Agent 集成)"
        ClaudeCode[Claude Code 插件]
        Codex[Codex 插件]
        OpenCode[OpenCode 插件]
        OpenClaw[OpenClaw 插件]
    end
    
    subgraph "CLI/API 层"
        CLI[memsearch CLI]
        API[Python API]
    end
    
    subgraph "核心功能层"
        Index[索引引擎]
        Search[搜索/检索]
        Milvus[Milvus 向量存储]
    end
    
    User --> ClaudeCode
    User --> Codex
    User --> OpenCode
    User --> OpenClaw
    
    ClaudeCode --> CLI
    Codex --> CLI
    OpenCode --> CLI
    OpenClaw --> CLI
    
    CLI --> API
    API --> Index
    API --> Search
    
    Index --> Milvus
    Search --> Milvus

资料来源：README.md

支持的插件平台

MemSearch 当前支持以下 AI 编码代理平台的插件集成：

每个插件的 collection 名称通过工作空间路径派生算法生成，确保不同平台和不同工作空间之间的内存隔离。

资料来源：plugins/openclaw/README.md

插件架构

共享资源层

所有插件共享 plugins/_shared/ 目录下的公共资源，包括：

graph LR
    subgraph "plugins/_shared/"
        Scripts[脚本]
        Prompts[提示词模板]
    end
    
    Scripts --> MaintenanceRunner[维护运行器]
    Scripts --> CaptureScripts[捕获脚本]
    
    Prompts --> Summarize[摘要提示词]
    Prompts --> ProjectReview[项目回顾提示词]
    Prompts --> UserProfile[用户画像提示词]
    
    MaintenanceRunner --> ClaudeCode
    MaintenanceRunner --> Codex
    MaintenanceRunner --> OpenCode
    MaintenanceRunner --> OpenClaw

#### 共享提示词

项目回顾提示词 (project_review.txt) 定义了项目内存的推荐结构：

# Project Memory
## Current Direction
## Active Threads
## Recent Progress
## Decisions
## Open Questions
## Risks and Constraints
## Next Steps
## Cold Items

该提示词强调：

• 保持文件聚焦于项目，而非用户个人偏好
• 优先小范围增量更新，而非全面重写
• 包含 JSON 格式的操作指令 (action:none/replace)

资料来源：plugins/_shared/prompts/project_review.txt

内存捕获流程

插件的核心功能之一是在每次对话轮次后自动捕获和摘要记忆。Claude Code 插件展示了典型的捕获流程：

sequenceDiagram
    participant User as 用户
    participant Agent as Claude Agent
    participant StopHook as Stop Hook
    participant Summarizer as LLM (haiku)
    participant MemoryFS as memory/*.md
    participant MemSearch as memsearch index

    User->>Agent: 提问
    Agent-->>User: 响应
    Agent->>StopHook: 触发 Stop 钩子
    StopHook->>StopHook: 解析最后轮次
    StopHook->>Summarizer: 发送摘要请求
    Summarizer-->>StopHook: 返回摘要
    StopHook->>MemoryFS: 追加到每日内存文件
    Note over MemoryFS: 添加 session:UUID 锚点
    StopHook->>MemSearch: 执行索引
    MemSearch->>Milvus: 更新向量索引

资料来源：README.md

三层递进检索

当用户查询记忆时，插件提供三层递进式检索：

graph TD
    Query["用户查询: \"batch size 相关讨论\""]
    L1["L1: memsearch search"]
    Chunks["排名结果 chunks"]
    L2{"需要详情？"}
    L3{"需要原始对话？"}
    Section["完整节段"]
    Transcript["原始对话"]
    End["返回结果"]

    Query --> L1
    L1 --> Chunks
    Chunks --> L2
    L2 -->|"否"| End
    L2 -->|"是"| L3
    L3 -->|"否"| Section
    L3 -->|"是"| Transcript
    Section --> End
    Transcript --> End

资料来源：plugins/openclaw/skills/memory-recall/SKILL.md

工具定义

OpenCode 插件工具

OpenCode 插件通过 TypeScript 定义了三个核心工具：

memory_search: tool({
  description: "Search semantic memory with hybrid BM25 + vector search",
  args: {
    query: tool.schema.string(),
    limit: tool.schema.number().optional()
  }
})

memory_get: tool({
  description: "Expand a memory chunk to see full markdown section with context",
  args: {
    chunk_hash: tool.schema.string()
  }
})

memory_transcript: tool({
  description: "Retrieve original conversation from past OpenCode session",
  args: {
    session_id: tool.schema.string(),
    turn_id: tool.schema.string().optional()
  }
})

资料来源：plugins/opencode/index.ts

配置管理

插件配置选项

每个插件支持独立的配置项，通过 memsearch config set 命令管理：

嵌入提供者配置

插件支持多种嵌入提供者：

# 切换到 OpenAI 嵌入
memsearch config set embedding.provider openai

# 切换回本地 ONNX
memsearch config set embedding.provider onnx

Milvus 后端配置

# 使用远程 Milvus 服务器
memsearch config set milvus.uri http://localhost:19530

资料来源：plugins/codex/README.md

插件隔离机制

多代理内存隔离

每个 AI 代理独立存储内存，使用独立的工作空间目录：

~/.claude/codex/.memsearch/memory/     ← Codex 主代理
~/.claude/workspace/.memsearch/memory/ ← Claude Code

~/.openclaw/workspace/.memsearch/memory/      ← OpenClaw 主代理
~/.openclaw/workspace-work/.memsearch/memory/ ← OpenClaw 工作代理

Collection 名称从工作空间路径派生，确保不同平台和不同工作空间之间的内存完全隔离。当一个代理的工作空间指向其他平台使用的项目目录时，记忆会自动跨平台共享。

资料来源：plugins/openclaw/README.md

已知限制与问题

已识别的社区问题

Codex 插件弃用警告

Codex CLI 当前会警告 [features].codex_hooks 已弃用，应替换为 [features].hooks。MemSearch Codex 插件的安装器、Stop hook 隔离和文档仍使用已弃用的键。

资料来源：plugins/codex/README.md

安装与维护

插件更新

# 重新安装插件以获取最新版本
memsearch plugin update

# 完全卸载插件
memsearch plugin uninstall

配置初始化

# 全局交互式配置
memsearch config init

# 项目级交互式配置
memsearch config init --project

# 直接设置配置
memsearch config set plugins.codex.summarize.model gpt-5.1-codex-mini

配置更改后建议启动新的代理会话，以确保加载最新的 hook/skill 状态。

扩展插件开发

开发新插件时应遵循以下架构原则：

1. 共享资源优先：使用 plugins/_shared/ 下的共享脚本和提示词
2. 工具三元组：实现 memory_search、memory_get、memory_transcript 三个核心工具
3. Hook 集成：通过 Stop/SessionStart Hook 触发捕获流程
4. 配置隔离：支持独立的 provider/model 配置项
5. Collection 派生：使用统一的算法从工作空间路径派生 collection 名称

项目内存结构建议

所有插件推荐使用统一的项目内存结构：

# Project Memory

## Current Direction
描述当前项目的核心方向和目标

## Active Threads
当前活跃的讨论或任务线索

## Recent Progress
近期完成的工作和进展

## Decisions
重要的技术决策记录

## Open Questions
待解决的问题

## Risks and Constraints
已识别的风险和约束条件

## Next Steps
下一步计划

## Cold Items
长期搁置或低优先级的事项

此结构通过 project_review.txt 提示词模板标准化，确保跨平台的一致性。

核心功能概览

架构设计

数据流总览

graph TD
    subgraph 捕获阶段["捕获阶段"]
        A[用户对话] --> B[Stop 钩子触发]
        B --> C[transcript.py 解析对话]
        C --> D[claude -p 生成摘要]
        D --> E[追加至 memory/YYYY-MM-DD.md]
        E --> F[memsearch index 索引]
        F --> G[Milvus 向量存储]
    end
    
    subgraph 检索阶段["检索阶段 (3层递进)"]
        H[用户查询] --> I[L1: memsearch search]
        I --> J[相关性排序结果]
        J --> K{需要更多细节?}
        K -->|是| L[L2: memsearch expand]
        L --> M[完整 Markdown 段落]
        M --> N{需要原始对话?}
        N -->|是| O[L3: transcript.py 解析]
        O --> P[原始对话记录]
    end

插件目录结构

plugins/claude-code/
├── README.md                    # 插件说明文档
├── hooks/
│   ├── session-start.sh         # 会话启动钩子
│   ├── stop.sh                  # 会话停止钩子
│   └── user-prompt-submit.sh    # 提示提交钩子
├── transcript.py                # 对话记录解析器
├── prompts/
│   └── project_review.txt       # 项目回顾提示模板
├── skills/
│   ├── memory-config/          # 记忆配置技能
│   └── memory-recall/           # 记忆检索技能
└── installer/                   # 安装脚本

工作机制详解

1. 会话启动（SessionStart Hook）

session-start.sh 在每次 Claude Code 启动时执行，负责初始化当日记忆文件：

sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant SS as session-start.sh
    participant FS as 文件系统

    CC->>SS: 触发 SessionStart 钩子
    SS->>SS: 检查 .memsearch/memory/ 目录
    SS->>FS: 创建/追加 memory/YYYY-MM-DD.md
    Note over SS: 添加会话元信息标记
    SS-->>CC: 完成

关键功能：

• 检查 .memsearch/memory/ 目录是否存在，不存在则创建
• 在当日记忆文件中追加会话头信息（## Session HH:MM）
• 注入会话路径锚点，便于后续定位原始对话

⚠️ 已知问题：Issue #520 报告 stop.sh 中调用的 claude -p 子进程会意外触发 SessionStart 钩子，导致每日日志被污染并泄漏到嵌套目录。社区正在评估解决方案。

2. 提示提交（UserPromptSubmit Hook）

user-prompt-submit.sh 在用户每次提交提示时执行，用于标记对话轮次边界：

# 核心逻辑：追加会话锚点注释
<!-- session:${CLAUDE_SESSION_ID} turn:${TURN_COUNT} -->

此锚点嵌入记忆文件，使后续检索能追溯到原始对话记录。

3. 会话停止（Stop Hook）

stop.sh 是插件的核心，负责捕获和保存对话摘要：

flowchart LR
    A[Stop 钩子触发] --> B[解析最后对话轮次]
    B --> C{摘要提供者}
    C -->|native| D[claude -p --model haiku]
    C -->|openai| E[OpenAI API]
    D --> F[生成结构化摘要]
    E --> F
    F --> G[追加至记忆文件]
    G --> H[执行 memsearch index]

摘要格式示例：

- 用户询问了 X 问题
- Claude 分析了 Y 方案
- 双方讨论了 Z 限制
<!-- session:uuid transcript:/path/to/transcript.jsonl -->

⚠️ 已知问题：Issue #527 报告当用户账户触发 Anthropic API 速率限制时，claude -p 返回人类可读的错误字符串而非摘要内容，stop.sh 仅检查非零退出码，未验证输出格式，导致错误信息被写入记忆文件。

4. 向量索引同步

Stop 钩子完成后，自动调用 memsearch index 将新增记忆同步至 Milvus：

memsearch index .memsearch/memory/

使用 BGE-M3 ONNX 模型生成分块向量，支持混合搜索（稠密向量 + BM25 + RRF）。

记忆文件格式

每日记忆文件

位置：.memsearch/memory/YYYY-MM-DD.md

# Daily Memory

## Session 14:23
- 用户询问关于批处理大小的问题
- Claude 分析了内存使用情况
- 决定使用 64 的批次大小
<!-- session:abc123 turn:5 transcript:/path/to/session.jsonl -->

## Session 15:45
- 讨论了缓存策略
- ...

项目回顾文件

位置：.memsearch/PROJECT_MEMORY.md

建议结构：

# Project Memory

## Current Direction
## Active Threads
## Recent Progress
## Decisions
## Open Questions
## Risks and Constraints
## Next Steps
## Cold Items

3层递进检索模式

graph LR
    A[用户查询] --> B{L1 快速回忆}
    B --> C[memsearch search]
    C --> D{结果足够?}
    D -->|否| E{L2 获取细节}
    E --> F[memsearch expand]
    F --> G{需要原始对话?}
    G -->|是| H{L3 原始对话}
    H --> I[transcript.py 解析]
    
    style B fill:#90EE90
    style E fill:#FFD700
    style H fill:#FFB6C1

配置选项

插件级配置

# 初始化配置
memsearch config init --project

# 查看当前配置
memsearch config list

使用外部摘要提供者

# 配置 OpenAI 作为摘要提供者
memsearch config set llm.providers.openai.type openai
memsearch config set llm.providers.openai.model gpt-4o-mini
memsearch config set llm.providers.openai.api_key env:OPENAI_API_KEY
memsearch config set plugins.claude-code.summarize.provider openai
memsearch config set plugins.claude-code.summarize.model gpt-4o-mini

安装与卸载

安装步骤

1. 安装 memsearch：

uv pip install memsearch

1. 在 Claude Code 中安装插件：

/install https://github.com/zilliztech/memsearch

1. 初始化项目配置：

cd your-project
memsearch config init --project

卸载步骤

1. 在 Claude Code 中卸载插件：

/uninstall memsearch

1. 清理项目数据（可选）：

rm -rf .memsearch/

⚠️ 注意：卸载插件不会自动删除 .memsearch/ 目录中的记忆数据。

与 Codex 插件的差异

故障排查

常见问题

诊断命令

# 检查插件状态
memsearch stats -c <collection>

# 查看索引详情
memsearch index .memsearch/memory/ -v

# 测试检索
memsearch search "your query"

相关社区议题

参考资料

• 插件完整说明：plugins/claude-code/README.md
• 工作原理详解：docs/platforms/claude-code/how-it-works.md
• 会话启动钩子源码：plugins/claude-code/hooks/session-start.sh
• 会话停止钩子源码：plugins/claude-code/hooks/stop.sh
• 对话记录解析器：plugins/claude-code/transcript.py
• 提示提交钩子：plugins/claude-code/hooks/user-prompt-submit.sh

概述

Codex CLI 插件是 memsearch 为 Anthropic Codex CLI 提供的原生集成方案，使 Codex 用户能够自动捕获对话记忆、进行语义搜索检索，并在会话之间保持上下文连续性。

该插件通过 Codex 的 hooks 机制工作，在每次对话轮次结束后自动将摘要追加到项目级 Markdown 记忆文件，并同步索引到 Milvus 向量数据库。

核心功能

记忆捕获（Capture）

每次对话轮次结束后自动执行：

• 解析最后一个对话回合
• 调用 haiku 模型生成结构化摘要
• 将摘要追加到 memory/YYYY-MM-DD.md 文件
• 同时索引到 Milvus 向量数据库

记忆检索（Recall）

三层递进式检索机制：

工作原理

架构图

graph TD
    A[Codex CLI 启动] --> B[SessionStart Hook]
    B --> C[检查 memory 目录]
    B --> D[注入会话锚点]
    
    E[用户与 Codex 对话] --> F[对话轮次结束]
    F --> G[Stop Hook 触发]
    G --> H[解析最后回合]
    H --> I[LLM 摘要 haiku]
    I --> J[追加到 memory/YYYY-MM-DD.md]
    J --> K[memsearch index]
    K --> L[Milvus 向量索引]
    
    M[用户检索记忆] --> N[memsearch search]
    N --> O[hybrid BM25 + vector]
    O --> P[返回排名结果]

Stop Hook 执行流程

用户提问 → Agent 响应 → Stop Hook 触发
                            │
          ┌─────────────────┘
          ▼
    解析最后回合
          │
          ▼
    LLM 摘要 (haiku)
    "- 用户询问 X"
    "- Codex 执行 Y"
          │
          ▼
    追加到 memory/YYYY-MM-DD.md
    (含 <!-- session:UUID --> 锚点)
          │
          ▼
    memsearch index → Milvus

资料来源：README.md:59-72

安装与配置

安装命令

# 进入 Codex 插件目录
cd plugins/codex

# 运行安装脚本
./scripts/install.sh

安装脚本会自动配置以下内容：

• 创建项目级 .memsearch/ 目录结构
• 配置 Codex hooks（SessionStart 和 Stop）
• 设置默认的记忆摘要模型

初始化配置

# 全局交互式初始化
memsearch config init

# 项目级交互式初始化
memsearch config init --project

关键配置项

资料来源：plugins/codex/skills/memory-config/SKILL.md:3-5

嵌入模型配置

# 切换到 OpenAI 嵌入（需要 OPENAI_API_KEY）
memsearch config set embedding.provider openai

# 切换回本地 ONNX
memsearch config set embedding.provider onnx

Milvus 后端配置

# 使用远程 Milvus 服务器
memsearch config set milvus.uri http://localhost:19530

# 默认使用 Milvus Lite（本地 .db 文件）

资料来源：plugins/codex/README.md:18-30

插件工具集

Codex 插件提供以下 MCP 工具：

memory_search

语义搜索工具，用于快速检索相关记忆块。

参数：

• query: 搜索查询字符串

返回： 排名结果列表，包含 chunk_hash 和相关性分数

memory_get

展开工具，用于获取匹配块的完整 Markdown 段落及上下文。

参数：

• chunk_hash: 搜索结果中的块哈希值

返回： 完整段落文本，可能包含会话锚点（如 <!-- session:UUID -->）

memory_transcript

原始对话检索工具，从会话转录文件解析原始对话内容。

参数：

• session_id: 锚点注释中的会话 ID
• turn_id: 可选的回合 ID

返回： 格式化的对话内容，带 [User] 和 [Assistant] 标签

资料来源：plugins/claude-code/skills/memory-recall/SKILL.md:8-30

记忆文件结构

目录布局

.memsearch/
├── memory/
│   ├── 2026-03-27.md
│   ├── 2026-03-26.md
│   └── ...
└── config.yaml

记忆文件格式

# 2026-03-27

## 会话摘要

- 用户询问了关于 batch size 的配置问题
- Codex 建议使用环境变量覆盖默认值
- 用户确认了修改方案

<!-- session:abc12345 turn:1 transcript:/path/to/session.jsonl -->

PROJECT_MEMORY.md 结构

# Project Memory

## Current Direction
[当前项目方向]

## Active Threads
[活跃任务]

## Recent Progress
[近期进展]

## Decisions
[已做决策]

## Open Questions
[待解决问题]

## Risks and Constraints
[风险与约束]

## Next Steps
[下一步计划]

## Cold Items
[搁置事项]

资料来源：plugins/codex/prompts/project_review.txt:18-35

已知问题

Issue #535: 使用已弃用的 features.codex_hooks

Codex CLI 现在警告 [features].codex_hooks 已弃用，应替换为 [features].hooks。当前 memsearch Codex 插件仍在 installer、stop hook isolation 和文档中使用已弃用的键。

影响范围：

• 插件安装脚本
• Stop hook 隔离逻辑
• 相关文档说明

状态： 待修复

资料来源：社区 Issue #535

Issue #520: Stop hook 的 claude -p 调用触发 SessionStart

即使设置了 --no-session-persistence、--no-chrome 并清除 CLAUDECODE=，内部的 claude -p 调用仍会触发插件的 SessionStart Hook，导致：

• 每日日志被污染
• 记忆泄漏到嵌套目录

资料来源：社区 Issue #520

Issue #527: Rate-limit 错误被写入记忆摘要

当用户账户触发 API 速率限制时，stop.sh 中的 claude -p --model haiku 调用返回错误字符串而非摘要。当前 stop.sh 仅检查退出码，未验证输出内容是否为有效摘要。

资料来源：社区 Issue #527

Issue #537: 预压缩转录未被 Stop Hook 捕获

如果会话中间发生转录压缩（compaction），Stop 的 parse-transcript.sh 在压缩已将预压缩转录合并为单个 isCompactSummary 标记之后才运行，导致长时 Agent 运行在压缩中期的对话细节丢失。

资料来源：社区 Issue #537

配置初始化交互

memsearch CLI 提供交互式配置流程，支持 Codex 相关配置：

memsearch config init

交互提示包括：

资料来源：src/memsearch/cli.py:145-160

最佳实践

会话恢复

遇到复杂问题时，可使用会话恢复功能获取之前对话的上下文：

memsearch expand <chunk_hash>

定期维护

1. 项目回顾：启用 plugins.codex.project_review 定期生成项目状态摘要
2. 索引重建：定期运行 memsearch index 确保 Milvus 索引与 Markdown 文件同步
3. 配置检查：修改配置后启动新 Codex 会话以加载新状态

调试建议

配置变更后，建议启动新 Codex 会话，因为当前会话可能已缓存旧状态。配置项如 plugins.codex.summarize.*、[llm.providers.*]、[milvus.*] 等通常在下次捕获、检索、索引或维护调用时生效。

资料来源：plugins/codex/skills/memory-config/SKILL.md:3-6

与 Claude Code 插件对比

两个插件共享相同的底层 memsearch 核心，差异主要在于 hook 脚本的实现细节和 agent 特定的配置命名空间。

概述

OpenClaw 是 memsearch 项目支持的多 agent 平台插件之一，为 OpenClaw agent 提供语义记忆能力。与 Claude Code、Codex、OpenCode 等插件类似，OpenClaw 插件通过 hook 机制捕获会话内容，并将其持久化到 markdown 文件中，同时利用 memsearch 的向量搜索能力实现高效检索。

OpenClaw 插件的核心功能包括：

• 会话捕获：在每次对话轮次后自动生成摘要并追加到记忆文件
• 语义搜索：提供 memory_search、memory_get、memory_transcript 三层递进式检索
• 自动维护：支持项目回顾（project_review）和用户画像（user_profile）自动维护任务
• 配置管理：提供 memory-config skill 引导式配置界面

资料来源：plugins/openclaw/README.md:1-20

架构设计

插件组件结构

OpenClaw 插件位于 plugins/openclaw/ 目录下，采用模块化设计：

资料来源：plugins/openclaw/index.ts:1-50

记忆检索工具

OpenClaw 插件提供三个递进式记忆检索工具，形成"快速回忆 → 详情展开 → 原始对话"的检索链路：

graph LR
    A[用户查询] --> B[memory_search]
    B --> C{是否需要详情?}
    C -->|是| D[memory_get]
    D --> E{需要原始对话?}
    E -->|是| F[memory_transcript]
    E -->|否| G[返回展开内容]
    C -->|否| H[返回搜索结果]

#### 1. memory_search — 语义搜索

在记忆语料库中执行混合搜索（BM25 + 向量相似度），返回相关片段列表。

参数：

返回：包含 chunk_hash、text、score 的结果数组

资料来源：plugins/openclaw/index.ts:100-130

#### 2. memory_get — 展开详情

根据 memory_search 返回的 chunk_hash 展开完整的 markdown 段落，包含周围上下文。

参数：

返回：完整的 markdown 区块文本，可能包含会话锚点注释 <!-- session:UUID transcript:PATH -->

资料来源：plugins/openclaw/index.ts:130-160

#### 3. memory_transcript — 原始对话

解析原始会话转录文件，返回格式化的对话内容，包含 [User] 和 [Assistant] 标签。

参数：

返回：带标签的原始对话，包含工具调用信息

注意：如果锚点格式与预期不符（如使用 rollout:、turn:、db: 而非 transcript:），建议直接读取引用的文件探索其结构。

资料来源：plugins/openclaw/skills/memory-recall/SKILL.md:30-50

决策指南

资料来源：plugins/openclaw/skills/memory-recall/SKILL.md:55-65

工作流程

会话捕获流程

OpenClaw 插件在每次对话轮次结束后触发 hook，执行以下流程：

graph TD
    A[用户提问] --> B[Agent 响应]
    B --> C[Stop Hook 触发]
    C --> D[解析最后轮次]
    D --> E[LLM 摘要生成]
    E --> F["摘要: '- 用户问了 X。<br/>- Agent 做了 Y.'"]
    F --> G[追加到 memory/YYYY-MM-DD.md]
    G --> H[添加 session 锚点]
    H --> I[memsearch index → Milvus]

资料来源：plugins/openclaw/README.md:50-80

自动维护任务

OpenClaw 支持两种自动维护任务（默认禁用）：

这些任务按 min_interval_hours 间隔执行，可配置 provider、model 和 input_dir。

资料来源：src/memsearch/config.py:80-100

配置管理

可配置项

OpenClaw 插件的配置项位于 plugins.openclaw 命名空间下：

交互式配置

用户可以通过 memory-config skill 进入引导式配置流程：

memsearch config init --project   # 项目级交互配置
memsearch config set/get/list     # 直接 CLI 修改

重要提示：修改配置后，建议开启新的 agent 会话，因为当前会话可能已加载旧配置。配置变更会在下次捕获、检索、索引或维护调用时生效。

资料来源：plugins/openclaw/skills/memory-config/SKILL.md:1-30

项目回顾 Prompt 规范

项目回顾功能使用共享的 prompt 模板，关键要求包括：

必须遵守：

• 文件内容应聚焦于项目本身，而非用户个人偏好
• 将用户偏好、通信风格等放入 USER.md
• 仅在项目明确要求时包含约束条件
• 保持文件简洁可审查

推荐的文件结构：

# Project Memory

## Current Direction
## Active Threads
## Recent Progress
## Decisions
## Open Questions
## Risks and Constraints
## Next Steps
## Cold Items

输出格式：

{"action":"none","reason":"Recent journals do not change durable project state."}
{"action":"replace","reason":"Recent journals add a new active thread.","content":"# Project Memory\n\n..."}

资料来源：plugins/openclaw/prompts/project_review.txt:1-30

与其他插件的对比

所有插件共享相同的记忆检索工具链和项目维护框架，确保用户体验一致性。

资料来源：plugins/_shared/prompts/project_review.txt:1-20

相关社区问题

以下社区报告的问题可能影响 OpenClaw 插件的使用体验：

提示：遇到搜索或索引问题时，首先确认 Milvus 集合状态是否正确加载（调用 load() 或重启 watch 进程）。

快速入门

``bash memsearch plugin install openclaw ``

1. 安装 OpenClaw 插件：

``bash memsearch plugin list ``

1. 验证安装：

``bash memsearch config set plugins.openclaw.summarize.provider openai memsearch config set plugins.openclaw.summarize.model gpt-5-mini ``

1. 配置 provider（可选）：

1. 开始使用：

• 在 OpenClaw 会话中直接询问记忆相关问题
• 使用 memory_search、memory_get、memory_transcript 工具检索

Pitfall Log / 踩坑日志

项目：zilliztech/memsearch

摘要：发现 23 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：MilvusStore.upsert() reports success but writes are not durable on remote Milvus 2.5+ (missing flush)。

1. 安装坑 · 来源证据：MilvusStore.upsert() reports success but writes are not durable on remote Milvus 2.5+ (missing flush)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：MilvusStore.upsert() reports success but writes are not durable on remote Milvus 2.5+ (missing flush)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e448ba5c18f74fbcac5193643cf9bf00 | https://github.com/zilliztech/memsearch/issues/534 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：OpenCode plugin installation silently fails

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

3. 安装坑 · 来源证据：Stop hook's `claude -p` summarize call fires SessionStart, polluting daily logs and leaking to nested directories

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Stop hook's claude -p summarize call fires SessionStart, polluting daily logs and leaking to nested directories
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_f7c0535d74d940bba792903b440f1808 | https://github.com/zilliztech/memsearch/issues/520 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安全/权限坑 · 来源证据：Enhance robustness of memory search with jieba-next CJK tokenizer and native Markdown parsing

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enhance robustness of memory search with jieba-next CJK tokenizer and native Markdown parsing
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_bcaeec224c444d9484142ebf19f6ecc8 | https://github.com/zilliztech/memsearch/issues/102 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

5. 安全/权限坑 · 来源证据：Indexing leaks ~9 MB anon-rss per chunk in single process; OOM-kills mid-corpus on 15 GB host

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Indexing leaks ~9 MB anon-rss per chunk in single process; OOM-kills mid-corpus on 15 GB host
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_b8e6b6226cfa4953ab4ffffc71e575e8 | https://github.com/zilliztech/memsearch/issues/533 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

6. 安全/权限坑 · 来源证据：Stop hook writes Anthropic API rate-limit error string as memory summary content

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stop hook writes Anthropic API rate-limit error string as memory summary content
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_05b51b5d9b1145fca49076b5f0a3e9d2 | https://github.com/zilliztech/memsearch/issues/527 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：Codex plugin still uses deprecated features.codex_hooks instead of features.hooks

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Codex plugin still uses deprecated features.codex_hooks instead of features.hooks
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c7024063d9bc4202803e0629e7ba02bc | https://github.com/zilliztech/memsearch/issues/535 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安装坑 · 来源证据：Pre-compaction transcript not captured by Stop hook?

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pre-compaction transcript not captured by Stop hook?
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9276552f302c48309d9a27db91487d0d | https://github.com/zilliztech/memsearch/issues/537 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安装坑 · 来源证据：v0.3.1

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

10. 安装坑 · 来源证据：v0.4.2

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

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

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

12. 配置坑 · 来源证据：CLI search fails on Milvus Lite: collection in 'released' state

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：CLI search fails on Milvus Lite: collection in 'released' state
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5b382c2552e449c698d3757e72374f04 | https://github.com/zilliztech/memsearch/issues/540 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 配置坑 · 来源证据：duplicate primary keys are not allowed in the same batch: invalid parameter

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：duplicate primary keys are not allowed in the same batch: invalid parameter
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_21c6616f42744bc89c90a6676994c526 | https://github.com/zilliztech/memsearch/issues/539 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

14. 配置坑 · 来源证据：v0.4.0

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.4.0
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a69a50a3b98b49b3a51e42111ca0fbf4 | https://github.com/zilliztech/memsearch/releases/tag/v0.4.0 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

15. 能力坑 · 来源证据：v0.3.0

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

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

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

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

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

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

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

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

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

20. 安全/权限坑 · 来源证据：memsearch stats shows 0 chunks when collection name is only set in config file

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：memsearch stats shows 0 chunks when collection name is only set in config file
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d0384d88066d481c99825331e5666168 | https://github.com/zilliztech/memsearch/issues/538 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

21. 安全/权限坑 · 来源证据：v0.4.1

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

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

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

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

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