VelesDB Memory

VelesDB

一个约 14 MB 的二进制文件，将向量、图和列式存储融合在同一种查询语言之下——配备可展示证据的 Agent 记忆，以及能减少实际计费 Token 开销的确定性上下文编译器。
本地优先：数据不会离开设备，记忆路径无需大模型和 API 密钥。下方的每个数据都链接到已提交的测试工具，可供你重新运行。

快速开始 • 性能证明 • 已知限制 • 架构 • 路线图 • velesdb.com

---

从这里开始 — 三条可用命令

pip install velesdb
curl -O https://raw.githubusercontent.com/cyberlife-coder/VelesDB/main/examples/python/hello_velesdb.py
python hello_velesdb.py

如果想搜索自己的文本，而不是手写向量，请安装可选的本地适配器（pip install "velesdb[embed-sentence-transformers]"），然后运行 hello_velesdb_text.py；首次运行时会下载 all-MiniLM-L6-v2。

预期输出，逐字节一致（查看脚本 — 无需服务端，也无需嵌入模型）：

Query: "tech"
  score=1.000  Rust 1.89 release notes
  score=0.600  AI-generated jazz: the new wave
  score=0.000  Best ramen in Tokyo

Query: "tech + music"
  score=0.990  AI-generated jazz: the new wave
  score=0.707  Rust 1.89 release notes
  score=0.707  Miles Davis discography

嵌入模型决定向量维度，而相似度语义决定度量指标。创建集合时，这两者都会固定；若要更改其中任何一项，请创建新集合并重新索引文档。

为你的 Agent 提供持久记忆 — 再运行三条命令：

cargo install velesdb-memory                                    # the local MCP memory server
claude mcp add velesdb-memory -- ~/.cargo/bin/velesdb-memory    # any MCP client works
curl -L https://github.com/cyberlife-coder/VelesDB/releases/latest/download/velesdb-skills.tar.gz | tar -xz -C ~/.claude/skills/

没有 Rust 工具链？可以运行 npm i @wiscale/velesdb-memory-node，或者从官方 MCP Registry 获取预构建的 .mcpb 捆绑包（io.github.cyberlife-coder/velesdb-memory）。

其他方式 — 常驻钩子、共享守护进程、Rust、Docker、WASM、REST

持续使用的记忆，而非仅仅可用： integrations/agent-hooks/ 配置五个 Claude Code 钩子 — SessionStart/Stop/PreCompact 用于恢复和保存工作上下文，PreToolUse 要求在对启用此功能的代码库进行编辑前成功检索记忆，而 PostToolUse 不仅会记录这次检索，还会在过大的工具结果进入对话记录前对其进行编译。全局安装即可覆盖所有项目，无需在明确配置的代码库之外启用编辑防护。

多个客户端共享同一份记忆（Claude Code、Codex CLI、Claude Desktop、Windsurf、Devin CLI）：scripts/install-memory-daemon.sh 将 velesdb-memory 作为单一本地守护进程运行 — 默认使用 HTTPS，并原生生成本地 CA。

Cargo（Rust + REST 服务端）： cargo install velesdb-server velesdb-cli — Docker（多架构 linux/amd64 + linux/arm64）：运行 docker run -d -p 8080:8080 -v velesdb_data:/data --name velesdb ghcr.io/cyberlife-coder/velesdb:latest，然后运行 curl http://localhost:8080/health。

浏览器 / 边缘端： WASM 构建经 gzip 压缩后约为 710 KB，可完全在客户端运行（TypeScript SDK）。REST： 54 个 REST 端点（OpenAPI 规范）。完整选项列表：安装指南。

---

为什么选择 VelesDB

• 一个数据库，而不是三个。 向量用于回答“什么感觉相似”，图用于回答“什么彼此关联”，类型化列用于回答“我确定知道什么” — 通常需要三套部署、三种查询语言和胶水代码。在这里，它们集于一个二进制文件和一种语言。
• 可审计的记忆，而不仅仅是可查询的记忆。 每次检索都能展示背后的证据；每个压缩决策都包含规则 ID、原因和风险级别。设计上即具备确定性 — 写入路径中没有模型，因此不会发生漂移，也无需重新审议。
• 本地优先关乎主权，而非延迟。 无云服务、无 API 密钥、无数据处理方：你可以选择与外部网络隔离，默认则将数据保留在你的司法辖区内。为何这很重要 · 深入了解其定位。

用通俗的话来说，它的工作原理

这里会发生四件事，而且没有一件会调用 AI 提供方。

