Mneme Decision MCP

Mneme HQ

Mneme 是一个开放的决策与控制层，服务于 Agent 化软件开发。

它将持久的工程决策转化为 Agent 上下文、确定性执行机制和可检查的执行结果，覆盖 AI 编码 Agent、代码仓库和 CI 工作流。架构是目前首个支持的决策领域：Mneme 通过将架构决策和 ADR 转化为确定性护栏，防止架构漂移，这些护栏覆盖编码 Agent、代码仓库变更、生成的规则和 CI 门禁。

你的架构实际上在哪里得到执行？ 运行架构审计，查看哪些决策受到保护、哪些可以转化为确定性护栏，以及哪些仍依赖有人记住规则。立即试用 →

Mneme 是防止这种漂移机制背后的决策层。随着 AI 编码系统提出并修改代码，它会让记录下来的工程决策持续生效，而不是让 ADR 沦为被动文档。

_{实线所示的功能目前已发布；虚线所示的功能尚在计划中。各集成的支持级别详见：集成矩阵。}

**当前阶段：**第 1 层验证。检索、执行和基准测试的语义由已接受的架构和冻结记录约束。更改核心行为前，请参阅当前阶段。

Mneme 的功能

Mneme 将架构指导与确定性执行分开：

• 记录架构决策，形成结构化、可审计的决策库。
• 检索相关决策，在 Agent 或模型需要架构指导时提供支持。
• 在明确的适用性语义下，确定性地执行受治理的规则。
• 在每种编码工作流提供的最早可靠边界集成。
• 审计可绕过的变更路径，适用于技术上无法在变更前阻止操作的情况。
• 在 CI 中运行，作为接受不兼容变更前的最终确定性门禁。

相同输入和受治理的决策状态会产生相同的执行结果。Mneme 的核心允许／警告／失败判定不依赖 LLM 评判器。

Mneme 并非通用向量存储、对话记忆系统、自主编码 Agent 或部署可观测性平台。

安装

需要 Python 3.11+。

pip install mneme-hq

验证 CLI：

mneme --help

用于代码仓库开发：

git clone https://github.com/MnemeHQ/mneme.git
cd mneme
pip install -e ".[dev]"

Decision MCP

Mneme 通过本地 MCP 服务公开 Decision Index，让支持 MCP 的客户端能够提出候选架构决策并查询决策状态，而无需获得更改该状态的权限。

安装可选的 MCP 依赖：

pip install "mneme-hq[mcp]"

启动本地 stdio 服务。默认情况下，规范读取内容来自持久化的 .mneme/project_memory.json 中的 Decision Index；提案存储仍保持独立。

mneme decision-mcp

使用 --memory 选择其他项目记忆文件。该文件必须包含有效且权威的 decision_index 部分；MCP 会采取失败关闭策略，不会从兼容性 decisions[] 快照重建权限信息。

mneme decision-mcp --memory path/to/project_memory.json

由 mneme init 或 mneme setup 创建的记忆已包含空的 decision_index 部分，无需迁移。如果旧文件尚无 decision_index 部分，MCP 会停止并提示你进行迁移。请先预览迁移。预览不会写入任何内容，并会列出可见影响：非 active 决策会离开 Layer 1，旧版 rule/anti_pattern 项目会迁移一次。

mneme decision-index migrate --memory path/to/project_memory.json

然后准确应用该迁移：

mneme decision-index migrate --memory path/to/project_memory.json --apply

迁移要么无损完成，要么拒绝执行。没有强制或修复模式。若记忆包含规范索引无法表示的旧版决策元数据（例如从 EventCatalog 导入的决策），则仍保留在无此部分的路径上，不会迁移。

--adr-dir 现在仅作为可选验证输入。Mneme 仍会在启动前验证并解析该语料库的优先级，但 ADR 不会成为第二个 MCP 权威来源。

mneme decision-mcp --memory path/to/project_memory.json --adr-dir path/to/adrs

