memvid--memvid/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Memvid 是面向 AI 智能体的单文件记忆层，支持即时检索与长期记忆。
持久化、可版本化、可移植的记忆，无需数据库。

官网 · 试用沙盒 · 文档 · 讨论

基准测试亮点

🚀 准确度高于任何其他记忆系统： 在 LoCoMo 上达到 SOTA +35%，同类最佳的长程对话召回与推理能力

🧠 卓越的多跳与时序推理能力： 多跳 +76%、时序 +56%（相对行业平均水平）

⚡ 大规模场景下的超低延迟： P50 0.025ms、P99 0.075ms，吞吐量较标准方案高 1,372 倍

🔬 完全可复现的基准测试： LoCoMo（10 × 约 26K token 对话）、开源评测、LLM-as-Judge

什么是 Memvid？

Memvid 是一种可移植的 AI 记忆系统，将你的数据、嵌入向量、检索结构与元数据打包进单个文件。

无需运行复杂的 RAG 流水线或基于服务器的向量数据库，Memvid 可直接从文件中快速检索。

最终得到一个与模型无关、无需基础设施的记忆层，为 AI 智能体提供可随身携带的持久化长期记忆。

什么是 Smart Frames？

Memvid 借鉴视频编码思路，并非用于存储视频，而是将 AI 记忆组织为仅追加、超高效率的 Smart Frame 序列。

Smart Frame 是不可变单元，存储内容以及时间戳、校验和与基础元数据。 Frame 按特定方式分组，以实现高效压缩、索引与并行读取。

这种基于 Frame 的设计带来：

• 仅追加写入，无需修改或破坏已有数据
• 对历史记忆状态的查询
• 以时间线方式检视知识如何演化
• 通过已提交、不可变的 Frame 实现崩溃安全
• 采用借鉴自视频编码的技术实现高效压缩

最终得到一个文件，对 AI 系统而言就像可回放的记忆时间线。

核心概念

• Living Memory Engine（活体记忆引擎） 跨会话持续追加、分支并演化记忆。

• Capsule Context（.mv2） 自带规则与过期时间的、可独立共享的记忆胶囊。

• Time-Travel Debugging（时光回溯调试） 回退、重放或分支任意记忆状态。

• Smart Recall（智能召回） 亚 5ms 本地记忆访问，配合预测性缓存。

• Codec Intelligence（编解码智能） 随时间自动选择并升级压缩方案。

应用场景

Memvid 是可移植、无服务器的记忆层，为 AI 智能体提供持久记忆与快速召回。由于与模型无关、支持多模态且可完全离线运行，开发者已在众多实际应用中采用 Memvid。

• 长时运行 AI 智能体
• 企业知识库
• 离线优先 AI 系统
• 代码库理解
• 客户支持智能体
• 工作流自动化
• 销售与营销 Copilot
• 个人知识助手
• 医疗、法律与金融智能体
• 可审计、可调试的 AI 工作流
• 自定义应用

SDK 与 CLI

使用你偏好的语言接入 Memvid：

软件包	安装	链接
CLI	npm install -g memvid-cli
Node.js SDK	npm install @memvid/sdk
Python SDK	pip install memvid-sdk
Rust	cargo add memvid-core

---

安装（Rust）

环境要求

• Rust 1.85.0+ — 从 rustup.rs 安装

添加到你的项目

[dependencies]
memvid-core = "2.0"

功能特性（Feature Flags）

特性	说明
lex	基于 BM25 排序的全文检索（Tantivy）
pdf_extract	纯 Rust PDF 文本提取
vec	向量相似度检索（HNSW + 通过 ONNX 的本地文本嵌入）
clip	用于图像检索的 CLIP 视觉嵌入
whisper	使用 Whisper 进行音频转写
api_embed	云端 API 嵌入（OpenAI）
temporal_track	自然语言日期解析（如 "last Tuesday"）
parallel_segments	多线程数据摄入
encryption	基于密码的加密胶囊（.mv2e）
symspell_cleanup	健壮的 PDF 文本修复（修复如 "emp lo yee" -> "employee"）

按需启用特性：

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

快速开始

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

fn main() -> memvid_core::Result<()> {
    // Create a new memory file
    let mut mem = Memvid::create("knowledge.mv2")?;

    // Add documents with metadata
    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()?;

    // Search
    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(())
}

---

构建

克隆仓库：

git clone https://github.com/memvid/memvid.git
cd memvid

以 debug 模式构建：

cargo build

以 release 模式（优化）构建：

cargo build --release

启用指定功能构建：

cargo build --release --features "lex,vec,temporal_track"

---

运行测试

运行全部测试：

cargo test

运行测试并输出结果：

cargo test -- --nocapture

运行指定测试：

cargo test test_name

仅运行集成测试：

cargo test --test lifecycle
cargo test --test search
cargo test --test mutation

---

示例

examples/ 目录包含可运行的示例：

基础用法

演示 create、put、search 和 timeline 操作：

cargo run --example basic_usage

PDF 导入

导入并搜索 PDF 文档（使用论文《Attention Is All You Need》）：

cargo run --example pdf_ingestion

CLIP 视觉搜索

使用 CLIP 嵌入（embeddings）进行图像搜索（需要 clip 功能）：

cargo run --example clip_visual_search --features clip

Whisper 转录

音频转录（需要 whisper 功能）：

cargo run --example test_whisper --features whisper -- /path/to/audio.mp3

可用模型：

