Memvid 单文件智能体记忆

这个 Agent 能做什么，适合哪些场景？

Memvid 是一个以 Rust 核心库为基础的智能体记忆系统，将内容、嵌入、搜索结构和元数据封装在单个 .mv2 文件中。它采用只追加的 Smart Frames 保存不可变内容及时间戳、校验和与基础元数据，并通过内嵌 WAL 提供崩溃恢复。可选功能包括基于 Tantivy 的 BM25 全文检索、HNSW 向量检索、本地 ONNX 文本嵌入、CLIP 图像检索、Whisper 音频转写、PDF 提取、时间解析和加密胶囊。开发者可以通过 Rust crate、Node.js SDK、Python SDK或命令行工具接入；核心设计不绑定模型，且支持完全离线使用。它适合希望以本地文件替代服务端向量数据库和多组件 RAG 基础设施的团队，但启用不同检索与多模态能力需要选择相应 feature、模型文件及运行资源。

应用通过 Memvid::create 创建 .mv2 文件，再使用 put_bytes_with_options 写入内容以及标题、URI、标签等元数据，并调用 commit 提交。文件内部保存压缩帧、内嵌 WAL、目录表以及可选的词法、向量和时间索引；已有帧保持不可变，新记忆以追加方式写入。查询端向 mem.search 传入 SearchRequest，获得包含标题、文本和片段的命中结果。lex feature 使用 Tantivy 和 BM25，vec 使用 HNSW 以及本地 ONNX 文本嵌入，api_embed 可调用 OpenAI 嵌入 API；clip、whisper 和 pdf_extract 分别支持图像检索、音频转写和 PDF 文本提取。系统还支持查询过去的记忆状态，以及对记忆进行回放、分支和时间线式检查。

1. 构建需要跨会话保留用户信息和历史上下文的长期运行智能体，并把记忆随应用一起迁移。
2. 为不能依赖远程数据库的边缘设备或隔离环境建立可完全离线搜索的知识库。
3. 让开发团队索引代码库和技术资料，通过全文或向量检索辅助代码理解。
4. 为客服、销售或工作流自动化系统保存持续积累的会话与业务资料，并快速召回相关内容。
5. 在需要审计的医疗、法律或金融工作流中，用不可变帧和历史状态回溯检查知识如何演变。
6. 为包含 PDF、图片或音频的资料库启用提取、视觉搜索或转写，但需配置对应 feature 与模型。

如何安装或部署这个 Agent？

核心 Rust 库要求 Rust 1.85.0 或更高版本。可在现有项目的 Cargo.toml 中加入：

[dependencies]
memvid-core = "2.0"

按需启用全文检索、向量检索和时间解析：

[dependencies]
memvid-core = { version = "2.0", features = ["lex", "vec", "temporal_track"] }

也可以克隆并构建仓库：

git clone https://github.com/memvid/memvid.git
cd memvid
cargo build --release

其他已记录的分发方式包括：

npm install -g memvid-cli
npm install @memvid/sdk
pip install memvid-sdk
cargo add memvid-core

使用 vec 的本地默认 BGE-small 模型前，需要下载 ONNX 模型和 tokenizer：

mkdir -p ~/.cache/memvid/text-models
curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx' \
  -o ~/.cache/memvid/text-models/bge-small-en-v1.5.onnx
curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/tokenizer.json' \
  -o ~/.cache/memvid/text-models/bge-small-en-v1.5_tokenizer.json

只有使用可选的 OpenAI 云端嵌入时才需要凭据：

export OPENAI_API_KEY="sk-..."

如何使用这个 Agent？

下面的 Rust 示例创建记忆文件、写入一条带元数据的内容、提交并搜索：

use memvid_core::{Memvid, PutOptions, SearchRequest};

fn main() -> memvid_core::Result<()> {
    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_bytes_with_options(b"Q4 planning discussion...", opts)?;
    mem.commit()?;

    let response = mem.search(SearchRequest {
        query: "planning".into(),
        top_k: 10,
        snippet_chars: 200,
        ..Default::default()
    })?;

    for hit in response.hits {
        println!("{}: {}", hit.title.unwrap_or_default(), hit.text);
    }

    Ok(())
}

使用本地嵌入时，可将索引绑定到模型，避免查询和建库误用不同模型：

mem.set_vec_model("bge-small-en-v1.5")?;

仓库示例可直接运行：

cargo run --example basic_usage
cargo run --example pdf_ingestion
cargo run --example clip_visual_search --features clip
cargo run --example test_whisper --features whisper -- /path/to/audio.mp3

可通过以下命令验证构建：

cargo test

这个 Agent 有哪些优点和局限？

这个 Agent 与同类方案有什么区别？

与相关度最高的同类 agent 并排比较关键指标。

FollowAgents 如何评估这个 Agent？

最近版本

来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。

1. v2.0.140 2026-05-27
   发布说明摘录

   Bug fixes #230 — WAL checksum mismatch after region growth Sustained put + commit workloads that grew the embedded WAL could corrupt it, surfacing as Embedded WAL is corrupted at offset N: wal record checksum mismatch (and, in some reports, runaway sparse-file growth past EOF). grow_wal_region / ensure_wal_capacity shifted the data region right by delta and updated data_end/footer_offset, but left cached_payload_end stale. rebuild_indexes then seeked to that pre-growth offset — now inside the grown WAL region — and overwrote live WAL record payloads. `cached_payloa …

   在 GitHub 查看 ↗
2. v2.0.139 2026-03-13
   发布说明摘录

   v2.0.139 Release Date: March 13, 2026 Overview This release completes the fix for MV005 (Time index track is invalid: frame id out of range) by extending graceful stale frame_id handling to all search paths — find(), ask(), Tantivy, lex fallback, vec search, and temporal metadata lookups. --- 🐛 Bug Fixes MV005 crash in find() and ask() search paths — Issue #196 (continued) - v2.0.138 fixed the timeline.rs path only; stale frame_ids in Tantivy evaluation, snippet assembly, lex fallback, and temporal metadata lookups still caused hard crashes …

   在 GitHub 查看 ↗
3. v2.0.138 2026-03-03
   发布说明摘录

   v2.0.138 Release Date: March 3, 2026 Overview This release fixes two SDK issues: lex_enabled/vec_enabled state not persisting after re-opening .mv2 files, and ask() crashing with "frame id out of range" on files with inconsistent time indexes. --- 🐛 Bug Fixes lex_enabled/vec_enabled reset to None on re-open — Issue #194 - Added lex_enabled and vec_enabled fields to the core Stats struct so SDKs can read runtime search engine state …

   在 GitHub 查看 ↗

常见问题