MCP 接口有意固定为六个工具：

• decision.propose
• decision.propose_batch
• decision.get
• decision.search
• decision.applicable_to
• decision.trace

提案工具只会创建非权威提案。读取工具会查询提案和规范决策状态。MCP 有意不提供接受、拒绝、激活、取代、例外、绕过或可信证据权限。

人类权限仍通过 mneme decision proposals | show | accept | reject 明确行使。接受提案会将其转化为规范决策；这不会激活保护措施，也不会运行 Architecture Audit。

有关权限边界和发布约定，请参阅 ADR-027 和 v0.9.0 发布说明。

Architecture Audit

了解你的架构实际受到哪些保护，以及哪些方面仍依赖人们记住规则。

Mneme 会审计你的代码库，并展示哪些架构决策属于以下类别：

• 已保护 — 已通过机制强制执行
• Mneme-ready — 可转化为确定性护栏
• 需要建模 — 很重要，但尚不适合自动化
• 指导建议 — 有用的背景信息，但不应强制执行

运行审计：

mneme audit --memory .mneme/project_memory.json --repo-root .

对于 Mneme-ready 决策，请先验证拟议的保护措施，再启用它：

mneme protect validate <decision-id> --memory .mneme/project_memory.json

然后明确激活它：

mneme protect activate <decision-id> --memory .mneme/project_memory.json

只有在能够验证实际强制措施已到位后，Mneme 才会将决策报告为已保护。完整的激活约定见 Protection Activation。

试用 Architecture Audit →

60 秒强制执行示例

初始化项目本地决策语料：

mneme init

记录一项架构决策：

mneme add_decision \
  --memory .mneme/project_memory.json \
  --id config-format \
  --decision "Use JSON for configuration files" \
  --scope config \
  --constraint "Use JSON only" \
  --anti-pattern "Do not use YAML"

创建一个违反该决策的拟议输入：

python -c "import pathlib; pathlib.Path('prompt.txt').write_text('Set up a new YAML config file', encoding='utf-8')"

运行确定性检查：

mneme check \
  --memory .mneme/project_memory.json \
  --input prompt.txt \
  --query configuration

在严格模式下，被禁止的 YAML 提案会返回 FAIL 判定和退出代码 2。符合要求的 JSON 提案会返回 PASS 和退出代码 0。

CLI 是通用的强制执行界面。Agent 集成会将其原生事件转换为相同的 Mneme 决策和强制执行模型。

若要非权威地预览哪些规范决策适用于调用方声明的上下文标签，可在 mneme check 中选择性地重复添加 --applicability-preview <label>：

mneme check --memory .mneme/project_memory.json --input prompt.txt --query configuration --applicability-preview platform:windows

预览内容只会输出到 stderr，且独立于常规检查结果。它不会信任提供的标签、排除决策、改变强制执行行为，也不会更改 stdout、JSON mneme.check/v1、钩子行为或退出代码。如果记忆文件没有章节，或预览计算出错，则会在 stderr 上报告 PREVIEW UNAVAILABLE；它不会迁移记忆文件，也不会削弱强制执行。此预览不是安全控制措施。

设置模式（不强制执行）

mneme setup 会在仓库中初始化 Mneme，而不改变团队的工作方式：它会创建或检测项目记忆文件、检测受支持的 Agent 环境，并报告保护就绪情况——以上操作都不会启用任何阻止性强制执行。设置不会将警告／观察行为转变为阻止性行为；启用预防性强制执行始终是一个单独且明确的决定。

mneme setup

也可以选择记录不透明的 Architecture Audit 引用，以便将设置归因到已保存的 Audit 基线：

mneme setup --audit-ref <reference>

设置具有幂等性：在现有 Mneme 项目上重新运行，不会改动有效配置。

工作原理

Architectural decisions / ADRs
            |
            v
   structured decision corpus
            |
      +-----+--------------------+
      |                          |
      v                          v
