Verified Repo Memory

Verified Repo Memory MCP v0.1.2

带引用、即时验证和 TTL 的防过时仓库记忆（按仓库隔离）。

一个为 AI 编码 Agent 提供“安全记忆”的 MCP 服务。记忆按仓库隔离，以代码引用为依据，并经过即时验证，因此底层代码发生变化时，Agent 也不会收到过时信息。

快速开始

通过 npx 运行：

npx -y @cognitivemyriad/vrm-local --repo /path/to/repo

（或者从源代码运行：npm ci && npm run build && node build/index.js --repo /path/to/repo）

工具

• vrm_store：存储带文件引用的新记忆。
• vrm_search：按关键词搜索候选记忆。
• vrm_retrieve：对候选记忆进行即时验证，并仅返回有效记忆。（Agent 的主要工具）
• vrm_list：按状态（有效、过时、缺失）列出记忆。
• vrm_forget：手动删除记忆。

输入/输出示例

存储： 输入：

{
  "subject": "API version sync",
  "fact": "When changing API version, update client/server/docs together.",
  "citations": [{ "path": "src/api.ts", "startLine": 10, "endLine": 15 }]
}

输出：

{
  "stored": true,
  "memoryId": "uuid-...",
  "expiresAt": "2026-03-21T00:00:00Z"
}

检索： 输入：

{ "query": "API version" }

输出：

{
  "query": "API version",
  "valid": [ ... ],
  "stats": { "verified": 1, "validCount": 1 }
}

工作原理

graph TD
    A[Agent] -->|Store Fact + Citation| B(Verified Repo Memory)
    B --> C{Save to Disk}
    C -->|Hash Code Snippet| D[(memories.json)]
    
    A -->|Retrieve Fact| B
    B --> E{JIT Verification}
    E -->|Check File Hash| F{Unchanged or Relocated?}
    F -->|Yes| G[Return VALID Memory]
    F -->|No| H[Return STALE/MISSING]

1. **引用：**每条事实都关联到文件路径和行范围。系统会对精确的代码片段进行哈希处理并保存。
2. **即时验证：**在通过 vrm_retrieve 向 Agent 返回记忆之前，服务会检查实际文件。如果代码片段的位置发生变动，系统会重新定位引用。如果代码片段已更改或删除，该记忆会被标记为 STALE/MISSING，并从结果中排除。
3. **TTL（生存时间）：**记忆会自动过期（默认 28 天），除非它们被成功检索并使用，这样会延长其有效期。

数据位置

数据严格按仓库隔离，并保存在： <repoRoot>/.verified-repo-memory

其中包括 memories.json 和一个指纹/元数据文件，以防止意外的跨仓库污染。请将此目录添加到 .gitignore。

安全性

• **不传输网络数据：**这是一个仅在本地运行的 stdio 服务，不会发起 HTTP 调用。
• **路径安全：**禁止通过任何路径遍历（../）访问仓库根目录之外的内容，也禁止访问 .git/ 或 .verified-repo-memory/。
• **不污染标准输出：**日志严格仅写入 stderr。
• **机密信息扫描：**内置启发式机密信息扫描，可拒绝看起来像 API 密钥/私钥的记忆（可通过 --no-secret-scan 禁用）。

与 Claude 搭配使用

Claude Desktop

要将此服务添加到 Claude Desktop 应用，请编辑配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "verified-repo-memory": {
      "command": "npx",
      "args": [
        "-y",
        "@cognitivemyriad/vrm-local",
        "--repo",
        "/absolute/path/to/your/repo"
      ]
    }
  }
}

Claude Code

要通过 stdio 传输方式将此服务添加到 Claude Code：

claude mcp add mcp-verified-repo-memory --transport stdio -- npx -y @cognitivemyriad/vrm-local

Windows 用户须知： 你可能需要在命令前加上 cmd /c：

claude mcp add mcp-verified-repo-memory --transport stdio -- cmd /c npx -y @cognitivemyriad/vrm-local

---

发布指南

本节介绍如何将软件包发布到 NPM，并将其注册到 Anthropic MCP Registry，以便公开提供。

第 1 步：发布到 NPM

NPM（Node Package Manager）是软件包分发平台。在此发布后，任何人都可以通过一条命令安装你的工具。

前提条件

• 一个 NPM 账户（免费）
• 已在 NPM 账户上启用双重身份验证（2FA）
• 已在你的计算机上安装 Node.js

流程

1. 在终端中登录 NPM：

npm login

系统会打开一个浏览器窗口。使用你的 NPM 账号登录。出现提示时，输入身份验证器应用中的 2FA 验证码。

2. 发布软件包：

npm publish --access public

此命令会执行以下操作：

• 将 TypeScript 编译为 JavaScript（npm run build）
• 创建包含编译后文件的 .tgz 压缩包
• 将压缩包上传到 https://registry.npmjs.org/

3. 验证发布：

在浏览器中访问 https://www.npmjs.com/package/@cognitivemyriad/vrm-local。你应该会看到软件包页面。

注意： 如果需要重新发布，必须先递增 package.json 和 server.json 中的版本号（npm version patch）。NPM 不允许覆盖已有版本。

---

第 2 步：在 Anthropic MCP 注册表中注册

MCP 注册表是 Anthropic 官方的 MCP 服务目录。在此注册后，Claude Desktop、Claude Code 和其他 MCP 客户端便可发现并安装你的服务。

重要： 必须先发布 NPM 软件包（第 1 步）。MCP 注册表会先验证 NPM 软件包是否存在，然后才接受注册。

前提条件

• 一个 GitHub 账号（仅用于身份验证）
• mcp-publisher CLI 工具

安装 mcp-publisher

# macOS (Homebrew)
brew install nicholasgriffintn/tap/mcp-publisher

# Or via npx (no install required)
npx @anthropic-ai/mcp-publisher

流程

1. 通过 GitHub 登录 MCP 注册表：

mcp-publisher login github

系统会打开一个浏览器窗口。使用你的 GitHub 账号授权该应用。

2. 发布到 MCP 注册表：

mcp-publisher publish

此命令会读取当前目录中的 server.json，并在 MCP 注册表中注册该服务。注册表会：

• 验证 server.json 架构
• 检查 NPM 软件包是否存在且可访问
• 注册服务元数据（名称、描述、版本、环境变量）

3. 验证注册：

访问 https://registry.modelcontextprotocol.io 并搜索你的服务名称。

注意： 版本发布到 MCP 注册表后即为不可变，无法更改。如需发布更新，请递增 package.json 和 server.json 中的版本号，先发布到 NPM，然后再次运行 mcp-publisher publish。

---

版本管理

发布新版本时，务必更新以下三个位置的版本号：

# 1. Bump version in package.json
npm version patch  # 0.1.2 → 0.1.3

# 2. Update server.json (both top-level and packages[].version)
# Edit server.json manually to match the new version

# 3. Publish
npm publish --access public
mcp-publisher publish

文件	字段	必须一致
package.json	version	✅
server.json	version（顶层）	✅
server.json	packages[0].version	✅