memvid — 用视频作为向量记忆载体的有趣实验项目

Memvid 是一个为 AI 智能体设计的单文件内存层，具备即时检索和长期记忆能力。
持久化、版本化、可移植的内存系统，无需数据库。

官方网站 · 试用沙盒 · 文档 · 讨论区

性能亮点

🚀 超越其他所有内存系统的准确率： 在 LoCoMo 基准测试中领先 SOTA 35%，在长程对话回忆与推理方面表现最佳。

🧠 卓越的多跳与时间推理能力： 多跳推理能力领先行业平均水平 76%，时间推理能力领先 56%。

⚡ 大规模下的超低延迟： P50 延迟 0.025ms，P99 延迟 0.075ms，吞吐量比标准方案高 1372 倍。

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

什么是 Memvid？

Memvid 是一个可移植的 AI 内存系统，它将您的数据、嵌入向量、搜索结构和元数据打包到一个单一文件中。

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

其结果是一个与模型无关、无需基础设施的内存层，为 AI 智能体提供了可以随身携带的持久化长期记忆。

什么是智能帧？

Memvid 的灵感来源于视频编码，但并非用于存储视频，而是将 AI 内存组织为一个仅追加、超高效的智能帧序列。

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

这种基于帧的设计实现了：

• 仅追加写入，不会修改或损坏现有数据
• 对过去内存状态的查询
• 以时间线方式检查知识的演变
• 通过已提交的、不可变的帧实现崩溃安全
• 使用源自视频编码的技术进行高效压缩

其结果是一个行为类似于 AI 系统可回放内存时间线的单一文件。

核心概念

• 动态内存引擎
  跨会话持续追加、分支和演进内存。

• 胶囊上下文 (.mv2)
  自包含、可共享的内存胶囊，包含规则和过期设置。

• 时间旅行调试
  回退、重播或分支任何内存状态。

• 智能回忆
  本地内存访问延迟低于 5ms，并具备预测性缓存。

• 编解码器智能
  自动选择并随时间升级压缩算法。

使用场景

Memvid 是一个可移植、无服务器的内存层，为 AI 智能体提供持久化内存和快速回忆能力。由于它与模型无关、支持多模态且完全离线工作，开发者正在各种现实应用中使用 Memvid。

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

SDK 与 CLI

使用您偏好的语言：

包	安装命令	链接
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"

功能特性

按需启用特性：

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

快速开始

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

构建

克隆仓库：

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

可用模型：

模型选择：

# 默认 (FP32 small, 最高准确率)
cargo run --example test_whisper --features whisper -- audio.mp3

# 量化 tiny 模型 (体积小 75%，更快)
MEMVID_WHISPER_MODEL=whisper-tiny-en-q8k cargo run --example test_whisper --features whisper -- audio.mp3

编程配置：

use memvid_core::{WhisperConfig, WhisperTranscriber};

// 默认 FP32 small 模型
let config = WhisperConfig::default();

// 量化 tiny 模型 (更快，更小)
let config = WhisperConfig::with_quantization();

// 指定模型
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

# 下载 ONNX 模型
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

可用模型

其他模型

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;

// 使用默认模型 (BGE-small)
let config = TextEmbedConfig::default();
let embedder = LocalTextEmbedder::new(config)?;

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

// 使用不同模型
let config = TextEmbedConfig::bge_base();
let embedder = LocalTextEmbedder::new(config)?;

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

模型一致性

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

// 将索引绑定到特定模型。
// 如果索引之前是用不同模型创建的，这将返回错误。
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;

// 使用默认模型 (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);

// 使用更高质量的模型
let config = OpenAIConfig::large();  // text-embedding-3-large (3072 维)
let embedder = OpenAIEmbedder::new(config)?;

可用模型