relevant guidance       deterministic enforcement
   retrieval             + applicability checks
      |                          |
      +------------+-------------+
                   |
                   v
       workflow-specific boundary
                   |
      +------------+-------------+
      |            |             |
 pre-change     post-change      CI
   hooks          audit          gate

Mneme 会在工作流所提供的最早可靠边界实施治理：

1. 生成前：可将架构上下文注入模型调用时。
2. 受支持的文件变更前：Agent 提供阻止性工具调用前钩子时。
3. 可绕过的变更后：无法在执行前安全检查 Shell／脚本写入时，通过有界工作树审计进行治理。
4. 合并前：通过基于 CLI 的 CI 门禁进行治理。

这些边界相辅相成。集成只会声明已针对相应运行环境实现并验证的界面。

检索不等于强制执行

决策检索要回答的问题是：哪些架构决策可为这项任务提供有用指引？

强制执行要回答的问题是：拟议变更是否违反了适用于此处的受治理规则？

这两者有意分开。请参阅 ADR-017、ADR-019 和 ADR-020。

支持的界面

权威支持矩阵见 docs/integrations/README.md。下方标签代表不同的证据级别，不可互换使用，也不是营销用语。

支持级别	界面
原生集成	Claude Code
原生集成	Claude Agent SDK
原生集成	Google Antigravity
原生集成	Codex CLI
原生集成	Kiro CLI 3.0 / v3
已验证兼容性	Paperclip — CLI 和 ACP 传输，无需适配器
规则导出	Cursor
基于 CLI 的 CI 门禁	GitHub Actions、GitLab CI
实验性	OpenCode
计划中	Deep Agents 中间件 POC

每项集成都记录了实际的阻止边界、绕过路径、降级行为和验证证据。请先查看集成矩阵，不要根据其他运行环境作出假设。

ADR 和项目记忆

Mneme 可以将架构决策编译为结构化治理记录，而不是将 ADR 视为被动的散文。

.mneme/project_memory.json 是仓库治理的唯一事实来源。ADR 导入路径会在可用时保留明确的来源信息，以便一致地检查和执行类型化规则。

参见：

• 架构概览：ASCII + C4 + ADR 映射
• ADR 导入
• 已接受的 ADR
• 当前架构阶段

架构保障原则

以下三项原则指导当前机制：

• 确定性 > 取巧。 执行行为必须可复现。
• 可审计 > 自主性。 判定应可追溯到产生它的决策、规则、适用性状态和证据。
• 预防优先于审查。 如果存在可靠的变更前边界，就使用它；如果不存在，则明确说明限制并在之后审计，而不是假装变更路径已被阻断。

当前第 1 层的范围、冻结的行为面、已接受的修订、实验性工作以及延期的第 2 层工作，均维护在 docs/architecture/current-phase.md 中。

如果链接的 ADR 或架构文档有更具体的说明，请勿仅根据此 README 推断架构。

基准测试与验证

Mneme 的基准测试是检索和执行行为的回归与完整性检测工具，并非通用的模型质量基准测试。

基准测试将检索与执行评分分开，以防变更在悄然改善一个行为面的同时导致另一个行为面退化。

参见：

• 基准测试方法
• 公开基准测试
• 当前阶段与冻结状态
• 发行说明

演示

• 受治理的 Python Agent
• ADR 导入
• 架构漂移
• GitHub Actions 治理
• 依赖项策略

更多示例：mnemehq.com/demo

贡献

在更改检索、执行、适用性、冲突处理或基准测试语义之前，请先阅读负责相应行为面的架构文档和 ADR。

• 贡献指南
• 当前架构阶段
• 安全策略
• 变更日志

核心行为的变更可能需要遵循仓库的章程修订流程。文档、工具、集成和示例不会自动授权更改已冻结的行为。

许可证

MIT。参见 LICENSE。