> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/memvid/memvid) · [上游 README](https://github.com/memvid/memvid/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 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` | [](https://www.npmjs.com/package/memvid-cli) |
| **Node.js SDK** | `npm install @memvid/sdk` | [](https://www.npmjs.com/package/@memvid/sdk) |
| **Python SDK** | `pip install memvid-sdk` | [](https://pypi.org/project/memvid-sdk/) |
| **Rust** | `cargo add memvid-core` | [](https://crates.io/crates/memvid-core) |
---
## 安装（Rust）
### 环境要求
- **Rust 1.85.0+** — 从 [rustup.rs](https://rustup.rs) 安装
### 添加到你的项目
```toml
[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"） |
按需启用特性：
```toml
[dependencies]
memvid-core = { version = "2.0", features = ["lex", "vec", "temporal_track"] }
```
## 快速开始
```rust
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(())
}
```
---
## 构建
克隆仓库：
```bash
git clone https://github.com/memvid/memvid.git
cd memvid
```
以 debug 模式构建：
```bash
cargo build
```
以 release 模式（优化）构建：
```bash
cargo build --release
```
启用指定功能构建：
```bash
cargo build --release --features "lex,vec,temporal_track"
```
---
## 运行测试
运行全部测试：
```bash
cargo test
```
运行测试并输出结果：
```bash
cargo test -- --nocapture
```
运行指定测试：
```bash
cargo test test_name
```
仅运行集成测试：
```bash
cargo test --test lifecycle
cargo test --test search
cargo test --test mutation
```
---
## 示例
`examples/` 目录包含可运行的示例：
### 基础用法
演示 create、put、search 和 timeline 操作：
```bash
cargo run --example basic_usage
```
### PDF 导入
导入并搜索 PDF 文档（使用论文《Attention Is All You Need》）：
```bash
cargo run --example pdf_ingestion
```
### CLIP 视觉搜索
使用 CLIP 嵌入（embeddings）进行图像搜索（需要 `clip` 功能）：
```bash
cargo run --example clip_visual_search --features clip
```
### Whisper 转录
音频转录（需要 `whisper` 功能）：
```bash
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 | 最快 | 快速测试、资源受限场景 |
**模型选择：**
```bash
# 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
```
**编程配置：**
```rust
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 维，快速高效）：
```bash
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 维）：
```bash
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 维）：
```bash
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 维）：
```bash
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
```
### 代码中的用法
```rust
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 实例显式绑定到特定模型名称：
```rust
// 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 密钥：
```bash
export OPENAI_API_KEY="sk-..."
```
### 用法
```rust
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](MV2_SPEC.md) 了解完整文件格式规范。
## 支持
有问题或反馈？
Email: contact@memvid.com
**点个 ⭐ 表示支持**
---
> **Memvid v1（基于 QR 的 memory）已弃用**
>
> 如果你在引用 QR 码，说明你使用的是过时信息。
>
> 参见：https://docs.memvid.com/memvid-v1-deprecation
---
## 许可证
Apache License 2.0 — 详见 [LICENSE](LICENSE) 文件。