1 · 它存储事实，而不是对话。 你提供一条陈述——“API 端口是 6333，因为 3000 与 Web UI 冲突”——它就会存入本地文件存储。不会调用模型，也不会把任何内容发送到别处。

2 · 它按含义查找。 即使提问“我们最终选了哪个端口”时，词语与事实中的词语完全不同，也能找到那条事实。本地嵌入模型会将文本转换为坐标；含义越接近，坐标就越接近。

3 · 它会把事实关联起来，这是搜索引擎做不到的。 每条事实都会关联到它提及的主题。why() 会从最匹配的结果开始，然后沿着这些关联逐步查找，因此它返回的不只是答案，还包括能够解释答案的事实——其中甚至有些事实与问题没有任何共同词汇。

这些关联必须存在。逐条存储事实时，图会保持扁平，因此 why() 的表现就像搜索一样。把一段文字交给 remember_extracted，它就会将文字拆分成事实，并自动建立关联。

4 · 在你为它付费之前，它会压缩过大的内容。 把累积的上下文和令牌预算交给编译器，它会返回一个更小的版本，其中每个片段都对应一项已记录的决策——保留、抽象或舍弃——并提供一个句柄，让你逐字取回任何原始内容。输入相同，输出字节每次都相同。这就是下方的 82.5 %所衡量的内容。

---

独有的组合

1 · 三种引擎，一次查询

引擎	功能
Vector	语义相似度（HNSW + AVX2/NEON SIMD）
Graph	类型化关系、BFS/DFS、本机 MATCH 子句（模式）
ColumnStore	类型化列式元数据筛选、二级索引

一条语句即可贯穿这三种引擎——相似度、关系和类型化筛选，无需胶水代码：

MATCH (doc:Document)-[:AUTHORED_BY]->(author:Person)
WHERE similarity(doc.embedding, $question) > 0.8
  AND author.department = 'Engineering'
RETURN author.name, doc.title
ORDER BY similarity() DESC LIMIT 5

2 · 能展示证据的记忆 — why()

大多数“Agent 记忆”都是向量召回：它会找到看起来像你的查询的文本。VelesDB 通过带类型的链接关联记忆，因此可以沿着图遍历，找到与问题没有任何共同用词的上下文，从而回答为什么发生了某件事——即使进程重启、离线运行，也无需 API 密钥：

from velesdb import MemoryService            # pip install velesdb

mem = MemoryService("./agent_memory")        # a real on-disk store; survives restarts
reason = mem.remember("Robert is recovering from knee surgery")
mem.remember("Booked the aisle seat on Robert's flight", links=[(reason, "because")])

# A *new* process, weeks later, reopens the same store and asks why:
mem.why("why the aisle seat on Robert's flight?")   # walks booking → reason — recall() can't

MemoryService 默认使用离线的 hash 嵌入器：它是确定性的，但 基于词汇而非语义，因此无关的措辞可能得到 0.000 的分数。 现在打开它时，会在 stderr 上提示一次。若要进行基于含义的召回，请传入 embedder="ollama"；请参阅 5 分钟实现真正的语义召回。

记忆默认永久保留；forget(id) 会删除一条记忆，ttl_seconds 则为事实设置持久的过期时间。每次 remember 都会自动标记存储日期，因此无需任何设置即可进行按近期程度加权的召回。同样的优势也适用于 Python、Node、MCP 服务以及TypeScript SDK中的内存模式。

证明这并非弱嵌入器造成的假象——以下四个可运行示例中，即使使用真正的语义嵌入器（ollama / all-minilm），recall 仍然无法找到原因，因为原因是通过决策关联的，而非表面相似性：why_across_sessions.py（进程重启后依然有效）· why_magic_constant.py（业务原因与代码没有共同用词）· memory_builds_its_own_graph.py（输入原始文本，输出自动构建的图）· why_magic_constant.mjs（Node）。基准测试表现，包括 LoCoMo，以及为什么不同实验室的分数无法公平比较：BENCHMARK.md · Agent 记忆指南。

3 · 确定性上下文编译器

Agent 大部分预算都耗在反复读取冗余上下文上。compile_context / compile_transcript（MCP 中提供，Rust 中为 ContextCompiler）无需大模型或网络即可缩减上下文：

• 确定性 — 相同输入始终编译为相同字节；每次运行中，所有已提交的基准测试都会断言两次。这也能生成字节稳定的缓存前缀，供提供商的提示词缓存实际命中。
• 可审计 — explain_compilation 为每个保留或丢弃的片段提供稳定的规则 ID、原因和风险级别。
• 可逆 — 超出预算的内容会变成可恢复的 ctx://source/ 句柄；retrieve_context_source 可按需还原原始字节。
• 有界 — 它只压缩 Agent 明确交给它的内容，绝不压缩运行框架的系统提示词；未经明确调用 remember 的内容不会进入可召回记忆。

