- Memvid is a single-file memory layer for AI agents with instant retrieval and long-term memory.
- Persistent, versioned, and portable memory, without databases.
+ Memvid 是面向 AI 智能体的单文件记忆层，支持即时检索与长期记忆。
+ 持久化、可版本化、可移植的记忆，无需数据库。
- Website + 官网 · - Try Sandbox + 试用沙盒 · - Docs + 文档 · - Discussions + 讨论
@@ -42,84 +48,84 @@ -## Benchmark Highlights +## 基准测试亮点 -**🚀 Higher accuracy than any other memory system :** +35% SOTA on LoCoMo, best-in-class long-horizon conversational recall & reasoning +**🚀 准确度高于任何其他记忆系统：** 在 LoCoMo 上达到 SOTA +35%，同类最佳的长程对话召回与推理能力 -**🧠 Superior multi-hop & temporal reasoning:** +76% multi-hop, +56% temporal vs. the industry average +**🧠 卓越的多跳与时序推理能力：** 多跳 +76%、时序 +56%（相对行业平均水平） -**⚡ Ultra-low latency at scale** 0.025ms P50 and 0.075ms P99, with 1,372× higher throughput than standard +**⚡ 大规模场景下的超低延迟：** P50 0.025ms、P99 0.075ms，吞吐量较标准方案高 1,372 倍 -**🔬 Fully reproducible benchmarks:** LoCoMo (10 × ~26K-token conversations), open-source eval, LLM-as-Judge +**🔬 完全可复现的基准测试：** LoCoMo（10 × 约 26K token 对话）、开源评测、LLM-as-Judge -## What is Memvid? +## 什么是 Memvid？ -Memvid is a portable AI memory system that packages your data, embeddings, search structure, and metadata into a single file. +Memvid 是一种可移植的 AI 记忆系统，将你的数据、嵌入向量、检索结构与元数据打包进单个文件。 -Instead of running complex RAG pipelines or server-based vector databases, Memvid enables fast retrieval directly from the file. +无需运行复杂的 RAG 流水线或基于服务器的向量数据库，Memvid 可直接从文件中快速检索。 -The result is a model-agnostic, infrastructure-free memory layer that gives AI agents persistent, long-term memory they can carry anywhere. +最终得到一个与模型无关、无需基础设施的记忆层，为 AI 智能体提供可随身携带的持久化长期记忆。 -## What are Smart Frames? +## 什么是 Smart Frames？ -Memvid draws inspiration from video encoding, not to store video, but to **organize AI memory as an append-only, ultra-efficient sequence of Smart Frames.** +Memvid 借鉴视频编码思路，并非用于存储视频，而是**将 AI 记忆组织为仅追加、超高效率的 Smart Frame 序列。** -A Smart Frame is an immutable unit that stores content along with timestamps, checksums and basic metadata. -Frames are grouped in a way that allows efficient compression, indexing, and parallel reads. +Smart Frame 是不可变单元，存储内容以及时间戳、校验和与基础元数据。 +Frame 按特定方式分组，以实现高效压缩、索引与并行读取。 -This frame-based design enables: +这种基于 Frame 的设计带来： -- Append-only writes without modifying or corrupting existing data -- Queries over past memory states -- Timeline-style inspection of how knowledge evolves -- Crash safety through committed, immutable frames -- Efficient compression using techniques adapted from video encoding +- 仅追加写入，无需修改或破坏已有数据 +- 对历史记忆状态的查询 +- 以时间线方式检视知识如何演化 +- 通过已提交、不可变的 Frame 实现崩溃安全 +- 采用借鉴自视频编码的技术实现高效压缩 -The result is a single file that behaves like a rewindable memory timeline for AI systems. +最终得到一个文件，对 AI 系统而言就像可回放的记忆时间线。 -## Core Concepts +## 核心概念 -- **Living Memory Engine** - Continuously append, branch, and evolve memory across sessions. +- **Living Memory Engine（活体记忆引擎）** + 跨会话持续追加、分支并演化记忆。 -- **Capsule Context (`.mv2`)** - Self-contained, shareable memory capsules with rules and expiry. +- **Capsule Context（`.mv2`）** + 自带规则与过期时间的、可独立共享的记忆胶囊。 -- **Time-Travel Debugging** - Rewind, replay, or branch any memory state. +- **Time-Travel Debugging（时光回溯调试）** + 回退、重放或分支任意记忆状态。 -- **Smart Recall** - Sub-5ms local memory access with predictive caching. +- **Smart Recall（智能召回）** + 亚 5ms 本地记忆访问，配合预测性缓存。 -- **Codec Intelligence** - Auto-selects and upgrades compression over time. +- **Codec Intelligence（编解码智能）** + 随时间自动选择并升级压缩方案。 -## Use Cases +## 应用场景 -Memvid is a portable, serverless memory layer that gives AI agents persistent memory and fast recall. Because it's model-agnostic, multi-modal, and works fully offline, developers are using Memvid across a wide range of real-world applications. +Memvid 是可移植、无服务器的记忆层，为 AI 智能体提供持久记忆与快速召回。由于与模型无关、支持多模态且可完全离线运行，开发者已在众多实际应用中采用 Memvid。 -- Long-Running AI Agents -- Enterprise Knowledge Bases -- Offline-First AI Systems -- Codebase Understanding -- Customer Support Agents -- Workflow Automation -- Sales and Marketing Copilots -- Personal Knowledge Assistants -- Medical, Legal, and Financial Agents -- Auditable and Debuggable AI Workflows -- Custom Applications +- 长时运行 AI 智能体 +- 企业知识库 +- 离线优先 AI 系统 +- 代码库理解 +- 客户支持智能体 +- 工作流自动化 +- 销售与营销 Copilot +- 个人知识助手 +- 医疗、法律与金融智能体 +- 可审计、可调试的 AI 工作流 +- 自定义应用 -## SDKs & CLI +## SDK 与 CLI -Use Memvid in your preferred language: +使用你偏好的语言接入 Memvid： -| Package | Install | Links | +| 软件包 | 安装 | 链接 | | --------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------- | | **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) | @@ -128,35 +134,35 @@ Use Memvid in your preferred language: --- -## Installation (Rust) +## 安装（Rust） -### Requirements +### 环境要求 -- **Rust 1.85.0+** — Install from [rustup.rs](https://rustup.rs) +- **Rust 1.85.0+** — 从 [rustup.rs](https://rustup.rs) 安装 -### Add to Your Project +### 添加到你的项目 ```toml [dependencies] memvid-core = "2.0" ``` -### Feature Flags +### 功能特性（Feature Flags） -| Feature | Description | +| 特性 | 说明 | | ------------------- | ---------------------------------------------------------------- | -| `lex` | Full-text search with BM25 ranking (Tantivy) | -| `pdf_extract` | Pure Rust PDF text extraction | -| `vec` | Vector similarity search (HNSW + local text embeddings via ONNX) | -| `clip` | CLIP visual embeddings for image search | -| `whisper` | Audio transcription with Whisper | -| `api_embed` | Cloud API embeddings (OpenAI) | -| `temporal_track` | Natural language date parsing ("last Tuesday") | -| `parallel_segments` | Multi-threaded ingestion | -| `encryption` | Password-based encryption capsules (.mv2e) | -| `symspell_cleanup` | Robust PDF text repair (fixes "emp lo yee" -> "employee") | +| `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"） | -Enable features as needed: +按需启用特性： ```toml [dependencies] @@ -164,7 +170,7 @@ memvid-core = { version = "2.0", features = ["lex", "vec", "temporal_track"] } ``` -## Quick Start +## 快速开始 ```rust use memvid_core::{Memvid, PutOptions, SearchRequest}; @@ -200,28 +206,28 @@ fn main() -> memvid_core::Result<()> { --- -## Build +## 构建 -Clone the repository: +克隆仓库： ```bash git clone https://github.com/memvid/memvid.git cd memvid ``` -Build in debug mode: +以 debug 模式构建： ```bash cargo build ``` -Build in release mode (optimized): +以 release 模式（优化）构建： ```bash cargo build --release ``` -Build with specific features: +启用指定功能构建： ```bash cargo build --release --features "lex,vec,temporal_track" @@ -229,27 +235,27 @@ cargo build --release --features "lex,vec,temporal_track" --- -## Run Tests +## 运行测试 -Run all tests: +运行全部测试： ```bash cargo test ``` -Run tests with output: +运行测试并输出结果： ```bash cargo test -- --nocapture ``` -Run a specific test: +运行指定测试： ```bash cargo test test_name ``` -Run integration tests only: +仅运行集成测试： ```bash cargo test --test lifecycle @@ -259,51 +265,51 @@ cargo test --test mutation --- -## Examples +## 示例 -The `examples/` directory contains working examples: +`examples/` 目录包含可运行的示例： -### Basic Usage +### 基础用法 -Demonstrates create, put, search, and timeline operations: +演示 create、put、search 和 timeline 操作： ```bash cargo run --example basic_usage ``` -### PDF Ingestion +### PDF 导入 -Ingest and search PDF documents (uses the "Attention Is All You Need" paper): +导入并搜索 PDF 文档（使用论文《Attention Is All You Need》）： ```bash cargo run --example pdf_ingestion ``` -### CLIP Visual Search +### CLIP 视觉搜索 -Image search using CLIP embeddings (requires `clip` feature): +使用 CLIP 嵌入（embeddings）进行图像搜索（需要 `clip` 功能）： ```bash cargo run --example clip_visual_search --features clip ``` -### Whisper Transcription +### Whisper 转录 -Audio transcription (requires `whisper` feature): +音频转录（需要 `whisper` 功能）： ```bash cargo run --example test_whisper --features whisper -- /path/to/audio.mp3 ``` -**Available Models:** +**可用模型：** -| Model | Size | Speed | Use Case | +| 模型 | 大小 | 速度 | 用途 | | --------------------- | ------ | ------- | ----------------------------------- | -| `whisper-small-en` | 244 MB | Slowest | Best accuracy (default) | -| `whisper-tiny-en` | 75 MB | Fast | Balanced | -| `whisper-tiny-en-q8k` | 19 MB | Fastest | Quick testing, resource-constrained | +| `whisper-small-en` | 244 MB | 最慢 | 最高精度（默认） | +| `whisper-tiny-en` | 75 MB | 快 | 均衡 | +| `whisper-tiny-en-q8k` | 19 MB | 最快 | 快速测试、资源受限场景 | -**Model Selection:** +**模型选择：** ```bash # Default (FP32 small, highest accuracy) @@ -313,7 +319,7 @@ cargo run --example test_whisper --features whisper -- audio.mp3 MEMVID_WHISPER_MODEL=whisper-tiny-en-q8k cargo run --example test_whisper --features whisper -- audio.mp3 ``` -**Programmatic Configuration:** +**编程配置：** ```rust use memvid_core::{WhisperConfig, WhisperTranscriber}; @@ -333,13 +339,13 @@ println!("{}", result.text); ``` -## Text Embedding Models +## 文本嵌入（Text Embedding）模型 -The `vec` feature includes local text embedding support using ONNX models. Before using local text embeddings, you need to download the model files manually. +`vec` 功能包含基于 ONNX 模型的本地文本嵌入支持。使用本地文本嵌入前，你需要手动下载模型文件。 -### Quick Start: BGE-small (Recommended) +### 快速开始：BGE-small（推荐） -Download the default BGE-small model (384 dimensions, fast and efficient): +下载默认 BGE-small 模型（384 维，快速高效）： ```bash mkdir -p ~/.cache/memvid/text-models @@ -353,18 +359,18 @@ curl -L 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/tokenizer.js -o ~/.cache/memvid/text-models/bge-small-en-v1.5_tokenizer.json ``` -### Available Models +### 可用模型 -| Model | Dimensions | Size | Best For | +| 模型 | 维度 | 大小 | 适用场景 | | ----------------------- | ---------- | ------ | --------------- | -| `bge-small-en-v1.5` | 384 | ~120MB | Default, fast | -| `bge-base-en-v1.5` | 768 | ~420MB | Better quality | -| `nomic-embed-text-v1.5` | 768 | ~530MB | Versatile tasks | -| `gte-large` | 1024 | ~1.3GB | Highest quality | +| `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 | 最高质量 | -### Other Models +### 其他模型 -**BGE-base** (768 dimensions): +**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 @@ -372,7 +378,7 @@ curl -L 'https://huggingface.co/BAAI/bge-base-en-v1.5/resolve/main/tokenizer.jso -o ~/.cache/memvid/text-models/bge-base-en-v1.5_tokenizer.json ``` -**Nomic** (768 dimensions): +**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 @@ -380,7 +386,7 @@ curl -L 'https://huggingface.co/nomic-ai/nomic-embed-text-v1.5/resolve/main/toke -o ~/.cache/memvid/text-models/nomic-embed-text-v1.5_tokenizer.json ``` -**GTE-large** (1024 dimensions): +**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 @@ -388,7 +394,7 @@ curl -L 'https://huggingface.co/thenlper/gte-large/resolve/main/tokenizer.json' -o ~/.cache/memvid/text-models/gte-large_tokenizer.json ``` -### Usage in Code +### 代码中的用法 ```rust use memvid_core::text_embed::{LocalTextEmbedder, TextEmbedConfig}; @@ -406,11 +412,11 @@ let config = TextEmbedConfig::bge_base(); let embedder = LocalTextEmbedder::new(config)?; ``` -See `examples/text_embedding.rs` for a complete example with similarity computation and search ranking. +参见 `examples/text_embedding.rs` 获取包含相似度计算和搜索排序的完整示例。 -### Model Consistency +### 模型一致性 -To prevent accidental model mixing (e.g., querying a BGE-small index with OpenAI embeddings), you can explicitly bind your Memvid instance to a specific model name: +为防止意外混用模型（例如用 OpenAI 嵌入查询 BGE-small 索引），你可以将 Memvid 实例显式绑定到特定模型名称： ```rust // Bind the index to a specific model. @@ -418,23 +424,23 @@ To prevent accidental model mixing (e.g., querying a BGE-small index with OpenAI mem.set_vec_model("bge-small-en-v1.5")?; ``` -This binding is persistent. Once set, future attempts to use a different model name will fail fast with a `ModelMismatch` error. +该绑定是持久化的。设置后，若尝试使用不同模型名称，将立即以 `ModelMismatch` 错误失败。 -## API Embeddings (OpenAI) +## API 嵌入（OpenAI） -The `api_embed` feature enables cloud-based embedding generation using OpenAI's API. +`api_embed` 功能通过 OpenAI API 启用基于云的嵌入生成。 -### Setup +### 设置 -Set your OpenAI API key: +设置你的 OpenAI API 密钥： ```bash export OPENAI_API_KEY="sk-..." ``` -### Usage +### 用法 ```rust use memvid_core::api_embed::{OpenAIConfig, OpenAIEmbedder}; @@ -452,21 +458,21 @@ let config = OpenAIConfig::large(); // text-embedding-3-large (3072 dims) let embedder = OpenAIEmbedder::new(config)?; ``` -### Available Models +### 可用模型 -| Model | Dimensions | Best For | +| 模型 | 维度 | 适用场景 | | ------------------------ | ---------- | -------------------------- | -| `text-embedding-3-small` | 1536 | Default, fastest, cheapest | -| `text-embedding-3-large` | 3072 | Highest quality | -| `text-embedding-ada-002` | 1536 | Legacy model | +| `text-embedding-3-small` | 1536 | 默认、最快、最便宜 | +| `text-embedding-3-large` | 3072 | 最高质量 | +| `text-embedding-ada-002` | 1536 | 旧版模型 | -See `examples/openai_embedding.rs` for a complete example. +参见 `examples/openai_embedding.rs` 获取完整示例。 -## File Format +## 文件格式 -Everything lives in a single `.mv2` file: +所有内容都存放在单个 `.mv2` 文件中： ``` ┌────────────────────────────┐ @@ -486,29 +492,29 @@ Everything lives in a single `.mv2` file: └────────────────────────────┘ ``` -No `.wal`, `.lock`, `.shm`, or sidecar files. Ever. +没有 `.wal`、`.lock`、`.shm` 或 sidecar 文件。永远如此。 -See [MV2_SPEC.md](MV2_SPEC.md) for the complete file format specification. +参见 [MV2_SPEC.md](MV2_SPEC.md) 了解完整文件格式规范。 -## Support +## 支持 -Have questions or feedback? +有问题或反馈？ Email: contact@memvid.com -**Drop a ⭐ to show support** +**点个 ⭐ 表示支持** --- -> **Memvid v1 (QR-based memory) is deprecated** +> **Memvid v1（基于 QR 的 memory）已弃用** > -> If you are referencing QR codes, you are using outdated information. +> 如果你在引用 QR 码，说明你使用的是过时信息。 > -> See: https://docs.memvid.com/memvid-v1-deprecation +> 参见：https://docs.memvid.com/memvid-v1-deprecation --- -## License +## 许可证 -Apache License 2.0 — see the [LICENSE](LICENSE) file for details. +Apache License 2.0 — 详见 [LICENSE](LICENSE) 文件。