# https://github.com/Vektor-Memory/Vex 项目说明书

生成时间：2026-06-17 05:33:07 UTC

## 目录

- [Vex 概览与系统架构](#page-1)
- [迁移引擎与 7 步抽取流水线](#page-2)
- [vmig 格式、连接器与 LangChain 适配器](#page-3)
- [主权备份、签名验证、CLI 工具与扩展](#page-4)

<a id='page-1'></a>

## Vex 概览与系统架构

### 相关页面

相关主题：[迁移引擎与 7 步抽取流水线](#page-2), [vmig 格式、连接器与 LangChain 适配器](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Vektor-Memory/Vex/blob/main/README.md)
- [package.json](https://github.com/Vektor-Memory/Vex/blob/main/package.json)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Vex/blob/main/CHANGELOG.md)
- [SPEC.md](https://github.com/Vektor-Memory/Vex/blob/main/SPEC.md)
- [pipeline/index.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/index.js)
- [pipeline/02-extract.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/02-extract.js)
- [formats/vmig.js](https://github.com/Vektor-Memory/Vex/blob/main/formats/vmig.js)
- [core/sign.js](https://github.com/Vektor-Memory/Vex/blob/main/core/sign.js)
- [connectors/claude-export.js](https://github.com/Vektor-Memory/Vex/blob/main/connectors/claude-export.js)
- [connectors/pinecone.js](https://github.com/Vektor-Memory/Vex/blob/main/connectors/pinecone.js)
- [SECURITY.md](https://github.com/Vektor-Memory/Vex/blob/main/SECURITY.md)
</details>

# Vex 概览与系统架构

## 项目定位与核心能力

Vex 是 VEKTOR Memory 推出的向量记忆可移植性 CLI，定位为"代理记忆的搬运与转换层"。其在 [README.md](https://github.com/Vektor-Memory/Vex/blob/main/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](https://github.com/Vektor-Memory/Vex/blob/main/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](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/02-extract.js) 实现了 `groq → ollama → openai → anthropic` 的瀑布式故障切换，支持逗号分隔的多密钥轮换、Ollama 草稿模型的投机解码、429 自适应退避与"永不停止"（耗尽的块被跳过并记录）。**3. 通用 .vmig.jsonl 格式** — [SPEC.md](https://github.com/Vektor-Memory/Vex/blob/main/SPEC.md) 规定每行一个 JSON 对象，必填 `id`、`vex_version`，条件必填 `text` / `vector`；校验规则要求 `dims === vector.length`、`metadata` 必须是扁平的标量键值对。**4. 连接器接口** — 各 `connectors/*.js`（如 [connectors/pinecone.js](https://github.com/Vektor-Memory/Vex/blob/main/connectors/pinecone.js)、[connectors/claude-export.js](https://github.com/Vektor-Memory/Vex/blob/main/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]()。

```mermaid
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](https://github.com/Vektor-Memory/Vex/blob/main/core/sign.js) 为核心，提供"无 LLM、无目标 store"即可执行的完整性证明。**安全策略**：[SECURITY.md](https://github.com/Vektor-Memory/Vex/blob/main/SECURITY.md) 明确"数据本地化"立场——VEKTOR 工具不存储任何用户数据（记忆、凭证、保险库、API Key），并要求漏洞通过 `hello@vektormemory.com` 私下报告，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 加密同步机制

---

<a id='page-2'></a>

## 迁移引擎与 7 步抽取流水线

### 相关页面

相关主题：[Vex 概览与系统架构](#page-1), [vmig 格式、连接器与 LangChain 适配器](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [pipeline/index.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/index.js)
- [pipeline/02-extract.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/02-extract.js)
- [pipeline/06-graph.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/06-graph.js)
- [formats/vmig.js](https://github.com/Vektor-Memory/Vex/blob/main/formats/vmig.js)
- [utils/progress.js](https://github.com/Vektor-Memory/Vex/blob/main/utils/progress.js)
- [core/sign.js](https://github.com/Vektor-Memory/Vex/blob/main/core/sign.js)
- [adapters/convert/index.js](https://github.com/Vektor-Memory/Vex/blob/main/adapters/convert/index.js)
- [adapters/langchain.js](https://github.com/Vektor-Memory/Vex/blob/main/adapters/langchain.js)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Vex/blob/main/CHANGELOG.md)
- [README.md](https://github.com/Vektor-Memory/Vex/blob/main/README.md)
- [package.json](https://github.com/Vektor-Memory/Vex/blob/main/package.json)
</details>

# 迁移引擎与 7 步抽取流水线

## 概述与定位

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` 七个模块。

| 步骤 | 模块 | 职责 |
|------|------|------|
| 1. CHUNK | `01-chunk.js` | 把会话切分为可处理的块，过短文本走 SKIP_PATTERNS 直接丢弃 |
| 2. EXTRACT | `02-extract.js` | LLM 抽取原子事实（仅 `extract` / `smart` 模式） |
| 3. SCORE | `03-score.js` | 重要性 + 时效性打分 |
| 4. DEDUP | `04-dedup.js` | 批内近重复合并（默认阈值 0.72） |
| 5. EMBED | `05-embed.js` | 可选向量化（OpenAI / Ollama / 自定义端点） |
| 6. GRAPH | `06-graph.js` | 实体抽取 + 时序、标签、因果边构建 |
| 7. STORE | `07-store.js` | 通过目标连接器 upsert |

```mermaid
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 签名可实现：

```bash
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 })`：在导入/导出末尾打印带 `┌─` `│` `└` 框线的统计块。

部署与运行时的常见坑：

| 现象 | 原因 | 处置 |
|------|------|------|
| `Unknown convert adapter: "..."` | 拼写错误或别名不对 | 用 `vex adapters` 查合法名字（`openai` / `anthropic` / `mistral` / `together` / `plain-text`） |
| 抽取阶段 0 fact 写出 | chunk 全被 `SKIP_PATTERNS` 跳过 | 改用 `smart` 模式或调小切分阈值 |
| 429 仍卡住 | Groq 免费层并发过高 | `--concurrency 1` 并启用密钥轮换 |
| pgvector 报 HNSW 不支持 | 老版本 PG | 自动回退到 IVFFlat（见 CHANGELOG） |
| `verify` 退出码 1 | `.vmig.jsonl` 被修改 | 用 `vex inspect` 复核记录，再决定是否重新 `sign` |

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 交互式向导与命令面板](tui-command-palette.md)
- [.vmig.jsonl 格式规范](vmig-format-spec.md)
- [BLAKE3 + Ed25519 签名与校验](sign-verify.md)
- [LangChain / CrewAI 集成](langchain-integration.md)

---

<a id='page-3'></a>

## vmig 格式、连接器与 LangChain 适配器

### 相关页面

相关主题：[迁移引擎与 7 步抽取流水线](#page-2), [主权备份、签名验证、CLI 工具与扩展](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [formats/vmig.js](https://github.com/Vektor-Memory/Vex/blob/main/formats/vmig.js)
- [SPEC.md](https://github.com/Vektor-Memory/Vex/blob/main/SPEC.md)
- [README.md](https://github.com/Vektor-Memory/Vex/blob/main/README.md)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Vex/blob/main/CHANGELOG.md)
- [connectors/pinecone.js](https://github.com/Vektor-Memory/Vex/blob/main/connectors/pinecone.js)
- [connectors/claude-export.js](https://github.com/Vektor-Memory/Vex/blob/main/connectors/claude-export.js)
- [pipeline/index.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/index.js)
- [pipeline/02-extract.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/02-extract.js)
- [core/sign.js](https://github.com/Vektor-Memory/Vex/blob/main/core/sign.js)
- [adapters/langchain.js](https://github.com/Vektor-Memory/Vex/blob/main/adapters/langchain.js)
- [package.json](https://github.com/Vektor-Memory/Vex/blob/main/package.json)
- [SECURITY.md](https://github.com/Vektor-Memory/Vex/blob/main/SECURITY.md)
</details>

# vmig 格式、连接器与 LangChain 适配器

Vex 是 VEKTOR 记忆生态中的「向量记忆可移植层」，围绕三块核心构建：`vmig` 互换格式、统一连接器体系，以及面向 LangChain 的记忆适配器。三者协同让对话、嵌入、图谱记忆能够在本地 SQLite、托管向量库与 LLM 框架之间自由流转，而不必被任何单一后端锁定。

## vmig 互换格式（.vmig.jsonl）

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

### 字段与状态

| 字段 | 类型 | 状态 | 含义 |
|---|---|---|---|
| `id` | string | 必填 | 稳定唯一 ID，缺省时回填 UUIDv4 |
| `text` | string \| null | 条件必填 | 原始文本，`re-embed` 策略时必备 |
| `vector` | float[] \| null | 条件必填 | 扁平浮点数组；为空表示导入时重新嵌入 |
| `model` / `dims` | string / int | 可选 | 嵌入模型与维度，二者需保持一致 |
| `namespace` | string | 可选 | 顶层逻辑分区 |
| `metadata` | object | 可选 | 仅允许标量，禁止嵌套 |
| `created_at` / `source_store` / `modality` / `score` | — | 可选 | 时间、来源、模态、相似度 |
| `vex_version` | string | 必填 | Semver，例如 `1.0.0` |

校验规则要求：至少 `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]()。

### 已支持的目标库

| 存储 | 导入 | 导出 | 关键说明 |
|---|---|---|---|
| VEKTOR Slipstream | ✓ | ✓ | 本地 SQLite，承载完整 MAGMA 图 |
| Pinecone | ✓ | ✓ | 支持 Serverless 与 Pod 模式 |
| Qdrant / ChromaDB / Weaviate | ✓ | ✓ | 兼顾本地与云端部署 |
| pgvector | ✓ | ✓ | PostgreSQL + Supabase，含 HNSW 索引 |
| Redis | ✓ | ✓ | RediSearch VSS（HNSW/COSINE），无模块时回退普通 Hash |
| Milvus / Zilliz | ✓ | ✓ | IVF_FLAT，零向量兜底 |
| Neo4j | ✓ | ✓ | MERGE 写入，Entity 节点 + Cypher 边 |
| Claude / ChatGPT 导出 | ✓ | — | 解析官方 `conversations.json` |

新增连接器依赖需手动安装，例如 `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]()。

```mermaid
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](https://github.com/Vektor-Memory/Vex/blob/main/README.md) — CLI 命令、连接器矩阵、提取标志。
- [SPEC.md](https://github.com/Vektor-Memory/Vex/blob/main/SPEC.md) — `vmig` 格式的字段表与校验规则。
- [CHANGELOG.md](https://github.com/Vektor-Memory/Vex/blob/main/CHANGELOG.md) — 连接器与 TUI 的版本演进记录。

---

<a id='page-4'></a>

## 主权备份、签名验证、CLI 工具与扩展

### 相关页面

相关主题：[Vex 概览与系统架构](#page-1), [vmig 格式、连接器与 LangChain 适配器](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [core/sign.js](https://github.com/Vektor-Memory/Vex/blob/main/core/sign.js)
- [formats/vmig.js](https://github.com/Vektor-Memory/Vex/blob/main/formats/vmig.js)
- [utils/checksum.js](https://github.com/Vektor-Memory/Vex/blob/main/utils/checksum.js)
- [utils/progress.js](https://github.com/Vektor-Memory/Vex/blob/main/utils/progress.js)
- [pipeline/index.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/index.js)
- [pipeline/02-extract.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/02-extract.js)
- [pipeline/06-graph.js](https://github.com/Vektor-Memory/Vex/blob/main/pipeline/06-graph.js)
- [adapters/convert/index.js](https://github.com/Vektor-Memory/Vex/blob/main/adapters/convert/index.js)
- [connectors/claude-export.js](https://github.com/Vektor-Memory/Vex/blob/main/connectors/claude-export.js)
- [connectors/pinecone.js](https://github.com/Vektor-Memory/Vex/blob/main/connectors/pinecone.js)
- [adapters/langchain.js](https://github.com/Vektor-Memory/Vex/blob/main/adapters/langchain.js)
- [CHANGELOG.md](https://github.com/Vektor-Memory/Vex/blob/main/CHANGELOG.md)
- [README.md](https://github.com/Vektor-Memory/Vex/blob/main/README.md)
- [SECURITY.md](https://github.com/Vektor-Memory/Vex/blob/main/SECURITY.md)
- [SPEC.md](https://github.com/Vektor-Memory/Vex/blob/main/SPEC.md)
- [package.json](https://github.com/Vektor-Memory/Vex/blob/main/package.json)
</details>

# 主权备份、签名验证、CLI 工具与扩展

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 端到端主权备份的关键步骤及对应源码：

| 步骤 | CLI/动作 | 主要源码 |
|---|---|---|
| 导出 | `vex export` | `formats/vmig.js` |
| 签名 | `vex sign` | `core/sign.js`、`utils/checksum.js` |
| 验证 | `vex verify` | `core/sign.js` |
| 转换 | `vex convert --to openai` | `adapters/convert/index.js` |
| 智能体注入 | LangChain / MCP | `adapters/langchain.js` |
| 图谱构建 | `pipeline/06-graph.js` | `pipeline/06-graph.js` |

## 常见失败模式

- **签名密钥丢失**：`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

- [向量库与图谱连接器总览](README.md)
- [LangChain 适配器](adapters/langchain.js)
- [数据安全与签名机制](SECURITY.md)
- [`.vmig.jsonl` 格式规范](SPEC.md)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: Vektor-Memory/Vex; human_manual_source: deepwiki_human_wiki -->