代码、URL、数字和否定约束都会原样保留。velesdb-context-optimizer 技能介绍了这一工作流，包括何时不应压缩。

---

证据 — 三个数字，每个都对应其测试框架

这里没有任何数字是从演示文稿中估算出来的；每个数字都链接到本仓库中生成它的日志或脚本。

声明	测量结果	测试工具
实际节省的账单金额：同一 Agent 会话分别发送原始内容与编译后内容（按 Claude 实际计费，使用确定性的事实核对清单评分器——不使用 LLM 评判器）	在真实 Retina 截图权重下为 21.9 %，质量持平（两组均为 23.0/23 项事实）	real-session-benchmark · 原始日志
已提交的 12 轮 Agent 会话语料的实际（cl100k）输入令牌节省	82.5 %，无状态编译平均耗时约 0.7 ms（启用源内容持久化时约 24.5 ms）	context_savings
完整生产路径上的向量搜索延迟（Python SDK → HNSW → 负载填充，WAL ON）	450 us p50（10K/384D，召回率 ≥ 96 %）；测量于 2026-03-27，版本为 1.7.2，当时 Balanced 使用 ef 128	velesdb_benchmark.py · 测量报告

同一轮测试中，不那么亮眼的结果是：裁剪截图下为 10.9 %，36 轮、跨日会话为 14.7 %，直接使用 Messages API 时输入令牌为 15.1 %，不含截图的变体则为 2.5 %——这种差异正是媒体机制的实际价值，因此我们将这些数据与醒目结果同等突出地公布。如实解读、局限性与完整协议。本页所有数字均由 承诺契约通过 CI 守护，该契约将 README 中的数据绑定到已提交的源文件。

完整测量表——账单 A/B 测试、检索质量、引擎微基准测试

账单 A/B 会话（2026-07-19，claude-sonnet-5；原始日志逐字提交）：

会话	运行器	节省金额	质量（原始与编译后）
19 轮功能开发会话，裁剪截图	Claude CLI	10.9 %	22.8/23 vs 23.0/23 项事实
同一会话，真实 Retina 权重截图	Claude CLI	21.9 %	23.0/23 vs 23.0/23
36 轮、跨日会话	Claude CLI	14.7 %	49.6/50 vs 49.2/50 项事实 *
19 轮会话，直接使用 Messages API	API	输入令牌 15.1 %	23.0/23 vs 23.0/23

* 后来发现两轮的评分标准存在缺陷（两组在这两轮均得满分；质量持平的结论仍然成立）——披露说明。在一个 36 轮会话中，编译后的上下文增长慢 1.7×，因此会话在触及上下文窗口前可持续更久。

记忆检索质量，公开测试集，不使用 AI 评分器：多跳问答（HotpotQA）提升 7.2 分，限定时间范围的回忆（TimeQA）提升 9.7 分，在一项需同时使用两个引擎的受控任务中提升 29 分——BENCHMARK.md。

端到端搜索（标准结果）：搜索 p50 450 us（10K，384D，WAL ON；测量于 2026-03-27，版本为 1.7.2，当时 Balanced 使用 ef 128——测试工具、测量报告）· 量化 PQ（尺寸缩小 2 × dim / m：默认 m = 8 时为 dim/4）、RaBitQ（缩小 32x）、SQ8（缩小 4x）、Binary（缩小 32x）——适用范围与注意事项。

仅索引微基准测试（无 WAL、无负载、热缓存——不可与上方端到端数据直接比较），均可使用 cargo bench -p velesdb-core --bench <name> 复现：HNSW 仅索引搜索（10K/768D，k=10）55 us（hnsw_benchmark -- hnsw_search_latency）· SIMD 点积（768D，AVX2）21.7 ns（simd_benchmark）· 平衡模式 Recall@10 为 99.8%，精准模式为 100%（10K/128D，recall_benchmark）· BM25 稀疏搜索仅索引（10K 文档，top-10）57.6 us（sparse_benchmark -- top10_10k_corpus）。

搜索模式	ef_search	Recall@10	用例
快速	96	97.4%	实时建议、输入联想
均衡（默认）	160	99.8%	生产环境搜索、RAG 流水线
精确	512	100%	评估、与真实值比较

ef_search 是每个预设的基础值，在最多 10K 个向量且 k ≤ 32 时直接使用；ef_search_for_scale 会进一步提高该值。Recall@10：recall_benchmark，10K/128D，2026-09-10，使用 Apple M5 Pro。

