Conventions MCP

conventions-mcp

用于保存持久编码规范和长期指令的个人记忆库——一个存储库，适用于任何兼容 MCP 的 AI 客户端，并在每个项目中可用。它保存诸如“此语言始终使用 2 个空格缩进”“绝不对 main 执行强制推送”、长期有效的纠正，以及应延续到未来会话、无需每次重新解释的长期工作流偏好。它有意不记录单项工作的历史，也不用于存放特定任务的指令、临时决定、当前状态或一次性命令。

为什么选择它

记忆 MCP 服务并不少见——已有多个成熟方案（mem0/OpenMemory、Zep/Graphiti、官方参考记忆服务，以及许多较小的项目）都能实现“跨会话记住信息”。本项目的不同之处在于：

• 分类体系精简，而非通用笔记库。 每条记录都必须是适用于未来工作的持久规则，并归入五种专用类型之一——规范、指令、纠正、偏好、其他——另有项目字段和主题标签。特定任务的流程和工作历史不予收录，让检索保持精准，避免噪声。
• 确定性检索，而非尽力而为。 大多数记忆 MCP 服务完全依赖调用模型自行发现某个工具描述与当前情境相关，并决定是否调用——这会导致问题悄无声息地发生，且表现不稳定。Codex 和 Claude Code 钩子会强制 Agent 调用 list_rules：SessionStart 提供指令，而 PreToolUse 会在该调用完成前拒绝所有其他工具。
• 默认透明，而非悄无声息。 每次记录和更新后，都会立即回显原样保存的内容，并说明它是全局规则还是项目范围规则。因此，听错或分类错误的规则会立刻显现并得到纠正，而不是等到三次会话之后才通过搜索发现。
• 运行时完全本地化。 使用 SQLite 和本地嵌入，无托管服务、无按 Token 计费，也无需 API 密钥。嵌入模型会在首次使用时下载一次（也可通过 conventions-mcp warmup 显式下载），之后就在本地运行。分类（类型/主题/项目范围）由调用 Agent 在记录时完成，并由工具描述提供指引——它已经掌握这条想法所出自的完整对话，获得的上下文比单独的提取模型仅凭一段内容字符串能得到的丰富得多。
• 项目范围明确，无模糊匹配。 规则可以是全局规则（默认），也可以关联到某个特定代码库。Stdio 客户端会根据工作目录推断项目；HTTP 客户端则提供 MCP 根目录或 X-Conventions-Project 标头。项目标识符绝不会由 LLM 根据自由文本猜测。

如果你需要的是通用型“什么都记住”的存储库，或者你不使用 Claude Code，也不需要由钩子驱动的确定性，那么上面更通用的方案可能更适合你。本项目面向的是明确需要聚焦编码规范、保持准确，并且不必相信模型会记得主动检查的用户。

它适合存储的内容

调用 Agent 会根据 capture_thought 的工具描述（src/server.js），将每条记录归为以下五种类型之一：

类型	含义
convention	具体的编码风格／模式规则（例如：“始终使用 2 个空格缩进”）
instruction	关于工作方式／行为的长期指令（例如：“绝不对 main 执行强制推送”）
correction	对未来行为的长期纠正
preference	长期有效但不那么严格的偏好，而非硬性规则
other	不属于上述四种具体类型的其他持久性、面向未来的规则

每条记录还会添加 1–3 个主题标签，用于筛选。它的用途刻意限定在较窄的范围内——并非通用的笔记存储工具——但分类体系并没有硬编码在逻辑中，只体现在 src/server.js 中的工具描述措辞和 zod schema 里。调整 convention 与 instruction 的判定标准，或添加新类型，只需修改描述文本，无需重构代码。有一点需要注意：这五种类型名称也会在 list_thoughts 的 type 筛选器枚举中引用（src/server.js）——如果重命名或添加类型，也要更新该枚举，否则新类型会被拒绝为筛选值。所有内容都存储在 JSON blob 列中，因此无需进行 schema 迁移。

每条记录都有一个项目字段：null 表示适用于所有项目；否则，该字段是以 path: 为前缀的规范化绝对路径。路径分隔符会保留，因此 /work/a-b 和 /work/a/b 会标识不同的项目。调用 Agent 只需判断某条规则是否限定于特定项目。现有的连字符形式 ID 需要按照 upgrading.md 中的说明，先备份再显式迁移项目。