模型	大小	速度	用途
whisper-small-en	244 MB	最慢	最高精度（默认）
whisper-tiny-en	75 MB	快	均衡
whisper-tiny-en-q8k	19 MB	最快	快速测试、资源受限场景

模型选择：

# Default (FP32 small, highest accuracy)
cargo run --example test_whisper --features whisper -- audio.mp3

# Quantized tiny (75% smaller, faster)
MEMVID_WHISPER_MODEL=whisper-tiny-en-q8k cargo run --example test_whisper --features whisper -- audio.mp3

编程配置：

use memvid_core::{WhisperConfig, WhisperTranscriber};

// Default FP32 small model
let config = WhisperConfig::default();

// Quantized tiny model (faster, smaller)
let config = WhisperConfig::with_quantization();

// Specific model
let config = WhisperConfig::with_model("whisper-tiny-en-q8k");

let transcriber = WhisperTranscriber::new(&config)?;
let result = transcriber.transcribe_file("audio.mp3")?;
println!("{}", result.text);

文本嵌入（Text Embedding）模型

vec 功能包含基于 ONNX 模型的本地文本嵌入支持。使用本地文本嵌入前，你需要手动下载模型文件。

快速开始：BGE-small（推荐）

下载默认 BGE-small 模型（384 维，快速高效）：

mkdir -p ~/.cache/memvid/text-models

# Download ONNX model
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

# Download tokenizer
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

可用模型

模型	维度	大小	适用场景
bge-small-en-v1.5	384	~120MB	默认、快速
bge-base-en-v1.5	768	~420MB	更高质量
nomic-embed-text-v1.5	768	~530MB	通用任务
gte-large	1024	~1.3GB	最高质量

其他模型

BGE-base（768 维）：

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

Nomic（768 维）：

curl -L 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/onnx/model.onnx' \
  -o ~/.cache/memvid/text-models/nomic-embed-text-v1.5.onnx
curl -L 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/tokenizer.json' \
  -o ~/.cache/memvid/text-models/nomic-embed-text-v1.5_tokenizer.json

GTE-large（1024 维）：

curl -L 'https://huggingface.co/thenlper/gte-large/resolve/main/onnx/model.onnx' \
  -o ~/.cache/memvid/text-models/gte-large.onnx
curl -L 'https://huggingface.co/thenlper/gte-large/resolve/main/tokenizer.json' \
  -o ~/.cache/memvid/text-models/gte-large_tokenizer.json

代码中的用法

use memvid_core::text_embed::{LocalTextEmbedder, TextEmbedConfig};
use memvid_core::types::embedding::EmbeddingProvider;

// Use default model (BGE-small)
let config = TextEmbedConfig::default();
let embedder = LocalTextEmbedder::new(config)?;

let embedding = embedder.embed_text("hello world")?;
assert_eq!(embedding.len(), 384);

// Use different model
let config = TextEmbedConfig::bge_base();
let embedder = LocalTextEmbedder::new(config)?;

参见 examples/text_embedding.rs 获取包含相似度计算和搜索排序的完整示例。

模型一致性

为防止意外混用模型（例如用 OpenAI 嵌入查询 BGE-small 索引），你可以将 Memvid 实例显式绑定到特定模型名称：

// Bind the index to a specific model.
// If the index was previously created with a different model, this will return an error.
mem.set_vec_model("bge-small-en-v1.5")?;

该绑定是持久化的。设置后，若尝试使用不同模型名称，将立即以 ModelMismatch 错误失败。

API 嵌入（OpenAI）

api_embed 功能通过 OpenAI API 启用基于云的嵌入生成。

设置

设置你的 OpenAI API 密钥：

export OPENAI_API_KEY="sk-..."

用法

use memvid_core::api_embed::{OpenAIConfig, OpenAIEmbedder};
use memvid_core::types::embedding::EmbeddingProvider;

// Use default model (text-embedding-3-small)
let config = OpenAIConfig::default();
let embedder = OpenAIEmbedder::new(config)?;

let embedding = embedder.embed_text("hello world")?;
assert_eq!(embedding.len(), 1536);

// Use higher quality model
let config = OpenAIConfig::large();  // text-embedding-3-large (3072 dims)
let embedder = OpenAIEmbedder::new(config)?;

可用模型

模型	维度	适用场景
text-embedding-3-small	1536	默认、最快、最便宜
text-embedding-3-large	3072	最高质量
text-embedding-ada-002	1536	旧版模型

参见 examples/openai_embedding.rs 获取完整示例。

文件格式

所有内容都存放在单个 .mv2 文件中：

┌────────────────────────────┐
│ Header (4KB)               │  Magic, version, capacity
├────────────────────────────┤
│ Embedded WAL (1-64MB)      │  Crash recovery
├────────────────────────────┤
│ Data Segments              │  Compressed frames
├────────────────────────────┤
│ Lex Index                  │  Tantivy full-text
├────────────────────────────┤
│ Vec Index                  │  HNSW vectors
├────────────────────────────┤
│ Time Index                 │  Chronological ordering
├────────────────────────────┤
│ TOC (Footer)               │  Segment offsets
└────────────────────────────┘

没有 .wal、.lock、.shm 或 sidecar 文件。永远如此。

参见 MV2_SPEC.md 了解完整文件格式规范。

支持

有问题或反馈？ Email: contact@memvid.com

点个 ⭐ 表示支持

---

Memvid v1（基于 QR 的 memory）已弃用

如果你在引用 QR 码，说明你使用的是过时信息。

参见：https://docs.memvid.com/memvid-v1-deprecation

---

许可证

Apache License 2.0 — 详见 LICENSE 文件。