距离度量 — 支持 5 种 SIMD 加速度量（AVX-512、AVX2、NEON）。在 i9-14900KF 参考设备上以 768D 测试（AVX2，热缓存；测试运行于 2026 年 4 月 3 日，详见 docs/BENCHMARKS.md §1）：Cosine 32 ns · Euclidean 26 ns · Dot Product 22 ns · Hamming 35 ns · Jaccard 27 ns。

ColumnStore — 类型化列式过滤；在 i9-14900KF 参考设备上处理 100K 行时，比 JSON 扫描快 130 倍（JSON scan 3.84 ms → ColumnStore 29.5 us）。该比率受硬件影响：在 Apple Silicon（M5 Pro，2026-07-20）上，JSON 扫描本身快约 2.8 倍，因此同一基准测试得出的结果约为 50–105 倍，而 ColumnStore 的绝对耗时保持不变（约 27 µs）。

数据来源： Intel Core i9-14900KF（x86_64，AVX2）。不同机器上的数据会有所不同；Apple Silicon 交叉验证、SIFT1M 标准化 ANN 测试以及完整方法详见 docs/BENCHMARKS.md。使用 python benchmarks/velesdb_benchmark.py --recall 可复现端到端测试数据。

---

选择你的入口

我想要……	使用	备注
在一个文件中试用	velesdb（Python 3.9+）	最快捷的上手方式
嵌入引擎	velesdb-core（Rust）	引擎本身
为我的 Agent 提供记忆	velesdb-memory	MCP 服务 + 上下文编译器，适用于任何 MCP 客户端；.mcpb 包可在 MCP Registry 获取
从 Node 调用	@wiscale/velesdb-memory-node	记忆模块（通过服务 + TS SDK 使用完整引擎）
在浏览器中运行	@wiscale/velesdb-sdk	WASM，压缩后约 710 KB，完全在客户端运行
通过 HTTP 提供服务	velesdb-server	54 个 REST 端点——API 参考 · OpenAPI · 服务安全
部署到移动端/桌面端	velesdb-mobile · Tauri 插件	iOS / Android / 桌面端

我们如实公布各个平台的工具覆盖情况——包括仍有差距的平台：记忆 crate README。示例：examples/。

通过 HTTP 提供服务——按类别划分的 54 个 REST 端点

类别	主要端点
集合	POST /collections、GET /collections、GET/DELETE /collections/{name}
点	/collections/{name}/points、/collections/{name}/points/raw、/collections/{name}/points/scroll、/collections/{name}/stream/insert、/collections/{name}/stream/enable、/collections/{name}/points/{id}/relations、/collections/{name}/points/{id}/ttl、/collections/{name}/relations
搜索	/collections/{name}/search、/collections/{name}/search/batch、/collections/{name}/search/hybrid、/collections/{name}/search/text、/collections/{name}/search/multi、/collections/{name}/search/ids、/collections/{name}/match
图	/collections/{name}/graph/edges、/collections/{name}/graph/edges/{id}、/collections/{name}/graph/edges/count、/collections/{name}/graph/traverse、/collections/{name}/graph/traverse/stream、/collections/{name}/graph/traverse/parallel、/collections/{name}/graph/nodes、/collections/{name}/graph/nodes/{id}/degree、/collections/{name}/graph/nodes/{id}/edges、/collections/{name}/graph/nodes/{id}/payload、/collections/{name}/graph/search
索引	GET/POST /collections/{name}/indexes、DELETE /collections/{name}/indexes/{label}/{property}、/collections/{name}/index/rebuild
VelesQL	/query、/aggregate、/query/explain
管理	/health、/ready、/metrics、/guardrails、/collections/{name}/stats、/collections/{name}/config、/collections/{name}/flush、/collections/{name}/analyze、/collections/{name}/empty、/collections/{name}/sanity、/collections/{name}/compact、/collections/{name}/vacuum

完整 API 参考： docs/reference/api-reference.md | OpenAPI 规范： docs/openapi.yaml | 服务安全： docs/guides/SERVER_SECURITY.md

## 对比

	VelesDB	Chroma	Qdrant	pgvector