• 存储： SQLite（better-sqlite3）+ sqlite-vec，用于原生向量搜索；FTS5 用于关键词搜索；两者通过互反排名融合进行组合。单个文件，无需服务端或守护进程。
• 嵌入： 在本地通过 Xenova/bge-small-en-v1.5 实现（384 维，量化后约 130MB）。模型只下载一次到 ~/.conventions-mcp/models，按需加载，且无需 GPU。
• 分类： 在记录时由调用 Agent（Claude Code 或任何 MCP 客户端）根据工具描述完成——无需网络调用、外部模型或 API 密钥。
• 传输： 默认通过 stdio 使用 MCP，也可选择仅限 localhost 的 Streamable HTTP 模式，将其作为持久服务运行。
• 主动检索： Codex 和 Claude Code 钩子（见下文）会在每个上下文边界加载或强制执行长期规则——无需维护项目指令文件，也不依赖模型是否恰好注意到工具描述与当前任务相关。
• 范围限定检索： list_rules 和语义搜索会返回全局规则以及当前项目的规则；其他代码库的项目专属规则不会出现在常规检索结果中。list_thoughts 仍是用于管理所有记录的显式视图。

安装

使用编码 Agent 安装？ 将此仓库交给它，并要求它 按照规范的安装与客户端集成操作指南操作。 操作指南要求发现路径、合并配置而非覆盖配置、 执行真实的捕获／列表／删除验收测试，并清理测试记录。

有两种获取方式：Git 检出（如果你想阅读／修改源代码）或 npm 包（如果你只想运行它）。

Git 检出：

npm install
npm run init-db        # creates data/memory.db

npm 包：

npm install -g conventions-mcp --onnxruntime-node-install-cuda=skip
conventions-mcp init-db    # creates ~/.conventions-mcp/memory.db
conventions-mcp warmup     # downloads and verifies the embedding model

无需 API 密钥或外部服务。可选的数据库、模型缓存、 传输方式和超时设置列于 .env.example 中。

使用 conventions-mcp --help 查看已安装的命令， 并使用 conventions-mcp --version 确认 PATH 中的版本。有关本地信任模型和私密报告 说明，请参阅 SECURITY.md。 运行 conventions-mcp doctor，即可获取运行时、数据库、权限、 向量扩展和模型缓存就绪情况报告，且不会下载任何内容。 没有格式元数据的旧版数据库需要先备份，再运行 conventions-mcp migrate-storage <absolute-backup-path> 命令；对于声明为 不兼容的格式，系统会直接拒绝，而不会猜测。

持久化本地服务

当 MCP 客户端应连接到一个由启动管理的服务器，而不是每次会话都启动一个 stdio 子进程时，请使用 Streamable HTTP：

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=47123 conventions-mcp

在操作系统的服务管理器下运行该命令，并将 MCP 客户端配置为使用 http://127.0.0.1:47123/mcp。有关完整的 systemd、 launchd 和 Windows 设置及验证说明，请参阅 docs/shared-service.md。绑定到 localhost 时，服务器会拒绝 非本地主机的 Host 标头。MCP_HTTP_HOST 默认为 127.0.0.1，MCP_HTTP_PORT 默认为 47123。 该服务提供 GET /healthz，用于环回就绪检查，并通过 MCP_HTTP_MAX_SESSIONS（默认值：100）和 MCP_HTTP_SESSION_IDLE_MS（默认值：30 分钟）限制保留的会话数量。

支持 MCP roots 的 HTTP 客户端无需额外的项目配置。 对于不支持的客户端，请在项目本地 MCP 配置中将 X-Conventions-Project 设为项目的绝对路径。 如果 HTTP 会话未提供这两个值中的任意一个，则只会收到全局规则， 且无法创建项目范围的捕获记录，从而防止一个项目的规则泄漏到另一个项目。

Codex 可以动态地向共享 HTTP 服务器提供当前工作区：

[mcp_servers.conventions]
url = "http://127.0.0.1:47123/mcp"
http_headers_helper = "conventions-mcp codex-project-header"

Codex 会在当前工作区中运行该辅助程序。服务器会规范化该绝对路径， 并在其前面加上 path:，作为项目标识符。

注册到 Claude Code

请在用户范围内注册，以便它在每个项目中都可用，而不仅限于某个仓库——请使用 claude mcp add CLI，而不要手动编辑配置文件：

# Git checkout — an absolute path, since Claude Code may spawn this from an
# arbitrary working directory:
claude mcp add --scope user conventions -- node /absolute/path/to/conventions-mcp/src/server.js

# npm package — already on PATH:
claude mcp add --scope user conventions -- conventions-mcp

无论哪种方式，都会写入 ~/.claude.json 的 mcpServers 键；CLI 实际读取的正是该位置。直接放在 ~/.claude/settings.json 中的 mcpServers 条目会被静默忽略。使用 claude mcp list 验证。要让新注册的服务器生效，需要启动一个新的 Claude Code 会话。

Codex 常驻规则钩子

hooks/hooks.json 包含用户级 Codex SessionStart 和 PreToolUse 钩子。第一个会告知 Agent 调用 list_rules；第二个会在该调用发生前拒绝所有其他工具。每次启动、恢复、/clear 和压缩时，门禁都会重新启用，即使恢复的对话中已经加载过规则。规则本身不会放在钩子输出中，因此规则集再大，也不会在 Agent 从 MCP 工具获取规则前被截断。

