# https://github.com/memvid/memvid 项目说明书
生成时间：2026-06-22 20:47:46 UTC
## 目录
- [Memvid 概述与 Smart Frames 架构](#page-1)
- [数据摄入、生命周期与多模态支持](#page-2)
- [搜索、检索与嵌入模型](#page-3)
- [SDK、Docker、加密胶囊与运维](#page-4)
## Memvid 概述与 Smart Frames 架构
### 相关页面
相关主题：[数据摄入、生命周期与多模态支持](#page-2), [SDK、Docker、加密胶囊与运维](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/memvid/memvid/blob/main/README.md)
- [src/memvid/search/mod.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/mod.rs)
- [src/memvid/search/api.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/api.rs)
- [src/memvid/search/builders.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/builders.rs)
- [src/memvid/search/tantivy.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/tantivy.rs)
- [src/memvid/search/fallback.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/fallback.rs)
- [src/memvid/search/helpers.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/helpers.rs)
- [src/analysis/mod.rs](https://github.com/memvid/memvid/blob/main/src/analysis/mod.rs)
- [src/analysis/auto_tag.rs](https://github.com/memvid/memvid/blob/main/src/analysis/auto_tag.rs)
- [src/search/tantivy/mod.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/mod.rs)
- [src/search/tantivy/storage.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/storage.rs)
# Memvid 概述与 Smart Frames 架构
## 1. 项目定位与设计目标
Memvid 是一个面向 AI Agent 的"单文件记忆层"，其核心主张是把持久化、版本化、可移植的记忆封装到一个独立的 `.mv2` 文件中，无需任何外部数据库。README 中将其定位为"a single-file memory layer for AI agents with instant retrieval and long-term memory"，强调"Persistent, versioned, and portable memory, without databases"。这种设计的直接后果是：开发者无需再维护 `.wal`、`.lock`、`.shm` 等常见的边车文件，从而显著降低运维复杂度。资料来源：[README.md:1-50]()
围绕这一目标，Memvid 提出了"Living Memory Engine / Capsule Context / Time-Travel Debugging / Smart Recall / Codec Intelligence"等概念。其中 **Smart Recall** 明确给出了"亚 5ms 的本地访问 + 预测式缓存"的指标，**Codec Intelligence** 则意味着压缩策略会在写入过程中自动选择并可升级。资料来源：[README.md:50-100]()
## 2. .mv2 文件与 Smart Frames 数据模型
`.mv2` 是 Smart Frames 架构的物理载体。整个文件按固定布局分段：头部（Magic / 版本 / 容量）、嵌入式 WAL（1–64MB，用于崩溃恢复）、数据段（压缩后的帧）、Lex 索引（Tantivy 全文）、Vec 索引（HNSW 向量）、Time 索引（按时间排序）以及 TOC（Footer，记录段偏移）。资料来源：[README.md:120-160]()
**Smart Frame** 是逻辑层的最小单元，对应代码中的 `Frame` / `ChunkInfo` 与 `PutOptions`。一次 `put` 调用会附带 `title`、`uri`、`tag(k,v)` 等元数据，再被切分为若干 chunk 帧（`DocumentChunk`），并通过 `parent_id` 关联回文档帧，从而既支持单文档检索，也支持跨 chunk 上下文拼接。资料来源：[src/memvid/search/helpers.rs:1-50]()、[README.md:200-230]()
## 3. 模块化特性与可插拔检索管线
Memvid 通过 Cargo feature flags 把不同能力解耦，使核心运行时保持精简。`lex` 提供 Tantivy 全文检索（BM25），`vec` 提供 HNSW 向量检索（可本地 ONNX 嵌入），`clip` 提供图像向量，`whisper` 提供音频转写，`api_embed` 走 OpenAI，`temporal_track` 支持自然语言日期解析，`encryption` 生成 `.mv2e` 加密胶囊，`symspell_cleanup` 用于修复 PDF 提取乱码。资料来源：[README.md:160-200]()
检索管线在 `src/memvid/search/mod.rs` 中体现为三段式：先用 Sketch Track 做候选过滤（`hamming_threshold=32`，`max_candidates = top_k*10`），再用 Tantivy 做 BM25 重排，最后由向量分支兜底。资料来源：[src/memvid/search/mod.rs:1-80]()
```mermaid
flowchart LR
Q[Query] --> SK[Sketch Pre-Filter]
SK -->|候选 FrameId| TV[Tantivy BM25]
TV -->|hits| VR[Vector / Lex Fallback]
VR --> ACL[ACL Enforcement]
ACL --> R[SearchResponse]
```
各分支独立实现：`try_tantivy_search` 负责 BM25 主路径（使用词干化后的 token 与索引对齐），`search_with_lex_fallback` 在 Tantivy 不可用时回退到内存中的 `LexIndex`，`enrich_hits_with_entities` 把 Logic-Mesh 中的 NER 实体以及时间提及挂载到命中结果上。资料来源：[src/memvid/search/tantivy.rs:1-60]()、[src/memvid/search/fallback.rs:1-50]()、[src/memvid/search/helpers.rs:50-120]()
## 4. 分析层与可演进管线
分析层位于 `src/analysis/` 下，包含四个子模块：`auto_tag`（基于词频与停用词自动派生标签）、`ner`（命名实体识别并产出 Logic-Mesh）、`temporal`（基于 `temporal_track` 解析自然语言日期），以及 `temporal_enrich`（把时间元数据附加到命中）。`auto_tag` 通过正则切分 token、过滤停用词、按词频降序输出前 N 个候选，从而为帧补充可检索的"标签面"。资料来源：[src/analysis/mod.rs:1-10]()、[src/analysis/auto_tag.rs:1-60]()
索引构建侧则用 `builders.rs` 把新增向量/词条与已有索引合并：旧帧先以 `frame_is_active` 过滤后再 add，新帧追加，最后通过 `VecIndexBuilder::finish` 与 `LexIndex::decode` 输出 artifact，再写回 TOC。资料来源：[src/memvid/search/builders.rs:1-80]()
## 5. 常见误区与社区关注点
社区讨论中有几个反复出现的疑点需要澄清。第一，Memvid 不是 LLM 本身，而是**记忆与检索层**，"未来是不是要取代 LLM / 通往 AGI"的提问实际上超出了本仓库的范围。资料来源：[README.md:50-100]()。第二，benchmark 与真实负载问题（Issue #42）提示：当前示例数据规模有限，编码时间、向量段重建代价需要在自身数据上重测。第三，企业代理与本地 LLM（如 Ollama、LiteLLM、OpenAI 兼容网关）需要通过"自定义 base URL"能力（Issue #202、#23）来落地，这一能力在 `api_embed` 与 ask 流程中存在，但需按官方文档显式配置。第四，最新 v2.0.140 修复了 WAL 在 region 增长时的校验和损坏问题（Issue #230），意味着在持续 `put + commit` 负载下，旧版本可能出现稀疏文件越界，建议升级后再做压测。资料来源：[README.md:200-260]()
## See Also
- 文件格式规范：`MV2_SPEC.md`
- 检索 API：`src/memvid/search/api.rs`
- 时间旅行与提交：`src/memvid/lifecycle.rs`
- CLI 与 Node SDK：`memvid-cli`、`@memvid/sdk`（见 README "SDKs & CLI"）
---
## 数据摄入、生命周期与多模态支持
### 相关页面
相关主题：[Memvid 概述与 Smart Frames 架构](#page-1), [搜索、检索与嵌入模型](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/memvid/memvid/blob/main/README.md)
- [src/analysis/mod.rs](https://github.com/memvid/memvid/blob/main/src/analysis/mod.rs)
- [src/analysis/auto_tag.rs](https://github.com/memvid/memvid/blob/main/src/analysis/auto_tag.rs)
- [src/analysis/ner.rs](https://github.com/memvid/memvid/blob/main/src/analysis/ner.rs)
- [src/memvid/search/mod.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/mod.rs)
- [src/memvid/search/api.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/api.rs)
- [src/memvid/search/builders.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/builders.rs)
- [src/memvid/search/tantivy.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/tantivy.rs)
- [src/memvid/search/helpers.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/helpers.rs)
- [src/search/tantivy/mod.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/mod.rs)
- [src/search/tantivy/schema.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/schema.rs)
# 数据摄入、生命周期与多模态支持
## 1. 模块定位与总体架构
`memvid` 的核心定位是"单文件记忆层"：所有持久化数据（写入、日志、索引、目录）都集中在 `.mv2` 文件中，不再依赖外部 `.wal`、`.lock`、`.shm` 等伴随文件。这一点在 [README.md](README.md) 的"File Format"章节中以分层图的形式被明确描述：头部、嵌入式 WAL、数据段、Lex 索引、Vec 索引、时间索引、目录脚注。围绕该单文件结构，项目通过 Cargo feature flag 暴露一组可组合能力，包括 `lex`（Tantivy 全文检索）、`vec`（HNSW + ONNX 本地嵌入）、`clip`（图像检索）、`whisper`（音频转写）、`pdf_extract`（PDF 文本抽取）、`api_embed`（OpenAI 云端嵌入）、`temporal_track`（自然语言日期解析）、`parallel_segments`（多线程摄入）以及 `encryption`（`.mv2e` 加密胶囊）等（[README.md](README.md)）。这些开关共同决定了数据进入系统后会被哪些分析与索引链路处理。
从代码组织来看，分析与索引能力被拆分到三个模块：
- `src/analysis` 提供 `auto_tag`（自动标签）、`ner`（命名实体识别）、`temporal` / `temporal_enrich`（时间解析与富化），由 [src/analysis/mod.rs](src/analysis/mod.rs) 统一导出。
- `src/search/tantivy` 封装 Tantivy 全文搜索引擎，并定义其 schema（[src/search/tantivy/mod.rs](src/search/tantivy/mod.rs)、[src/search/tantivy/schema.rs](src/search/tantivy/schema.rs)）。
- `src/memvid/search` 负责把这些能力组装成高层 `search` API、混合检索、回退路径与索引构建器（[src/memvid/search/mod.rs](src/memvid/search/mod.rs)、[src/memvid/search/api.rs](src/memvid/search/api.rs)）。
## 2. 数据摄入与生命周期
摄入流程的入口是 `Memvid::create` 与 `PutOptions` 构造器，[README.md](README.md) 中的"Quick Start"示例展示了一条最小路径：创建 `.mv2` → 写入带元数据的文档 → 提交 → 检索。底层 `put` / `commit` 写入的是带嵌入 WAL 的段（[README.md](README.md) "Embedded WAL (1-64MB)"）；v2.0.140 修复的 `#230` 问题正是 WAL 在 `grow_wal_region` / `ensure_wal_capacity` 之后出现 checksum mismatch，说明 WAL 的区域增长是生命周期中的关键脆弱点。
写入过程中，分析模块以"内容驱动"方式产生附加产物：
- **自动标签**：[src/analysis/auto_tag.rs](src/analysis/auto_tag.rs) 中的 `derive_labels` 用正则 `(?m)^(?P[A-Z][A-Za-z0-9 &/-]{3,})$` 从文本中提取行首大写短语作为候选标签；同时基于词频与停用词表（`based`、`system`、`application` 等）筛除通用词，输出高频词作为补充标签。
- **命名实体识别**：[src/analysis/ner.rs](src/analysis/ner.rs) 中的 `NerModel::load` 加载 ONNX 会话与 `tokenizer.json`，使用 `PaddingStrategy::BatchLongest` 与右侧截断对齐批次输入；`decode_predictions_static` 解析 `[batch, seq_len, num_labels]` 的 logits 张量，按 `min_confidence` 阈值输出 `ExtractedEntity` 列表。
- **时间解析**：`temporal_track` / `temporal_enrich` 特性启用后，搜索阶段会通过 [src/memvid/search/helpers.rs](src/memvid/search/helpers.rs) 的 `attach_temporal_metadata` 把"last Tuesday"之类的自然语言时间锚点挂到 hit 元数据上。
这些分析产物并不直接改变帧内容，而是作为元数据进入后续的索引构建与命中富化。
## 3. 索引构建与多模态支持
摄入完成后，`commit` 会触发多路索引重建。`build_lex_artifact` 与 `build_vec_artifact`（[src/memvid/search/builders.rs](src/memvid/search/builders.rs)）分别把新增文档和已有活跃帧一起重新序列化到 Tantivy 段或 HNSW 索引；HNSW 侧的 `VecIndexBuilder::add_document(frame_id, embedding)` 同时接受 ONNX 本地嵌入与 `api_embed` 启用后的 OpenAI 嵌入，模型包括 `text-embedding-3-small`（1536 维）、`text-embedding-3-large`（3072 维）和 `text-embedding-ada-002`（[README.md](README.md) "Text Embedding Models"）。社区讨论 #202 提出了对自定义 base URL（LiteLLM、企业代理等）的需求，正是针对这条 `api_embed` 链路。
多模态输入通过不同 reader 解码后再走统一的 `put` 路径：纯文本经过 MIME 过滤后由 `is_frame_text_indexable` 判定是否进入 Lex 索引（[src/memvid/search/api.rs](src/memvid/search/api.rs)），其白名单覆盖 JSON/XML/PDF/RTF/YAML/TOML 等文本类型，并将 Office 与 OpenDocument 文档统一视为可索引；PDF 通过 `pdf_extract` 在 Rust 内核完成抽取。音频由 Whisper 处理：默认 FP32 small 模型（~75 MB），可通过 `MEMVID_WHISPER_MODEL=whisper-tiny-en-q8k` 切换为 19 MB 的量化 tiny（[README.md](README.md) "Whisper Models"）。图像通过 `clip` 特性生成视觉嵌入供 HNSW 检索。
## 4. 检索路径与社区关注点
检索阶段是生命周期的"消费侧"。[src/memvid/search/mod.rs](src/memvid/search/mod.rs) 显示搜索会先用 sketch 轨道做候选过滤（`hamming_threshold = 32`，候选数 `top_k * 10`），再用 BM25/Tantivy 重排；混合路径位于 [src/memvid/search/tantivy.rs](src/memvid/search/tantivy.rs)，回退路径位于 [src/memvid/search/fallback.rs](src/memvid/search/fallback.rs)。`build_context`（[src/memvid/search/helpers.rs](src/memvid/search/helpers.rs)）按 base URI 分组并设置 `MAX_CONTEXT_HITS = 24` 来平衡多样性与噪声；Tantivy schema（[src/search/tantivy/schema.rs](src/search/tantivy/schema.rs)）将 `tags`、`labels`、`track`、`uri`、`timestamp`、`frame_id` 列为索引字段，使元数据可被原生查询。
社区对生命周期与多模态的主要关切集中在三点：#43 质疑性能基准的可复现性，#42 要求公开大样本下的编码时间与视频编码开销，#23 询问本地 LLM（如 Ollama）替代云的可行性。这些都说明文档化的能力清单（feature flag）需要与可验证的基准、配额限制（`parallel_segments`、`WhisperConfig::with_quantization` 等开关）配套呈现，避免对"十亿级"规模（#44）做出无证据的承诺。
## See Also
- [文件格式规范](MV2_SPEC.md)
- [功能开关与依赖](README.md#feature-flags)
- [搜索 API 参考](src/memvid/search/api.rs)
---
## 搜索、检索与嵌入模型
### 相关页面
相关主题：[Memvid 概述与 Smart Frames 架构](#page-1), [数据摄入、生命周期与多模态支持](#page-2), [SDK、Docker、加密胶囊与运维](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/memvid/memvid/blob/main/README.md)
- [src/memvid/search/mod.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/mod.rs)
- [src/memvid/search/tantivy.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/tantivy.rs)
- [src/memvid/search/fallback.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/fallback.rs)
- [src/memvid/search/helpers.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/helpers.rs)
- [src/memvid/search/api.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/api.rs)
- [src/memvid/search/builders.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/builders.rs)
- [src/search/tantivy/mod.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/mod.rs)
- [src/search/tantivy/engine.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/engine.rs)
- [src/search/tantivy/schema.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/schema.rs)
- [src/search/tantivy/storage.rs](https://github.com/memvid/memvid/blob/main/src/search/tantivy/storage.rs)
- [src/analysis/mod.rs](https://github.com/memvid/memvid/blob/main/src/analysis/mod.rs)
- [src/analysis/ner.rs](https://github.com/memvid/memvid/blob/main/src/analysis/ner.rs)
- [src/analysis/auto_tag.rs](https://github.com/memvid/memvid/blob/main/src/analysis/auto_tag.rs)
- [docker/README.md](https://github.com/memvid/memvid/blob/main/docker/README.md)
# 搜索、检索与嵌入模型
## 一、定位与总体架构
Memvid 的定位是「面向 AI 智能体的单文件持久化记忆层」，搜索、检索与嵌入模型是其核心能力之一。它在 `.mv2` 单文件内同时承载**词法全文索引**（BM25 / Tantivy）、**向量索引**（HNSW）与**时间索引**，无需任何外部数据库或侧车文件（[README.md:75-90]()）。
搜索子系统在代码层面按 feature flag 解耦：
| 特性开关 | 作用 |
| --- | --- |
| `lex` | Tantivy 全文检索（BM25 排序） |
| `vec` | HNSW 向量相似度搜索 + 本地 ONNX 文本嵌入 |
| `api_embed` | OpenAI 等云端嵌入 API |
| `clip` | CLIP 视觉嵌入 |
| `whisper` | 音频转写 |
| `temporal_track` | 自然语言日期解析 |
仅在启用对应特性时，相关模块才会被编译进二进制（[src/memvid/search/tantivy.rs:1-12](), [src/analysis/mod.rs:1-5]()）。
## 二、搜索流水线与回退机制
`Memvid::search` 是检索入口，内部通过 `mod.rs` 的协调器按顺序尝试：Tantivy 全文 → 词法回退 → 向量/Hybrid 检索。当启用 `sketch`（草图）轨道时，会先用低成本的汉明距离候选过滤，把候选项交给 BM25 重排（[src/memvid/search/mod.rs:1-60]()）。
```mermaid
flowchart LR
Q[查询] --> S[sketch 草图预过滤]
S -->|可选| T[Tantivy BM25]
T -->|未命中/不可用| F[Lex 回退]
F --> V[Vec/Hybrid]
V --> H[构造 SearchResponse]
```
回退路径 `search_with_lex_fallback` 在 `lex_index` 内存索引上直接计算 `LexMatch`，并支持 `uri` / `scope` 过滤与片段（snippet）生成（[src/memvid/search/fallback.rs:1-60]()）。辅助模块负责上下文组装、token 出现位置收集、按 token 命中数重排，以及 Logic-Mesh 实体（[src/memvid/search/helpers.rs:1-50]()）。
`build_context` 在构造 LLM 输入上下文时执行**多文档多样化**策略：按 URI 分组，每组保留最佳命中，整体上限 24 条以平衡覆盖度与噪声（[src/memvid/search/helpers.rs:70-110]()）。
## 三、Tantivy 集成与 Schema
`src/search/tantivy/` 是 BM25 的底层实现，模块入口聚合 `engine / query / schema / storage / util / wal` 六个子模块（[src/search/tantivy/mod.rs:1-13]()）。
- **Engine**：`TantivyEngine` 通过 `TempDir` 在内存中创建 Tantivy `Index`，并接管 tokenizer 初始化与 `Schema` 构造（[src/search/tantivy/engine.rs:1-60]()）。
- **Schema**：`build_schema` 声明 `content / title / uri / tags / labels / track / timestamp / frame_id` 等字段；`uri` 使用 `raw` tokenizer 保持原始形态以支持精确匹配，`timestamp` 设为 `i64` 索引 + fast field（[src/search/tantivy/schema.rs:1-40]()）。
- **Storage / WAL**：`EmbeddedLexStorage` 将段（segment）元数据按路径 BTreeMap 化，可在 `.mv2` 文件内重建索引；`LexWalBatch` 负责 WAL 批处理（[src/search/tantivy/storage.rs:1-60](), [src/memvid/search/tantivy.rs:1-40]()）。
`try_tantivy_search` 还会对查询做**词形还原**（stemming），例如把 `technology → technolog`，使其与索引阶段的词干匹配（[src/memvid/search/tantivy.rs:30-60]()）。
## 四、嵌入与向量化
向量化路径支持两种来源：
1. **本地嵌入**：启用 `vec` 特性时使用 ONNX 运行时在本地生成文本嵌入，配合 HNSW 提供最近邻检索。`README.md` 列出了 OpenAI 三档云端模型（`text-embedding-3-small/large/ada-002`），可通过 `api_embed` 特性调用（[README.md:60-80]()）。
2. **CLIP / Whisper**：分别对图像和音频生成语义向量，前提是开启 `clip` / `whisper` 特性。
`build_vec_artifact` 在提交（commit）时把激活帧的向量重新打包为 `VecIndexArtifact`，并把字节流写回 `.mv2` 的 `Vec Index` 段（[src/memvid/search/builders.rs:1-60]()）。`is_text_indexable` 与 `is_text_mime` 控制哪些 MIME 类型可被全文索引，例如 `application/pdf`、`+xml`、`+json` 都被视为可索引（[src/memvid/search/api.rs:1-50]()）。
## 五、分析层：自动标签与 NER
`src/analysis/` 提供离线/在线分析能力：
- `auto_tag`：基于词频与停用词表生成标签和 `Camel Case` 短语候选（[src/analysis/auto_tag.rs:1-50]()）。
- `ner`：加载 ONNX 模型与 tokenizer 进行命名实体识别，结果合并到搜索结果的 `metadata.entities` 中（[src/analysis/ner.rs:1-50](), [src/memvid/search/helpers.rs:1-30]()）。
## 六、社区关注点与限制
- **Ollama / 本地 LLM 支持**（Issue #23）：社区希望检索能接入本地 LLM 编排；当前嵌入与生成通过 `api_embed` / CLI 暴露，尚未直接绑定 Ollama。
- **性能基准**（Issue #42）：单 PDF 样例不足以验证替代云端向量库的可行性，建议在评估时同时关注 `vec` / `lex` 的索引构建耗时与召回率。
- **自定义 Provider Base URL**（Issue #202）：OpenAI / Gemini 兼容网关（如 LiteLLM、企业代理）的 base URL 透传仍在 feature 请求阶段。
- **WAL 校验和损坏**（v2.0.140 修复 #230）：在反复 `put + commit` 触发 WAL 区域增长时曾出现 `wal record checksum mismatch`，v2.0.140 已修复 `grow_wal_region` / `ensure_wal_capacity` 的偏移错误（[README.md:1-10](), [docker/README.md:1-20]()）。
## 七、常见失败模式
1. **未启用特性却调用**：`is_text_indexable` 等接口依赖 `lex`/`vec` 编译开关；运行时会返回 `LexNotEnabled` 等错误。
2. **MIME 误判**：二进制视频/图像被 `is_text_mime` 直接跳过，不会进入全文索引。
3. **Tantivy 段丢失**：`.mv2` 文件若被外部截断，WAL 校验和会失败，需要从备份或 `commit` 后的镜像恢复。
## 另请参阅
- 文件格式：[MV2_SPEC.md](https://github.com/memvid/memvid/blob/main/MV2_SPEC.md)
- CLI 使用：[cli/README.md](https://github.com/memvid/memvid/blob/main/cli/README.md)
- Docker 部署：[docker/README.md](https://github.com/memvid/memvid/blob/main/docker/README.md)
- 官方文档：
---
## SDK、Docker、加密胶囊与运维
### 相关页面
相关主题：[Memvid 概述与 Smart Frames 架构](#page-1), [数据摄入、生命周期与多模态支持](#page-2), [搜索、检索与嵌入模型](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/memvid/memvid/blob/main/README.md)
- [docker/README.md](https://github.com/memvid/memvid/blob/main/docker/README.md)
- [docker/cli/README.md](https://github.com/memvid/memvid/blob/main/docker/cli/README.md)
- [docker/cli/Dockerfile](https://github.com/memvid/memvid/blob/main/docker/cli/Dockerfile)
- [docker/cli/TESTING.md](https://github.com/memvid/memvid/blob/main/docker/cli/TESTING.md)
- [docker/core/README.md](https://github.com/memvid/memvid/blob/main/docker/core/README.md)
- [docker/core/Dockerfile](https://github.com/memvid/memvid/blob/main/docker/core/Dockerfile)
- [src/memvid/search/api.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/api.rs)
- [src/memvid/search/mod.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/mod.rs)
- [src/memvid/search/helpers.rs](https://github.com/memvid/memvid/blob/main/src/memvid/search/helpers.rs)
# SDK、Docker、加密胶囊与运维
## 概览
`memvid` 定位为 AI 智能体的单文件记忆层，主仓库通过 `memvid-core` 库提供 SDK，同时通过 `docker/` 子目录交付 CLI 与开发容器镜像，并在 SDK 之上提供 `encryption` 特性来输出 `.mv2e` 加密胶囊。SDK 负责把文本、PDF、向量、Tantivy 词法索引等内容统一封装进 `.mv2` 文件；Docker 镜像则负责把整套工具链以可移植方式分发到生产或开发环境。本页围绕这三块——SDK 集成、容器化部署、加密胶囊，以及相关运维要点——梳理源码层面的事实。
## SDK 集成与特性开关
Rust 端通过 `memvid-core` crate 暴露 `Memvid`、`PutOptions`、`SearchRequest` 等核心 API：
```rust
use memvid_core::{Memvid, PutOptions, SearchRequest};
let mut mem = Memvid::create("knowledge.mv2")?;
let opts = PutOptions::builder()
.title("Meeting Notes")
.uri("mv2://meetings/2024-01-15")
.tag("project", "alpha")
.build();
mem.put(opts)?;
```
特性（Feature Flag）采用 Cargo 标准语义，关键开关包括 `lex`（Tantivy 全文 BM25）、`vec`（HNSW + ONNX 本地向量）、`clip`（图像 CLIP 嵌入）、`whisper`（音频转写）、`api_embed`（OpenAI 云端嵌入）、`temporal_track`（自然语言日期解析）、`parallel_segments`（并发摄入）、`encryption`（密码加密胶囊 `.mv2e`）、`symspell_cleanup`（PDF 文本修复）以及 `pdf_extract`（纯 Rust PDF 解析）。资料来源：[README.md](README.md)。
`vec` 特性默认采用 BGE-small ONNX 模型（384 维），同时支持 `api_embed` 走 `text-embedding-3-small/large/ada-002`。`whisper` 特性支持 `whisper-tiny-en`、`whisper-tiny-en-q8k` 等量化变体，可通过 `MEMVID_WHISPER_MODEL` 环境变量或 `WhisperConfig::with_model` 切换。资料来源：[README.md](README.md)。
## Docker 镜像与部署拓扑
仓库在 `docker/` 下分两层发布：
- `docker/core/`：开发与基准测试容器，提供 `cargo` 工具链并通过 Compose 挂载源码、cargo 缓存与 target 目录；可结合 `--memory=150m` 限制复现 OOM 场景，用来验证加密测试或 OOM 防护逻辑。资料来源：[docker/core/README.md](docker/core/README.md)。
- `docker/cli/`：发布到 Docker Hub 的 CLI 镜像 `memvid/cli`，支持 `linux/amd64` 与 `linux/arm64` 多架构，标签包括 `latest`、版本号（如 `2.0.129`）以及版本精确标签，由 `.github/workflows/docker-release.yml` 推送。镜像以非 root 用户 `memvid` 运行，挂载卷时需保证宿主机目录权限。资料来源：[docker/README.md](docker/README.md)、[docker/cli/README.md](docker/cli/README.md)。
整体拓扑可表示为：
```mermaid
flowchart LR
A[开发者主机] -->|cargo run --features| B(core 容器)
C[CI / GitHub Actions] -->|docker buildx| D(docker/cli 镜像)
D -->|docker pull memvid/cli:tag| E[生产节点]
B -->|挂载 .mv2| F[共享存储]
E -->|挂载 .mv2 / .mv2e| F
E -->|OPENAI_BASE_URL 等| G[OpenAI 兼容代理]
```
## 加密胶囊与文件格式
`.mv2` 容器自带 4KB 头、嵌入式 WAL（1–64MB，可按 `grow_wal_region` 增长）、压缩数据段、词法/向量/时间索引以及 TOC 页脚，明确声明“不会产生 `.wal`、`.lock`、`.shm` 等 sidecar 文件”。加密特性（`encryption`）在此之上再封装一层，得到 `.mv2e` 加密胶囊。资料来源：[README.md](README.md)。
`search` 模块承担主要的运行时查询逻辑：在 `src/memvid/search/mod.rs` 中，先用 sketch 轨道进行 Hamming 距离预筛，再尝试 Tantivy 词法搜索，缺失时回退到 `fallback.rs` 中的轻量 BM25。命中后由 `helpers.rs` 完成时间元数据挂载、ACL 过滤、上下文拼装（默认上限 24 条 `SearchHit`），最终通过 `api.rs` 暴露的 `Memvid::search` 返回 `SearchResponse`。资料来源：[src/memvid/search/mod.rs](src/memvid/search/mod.rs)、[src/memvid/search/tantivy.rs](src/memvid/search/tantivy.rs)、[src/memvid/search/fallback.rs](src/memvid/search/fallback.rs)、[src/memvid/search/helpers.rs](src/memvid/search/helpers.rs)、[src/memvid/search/api.rs](src/memvid/search/api.rs)。
## 运维要点与已知问题
1. **WAL 增长与校验和**：`v2.0.140` 修复了 issue #230：在持续 `put`+`commit` 工作负载下，`grow_wal_region`/`ensure_wal_capacity` 早期实现会触发 “wal record checksum mismatch” 并导致 sparse-file 越界增长。升级到 ≥ v2.0.140 可规避。
2. **本地 LLM 接入**：社区 issue #23 询问是否支持 Ollama；当前 SDK 主要通过 `api_embed` 对接 OpenAI 兼容云端，issue #202 提出为 OpenAI/Gemini 增加自定义 `base_url`（LiteLLM 代理、企业网关等）。在补丁合并前，可通过反向代理 + `OPENAI_BASE_URL` 类环境变量迂回实现。
3. **基准可复现性**：issue #42 要求在大规模数据上对比编码时间与向量库性能。建议使用 `docker/core` 提供的 `cargo test` + `--all-features` 流程以及固定 ONNX 模型路径（`~/.cache/memvid/text-models`）来得到可复现结果。
4. **声明的可验证性**：issue #43 链接了第三方 `memvid_critique.md`；在向生产推广前，应结合 `MV2_SPEC.md` 与上述 `src/memvid/search/*.rs` 实际行为对吞吐、召回与延迟做自有基准，而非依赖仓库自我宣传。
5. **加密胶囊密钥管理**：源码未内置 KMS 集成；建议把 `.mv2e` 的密码通过环境变量或外部 secrets 注入，避免硬编码。
## See Also
- `MV2_SPEC.md` — `.mv2` 文件格式完整规范
- `cli/README.md` — CLI 使用、Docker Compose 与测试指南
- `docs.memvid.com` — 官方文档站点
- `cli/TESTING.md` — CLI 容器端到端测试说明
---
---
## Doramagic 踩坑日志
项目：memvid/memvid
摘要：发现 16 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Feature Request: Concurrent Writers Support for Multi-Agent Scenarios。
## 1. 安装坑 · 来源证据：Feature Request: Concurrent Writers Support for Multi-Agent Scenarios
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature Request: Concurrent Writers Support for Multi-Agent Scenarios
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/218 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：EmbeddedWal checksum mismatch on 16th put of varied text
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：EmbeddedWal checksum mismatch on 16th put of varied text
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/230 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Python async SDK + MCP server + invalidation roadmap?
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python async SDK + MCP server + invalidation roadmap?
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/234 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：[BUG] Opening .mv2 file created with 2.0.152 in 2.0.159 hangs indefinitely on low-memory systems
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Opening .mv2 file created with 2.0.152 in 2.0.159 hangs indefinitely on low-memory systems
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/225 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：[BUG] Tantivy working directories leaked to %TEMP% on every `put()` call, never cleaned up
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Tantivy working directories leaked to %TEMP% on every `put()` call, never cleaned up
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/215 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 6. 配置坑 · 来源证据：[BUG]
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[BUG]
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/210 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。
## 7. 能力坑 · 来源证据：README Translations (i18n) – Tracking Issue
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：README Translations (i18n) – Tracking Issue
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/100 | 来源类型 github_issue 暴露的待验证使用条件。
## 8. 能力坑 · 来源证据：README translation: Romanian (ro)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：README translation: Romanian (ro)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/131 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/memvid/memvid | README/documentation is current enough for a first validation pass.
## 10. 运行坑 · 来源证据：TypeError: 'dict' object cannot be converted to 'PyString' when calling mem.put()
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：TypeError: 'dict' object cannot be converted to 'PyString' when calling mem.put()
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/222 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/memvid/memvid | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/memvid/memvid | no_demo; severity=medium
## 13. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/memvid/memvid | no_demo; severity=medium
## 14. 安全/权限坑 · 来源证据：Python SDK: put_many(embedder=) passes full doc text to embedder, not chunks
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Python SDK: put_many(embedder=) passes full doc text to embedder, not chunks
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/memvid/memvid/issues/219 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 15. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/memvid/memvid | issue_or_pr_quality=unknown
## 16. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/memvid/memvid | release_recency=unknown