架构	向量 + 图 + 列式，统一架构	仅向量	向量 + 负载	PostgreSQL 的向量扩展
元数据筛选	类型化 ColumnStore + 二级索引	JSON 扫描	JSON 负载	SQL
图支持	原生（MATCH 子句）	不支持	不支持	不支持
查询语言	VelesQL（SQL + NEAR + MATCH）	Python API	JSON API / gRPC	SQL + 运算符
根据文本生成嵌入	可选 本地 / OpenAI 适配器；不捆绑模型	嵌入函数，Python/TypeScript 中提供默认本地模型	可选的客户端 FastEmbed	无；需自行提供外部模型生成的向量
部署	嵌入式 / 服务端 / WASM / 移动端	服务端（Python）	服务端（Rust）	需要 PostgreSQL
二进制大小	~14 MB	~500 MB（含依赖项）	~50 MB	不适用（PG 扩展）
浏览器 / 移动端	支持 / 支持	不支持	不支持	不支持
离线 / 本地优先	支持	部分支持	不支持	不支持

适用场景： 在单一引擎中实现向量 + 图 + 结构化筛选，采用本地优先模式且可审计。目前不太适合： 需要多节点分布式集群的托管云服务。竞品数据为常见公开范围，并非我们实际进行的同场基准测试——自行运行。截至 2026 年年中，与 Agent 记忆产品（Mem0、Zep、Letta）的详细对比：docs/WHY_VELESDB.md。

VelesDB Premium — 企业级控制平面

核心引擎采用源代码可用模式，并将继续如此。Premium 在相同二进制文件之上增加企业级功能层，面向使用敏感数据运行 Agent 集群的组织：所有端点（包括记忆和上下文编译器界面）均支持 RBAC · 审计跟踪（谁、做了什么、何时发生——仅记录元数据，兼顾 GDPR）并支持取证回放 · 多租户，提供严格的租户隔离和两级删除权限 · 集群和气隙部署 · 面向运维人员的 WebAdmin UI。

价格面议——[email protected] · velesdb.com。由 Wiscale 开发（法国；原生支持 GDPR 和数据主权）。

---

已知限制 — 诚实说明边界

以下项目是有意取舍或由 Premium 跟踪的功能，并非正确性缺陷——Community Edition 已可用于生产环境中的单节点、本地优先部署。我们会将这些限制与优势一并公布，包括尚未修复的项目。

#	限制	范围	跟踪状态
1	每个集合仅支持单个写入器——WAL 采用串行写入；并发写入器会争用同一个 fsync 锁。	设计取舍（默认采用本地优先、崩溃安全设计）。读取吞吐量不受影响。	Premium 计划支持并发 WAL 写入器。参见 docs/CONCURRENCY_MODEL.md。
2	不支持分布式复制——仅支持单节点；Core 不支持 Raft、分片或自动故障转移。	有意如此：最适合本地优先／嵌入式场景。	基于 Raft 的复制功能由 Premium 跟踪。
3	Core 不支持高级 RBAC／多租户隔离——Core 提供 DatabaseObserver 执行接口——自 3.10.0 起已应用于所有 HTTP 读取路径，在 4.0.0 中仍然如此——但不提供策略引擎。	Core 提供钩子，而非策略引擎。	Premium 功能。
4	WASM 中的 MATCH 最多支持 2 跳——在原生构建中，3 跳及以上的 MATCH 均可正常运行。	浏览器构建的范围限制，并非正确性问题。	正在跟踪。
5	尚未提交 SIFT1M 指纹旁路文件——参考机器提交固定哈希前，加载器会回退到 TOFU 模式。	这不是正确性问题——仍会进行形状验证。	引导流程已发布；旁路文件待定。
6	尚无与 Qdrant／Chroma／FAISS 的 Docker Compose 正面对比基准测试——SIFT1M 已提供可与文献结果相当的数据。	并列数据所需的基础设施尚未冻结。	正在跟踪。
7	各接口的上下文编译器工具支持情况不一——MCP 服务和 Rust 提供完整工具集；Node、Python 和 WASM 支持尚不完整，且 WASM 的工作上下文仅限会话内使用。	绑定层的范围限制，并非引擎缺陷；与此同时，MCP 可支持任意客户端。	各接口的对照表见 memory crate README。

内部技术限制（查询规划器近似处理、计划缓存语义）：docs/reference/KNOWN_LIMITATIONS.md。

贡献与联系

质量标准：cargo test --workspace——每次合并时，CI 都会运行覆盖 Rust、TypeScript 和 Python 的 9k+ 项测试；具体命令见 QUALITY_BAR.md。

欢迎贡献——请从 CONTRIBUTING.md 和适合新手的问题开始。安全问题报告：SECURITY.md。路线图：ROADMAP.md · 更新日志 · DeepWiki。

许可证：VelesDB Core License 1.0（可获取源代码）。Premium：商业许可证。 **联系：**[email protected] · velesdb.com

_{名称致意于Veles，这位古老斯拉夫神话中的神祇——隐藏知识与边界的守护者。}