memvid:基于多语言SDK的AI记忆系统项目

Memvid 是一个面向 AI 智能体的单文件内存层，具备即时检索与长期记忆能力。
无需数据库，即可实现持久化、版本化且可移植的记忆存储。

官网 · 试用沙箱 · 文档 · 讨论区

基准测试亮点

🚀 准确率超越所有其他记忆系统：在 LoCoMo 上实现了 +35% 的 SOTA 性能，在长程对话召回与推理方面表现卓越

🧠 卓越的多跳推理与时间推理能力：多跳推理较行业平均水平提升 +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 记忆组织为仅可追加、超高效率的智能帧序列。

智能帧是一个不可变的单元，存储内容的同时包含时间戳、校验和及基本元数据。 帧以特定方式分组，支持高效压缩、索引和并行读取。

这种基于帧的设计带来以下优势：

• 仅可追加写入，不会修改或损坏现有数据
• 可查询过去的记忆状态
• 按时间轴方式查看知识的演变过程
• 通过已提交的不可变帧确保崩溃安全性
• 采用源自视频编码的高效压缩技术

最终形成一个单文件，其作用相当于 AI 系统的可回溯记忆时间轴。

核心概念

• 动态记忆引擎（Living Memory Engine） 跨会话持续追加、分支和演化记忆。

• 胶囊上下文（.mv2） 自包含、可共享的记忆胶囊，包含规则和过期机制。

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

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

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

使用场景

Memvid 是一个可移植、无服务器的记忆层，为 AI 智能体提供持久化记忆和快速召回能力。由于它具备模型无关性、多模态支持以及完全离线运行的特性，开发者正将其应用于各种实际场景中。

• 长期运行的 AI 智能体
• 企业知识库
• 离线优先的 AI 系统
• 代码库理解
• 客户支持智能体
• 工作流自动化
• 销售与营销副驾驶
• 个人知识助手
• 医疗、法律与金融智能体
• 可审计和可调试的 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"

功能标志

功能	描述
lex	基于BM25排序的全文搜索（Tantivy）
pdf_extract	纯Rust PDF文本提取
vec	向量相似度搜索（HNSW + 基于ONNX的本地文本嵌入）
clip	用于图像搜索的CLIP视觉嵌入
whisper	使用Whisper进行音频转录
api_embed	云API嵌入（OpenAI）
temporal_track	自然语言日期解析（如“上周二”）
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

以调试模式构建：

cargo build

以发布模式构建（已优化）：

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/ 目录包含可运行的示例：

基本用法

演示创建、存入、搜索和时间线操作：

cargo run --example basic_usage

PDF 摄入

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

cargo run --example pdf_ingestion

CLIP 视觉搜索

使用 CLIP 嵌入的图像搜索（需要 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);

文本嵌入模型

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 或辅助文件。

完整的文件格式规范请参见 MV2_SPEC.md。

支持

有问题或反馈？ 邮箱：contact@memvid.com

请点个 ⭐ 以示支持

---

Memvid v1（基于二维码的内存）已弃用

若您的参考内容涉及二维码，则说明您正在使用过时信息。

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

---

许可证

Apache License 2.0 — 详情参见 LICENSE 文件。