# https://github.com/zilliztech/memsearch 项目说明书

生成时间：2026-05-31 18:47:49 UTC

## 目录

- [项目概述](#overview)
- [快速入门](#quickstart)
- [系统架构](#architecture)
- [核心模块详解](#core-modules)
- [文本分块与索引机制](#chunking-indexing)
- [检索算法实现](#search-algorithm)
- [插件系统概述](#plugin-system)
- [Claude Code 插件](#claude-code-plugin)
- [Codex CLI 插件](#codex-plugin)
- [OpenClaw 插件](#openclaw-plugin)

<a id='overview'></a>

## 项目概述

### 相关页面

相关主题：[系统架构](#architecture), [快速入门](#quickstart), [插件系统概述](#plugin-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/zilliztech/memsearch/blob/main/README.md)
- [mkdocs.yml](https://github.com/zilliztech/memsearch/blob/main/mkdocs.yml)
- [src/memsearch/__init__.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/__init__.py)
- [src/memsearch/cli.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py)
- [src/memsearch/chunker.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py)
- [src/memsearch/scanner.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py)
- [src/memsearch/watcher.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py)
</details>

# 项目概述

memsearch 是一款面向 AI 编码代理的跨平台语义记忆搜索工具，以 Markdown 文件为核心数据源，由 Milvus 向量数据库提供底层索引能力。资料来源：[mkdocs.yml:3]()

## 核心定位

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 编码代理集成，目前已支持的平台包括：

| 插件名称 | 集成方式 | 特点 |
|---------|---------|------|
| Claude Code | Claude Code hooks | 会话自动捕获、每日摘要 |
| Codex | Codex CLI hooks | 展开式对话解析 |
| OpenCode | TypeScript 工具 | 内存搜索、展开、回溯 |
| OpenClaw | 技能系统 | 项目回顾、用户画像 |

资料来源：[README.md:20-35]()

## 核心模块

### MemSearch 核心类

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

```python
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 和转录路径等元数据噪声

```python
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 文件元数据（路径、修改时间、大小），并支持隐藏文件过滤。

```python
@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）处理：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `debounce_ms` | 1500 | 事件触发间隔（毫秒） |
| 扩展名过滤 | `.md`, `.markdown` | 监控文件类型 |

资料来源：[src/memsearch/watcher.py:1-50]()

## CLI 命令

`memsearch` CLI 提供以下核心命令：

| 命令 | 功能 |
|------|------|
| `memsearch index <paths>` | 索引指定路径的 Markdown 文件 |
| `memsearch search <query>` | 语义+关键词混合搜索 |
| `memsearch expand <chunk_hash>` | 展开完整段落 |
| `memsearch watch <paths>` | 监控文件变化并自动索引 |
| `memsearch config` | 配置管理（init/set/get/list） |
| `memsearch stats` | 显示索引统计信息 |

资料来源：[src/memsearch/cli.py:1-50]()

## 检索流程

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

```mermaid
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 段落，可能包含会话锚点注释：

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

### 第三层：原始回溯

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

资料来源：[README.md:90-110]()

## 配置选项

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

### 嵌入模型配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `embedding.provider` | `onnx` | 嵌入提供者（onnx/openai） |
| `embedding.model` | `bge-m3` | 模型名称 |

### Milvus 后端配置

| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `milvus.uri` | `milvus_lite.db` | Milvus 服务器地址 |
| `milvus.token` | - | 认证令牌 |

### 插件配置

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

```bash
# 使用原生摘要模型
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]()

## 已知限制与社区问题

### 已识别的技术债务

| Issue | 影响范围 | 状态 |
|-------|---------|------|
| CLI 搜索在 Milvus Lite 中 collection 未加载 | #540 | 需手动调用 `load()` |
| 索引进程内存泄漏（约 9MB/块） | #533 | 单进程大批量索引时 OOM |
| `stats` 命令在配置文件中设置 collection 时显示 0 | #538 | 需显式传递 `-c` 参数 |
| Milvus 2.5+ 远程模式写入未 flush | #534 | upsert 后数据不可查询 |

### 社区功能请求

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

资料来源：[README.md:120-140]()

## 快速开始

### 安装

```bash
# 通过 uv 安装
uv tool install memsearch

# 或通过 pip 安装
pip install memsearch
```

### 初始化

```bash
# 全局配置
memsearch config init

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

### 基本使用

```bash
# 索引当前目录
memsearch index .

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

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

## 版本历史

| 版本 | 主要变更 |
|------|----------|
| v0.4.6 | 改进记忆捕获摘要和诊断功能 |
| v0.4.2 | 修复超大行拆分问题、插件 SIGPIPE 防护 |
| v0.4.1 | 修复 MEMSEARCH_DIR 集合派生问题 |

资料来源：[mkdocs.yml:1-10]()

---

<a id='quickstart'></a>

## 快速入门

### 相关页面

相关主题：[项目概述](#overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/zilliztech/memsearch/blob/main/README.md)
- [src/memsearch/__init__.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/__init__.py)
- [src/memsearch/cli.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py)
- [src/memsearch/chunker.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py)
- [src/memsearch/scanner.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py)
- [src/memsearch/watcher.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py)
- [mkdocs.yml](https://github.com/zilliztech/memsearch/blob/main/mkdocs.yml)
</details>

# 快速入门

memsearch 是一个面向 AI 编码代理的跨平台语义记忆系统，采用 Markdown 文件作为数据源，通过 Milvus 向量数据库提供语义搜索能力。本指南将帮助用户在 5 分钟内完成安装、配置和基础使用。

## 系统要求

| 组件 | 要求 |
|------|------|
| Python | ≥ 3.10 |
| 操作系统 | macOS、Linux、Windows |
| 存储 | 至少 500MB 可用空间（用于嵌入模型和 Milvus Lite） |

## 安装

### 通过 uv 安装（推荐）

```bash
uv tool install memsearch
```

### 通过 pip 安装

```bash
pip install memsearch
```

安装完成后，验证版本：

```bash
memsearch --version
```

资料来源：[pyproject.toml](https://github.com/zilliztech/memsearch/blob/main/pyproject.toml)

## 核心概念

### 架构概览

```mermaid
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](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py)

### 分块机制

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

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

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

资料来源：[src/memsearch/chunker.py:1-30](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py)

## 交互式配置

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

```bash
memsearch config init
```

配置向导将依次询问：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| 嵌入提供商 | 向量生成方式 | `onnx`（本地） |
| 嵌入模型 | 具体模型名称 | `bge-m3` |
| Milvus URI | 数据库连接地址 | `milvus_lite.db` |
| 批处理大小 | 单次索引块数 | 100 |

### 项目级配置

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

```bash
memsearch config init --project
```

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

### 手动配置命令

```bash
# 设置单个配置项
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](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py)

## 基础使用

### 索引操作

#### 索引当前目录

```bash
memsearch index .
```

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

#### 索引指定路径

```bash
memsearch index ./docs ./memory
```

#### 索引单个文件

```bash
memsearch index ./README.md
```

### 搜索操作

#### 语义搜索

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

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

#### 展开分块

获取分块的完整上下文：

```bash
memsearch expand <chunk_hash>
```

`chunk_hash` 来自搜索结果。

### 查看统计信息

```bash
memsearch stats
```

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

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

### 文件监控

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

```bash
memsearch watch . --debounce-ms 1500
```

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

```mermaid
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](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py)

## 插件集成

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

| 插件 | 支持的代理 |
|------|-----------|
| claude-code | Claude Code |
| codex | OpenAI Codex |
| opencode | OpenCode |
| openclaw | OpenClaw |

### Claude Code 插件

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

```mermaid
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](https://github.com/zilliztech/memsearch/blob/main/README.md)

### 配置摘要模型

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

```bash
# 使用 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`）

## 下一步

| 任务 | 文档链接 |
|------|----------|
| 深入配置选项 | [Configuration](home/configuration.md) |
| CLI 完整参考 | [CLI Reference](cli.md) |
| Python API 使用 | [Python API](python-api.md) |
| 插件详情 | [Claude Code Plugin](../platforms/claude-code/index.md) |
| 故障排除 | [Troubleshooting](troubleshooting.md) |

## 核心文件速查

| 文件 | 职责 |
|------|------|
| `src/memsearch/__init__.py` | 入口，导出 MemSearch 类 |
| `src/memsearch/cli.py` | CLI 命令实现 |
| `src/memsearch/scanner.py` | 文件扫描和元数据收集 |
| `src/memsearch/chunker.py` | Markdown 分块逻辑 |
| `src/memsearch/watcher.py` | 目录监控和增量索引 |

资料来源：[src/memsearch/__init__.py:1-10](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/__init__.py)

---

<a id='architecture'></a>

## 系统架构

### 相关页面

相关主题：[项目概述](#overview), [文本分块与索引机制](#chunking-indexing), [检索算法实现](#search-algorithm)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/architecture.md](https://github.com/zilliztech/memsearch/blob/main/docs/architecture.md)
- [docs/design-philosophy.md](https://github.com/zilliztech/memsearch/blob/main/docs/design-philosophy.md)
- [src/memsearch/core.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/core.py)
- [src/memsearch/chunker.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py)
- [src/memsearch/scanner.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py)
- [src/memsearch/watcher.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py)
- [src/memsearch/cli.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py)
</details>

# 系统架构

## 概述

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

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

资料来源：[docs/architecture.md]()

## 核心架构分层

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

```graph TD
    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 存储操作。

| 模块 | 职责 | 关键方法 |
|------|------|----------|
| `MemSearch.__init__` | 初始化，解析配置 | 接收路径列表、embedding 配置、Milvus 配置 |
| `index()` | 协程方法，扫描并索引文件 | 使用 `scan_paths()` 发现文件，`_index_file()` 处理单个文件 |
| `search()` | 语义 + 关键词混合搜索 | 调用 Milvus 向量搜索和 BM25 混合排序 |
| `expand()` | 展开块哈希获取完整上下文 | 根据 `chunk_hash` 检索完整 markdown 段落 |
| `watch()` | 启动文件监控守护进程 | 使用 watchdog 监听文件系统变化 |
| `get_stats()` | 获取索引统计信息 | 返回集合的块数量等元数据 |

资料来源：[src/memsearch/core.py]()

### Markdown 分块 (chunker.py)

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

**核心流程：**

```graph TD
    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[准备索引]
```

**关键函数：**

| 函数 | 用途 |
|------|------|
| `clean_content_for_embedding()` | 清理 HTML 注释等噪声，生成嵌入向量时使用 |
| `_has_meaningful_content()` | 验证块内容是否满足最小有意义长度（`_MIN_MEANINGFUL_LEN = 2`） |
| `_HEADING_RE` | 正则表达式匹配 1-6 级标题 |
| `_HTML_COMMENT_RE` | 正则表达式匹配 HTML 注释 `<!-- ... -->` |

资料来源：[src/memsearch/chunker.py]()

### 文件扫描 (scanner.py)

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

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

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

资料来源：[src/memsearch/scanner.py]()

### 文件监控 (watcher.py)

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

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `debounce_ms` | 1500 | 事件防抖延迟（毫秒） |
| `extensions` | `(".md", ".markdown")` | 监听的文件扩展名 |

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

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

资料来源：[src/memsearch/watcher.py]()

## 数据流架构

### 索引流程

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

### 搜索流程

```graph LR
    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    # 按日期组织的记忆文件
```

每个记忆文件包含带锚点注释的会话记录：
```markdown
## Session 14:32

- User asked about X
- Claude did Y

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

### Milvus 集合结构

| 字段 | 类型 | 说明 |
|------|------|------|
| `chunk_hash` | VARCHAR (主键) | 块的唯一标识符 |
| `content` | VARCHAR | 块的实际文本内容 |
| `embedding` | FLOAT_VECTOR | BGE-M3 向量嵌入 |
| `file_path` | VARCHAR | 源文件路径 |
| `headings` | VARCHAR | 标题层级结构 |

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

资料来源：[src/memsearch/core.py]()

## 向量模型层

| 提供商 | 模型 | 特点 |
|--------|------|------|
| ONNX (默认) | bge-m3 | 本地运行，无需 API Key |
| OpenAI | text-embedding-3-* | 云端服务，需 API Key |

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

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

资料来源：[plugins/codex/README.md]()

## CLI 命令体系

| 命令 | 功能 |
|------|------|
| `memsearch index` | 扫描并索引指定路径的 Markdown 文件 |
| `memsearch search` | 语义搜索匹配的块 |
| `memsearch expand` | 根据 chunk_hash 展开完整段落 |
| `memsearch watch` | 监听文件系统变化，实时增量索引 |
| `memsearch stats` | 显示集合统计信息 |
| `memsearch config` | 配置管理（init/set/get/list） |

资料来源：[src/memsearch/cli.py]()

## 插件架构

### 通用插件结构

```graph TD
    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               
```

### 三层召回机制

| 层级 | 操作 | 返回内容 |
|------|------|----------|
| L1 | `memsearch search` | 排名最高的语义块列表 |
| L2 | `memsearch expand <hash>` | 完整 Markdown 段落 |
| L3 | 解析 transcript | 原始对话 JSONL |

资料来源：[README.md]()

## 配置系统

### 配置层级

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

### 关键配置项

| 配置路径 | 类型 | 默认值 | 说明 |
|----------|------|--------|------|
| `embedding.provider` | string | `onnx` | 向量嵌入提供商 |
| `embedding.model` | string | `bge-m3` | 嵌入模型名称 |
| `milvus.uri` | string | 本地 `.db` | Milvus 服务器地址 |
| `milvus.token` | string | - | Milvus 认证令牌 |
| `collection` | string | 自动派生 | 集合名称 |
| `watch.debounce_ms` | int | 1500 | 文件监控防抖延迟 |
| `plugins.*.summarize.*` | - | - | 各插件的总结模型配置 |

资料来源：[src/memsearch/cli.py]()

## 已知限制与社区问题

| 问题 | 严重程度 | 说明 |
|------|----------|------|
| [Issue #540](https://github.com/zilliztech/memsearch/issues/540) | 高 | Milvus Lite 搜索时集合处于 'released' 状态 |
| [Issue #533](https://github.com/zilliztech/memsearch/issues/533) | 高 | ONNX 提供商索引时内存泄漏（约 9MB/块） |
| [Issue #534](https://github.com/zilliztech/memsearch/issues/534) | 中 | Milvus 2.5+ 远程写入不持久化（缺少 flush） |
| [Issue #539](https://github.com/zilliztech/memsearch/issues/539) | 中 | 批量 upsert 中重复主键错误 |
| [Issue #102](https://github.com/zilliztech/memsearch/issues/102) | 低 | CJK 语言分词和 Markdown 解析需增强 |

资料来源：[社区问题追踪](https://github.com/zilliztech/memsearch/issues)

## 扩展阅读

- [设计理念](design-philosophy.md) - 深入了解项目的核心设计决策
- [Python API](python-api.md) - MemSearch 类的详细 API 参考
- [CLI 参考](cli.md) - 命令行工具完整文档
- [平台对比](platforms/index.md) - 各代理插件的功能对比

---

<a id='core-modules'></a>

## 核心模块详解

### 相关页面

相关主题：[系统架构](#architecture), [文本分块与索引机制](#chunking-indexing), [检索算法实现](#search-algorithm)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/memsearch/__init__.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/__init__.py)
- [src/memsearch/core.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/core.py)
- [src/memsearch/config.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/config.py)
- [src/memsearch/scanner.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py)
- [src/memsearch/watcher.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py)
- [src/memsearch/chunker.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py)
- [src/memsearch/cli.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py)
</details>

# 核心模块详解

## 概述

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

```mermaid
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` 是整个系统的核心入口类，封装了索引、搜索、配置等核心功能：

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

from .core import MemSearch

__all__ = ["MemSearch"]
```

资料来源：[src/memsearch/__init__.py:1-5]()

核心类提供了统一的 API 接口，负责：
- 加载和合并配置（全局配置 + 项目配置）
- 管理 Milvus 集合的生命周期
- 协调扫描、分块、嵌入、存储等流程
- 提供搜索和查询接口

### 配置管理架构

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

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

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

| 配置分类 | 键路径 | 说明 |
|---------|--------|------|
| Milvus | `milvus.uri` | Milvus 服务器地址 |
| Milvus | `milvus.token` | 认证令牌 |
| 嵌入 | `embedding.provider` | 嵌入提供者 (onnx/openai/google 等) |
| 嵌入 | `embedding.model` | 嵌入模型名称 |
| LLM | `llm.providers.*.type` | LLM 提供者类型 |
| LLM | `llm.providers.*.model` | LLM 模型名称 |
| 插件 | `plugins.*.summarize.*` | 插件摘要配置 |

## 文件扫描器 (Scanner)

### 功能定位

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

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

    path: Path
    mtime: float
    size: int
```

资料来源：[src/memsearch/scanner.py:10-14]()

### 扫描函数签名

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

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| `paths` | `list[str | Path]` | - | 要扫描的文件或目录列表 |
| `extensions` | `tuple[str, ...]` | `(".md", ".markdown")` | 目标文件扩展名 |
| `ignore_hidden` | `bool` | `True` | 是否忽略隐藏文件/目录 |

### 扫描流程

```mermaid
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 文件按语义结构拆分为可索引的分块：

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

资料来源：[src/memsearch/chunker.py:1-2]()

### 核心正则表达式

| 模式 | 正则 | 用途 |
|-----|------|------|
| 标题匹配 | `r"^(#{1,6})\s+(.+)$"` | 按 Markdown 标题层级拆分 |
| HTML 注释 | `r"<!--.*?-->"` | 清理元数据噪声 |

### 内容清洗

```python
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]()

### 内容质量过滤

```python
_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 字符
- 无实质语义内容

### 分块策略

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

## 文件监视器 (Watcher)

### 功能定位

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

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

资料来源：[src/memsearch/watcher.py:1-2]()

### 核心类设计

```python
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:
```

| 参数 | 类型 | 说明 |
|-----|------|------|
| `callback` | `Callable[[str, Path], None]` | 文件变化时的回调函数 |
| `extensions` | `tuple[str, ...]` | 监控的文件扩展名 |
| `debounce_ms` | `int` | 防抖延迟（毫秒） |

### 防抖机制

```mermaid
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，用于：
- 避免同一文件的连续修改触发多次处理
- 等待文件写入完成后再处理

### 线程安全

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

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

## CLI 模块

### 命令行接口结构

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

```python
# 交互式配置示例
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,
)
```

### 主要命令

| 命令 | 功能 |
|-----|------|
| `memsearch search` | 语义搜索记忆 |
| `memsearch expand` | 展开分块上下文 |
| `memsearch index` | 索引文件到 Milvus |
| `memsearch stats` | 查看索引统计 |
| `memsearch config init` | 初始化配置 |
| `memsearch config set/get/list` | 配置管理 |

### 配置项详情

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

| 插件 | 配置键 | 类型 | 说明 |
|-----|--------|------|------|
| Claude Code | `plugins.claude-code.summarize.model` | string | 摘要模型 |
| Claude Code | `plugins.claude-code.summarize.provider` | string | 摘要提供者 |
| Codex | `plugins.codex.summarize.model` | string | 摘要模型 |
| Codex | `plugins.codex.summarize.provider` | string | 摘要提供者 |
| OpenClaw | `plugins.openclaw.summarize.model` | string | 摘要模型 |
| OpenClaw | `plugins.openclaw.summarize.enabled` | bool | 是否启用 |

## 数据模型

### ScannedFile 数据类

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

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

### 配置数据模型

| 字段 | 说明 |
|-----|------|
| `milvus.uri` | Milvus 服务器地址 |
| `milvus.token` | 认证令牌 |
| `embedding.provider` | 嵌入提供者 |
| `embedding.model` | 嵌入模型 |
| `collection.name` | 集合名称 |

## 已知问题与限制

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

### 内存泄漏问题

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` 参数。

## 模块依赖关系

```mermaid
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` 中添加额外的清洗规则

---

<a id='chunking-indexing'></a>

## 文本分块与索引机制

### 相关页面

相关主题：[系统架构](#architecture), [检索算法实现](#search-algorithm)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/memsearch/chunker.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py)
- [src/memsearch/scanner.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py)
- [src/memsearch/store.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/store.py)
- [src/memsearch/maintenance.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/maintenance.py)
- [src/memsearch/core.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/core.py)
- [src/memsearch/compact.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/compact.py)
</details>

# 文本分块与索引机制

memsearch 的文本分块与索引机制是实现语义记忆搜索的核心基础设施。它负责将 Markdown 文件分割为语义完整的块（chunk），生成向量嵌入，并同步存储到 Milvus 向量数据库中。整个流程遵循"Markdown 即真相来源"的设计原则——Milvus 仅作为可重建的影子索引。

## 核心架构概览

```mermaid
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` 数据类定义元数据：

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

### scan_paths 扫描函数

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

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| paths | list[str \| Path] | - | 要扫描的文件或目录列表 |
| extensions | tuple[str, ...] | (".md", ".markdown") | 目标文件扩展名 |
| ignore_hidden | bool | True | 是否忽略隐藏文件/目录 |

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

```python
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 标题：

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

分块逻辑遵循以下原则：

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

### 内容清洗与过滤

#### clean_content_for_embedding 函数

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

```python
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()
```

**清洗步骤：**

| 步骤 | 操作 | 目的 |
|------|------|------|
| 1 | 移除 HTML 注释 `<!-- ... -->` | 去除会话/轮次 UUID 和转录路径等噪声 |
| 2 | 折叠连续空行 | 规范化格式，减少嵌入噪声 |
| 3 | 首尾空白清理 | 确保内容一致性 |

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

#### _has_meaningful_content 函数

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

```python
_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` → 有实际内容 → **保留**

### 分块数据流

```mermaid
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` 类管理，关键字段包括：

| 字段 | 类型 | 说明 |
|------|------|------|
| collection_name | str | Milvus 集合名称 |
| primary_field | str | 主键字段（chunk_hash） |
| vector_field | str | 向量字段 |
| text_field | str | 文本内容字段 |

### 向量生成与写入流程

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

```python
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 驱动的块压缩功能：

```python
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 提供商：**

| 提供商 | 环境变量 |
|--------|----------|
| OpenAI | `OPENAI_API_KEY` / `OPENAI_BASE_URL` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Gemini | `GOOGLE_API_KEY` |

**默认压缩提示词：**

```
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 索引选项

```bash
memsearch index <paths> [options]
```

| 选项 | 说明 |
|------|------|
| `--provider, -p` | 嵌入提供者 |
| `--model, -m` | 覆盖嵌入模型 |
| `--batch-size` | 嵌入批处理大小（0 = 提供商默认） |
| `--collection, -c` | Milvus 集合名称 |
| `--milvus-uri` | Milvus 连接 URI |
| `--max-chunk-size` | 最大块大小限制 |

### watch 模式

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

```bash
memsearch watch <paths> --debounce-ms 5000
```

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

## 故障排查

| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 搜索返回 0 结果 | 集合处于 `released` 状态 | 运行 `memsearch index` 重新加载 |
| `memsearch stats` 显示 0 chunks | 集合名称未正确解析 | 显式传递 `-c` 参数 |
| 内存持续增长 | ONNX 嵌入提供者内存泄漏 | 分批处理或进程复用 |
| 写入失败但报告成功 | Milvus 未执行 flush | 检查 Milvus 服务状态 |

## 相关文档

- [memsearch 架构](architecture.md) - 系统整体架构
- [配置指南](home/configuration.md) - 嵌入和 Milvus 配置
- [故障排查](troubleshooting.md) - 常见问题解决方案
- [插件系统](../platforms/claude-code/index.md) - Claude Code 等平台的集成

---

<a id='search-algorithm'></a>

## 检索算法实现

### 相关页面

相关主题：[文本分块与索引机制](#chunking-indexing), [系统架构](#architecture)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/memsearch/core.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/core.py)
- [src/memsearch/chunker.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/chunker.py)
- [src/memsearch/scanner.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/scanner.py)
- [src/memsearch/watcher.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/watcher.py)
- [src/memsearch/embeddings/__init__.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/embeddings/__init__.py)
</details>

# 检索算法实现

## 概述

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

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

## 核心检索流程

### 搜索执行流程

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

MemSearch 支持两种后端模式：

| 后端类型 | 配置方式 | 适用场景 |
|---------|---------|---------|
| Milvus Lite | 默认本地 `.db` 文件 | 单机、离线、个人使用 |
| 远程 Milvus | `milvus.uri` 配置 | 团队共享、大规模数据 |

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

### 配置文件解析流程

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

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

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

## 数据模型与索引结构

### Chunk 数据结构

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

### 分块算法

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

```python
_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()` 检查块是否有足够的实质内容

```python
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 转换为高维向量：

| 组件 | 默认实现 | 备选方案 |
|-----|---------|---------|
| 向量模型 | BGE-M3 (ONNX 本地运行) | OpenAI text-embedding-* |
| 维度 | 模型自动确定 | 可配置 |
| Token 限制 | 512 tokens | 可通过 `max_chunk_size` 调整 |

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

资料来源：[plugins/codex/README.md]()

## 文件扫描与索引

### 扫描器架构

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

**扫描策略**：

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

```python
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 支持增量索引，仅处理自上次索引后修改的文件：

| 策略 | 实现方式 |
|-----|---------|
| 基于 mtime | 比较文件修改时间，跳过未变化文件 |
| Watch 模式 | 实时监控文件变化，触发增量索引 |
| Debounce | 1500ms 防抖，防止频繁写入 |

```python
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 负责向量数据的持久化和查询：

```python
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](https://github.com/zilliztech/memsearch/issues/534)

### 搜索结果格式

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

## CLI 检索命令

### search 子命令

```bash
memsearch search <query> [options]

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

### expand 子命令

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

```bash
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](https://github.com/zilliztech/memsearch/issues/533)

### CJK 分词支持

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

## 配置参考

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `milvus.uri` | `milvus_lite` | Milvus 连接 URI |
| `embedding.provider` | `onnx` | 嵌入提供商 |
| `watch.debounce_ms` | `1500` | 文件变化防抖时间 |
| `max_chunk_size` | `512` | 单个 chunk 最大 tokens |

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

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

## 故障排除

| 问题 | 原因 | 解决方案 |
|-----|------|---------|
| Search 失败 "collection is in state 'released'" | Milvus Lite 未加载 | 确保 watch 进程运行或手动调用 load |
| Stats 显示 0 chunks | Collection 名称未正确解析 | 显式使用 `-c` 参数指定 |
| upsert 成功但 row_count=0 | Milvus 2.5+ 缺少 flush | 检查版本或手动 flush |
| 搜索无结果 | CJK 分词问题 | 考虑使用 jieba 分词增强 |

---

<a id='plugin-system'></a>

## 插件系统概述

### 相关页面

相关主题：[Claude Code 插件](#claude-code-plugin), [Codex CLI 插件](#codex-plugin), [OpenClaw 插件](#openclaw-plugin)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/codex/README.md](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/README.md)
- [plugins/openclaw/README.md](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/README.md)
- [plugins/openclaw/skills/memory-recall/SKILL.md](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/skills/memory-recall/SKILL.md)
- [plugins/opencode/index.ts](https://github.com/zilliztech/memsearch/blob/main/plugins/opencode/index.ts)
- [plugins/_shared/prompts/project_review.txt](https://github.com/zilliztech/memsearch/blob/main/plugins/_shared/prompts/project_review.txt)
- [README.md](https://github.com/zilliztech/memsearch/blob/main/README.md)
</details>

# 插件系统概述

## 概述

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

```mermaid
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 编码代理平台的插件集成：

| 插件名称 | 平台类型 | 集成方式 | 内存隔离 |
|---------|---------|---------|---------|
| Claude Code | Anthropic Claude Code | Stop Hook / SessionStart Hook | 独立 collection |
| Codex | OpenAI Codex | 生命周期 Hook | 独立 collection |
| OpenCode | OpenCode CLI | Native 工具集成 | 独立 collection |
| OpenClaw | OpenClaw 多代理 | Native 工具集成 | 按工作空间隔离 |

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

资料来源：[plugins/openclaw/README.md]()

## 插件架构

### 共享资源层

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

```mermaid
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 插件展示了典型的捕获流程：

```mermaid
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]()

### 三层递进检索

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

| 层级 | 工具 | 功能 | 适用场景 |
|-----|------|------|---------|
| L1 | `memory_search` | 语义 + 关键词混合搜索 | 快速召回 ("我们讨论过 X 吗？") |
| L2 | `memory_get` / `memory_expand` | 展开完整 markdown 节段 | 需要详情 ("解决方案是什么？") |
| L3 | `memory_transcript` | 解析原始会话转录 | 需要原始对话 ("给我看原始对话") |

```mermaid
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 定义了三个核心工具：

```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` 命令管理：

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `plugins.{name}.summarize.enabled` | `true` | 启用自动摘要捕获 |
| `plugins.{name}.summarize.provider` | `native` | 摘要生成提供者 |
| `plugins.{name}.summarize.model` | 平台默认 | 摘要生成模型 |
| `plugins.{name}.autoCapture` | `true` | 自动捕获对话摘要 |
| `plugins.{name}.autoRecall` | `true` | 启动时自动注入记忆 |

### 嵌入提供者配置

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

| 提供者 | 说明 | API Key 要求 |
|-------|------|-------------|
| `onnx` | 本地 BGE-M3 模型 | 无 (默认) |
| `openai` | OpenAI 嵌入 | 需要 `OPENAI_API_KEY` |
| `google` | Google 嵌入 | 需要 API Key |
| `voyage` | Voyage AI | 需要 API Key |
| `jina` | Jina AI | 需要 API Key |
| `mistral` | Mistral AI | 需要 API Key |
| `ollama` | 本地 Ollama | 无 |

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

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

### Milvus 后端配置

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `milvus.uri` | `milvus_lite` | Milvus 服务器地址 |
| `milvus.token` | 无 | 远程 Milvus 认证令牌 |

```bash
# 使用远程 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]()

## 已知限制与问题

### 已识别的社区问题

| Issue | 描述 | 影响 |
|-------|------|------|
| #540 | Milvus Lite CLI 搜索在非活跃会话时失败 (collection 'released' 状态) | CLI search 命令无法独立工作 |
| #535 | Codex 插件仍使用已弃用的 `features.codex_hooks` | Codex CLI 产生弃用警告 |
| #520 | Stop hook 的 `claude -p` 调用触发 SessionStart | 污染每日日志 |
| #527 | API 速率限制时 Stop hook 写入错误字符串 | 摘要内容被污染 |

### Codex 插件弃用警告

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

资料来源：[plugins/codex/README.md]()

## 安装与维护

### 插件更新

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

# 完全卸载插件
memsearch plugin uninstall
```

### 配置初始化

```bash
# 全局交互式配置
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 名称

### 项目内存结构建议

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

```markdown
# Project Memory

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

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

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

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

## Open Questions
待解决的问题

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

## Next Steps
下一步计划

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

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

---

<a id='claude-code-plugin'></a>

## Claude Code 插件

### 相关页面

相关主题：[插件系统概述](#plugin-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/claude-code/README.md](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/README.md)
- [plugins/claude-code/hooks/session-start.sh](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/hooks/session-start.sh)
- [plugins/claude-code/hooks/stop.sh](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/hooks/stop.sh)
- [plugins/claude-code/hooks/user-prompt-submit.sh](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/hooks/user-prompt-submit.sh)
- [plugins/claude-code/transcript.py](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/transcript.py)
- [docs/platforms/claude-code/how-it-works.md](https://github.com/zilliztech/memsearch/blob/main/docs/platforms/claude-code/how-it-works.md)
</details>

# Claude Code 插件

Claude Code 插件是 memsearch 为 Claude Code（claude.ai/code）提供的原生集成层，通过 Claude Code 的钩子（hooks）系统实现会话记忆的自动捕获、索引和检索。该插件使 Claude Code 在项目开发过程中积累的对话上下文成为可搜索的语义记忆，从而实现跨会话的知识保留和上下文恢复。

## 核心功能概览

| 功能模块 | 触发时机 | 作用 |
|---------|---------|------|
| **SessionStart** | 会话启动时 | 初始化当日记忆文件，记录会话元信息 |
| **UserPromptSubmit** | 用户提交提示时 | 标记当前对话轮次，锚定会话路径 |
| **Stop** | 会话结束时 | 解析并总结对话内容，追加至记忆文件 |
| **自动索引** | Stop 钩子完成后 | 将新增记忆内容同步至 Milvus 向量库 |

## 架构设计

### 数据流总览

```mermaid
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 启动时执行，负责初始化当日记忆文件：

```mermaid
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` 在用户每次提交提示时执行，用于标记对话轮次边界：

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

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

### 3. 会话停止（Stop Hook）

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

```mermaid
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]
```

**摘要格式示例**：
```markdown
- 用户询问了 X 问题
- Claude 分析了 Y 方案
- 双方讨论了 Z 限制
<!-- session:uuid transcript:/path/to/transcript.jsonl -->
```

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

### 4. 向量索引同步

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

```bash
memsearch index .memsearch/memory/
```

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

## 记忆文件格式

### 每日记忆文件

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

```markdown
# Daily Memory

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

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

### 项目回顾文件

位置：`.memsearch/PROJECT_MEMORY.md`

建议结构：
```markdown
# Project Memory

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

## 3层递进检索模式

```mermaid
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
```

| 层级 | 命令 | 返回内容 | 使用场景 |
|-----|------|---------|---------|
| L1 | `memsearch search` | 相关性排序的分块列表 | 快速回忆"是否讨论过 X" |
| L2 | `memsearch expand <hash>` | 完整 Markdown 段落 | 需要具体解决方案细节 |
| L3 | `transcript.py` | 原始对话记录 | 需要查看具体措辞和上下文 |

## 配置选项

### 插件级配置

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

# 查看当前配置
memsearch config list
```

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `plugins.claude-code.enabled` | `true` | 启用/禁用插件 |
| `plugins.claude-code.summarize.enabled` | `true` | 自动摘要功能 |
| `plugins.claude-code.summarize.provider` | `native` | 摘要提供者：native/openai |
| `plugins.claude-code.summarize.model` | `haiku` | 摘要模型名称 |
| `plugins.claude-code.project_review.enabled` | `false` | 项目回顾功能 |
| `plugins.claude-code.user_profile.enabled` | `false` | 用户画像功能 |

### 使用外部摘要提供者

```bash
# 配置 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：
```bash
uv pip install memsearch
```

2. 在 Claude Code 中安装插件：
```
/install https://github.com/zilliztech/memsearch
```

3. 初始化项目配置：
```bash
cd your-project
memsearch config init --project
```

### 卸载步骤

1. 在 Claude Code 中卸载插件：
```
/uninstall memsearch
```

2. 清理项目数据（可选）：
```bash
rm -rf .memsearch/
```

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

## 与 Codex 插件的差异

| 特性 | Claude Code 插件 | Codex 插件 |
|-----|-----------------|-----------|
| 钩子系统 | Claude Code 原生 hooks | 自定义 hooks.json |
| 会话解析 | `transcript.py` | 自定义解析器 |
| 摘要生成 | `claude -p` 或外部 API | 类似机制 |
| 状态管理 | 文件锚点 + Milvus | 类似架构 |
| **弃用状态** | 活跃维护 | 使用废弃的 `features.codex_hooks`（见 Issue #535） |

## 故障排查

### 常见问题

| 问题 | 可能原因 | 解决方案 |
|-----|---------|---------|
| 记忆未写入 | 钩子未正确安装 | 检查 `~/.claude/settings.json` |
| 索引失败 | Milvus Lite 未加载 | 确保 watch 进程运行或手动 `memsearch index` |
| 摘要为空 | API 速率限制 | 检查 Issue #527，升级插件 |
| 会话污染 | `claude -p` 触发 SessionStart | 见 Issue #520，评估 `--no-session-persistence` |

### 诊断命令

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

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

# 测试检索
memsearch search "your query"
```

## 相关社区议题

| Issue | 描述 | 状态 |
|-------|------|------|
| #520 | `claude -p` 触发 SessionStart 导致日志污染 | 开放 |
| #527 | 速率限制错误被写入记忆摘要 | 开放 |
| #537 | 压缩前对话记录未捕获 | 开放 |
| #535 | 使用废弃的 `features.codex_hooks` 配置 | 开放 |

## 参考资料

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

---

<a id='codex-plugin'></a>

## Codex CLI 插件

### 相关页面

相关主题：[插件系统概述](#plugin-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/codex/README.md](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/README.md)
- [plugins/codex/skills/memory-config/SKILL.md](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/skills/memory-config/SKILL.md)
- [plugins/codex/prompts/project_review.txt](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/prompts/project_review.txt)
- [plugins/claude-code/README.md](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/README.md)
- [plugins/claude-code/skills/memory-recall/SKILL.md](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/skills/memory-recall/SKILL.md)
- [src/memsearch/cli.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py)
- [README.md](https://github.com/zilliztech/memsearch/blob/main/README.md)
</details>

# Codex CLI 插件

## 概述

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

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

## 核心功能

### 记忆捕获（Capture）

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

### 记忆检索（Recall）

三层递进式检索机制：

| 层级 | 工具 | 功能描述 |
|------|------|----------|
| L1 | `memsearch search` | 语义+关键词混合搜索，返回排名结果 |
| L2 | `memsearch expand` | 展开匹配块获取完整 Markdown 段落 |
| L3 | 解析 transcript | 从原始会话文件获取原始对话 |

## 工作原理

### 架构图

```mermaid
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](https://github.com/zilliztech/memsearch/blob/main/README.md)

## 安装与配置

### 安装命令

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

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

安装脚本会自动配置以下内容：
- 创建项目级 `.memsearch/` 目录结构
- 配置 Codex hooks（SessionStart 和 Stop）
- 设置默认的记忆摘要模型

### 初始化配置

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

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

### 关键配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `plugins.codex.summarize.enabled` | 是否启用自动摘要 | true |
| `plugins.codex.summarize.provider` | 摘要服务提供商 | native |
| `plugins.codex.summarize.model` | 摘要模型 | haiku |
| `plugins.codex.project_review.enabled` | 项目回顾任务 | false |
| `plugins.codex.user_profile.enabled` | 用户画像任务 | false |

资料来源：[plugins/codex/skills/memory-config/SKILL.md:3-5](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/skills/memory-config/SKILL.md)

### 嵌入模型配置

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

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

### Milvus 后端配置

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

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

资料来源：[plugins/codex/README.md:18-30](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/README.md)

## 插件工具集

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](https://github.com/zilliztech/memsearch/blob/main/plugins/claude-code/skills/memory-recall/SKILL.md)

## 记忆文件结构

### 目录布局

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

### 记忆文件格式

```markdown
# 2026-03-27

## 会话摘要

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

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

### PROJECT_MEMORY.md 结构

```markdown
# 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](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/prompts/project_review.txt)

## 已知问题

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

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

**影响范围：**
- 插件安装脚本
- Stop hook 隔离逻辑
- 相关文档说明

**状态：** 待修复

资料来源：[社区 Issue #535](https://github.com/zilliztech/memsearch/issues/535)

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

即使设置了 `--no-session-persistence`、`--no-chrome` 并清除 `CLAUDECODE=`，内部的 `claude -p` 调用仍会触发插件的 `SessionStart` Hook，导致：
- 每日日志被污染
- 记忆泄漏到嵌套目录

资料来源：[社区 Issue #520](https://github.com/zilliztech/memsearch/issues/520)

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

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

资料来源：[社区 Issue #527](https://github.com/zilliztech/memsearch/issues/527)

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

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

资料来源：[社区 Issue #537](https://github.com/zilliztech/memsearch/issues/537)

## 配置初始化交互

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

```bash
memsearch config init
```

**交互提示包括：**

| 配置项 | 提示文本 |
|--------|----------|
| Codex 摘要启用 | `Codex automatic summaries enabled` |
| Codex 摘要提供商 | `Codex summarize provider` |
| Codex 摘要模型 | `Codex summarize model` |
| Codex 项目回顾 | `Codex project review enabled` |
| Codex 用户画像 | `Codex user profile enabled` |

资料来源：[src/memsearch/cli.py:145-160](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/cli.py)

## 最佳实践

### 会话恢复

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

```bash
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](https://github.com/zilliztech/memsearch/blob/main/plugins/codex/skills/memory-config/SKILL.md)

## 与 Claude Code 插件对比

| 特性 | Codex 插件 | Claude Code 插件 |
|------|-----------|-----------------|
| 摘要模型 | 可配置 | 可配置 |
| 项目回顾 | 支持 | 支持 |
| 用户画像 | 支持 | 支持 |
| 转录解析 | 支持 | 支持 |
| 记忆锚点 | `session:UUID` | `session:UUID` |

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

---

<a id='openclaw-plugin'></a>

## OpenClaw 插件

### 相关页面

相关主题：[插件系统概述](#plugin-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [plugins/openclaw/README.md](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/README.md)
- [plugins/openclaw/index.ts](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/index.ts)
- [plugins/openclaw/skills/memory-recall/SKILL.md](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/skills/memory-recall/SKILL.md)
- [plugins/openclaw/skills/memory-config/SKILL.md](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/skills/memory-config/SKILL.md)
- [plugins/openclaw/prompts/project_review.txt](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/prompts/project_review.txt)
- [plugins/_shared/prompts/project_review.txt](https://github.com/zilliztech/memsearch/blob/main/plugins/_shared/prompts/project_review.txt)
- [src/memsearch/config.py](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/config.py)
</details>

# OpenClaw 插件

## 概述

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](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/README.md)

## 架构设计

### 插件组件结构

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

| 组件路径 | 功能说明 |
|---------|---------|
| `index.ts` | 主入口，定义 agent tools 和 hook 脚本 |
| `skills/memory-recall/SKILL.md` | 记忆检索 skill，定义 memory_search/get/transcript 工具用法 |
| `skills/memory-config/SKILL.md` | 配置管理 skill，引导用户完成 memsearch 配置 |
| `prompts/project_review.txt` | 项目回顾 prompt 模板 |
| `scripts/parse-transcript.sh` | 原始对话转录解析脚本 |

资料来源：[plugins/openclaw/index.ts:1-50](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/index.ts)

### 记忆检索工具

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

```mermaid
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 + 向量相似度），返回相关片段列表。

**参数**：

| 参数名 | 类型 | 必需 | 说明 |
|-------|------|------|------|
| query | string | 是 | 搜索查询文本 |

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

资料来源：[plugins/openclaw/index.ts:100-130](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/index.ts)

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

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

**参数**：

| 参数名 | 类型 | 必需 | 说明 |
|-------|------|------|------|
| chunk_hash | string | 是 | 搜索结果中的 chunk_hash |

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

资料来源：[plugins/openclaw/index.ts:130-160](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/index.ts)

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

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

**参数**：

| 参数名 | 类型 | 必需 | 说明 |
|-------|------|------|------|
| session_id | string | 是 | 会话 ID（从锚点注释获取） |
| turn_id | string | 否 | 指定轮次 ID |
| transcript_path | string | 否 | 转录文件路径 |

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

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

资料来源：[plugins/openclaw/skills/memory-recall/SKILL.md:30-50](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/skills/memory-recall/SKILL.md)

### 决策指南

| 用户意图 | 使用的工具 |
|---------|-----------|
| 快速回忆（"我们讨论过 X 吗？"） | memory_search |
| 需要详情（"解决方案是什么？"） | memory_search → memory_get |
| 需要原始对话（"展示原始对话内容"） | memory_search → memory_get → memory_transcript |

资料来源：[plugins/openclaw/skills/memory-recall/SKILL.md:55-65](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/skills/memory-recall/SKILL.md)

## 工作流程

### 会话捕获流程

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

```mermaid
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](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/README.md)

### 自动维护任务

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

| 任务类型 | 说明 | 配置项 |
|---------|------|--------|
| project_review | 项目回顾，维护 `PROJECT.md` 记忆文件 | `plugins.openclaw.project_review.*` |
| user_profile | 用户画像，维护 `USER.md` 个人偏好文件 | `plugins.openclaw.user_profile.*` |

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

资料来源：[src/memsearch/config.py:80-100](https://github.com/zilliztech/memsearch/blob/main/src/memsearch/config.py)

## 配置管理

### 可配置项

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

| 配置项 | 默认值 | 说明 |
|-------|--------|------|
| `summarize.enabled` | true | 是否启用自动摘要 |
| `summarize.provider` | native | 摘要 provider（native 表示使用插件内置） |
| `summarize.model` | - | 摘要模型名称 |
| `project_review.enabled` | false | 项目回顾任务开关 |
| `project_review.provider` | native | 项目回顾 provider |
| `project_review.model` | - | 项目回顾模型 |
| `project_review.min_interval_hours` | 24 | 最小执行间隔（小时） |
| `project_review.input_dir` | .memsearch/memory | 输入目录 |
| `user_profile.*` | - | 用户画像配置（同 project_review） |

### 交互式配置

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

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

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

资料来源：[plugins/openclaw/skills/memory-config/SKILL.md:1-30](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/skills/memory-config/SKILL.md)

## 项目回顾 Prompt 规范

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

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

**推荐的文件结构**：
```markdown
# Project Memory

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

**输出格式**：
```json
{"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](https://github.com/zilliztech/memsearch/blob/main/plugins/openclaw/prompts/project_review.txt)

## 与其他插件的对比

| 特性 | Claude Code | Codex | OpenCode | OpenClaw |
|-----|------------|-------|---------|----------|
| 记忆工具 | memory_search/get/transcript | memory_search/get/transcript | memory_search/get/transcript | memory_search/get/transcript |
| 摘要生成 | claude -p (haiku) | 原生代码模型 | 原生模型 | 原生模型 |
| 自动维护 | project_review/user_profile | project_review/user_profile | project_review/user_profile | project_review/user_profile |
| Hook 机制 | SessionStart/Stop | SessionStart/Stop | SessionStart/Stop | SessionStart/Stop |

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

资料来源：[plugins/_shared/prompts/project_review.txt:1-20](https://github.com/zilliztech/memsearch/blob/main/plugins/_shared/prompts/project_review.txt)

## 相关社区问题

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

| Issue | 问题描述 | 影响范围 |
|-------|---------|---------|
| #540 | Milvus Lite 集合处于 'released' 状态导致搜索失败 | CLI search |
| #539 | 同一批次中不允许重复主键 | 索引操作 |
| #538 | 仅在配置文件中设置 collection name 时 stats 显示 0 chunks | 统计命令 |
| #533 | 索引时每 chunk 泄漏约 9MB 内存 | 大型语料库 |
| #534 | MilvusStore.upsert() 报告成功但数据未持久化 | 远程 Milvus |

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

## 快速入门

1. **安装 OpenClaw 插件**：
   ```bash
   memsearch plugin install openclaw
   ```

2. **验证安装**：
   ```bash
   memsearch plugin list
   ```

3. **配置 provider（可选）**：
   ```bash
   memsearch config set plugins.openclaw.summarize.provider openai
   memsearch config set plugins.openclaw.summarize.model gpt-5-mini
   ```

4. **开始使用**：
   - 在 OpenClaw 会话中直接询问记忆相关问题
   - 使用 `memory_search`、`memory_get`、`memory_transcript` 工具检索

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: zilliztech/memsearch; human_manual_source: deepwiki_human_wiki -->