项目定位与核心能力

Vex 是 VEKTOR Memory 推出的向量记忆可移植性 CLI，定位为"代理记忆的搬运与转换层"。其在 README.md 中给出的核心命令面包括 export、import、migrate、convert、sync、sign、verify、inspect、validate，并支持 11 个连接器：VEKTOR Slipstream、Pinecone、Qdrant、ChromaDB、Weaviate、pgvector、Redis、Milvus / Zilliz、Neo4j、Claude 导出、ChatGPT 导出。仓库的 keywords 字段同时声明 vector、migration、embeddings、agent-memory、memory-portability、vmig 等，强调"在 LLM / 代理生态中做记忆资产迁移"这一目标。资料来源：README.md:1-40、package.json:8-40。

许可与运行环境：项目遵循 Apache-2.0，要求 Node.js ≥ 18.0.0，核心依赖仅 better-sqlite3 与 Ink 系列的 TUI 库（ink、ink-select-input、ink-text-input、react），其他向量库驱动一律以 peerDependencies / optionalDependencies 形式按需安装。资料来源：package.json:55-78。

系统架构：管线、连接器与格式

Vex 的运行时由三层组成：管线（pipeline）、连接器（connectors）、格式（formats）。

1. 7 步导入管线 — pipeline/index.js 串接 CHUNK → EXTRACT → SCORE → DEDUP → EMBED → GRAPH → STORE 七个步骤；提供 raw（步骤 1/5/6/7 走原始 blob 存储）、extract（全 7 步 + LLM 抽取原子事实）、smart（对小对话交换 chunk 策略）三种模式。2. LLM 提供方级联 — pipeline/02-extract.js 实现了 groq → ollama → openai → anthropic 的瀑布式故障切换，支持逗号分隔的多密钥轮换、Ollama 草稿模型的投机解码、429 自适应退避与"永不停止"（耗尽的块被跳过并记录）。3. 通用 .vmig.jsonl 格式 — SPEC.md 规定每行一个 JSON 对象，必填 id、vex_version，条件必填 text / vector；校验规则要求 dims === vector.length、metadata 必须是扁平的标量键值对。4. 连接器接口 — 各 connectors/*.js（如 connectors/pinecone.js、connectors/claude-export.js）以统一 toRecord 调用将外部记录规整为 vmig 记录，从而被管线复用。资料来源：pipeline/index.js:1-30、pipeline/02-extract.js:1-45、SPEC.md:1-30、connectors/claude-export.js:1-25。

flowchart LR
  A[来源：claude-export / chatgpt-export / 任意连接器] --> B[1 CHUNK]
  B --> C[2 EXTRACT<br/>provider cascade]
  C --> D[3 SCORE]
  D --> E[4 DEDUP]
  E --> F[5 EMBED]
  F --> G[6 GRAPH<br/>实体+边]
  G --> H[7 STORE]
  H --> I[(目标连接器<br/>vektor/pinecone/...)]
  H -.-> J[.vmig.jsonl<br/>便携导出]

CLI 命令面与可观测工具

vex 默认在真实 TTY 下启动 Ink 驱动的交互式面板（v0.8.6，2026-06-15），--help 仍回落到纯文本。每个命令对应一个分步向导：migrate 选择起止 store；convert 选择 5 种目标适配器；sign 提示密钥生成；sync 在 init / push / pull / status / diff 五个动作间切换。资料来源：CHANGELOG.md:30-58。

可观测命令不依赖任何向量库即可独立运行：inspect 输出记录数、命名空间、维度；validate 对 .vmig.jsonl 做 schema 校验；sign / verify 使用 BLAKE3 + Ed25519 签名，签名侧车文件包含 root_hash、record_hashes、public_key、signature 四要素，验证时按"重算每条记录 → 重算根哈希 → 验签"三步进行。资料来源：README.md:60-80、core/sign.js:1-30。

安全、同步与生态集成

签名与验证：BLAKE3 摘要 + Ed25519 签名以 core/sign.js 为核心，提供"无 LLM、无目标 store"即可执行的完整性证明。安全策略：SECURITY.md 明确"数据本地化"立场——VEKTOR 工具不存储任何用户数据（记忆、凭证、保险库、API Key），并要求漏洞通过 [email protected] 私下报告，7 天内响应。加密同步：vex sync 支持 GitHub / Codeberg / Gitea，目标 blob 用 HKDF-SHA256(machine-id + token hash) 派生密钥后做 AES-256-GCM 加密，宿主机仅看到不透明 blob。生态集成：peer 依赖涵盖 LangChain Core、Milvus、Neo4j、pg、redis、sqlite-vec、vektor-slipstream，形成"既能导入对话历史，也能直接落到生产向量库"的双向通道。资料来源：core/sign.js:1-25、SECURITY.md:1-30、README.md:40-60、package.json:60-80。

参见

• Vex 交互式 TUI 与命令面板
• .vmig.jsonl 格式规范详解
• 7 步导入管线与提供方级联
• BLAKE3 + Ed25519 签名与验证
• vex sync 加密同步机制

概述与定位

Vex 的迁移引擎（vex migrate）承担"跨向量库搬运 AI 记忆"的核心职责：把任意支持的源端（VEKTOR Slipstream、Pinecone、Qdrant、Chroma、Weaviate、pgvector、Redis、Milvus、Neo4j、Claude / ChatGPT 导出）抽取、清洗、再写回另一端。为了让搬运过程不只是向量复制，Vex 提供了一条可选的 7 步抽取流水线（raw / extract / smart 三种模式），把会话内容变成带标签、实体、潜在问句的"原子事实"，并通过 BLAKE3 + Ed25519 签名保证导出文件不可篡改。

资料来源：pipeline/index.js:1-20

资料来源：README.md:1-40

7 步流水线架构

pipeline/index.js 是编排器，依次调用 01-chunk.js 到 07-store.js 七个模块。

flowchart LR
  A[CHUNK] --> B[EXTRACT]
  B --> C[SCORE]
  C --> D[DEDUP]
  D --> E[EMBED]
  E --> F[GRAPH]
  F --> G[STORE]
  G --> H[(目标向量库)]

• raw 模式仅跑 1、5、6、7 步：把会话当 blob 直接落地，最快但缺少原子事实。
• extract 模式跑全部 7 步，强制需要 LLM。
• smart 模式同样跑 7 步，但会对短会话关闭切分，是 README 推荐的默认选项。

资料来源：pipeline/index.js:1-30

资料来源：pipeline/02-extract.js:1-30

资料来源：README.md:1-50

提供商级联、密钥轮换与容错

pipeline/02-extract.js 的设计重点是"任何情况下任务都能跑完"。

1. 提供商瀑布（provider cascade）：默认顺序为 groq → ollama → openai → anthropic，上游失败自动降级到下一家。--provider auto 会读取 vektor 配置，从所有已配置的 key 自动拼装链。
2. 密钥轮换：--groq-key k1,k2,k3 这样的逗号分隔列表会被 round-robin 使用，把 3 个免费层 Groq key 的 TPM 预算凑成 3 倍。
3. 推测解码：--ollama-draft llama3.2 给本地 Ollama 启用 draft 模型，可拿到 2-4× 提速。
4. 自适应退避：从 429 / "rate limit" / "try again in 3.435s" 之类错误消息里精确解析 retry-after，而不是固定 sleep。
5. 永不停止：耗尽的 chunk 会被跳过 + 日志记录，job 始终能写完 store。

默认并发为 3（--concurrency），免费层 Groq 建议显式设为 1。PROVIDER_DEFAULTS 表里为每个 provider 预置了 endpoint、模型和 TPM 上限，例如 Groq 默认 llama-3.1-8b-instant / 6000 TPM、Anthropic 默认 claude-haiku-4-5-20251001 / 20000 TPM。

资料来源：pipeline/02-extract.js:1-60

资料来源：CHANGELOG.md:1-20

事实结构、图谱边与导出格式

抽取阶段输出的每条 fact 都带 5 个关键字段：

• fact：自然语言事实本体
• entities：最多 8 个命名实体（用停用词表 + 词法规则抽）
• tags：1-4 个小写关键词
• potential：恰好 3 条"该 fact 能回答什么"的预设问句，用于提升 BM25 召回
• importance：0-1 浮点重要性

pipeline/06-graph.js 的 buildEdgesFromFacts 用实体做并查集合：共享实体的 fact 之间连边，限制每对 fact 最多与前 5 个邻居相连以避免爆炸式增长。最终写边由 writeEdgesToDb 落到目标库。

导出走 formats/vmig.js 的 .vmig.jsonl：每行一条 JSON 记录，包含 id / text / vector / dims / model / namespace / metadata / created_at / source_store / vex_version。writeJsonl 会同步生成一个 record_count + checksum 的元数据 sidecar，配合 core/sign.js 里的 BLAKE3 + Ed25519 签名可实现：

vex sign   memories.vmig.jsonl   # 生成 .vmig.sig
vex verify memories.vmig.jsonl   # 校验，0=有效，1=被篡改

adapters/convert/index.js 把同一份 .vmig.jsonl 转换为 OpenAI、Anthropic、Mistral、Together 聊天微调格式或纯文本，adapters/langchain.js 提供的 VektorMemory 继承自 @langchain/core/memory.BaseMemory（未安装时自动回退为 duck-typed 实现），使 CrewAI、LangChain 代理可直接使用。

资料来源：pipeline/06-graph.js:1-40

资料来源：formats/vmig.js:1-50

资料来源：core/sign.js:1-30

资料来源：adapters/convert/index.js:1-20

资料来源：adapters/langchain.js:1-30

资料来源：CHANGELOG.md:1-20

运行时可见性与常见失败模式

utils/progress.js 暴露两个工具函数：

• progress(current, total, label)：用 █/░ 字符绘制 20 格进度条，写在同一行用 \r 覆盖。
• summary({ connector, total, upserted, skipped, durationMs })：在导入/导出末尾打印带 ┌─ │ └ 框线的统计块。

部署与运行时的常见坑：

Node 版本需 >=18.0.0（见 package.json 的 engines），可选依赖 @noble/hashes 与 @noble/ed25519 负责签名/校验，redis、pg、neo4j-driver、@zilliz/milvus2-sdk-node 为对应连接器的 peer dependency，按需安装。

资料来源：utils/progress.js:1-20

资料来源：adapters/convert/index.js:1-20

资料来源：package.json:1-80

资料来源：CHANGELOG.md:1-30

See Also

• TUI 交互式向导与命令面板
• .vmig.jsonl 格式规范
• BLAKE3 + Ed25519 签名与校验
• LangChain / CrewAI 集成

vmig 互换格式（.vmig.jsonl）

.vmig.jsonl 是 Vex 定义的中性格式规范，UTF‑8 编码、LF 换行、Apache 2.0 许可，每行一个 JSON 对象，承载可被任意向量库读回的记录 资料来源：SPEC.md:1-12。

字段与状态

校验规则要求：至少 text 与 vector 之一非空；dims 必须等于 vector.length；文件内 id 唯一；metadata 仅标量值 资料来源：SPEC.md:25-30。

导入嵌入策略

格式规范定义了三层决策：

1. 模型相同 → 直接复制 vector。
2. 模型不同且 text 存在 → 重新嵌入。
3. 无 text → 退化到「Drift‑Adapter」（Phase 3）做维度漂移适配 资料来源：SPEC.md:32-39。

formats/vmig.js 中 writeJsonl 与 writeMeta 负责序列化及元数据副文件（checksum、exported_at、record_count）的生成，toRecord 在反序列化时按 vex_version 做向下兼容的字段回填 资料来源：formats/vmig.js:5-58。

连接器体系

Vex 把每一种向量库、对话导出格式和签名/校验工具都抽象成「连接器」，通过同一组 CLI 命令（export / import / migrate / convert / sign / verify / inspect / validate）统一调度 资料来源：README.md:9-25。

已支持的目标库

新增连接器依赖需手动安装，例如 npm install redis 或 npm install neo4j-driver，避免硬依赖 资料来源：CHANGELOG.md:1-25 / README.md:184-198。

提取阶段的提供者级联

在 extract 与 smart 模式下，pipeline/02-extract.js 维护一个级联链 groq → ollama → openai → anthropic → mistral → together，并支持：

• 多 Key 轮询：--groq-key k1,k2,k3 倍增有效 TPM 配额。
• Ollama 投机解码：传入 --ollama-draft llama3.2 利用草稿模型加速 2‑4×。
• 自适应退避：从 Please try again in 3.435s 之类的限流消息中精确解析等待时间。
• 「永不中断」：耗尽的 chunk 会被跳过并记录，作业始终收敛 资料来源：pipeline/02-extract.js:1-46。

代表性实现：Pinecone 与 Claude 导出

connectors/pinecone.js 在 extract 阶段通过 GET /indexes/{index} 拉取维度，按 namespace 分页游走 query/list，将 metadata 中的非对象标量过滤后用 toRecord 包装成 vmig 记录 资料来源：connectors/pinecone.js:24-80。connectors/claude-export.js 则把 conversations.json 中可能是字符串、也可能是 [{type:'text', text:'...'}] 数组的 content 归一化为纯文本，再交给 reEmbed 工具和 vmig 适配层 资料来源：connectors/claude-export.js:1-50。

LangChain 适配器

adapters/langchain.js 提供一个继承自 LangChain BaseMemory 的 VektorMemory 类，用作 LangChain Chain 与 VEKTOR 后端之间的桥梁 资料来源：adapters/langchain.js:1-40。

关键特性

• 可选硬依赖：await import('@langchain/core/memory') 失败时自动回退到 duck‑typed 的 BaseMemory 实现，确保不安装 LangChain 也能加载模块。
• 记忆类型标签：通过 saveContext() 写入的记忆默认打上 episodic 标签，可通过 opts.memory_type 覆盖为 semantic 等，用于后续按模态过滤。
• 每轮注入：topK（默认 5）控制注入到 prompt 的记忆条数，inputKey / outputKey 控制从 chain 输入/输出对象的哪个键读写。
• 图谱参与：检索时一并带回 entities 与 tags，便于在 LangChain Agent 内部做引用。

该适配器不修改 LangChain 主线协议，因此可以与 ConversationChain、AgentExecutor、RetrievalQA 等常见 Chain 自由组合 资料来源：adapters/langchain.js:18-90。

集成流水线与签名

整条管线在 pipeline/index.js 中被编排为 7 个步骤：CHUNK → EXTRACT → SCORE → DEDUP → EMBED → GRAPH → STORE 资料来源：pipeline/index.js:1-25。core/sign.js 在最后通过 BLAKE3 哈希根 + Ed25519 签名生成 .vmig.sig 副文件，校验时先重算每条记录哈希、再重算根哈希、最后验证签名 资料来源：core/sign.js:1-25。

flowchart LR
    A[对话源] --> B[CHUNK]
    B --> C{模式}
    C -- extract/smart --> D[EXTRACT<br/>级联 LLM]
    C -- raw --> E[EMBED]
    D --> F[SCORE]
    F --> G[DEDUP]
    G --> E
    E --> H[GRAPH<br/>实体/边]
    H --> I[STORE<br/>目标库]
    I --> J[SIGN<br/>BLAKE3+Ed25519]
    J --> K[.vmig.jsonl<br/>+.vmig.sig]

安全方面，VEKTOR Memory 明确声明「不收集、不存储用户数据」，包括 Vex 生成的任何导出与签名文件；签名密钥、API 密钥与 vault 文件全部留在用户本地 资料来源：SECURITY.md:18-32。package.json 中也将 redis、pg、neo4j-driver、@zilliz/milvus2-sdk-node 等列为 optionalDependencies / peerDependencies，安装与否完全由用户按需决定 资料来源：package.json:30-58。

See Also

• README.md — CLI 命令、连接器矩阵、提取标志。
• SPEC.md — vmig 格式的字段表与校验规则。
• CHANGELOG.md — 连接器与 TUI 的版本演进记录。

Vex 将"主权备份"(Sovereign Backup) 视为核心设计目标：用户在任何时候都能离线、签名、可验证地导出自己的记忆向量，并在不同向量库、LLM 框架或智能体运行时之间迁移。README.md 与 SECURITY.md 共同声明 "Your data belongs to you. That is not a policy. It is the architecture."，所有导出、签名、迁移流程均不依赖 Vektor Memory 的服务器 资料来源：README.md:1-60、资料来源：SECURITY.md:1-30。

1. `.vmig.jsonl` 可移植格式与签名验证

Vex 的标准导出格式为 .vmig.jsonl，由 formats/vmig.js 定义。writeJsonl() 将每条记录序列化为单行 JSON，并在末尾写出配套的 meta 块，包含 exported_at、source_store、record_count 与 checksum 等字段 资料来源：formats/vmig.js:1-60。

SPEC.md 给出了更严格的字段约束：id 在文件内必须唯一、dims 必须等于 vector.length、metadata 仅允许标量值，且每条记录必须包含 vex_version 字段以保证后续可校验 资料来源：SPEC.md。

签名与验证流程由 core/sign.js 与 utils/checksum.js 共同实现。vex sign 使用 BLAKE3 计算文件指纹，再以 Ed25519 私钥签名；vex verify 读取签名后立即返回退出码 0（合法）或 1（被篡改） 资料来源：README.md:120-140。依赖项 @noble/ed25519 与 @noble/hashes 作为可选依赖，避免增加默认安装体积 资料来源：package.json:55-65。

2. CLI 工具与交互式 TUI

命令行入口 vex.mjs 暴露 9 个核心子命令：migrate、export、import、convert、sync、sign、verify、inspect、validate 资料来源：README.md:150-180。自 v0.8.6 起，在真实 TTY 中直接运行 vex 将启动基于 Ink 的交互式 TUI，通过方向键选择命令后进入分步向导，自动生成正确的 CLI 参数；--help 仍输出原有纯文本帮助 资料来源：CHANGELOG.md。

utils/progress.js 提供统一的进度条与汇总输出：progress() 在终端中就地刷新 [████░░░░░░] 40% (8/20)；summary() 在导入/导出结束后打印 total / upserted / skipped / duration 四行报告，便于用户核对实际写入量 资料来源：utils/progress.js。

3. 提取管道：原子事实、图谱与去重

完整 7 步管道在 pipeline/index.js 中编排：CHUNK → EXTRACT → SCORE → DEDUP → EMBED → GRAPH → STORE，支持 raw、extract、smart 三种模式 资料来源：pipeline/index.js:1-30。pipeline/02-extract.js 实现了多 Provider 级联（groq → ollama → openai → anthropic），并支持以逗号分隔的轮询 Key（如 --groq-key k1,k2,k3）以提升总 TPM 配额；并发度可通过 --concurrency 调整 资料来源：pipeline/02-extract.js:1-80。

提取后的事实附带 tags、entities、potential（3 个候选查询问题）等字段，用于后续的图谱与 BM25 检索 资料来源：CHANGELOG.md。pipeline/06-graph.js 基于共享实体构建事实间边：同一实体出现 ≥ 2 次即生成边，单条事实实体上限为 8 个，并通过停用词表减少噪声 资料来源：pipeline/06-graph.js。

4. 扩展点：连接器、适配器与框架集成

Vex 通过三类扩展点覆盖不同运行时：

• 连接器：connectors/claude-export.js 把 conversations.json 中的每条对话切分为 user+assistant 配对，并附加 conversation_name、turn_count、source_format 等元数据 资料来源：connectors/claude-export.js。connectors/pinecone.js 提供分页流式导出，支持自定义命名空间与维度自动推断 资料来源：connectors/pinecone.js。
• 格式转换器：adapters/convert/index.js 注册了 openai、anthropic、anthropic-finetune、plain-text 等多种格式别名；getAdapter() 在未知名称时抛出可用列表 资料来源：adapters/convert/index.js。
• LLM 框架适配：adapters/langchain.js 定义 VektorMemory，在 @langchain/core 缺失时降级为 duck-typed BaseMemory；saveContext() 默认标记为 episodic，可通过 opts.memory_type 覆盖 资料来源：adapters/langchain.js。

下表总结了 Vex 端到端主权备份的关键步骤及对应源码：

常见失败模式

• 签名密钥丢失：vex verify 在 Ed25519 公钥缺失或文件被修改时退出码为 1，且不会打印任何受信任结果——务必在签名后立即将公钥与 .vmig.jsonl 一同备份 资料来源：README.md:120-140。
• 维度不匹配：SPEC.md 规定 dims 必须与 vector.length 一致；导入到 sqlite-vec 等强维度校验的存储时若不匹配会直接失败 资料来源：SPEC.md。
• Provider 限流：pipeline/02-extract.js 会从 429 响应中解析 retry-after，但若全部 Provider 同时耗尽，耗尽分块将被跳过并写入日志，整个作业仍会完成而不是中断 资料来源：pipeline/02-extract.js:1-80。

See Also

• 向量库与图谱连接器总览
• LangChain 适配器
• 数据安全与签名机制
• .vmig.jsonl 格式规范

Pitfall Log / 踩坑日志

项目：Vektor-Memory/Vex

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Vektor-Memory/Vex | host_targets=claude, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Vektor-Memory/Vex | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Vektor-Memory/Vex | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Vektor-Memory/Vex | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Vektor-Memory/Vex | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Vektor-Memory/Vex | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Vektor-Memory/Vex | release_recency=unknown