将其安装为 ~/.codex/hooks.json。如果该文件中已有钩子，请合并本文件的 SessionStart 和 PreToolUse 条目，而不是替换现有配置。钩子要求 MCP 服务注册名为 conventions，与上方的设置命令一致，并且已安装的 conventions-mcp 命令位于 PATH 中。在 Codex 中打开一次 /hooks，查看并信任新安装的钩子；必须开启新会话，启动钩子才能触发。

Claude Code 常驻规则钩子

检出代码的用户也可以为 Codex 钩子调用 Node 可执行文件和 bin/cli.js 的绝对路径； 请参阅安装说明。无需全局安装 npm 包。尝试调用 list_rules 后，钩子门禁就会解除，即使调用失败也一样；调用的 Agent 仍必须处理失败并获取规则。

~/.claude/settings.json 中的三个钩子会强制要求在使用工具前调用 list_rules——前两个负责提醒，第三个才会实际强制执行：

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/session-rules.js", "timeout": 15 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/prompt-reminder.js", "timeout": 5 }] }
    ],
    "PreToolUse": [
      { "matcher": "*", "hooks": [{ "type": "command", "command": "node /absolute/path/to/conventions-mcp/bin/pre-tool-check.js", "timeout": 5 }] }
    ]
  }
}

• bin/session-rules.js 在会话开始时触发，并发出简短提醒，要求先调用 list_rules——而不是直接将规则内容嵌入钩子输出中，因为这种方式无法扩展（存储的规则集一旦足够大，就会在传给模型前被静默截断，只剩下简短预览）。每次调用都会重新启用强制门禁，包括恢复、压缩和 /clear，因此先前的加载无法绕过新指令。
• bin/prompt-reminder.js 在每轮触发，并发出静态提醒，要求遵循已加载的约定；只记录确实持久、适用于未来会话或重复工作的规则。它明确排除特定于任务的指示、临时选择、当前状态、事件历史、单次任务命令，以及某项任务的具体完成记录。
• bin/pre-tool-check.js 在每次工具调用前触发；在本次会话运行 list_rules 之前，它会直接拒绝该调用——前两个钩子仅提供建议（只发出提醒），因此这一层才是真正强制执行要求的部分。它在每个会话中强制执行一次，而不是每轮执行一次。

这三个钩子都不会直接操作数据库。list_rules 会根据 stdio 工作目录、MCP 根目录或 HTTP 项目的 X-Conventions-Project 标头确定当前项目。

**npm 包：**脚本位于全局安装目录中，而不是已知的克隆路径下——先用 npm root -g 找到该目录，然后以同样的方式将钩子指向 $(npm root -g)/conventions-mcp/bin/session-rules.js。

**Windows：**将 command 指向 .cmd 包装脚本，而不是直接指向 .js 文件（无需添加 node 前缀——批处理文件会调用它）——git 检出版本使用 bin\session-rules.cmd / bin\prompt-reminder.cmd / bin\pre-tool-check.cmd；npm 包则使用 npm root -g 下的对应路径。

工具

工具	描述
capture_thought	保存一条约定、指令、更正或偏好。在本地生成嵌入；分类由调用方 Agent 提供。
update_thought	原位更正／完善现有想法——保留相同 ID，根据新内容重新生成嵌入并重新标记。
search_thoughts	混合语义搜索与关键词搜索。
list_thoughts	列出所有记录，可按类型筛选。
list_rules	在一次确定性调用中列出所有全局规则和当前项目规则——不使用嵌入，不进行排序，按 ID 排列。钩子在底层使用的工具。
thought_stats	总数、类型细分、热门主题和各项目的计数。
delete_thought	根据 ID 永久删除一条想法。

备注

• 升级时请遵循 docs/upgrading.md，以先备份，并执行旧版向量迁移、受保护的还原和回滚。

• 如果一条消息提出多条不同的规则，capture_thought 会针对每条规则分别调用一次，并逐条传递——不会将它们合并为一条记录或概括在一起。

• 数据库位于 Git 工作区中的 data/memory.db，或 npm 包中的 ~/.conventions-mcp/memory.db（可通过 MEMORY_DB_PATH 覆盖任一路径）。该文件已加入 Git 忽略列表，并以私有权限创建。使用 conventions-mcp backup <absolute-destination> 创建可安全用于运行中的数据库且经过完整性检查的备份。 docs/shared-service.md 介绍了定时设置。

• 嵌入模型和维度在 src/storage-format.js 中声明。 更换模型需要显式执行存储迁移，以便为现有规则重新生成嵌入；仅更改常量会导致现有存储不兼容。