vanguard-memory-node

Vanguard Memory Node（VMN）

通过模型上下文协议（MCP）为 AI Agent 提供本地、确定性的记忆。

无需云服务。无需向量数据库。不会发生语义漂移。数据始终保留在你的设备上。

---

功能

VMN 为任何兼容 MCP 的 AI Agent 提供一个持久、可查询的记忆库，所有数据均存储在本地磁盘。文本只需导入一次，即会通过 SHA-256 进行内容寻址、分段，并使用分片 BM25 倒排索引建立索引。检索过程具有确定性：对于相同的数据，同一查询始终会返回相同的排序结果。

还可以选择将记忆库同步到 ExergyNet LNES-17 ledger，以便跨设备和跨 Agent 检索记忆，并保留加密溯源信息。

---

安装

npm install -g @lnes/vanguard-memory-node

或者无需安装即可运行：

npx @lnes/vanguard-memory-node

---

Claude Desktop 集成

Mac — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "npx",
      "args": ["-y", "@lnes/vanguard-memory-node"]
    }
  }
}

启用 ExergyNet 记忆库同步：

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "npx",
      "args": ["-y", "@lnes/vanguard-memory-node"],
      "env": {
        "EXERGYNET_API_KEY": "sk-exergy-your-key",
        "EXERGYNET_NETWORK": "mainnet",
        "AUTO_SYNC_VAULT": "true"
      }
    }
  }
}

Windows 上的 WSL：

{
  "mcpServers": {
    "vanguard-memory": {
      "command": "wsl",
      "args": ["-d", "Ubuntu", "npx", "-y", "@lnes/vanguard-memory-node"]
    }
  }
}

---

工具（共 11 个）

vmn_ingest

将文本存储为通过 SHA-256 进行内容寻址的分片。对文本进行分段和索引，并更新本地目录。

参数	类型	必填	描述
text	string	是	要存储的内容
title	string	否	易于阅读的标签
namespace	string	否	逻辑分区（默认值：default）
tags	string[]	否	搜索标签
content_type	string	否	MIME 类型提示（默认值：text/plain）
source	string	否	来源标签

返回：SHA-256 根哈希值 + 记忆库路径 + vault_synced 标记。

vmn_recall

使用词法 BM25 评分，从指定分片中检索一个 900 字符的证据窗口。

参数	类型	必填	描述
hash	string	是	来自 vmn_ingest 的根哈希值
query	string	是	搜索查询

返回：最佳匹配的证据窗口；若无匹配项，则返回易于阅读的提示信息。

vmn_search

在所有已导入对象中搜索整个记忆库的关键词。返回带有摘要片段的排序结果。

参数	类型	必填	描述
query	string	是	搜索查询
limit	number	否	结果数量上限（默认值：10）
namespace	string	否	仅在此命名空间中搜索

vmn_ingest_file

增量导入不断增长的文件，并通过游标跟踪进度，因此每次调用只会导入新增行。专为 Stop 钩子和持续日志管道设计，可安全地重复调用，不会产生重复内容。

参数	类型	必填	描述
file_path	string	是	文件的绝对路径
session_id	string	否	游标键（默认为文件路径）
namespace	string	否	导入内容的命名空间（默认值：file_ingest）
title	string	否	可选的标题覆盖值
tags	string[]	否	可选标签

返回：lines_ingested、cursor_line 和分片 hash（若没有新内容则为 null）。

Stop 钩子示例 — 自动导入每个 Claude 会话：

{
  "hooks": {
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "npx -y @lnes/vanguard-memory-node vmn_ingest_file --file_path \"$CLAUDE_SESSION_FILE\" --session_id \"$CLAUDE_SESSION_ID\""
      }]
    }]
  }
}

vmn_list

列出记忆库中的所有记忆对象。

参数	类型	必填	描述
namespace	string	否	按命名空间筛选

vmn_inspect

返回指定对象的完整目录元数据。

参数	类型	必填	描述
hash	string	是	根哈希值

vmn_delete

永久删除一个对象及其所有索引条目。

参数	类型	必填	描述
hash	string	是	根哈希

vmn_stats

返回知识库的汇总统计信息：条目数、总字节数、命名空间以及最早／最晚时间戳。

vmn_index_status

返回当前 BM25 索引状态（READY、REBUILD_REQUIRED、REBUILDING、DEGRADED）。

vmn_rebuild_index

根据权威对象文件重建完整的 BM25 索引。随时都可安全执行——对象绝不会被修改。

vmn_sync_vault

将本地记忆对象同步到 ExergyNet LNES-17 知识库。需要 EXERGYNET_API_KEY。使用 EXERGYNET_NETWORK 指定目标为主网或测试网。

参数	类型	必填	描述
xlmp_root	string	是	要同步对象的根哈希
intent	string	否	同步意图标签（默认值：manual-sync）

返回：xlmp_root、bytes_committed、status 和解析后的知识库 URL。

---

环境变量

变量	默认值	描述
AUTO_SYNC_VAULT	false	设置为 true，即可将每次 vmn_ingest 自动同步到 ExergyNet
EXERGYNET_API_KEY	—	用于访问 ExergyNet 知识库的 API 密钥（sk-exergy-*）
EXERGYNET_NETWORK	testnet	目标网络：mainnet → portal.exergynet.org，testnet → dt.portal.exergynet.org
EXERGYNET_VAULT_URL	(resolved from EXERGYNET_NETWORK)	完全覆盖知识库基础 URL

---

知识库布局

~/.vanguard/
├── local_vault/
│   └── <sha256>.txt              # authoritative object files (never modified after write)
├── catalog/
│   └── <sha256>.json             # per-object metadata (O(1) reads)
├── segments/
│   └── <sha256>.json             # segment records with term frequencies
├── cursors/
│   └── <session_id>.json         # cursor state for vmn_ingest_file
└── index/
    └── v2/
        ├── index_manifest.json   # version + state header
        ├── corpus_stats.json     # BM25 corpus statistics
        └── postings/
            └── <2-hex>.json      # 256 sharded posting buckets

---

检索原理

1. 规范化 — Unicode NFC → 短语别名替换 → 分词 → 后缀词干提取 → 停用词过滤 → 词元别名扩展
2. 词干提取器 — 13 条后缀剥离规则：tions→ (5)、ions→ (4)、tion→ (4)、ings→ (4)、ing→ (3)、ers→ (3)、ies→ (3)、ic→ (2)、er→ (2)、ed→ (2)、es→ (2)、s→ (1)、y→ (1)。规则按长度从长到短应用；medications 和 medication 都会归约为相同的词根。
3. 别名扩展 — 临床、技术和法律同义词簇（smok↔tobacco↔cigarett、physician↔doctor、hypertens↔bp 等）
4. BM25 评分 — 分片式 256 桶倒排索引；每个词项最多取前 150 条倒排记录，以限制高 DF 导致的停滞
5. 回退 — 当 BM25 分数为零时比较词干化词元集合；防止部分词匹配导致误报

---

对比

	VMN	ChromaDB / Pinecone
结果确定性	同一查询始终返回相同结果	随模型版本而变化
数据位置	仅限本地磁盘	需要上传到云端
单次查询成本	$0	API 费用
设置时间	60 秒	账户 + 密钥 + SDK
语义漂移	无	模型更新时会失效
支持离线运行	是	否

---

许可证

MIT — 永久免费，无遥测，无使用限制。

由 ExergyNet 构建。