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

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"）

1. 模块定位与总体架构

memvid 的核心定位是"单文件记忆层"：所有持久化数据（写入、日志、索引、目录）都集中在 .mv2 文件中，不再依赖外部 .wal、.lock、.shm 等伴随文件。这一点在 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）。这些开关共同决定了数据进入系统后会被哪些分析与索引链路处理。

从代码组织来看，分析与索引能力被拆分到三个模块：

• src/analysis 提供 auto_tag（自动标签）、ner（命名实体识别）、temporal / temporal_enrich（时间解析与富化），由 src/analysis/mod.rs 统一导出。
• src/search/tantivy 封装 Tantivy 全文搜索引擎，并定义其 schema（src/search/tantivy/mod.rs、src/search/tantivy/schema.rs）。
• src/memvid/search 负责把这些能力组装成高层 search API、混合检索、回退路径与索引构建器（src/memvid/search/mod.rs、src/memvid/search/api.rs）。

2. 数据摄入与生命周期

摄入流程的入口是 Memvid::create 与 PutOptions 构造器，README.md 中的"Quick Start"示例展示了一条最小路径：创建 .mv2 → 写入带元数据的文档 → 提交 → 检索。底层 put / commit 写入的是带嵌入 WAL 的段（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 中的 derive_labels 用正则 (?m)^(?P<phrase>[A-Z][A-Za-z0-9 &/-]{3,})$ 从文本中提取行首大写短语作为候选标签；同时基于词频与停用词表（based、system、application 等）筛除通用词，输出高频词作为补充标签。
• 命名实体识别：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 的 attach_temporal_metadata 把"last Tuesday"之类的自然语言时间锚点挂到 hit 元数据上。

这些分析产物并不直接改变帧内容，而是作为元数据进入后续的索引构建与命中富化。

3. 索引构建与多模态支持

摄入完成后，commit 会触发多路索引重建。build_lex_artifact 与 build_vec_artifact（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 "Text Embedding Models"）。社区讨论 #202 提出了对自定义 base URL（LiteLLM、企业代理等）的需求，正是针对这条 api_embed 链路。

多模态输入通过不同 reader 解码后再走统一的 put 路径：纯文本经过 MIME 过滤后由 is_frame_text_indexable 判定是否进入 Lex 索引（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 "Whisper Models"）。图像通过 clip 特性生成视觉嵌入供 HNSW 检索。

4. 检索路径与社区关注点

检索阶段是生命周期的"消费侧"。src/memvid/search/mod.rs 显示搜索会先用 sketch 轨道做候选过滤（hamming_threshold = 32，候选数 top_k * 10），再用 BM25/Tantivy 重排；混合路径位于 src/memvid/search/tantivy.rs，回退路径位于 src/memvid/search/fallback.rs。build_context（src/memvid/search/helpers.rs）按 base URI 分组并设置 MAX_CONTEXT_HITS = 24 来平衡多样性与噪声；Tantivy schema（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

• 文件格式规范
• 功能开关与依赖
• 搜索 API 参考

一、定位与总体架构

Memvid 的定位是「面向 AI 智能体的单文件持久化记忆层」，搜索、检索与嵌入模型是其核心能力之一。它在 .mv2 单文件内同时承载词法全文索引（BM25 / Tantivy）、向量索引（HNSW）与时间索引，无需任何外部数据库或侧车文件（README.md:75-90）。

搜索子系统在代码层面按 feature flag 解耦：

仅在启用对应特性时，相关模块才会被编译进二进制（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）。

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
• CLI 使用：cli/README.md
• Docker 部署：docker/README.md
• 官方文档：<https://docs.memvid.com>

概览

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：

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。

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。

Docker 镜像与部署拓扑

仓库在 docker/ 下分两层发布：

• docker/core/：开发与基准测试容器，提供 cargo 工具链并通过 Compose 挂载源码、cargo 缓存与 target 目录；可结合 --memory=150m 限制复现 OOM 场景，用来验证加密测试或 OOM 防护逻辑。资料来源：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/cli/README.md。

整体拓扑可表示为：

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。

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/tantivy.rs、src/memvid/search/fallback.rs、src/memvid/search/helpers.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 容器端到端测试说明

Pitfall Log / 踩坑日志

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