关于 MemoryGuard
MemoryGuard 是面向编码 Agent 的本地优先 MCP 记忆后端，用于管理共享项目上下文。它通过分类、证据、范围规则和可逆变更治理写入，并将原始对话历史单独保存。
主要功能
- 01整理并去重记忆写入
- 02范围规则与受众匹配
- 03证据记录与替代链
- 04隔离敏感内容
- 05回滚与冲突解决
- 06本地构建 CodeGraph
适用场景
- 01维护多个编码 Agent 的共享记忆
- 02审查受治理的项目上下文变更
- 03避免敏感内容进入活动记忆
MCP 相关
它提供本地 stdio MCP 服务，让编码 Agent 访问受治理的记忆，并提供 CLI、GUI 和 Hook 集成。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
工具
本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。
详细介绍
MemoryGuard
为编码 Agent 提供受治理的共享记忆。
本地优先的 MCP 记忆，支持自动整理、分级规则、证据记录和回滚。
让 Agent 能够写入内容，而不让共享记忆变成未经审核的杂乱堆积。 MemoryGuard 会整理每次写入，保留变更依据，并 确保治理决策可撤销。
无需账户。无需远程服务。无远程遥测。可选的本地使用遥测 只会在本地存储有限且保护隐私的汇总数据。
快速开始 · 升级 · 知识库 · 架构 · 支持的宿主 · 隐私与安全
合成的受治理投影：信号在记忆类别中流动，而原始对话文本不会进入图中。
v0.7.15 新功能
- 自动构建 CodeGraph： 受信任的引导流程会在后台进程中启动项目的首次构建。默认设置和各项目的开关都会持久保存；关闭自动化不会删除图。受支持的文件写入事件会触发增量刷新。
- 清晰的图导航： 可在文件概览和符号之间切换，按文件筛选，查看相邻关系，并使用缩放控件。
- 有界临时存储： 常规图查询会直接读取 SQLite，而不会保留整个数据库的副本。验证和安装所用的临时文件会存放在所属项目或部署的缓存中，并在操作结束后清理。
请参阅 v0.7.15 发行说明和 CodeGraph 自动化详情。升级并修复提供程序集成后，请重新连接或 重启宿主。
早期治理改进
v0.7.13 加强了强制规则的替换与恢复，改进了受众感知身份处理，并改进了冲突解决：
- 安全替换强制规则： 替换操作会根据受众匹配、规范规则、去重、敏感度检查和发布预算验证最终的强制规则包。等效的未锁定前置规则会在同一事务中退役；验证失败则会回滚整个更新。请参阅替换与恢复详情。
- 原生 Agent／群组受众匹配： 匹配与去重不再仅因提供商或运行时角色不同，就将相同的原生受众拆分。不同的 Agent 身份仍保持区分，项目范围的受众也保留其项目边界。修复提供商时，会使用已验证的目标提供商身份。
- 易读、原子化的冲突解决： 冲突视图会保留易读的对等方信息；解决冲突时会保持对等方分组完整，并以原子方式应用所选更改。存在歧义的冲突仍保持未解决状态。
- Cursor Hook 保护： Cursor MemoryGuard Hooks 现在使用 30 秒超时，原为 15 秒，并设置了
failClosed: true。
v0.7.14 仅修正了 GitHub 仓库重命名后的发布元数据；不会改变运行时行为。请参阅 v0.7.14 发布说明。
请参阅 v0.7.13 发布说明和 发布历史。
更早的版本详情请见变更日志和 GitHub 发布记录。
Token 证据与演示
使用事件会区分 measured_cached_input 和
measured_cache_write_input。measured_cache_coverage.cache_read 和
cache_write 会报告 complete、partial 或 unavailable；实测为零时仍记为 0，而缺失的提供商数据仍记为 None／unavailable。
基于字符数的估算会明确标记为
estimated mg_deterministic_unit，绝不会冒充提供商 Token。
仅针对已获授权的本地工作区运行基准测试：
python scripts/benchmark_usage_telemetry.py --workspace . --window-days 7 --sync
请阅读基准测试指南，了解实测、估算、推导和不支持的语义。使用演示录制清单 进行脱敏演示。仓库中的合成图形作品并非产品实时画面；不能作为使用情况或节省量的证据。
v0.6.0 中的重大 V2 重构
v0.6.0 是一次生产数据平面重构，而不只是存储升级：
- 权威 V2 域： Memory、Rules、Evidence、Content、Runtime、Projection、Assets、CodeGraph、Skills 和 System 状态被分离到具有明确治理边界的 SQLite 域中。
- 明确切换：
V1_ACTIVE → V2_BUILDING → V2_READY → V2_ACTIVE采用失败关闭策略；达到 READY／ACTIVE 后，V2 绝不会静默回退到旧存储，也不会双写。 - 无损迁移： 冻结源数据的准备过程使用一致的 SQLite 在线备份，验证源端／目标端证据，重新检查实时源数据的变化，并保留 V1 数据及迁移备份以供回滚。
- 原生路由： MCP、CLI、GUI 和 Hook 界面均经过明确分类；此版本完成了 233 个界面的切换，其中 138 条路由已实现、95 条已退役，且中立／阻塞路由为零。
- 受治理的智能能力： 规则生命周期与 RuleMerge、提取／增强、外部 MCP 导入、提供商控制平面、对话历史、知识库和 GUI 治理均使用 V2 证据与决策路径。
- 运维证据： 参考审计、按域划分的 SQLite 健康状态、受保护的维护、回滚证据和安全的未绑定诊断均属于就绪状态与运维的一部分。
为什么选择 MemoryGuard
持久化记忆解决了存储问题，却没有解决治理问题。
当多个编码 Agent 向同一上下文写入内容时，记录可能会重复、过时、相互矛盾、范围过宽，或无法安全地重复使用。MemoryGuard 位于编码 Agent 与它们共享的记忆之间，让上下文保持可用。
| 缺乏治理 | 使用 MemoryGuard |
|---|---|
| 笔记不断累积，却没有权威状态 | 写入内容经过分类、去重、取代，或作为冲突呈现 |
| 一次更正会悄然销毁旧值 | 证据和取代链会保留变更内容及原因 |
| 令牌和凭据可能仍处于有效状态 | 看起来敏感的内容会从活动记忆中隔离 |
| 每次写入都需要手动批准 | Agent 照常写入；人员负责审核例外情况和结果 |
| 原始聊天日志泄漏到后续上下文中 | 对话历史仍保存在单独的、需明确读取的证据档案中 |
系统架构
%%{init: {"theme":"base","themeVariables":{"background":"#071521","fontFamily":"Arial, sans-serif","fontSize":"14px","primaryTextColor":"#EEF4F8","lineColor":"#557287","edgeLabelBackground":"#071521","clusterBkg":"#0A1A29","clusterBorder":"#27445A"},"flowchart":{"htmlLabels":true,"curve":"basis","nodeSpacing":32,"rankSpacing":48,"padding":14}}}%%
flowchart TB
Hosts["CODING-AGENT HOSTS<br/>Claude Code · Codex · Cursor · TRAE "]:::host
Gateway["LOCAL INTEGRATION<br/>MCP stdio · redirect rules · lifecycle hooks "]:::gateway
subgraph Core["GOVERNANCE CORE "]
direction LR
Identity["TRUST<br/>identity · scope "]:::core
MemoryAPI["MEMORY<br/>governed I/O "]:::active
Rules["RULES<br/>scope · assignment "]:::rule
HistoryAPI["HISTORY<br/>search · timeline "]:::history
Security["SAFETY<br/>validate · quarantine "]:::danger
Identity --> MemoryAPI
Identity --> Rules
Identity --> HistoryAPI
MemoryAPI --> Security
end
subgraph Stores["LOCAL GOVERNED STORES "]
direction LR
SharedDB[("V2 DOMAIN STORES<br/>Memory · Rules · Evidence · Content ")]:::store
HistoryDB[("HISTORY STORE<br/>isolated conversations ")]:::historyStore
AuditDB[("RECOVERY STORE<br/>versions · receipts · backups ")]:::store
end
Bootstrap["BOUNDED CONTEXT BOOTSTRAP<br/>mandatory rule pack · relevant recall "]:::bootstrap
Control["HUMAN CONTROL<br/>CLI · desktop governance console "]:::surface
Hosts --> Gateway --> Identity
MemoryAPI --> SharedDB
Rules --> SharedDB
HistoryAPI --> HistoryDB
Security --> AuditDB
SharedDB --> Bootstrap
Control --> Identity
classDef host fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.4px;
classDef gateway fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2.4px;
classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;
classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.8px;
classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;
classDef bootstrap fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;
classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.4px;
classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;
style Core fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
style Stores fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
linkStyle default stroke:#557287,stroke-width:1.4px;
快速开始
MCP Registry 元数据
此软件包以 io.github.MerakOsiris/memoryguard 的名称提供本地 stdio MCP 服务。
Registry 元数据保存在 server.json 中，上方的标记会随 PyPI 软件包 README 一同发布。发行版本通过 GitHub OIDC 发布到 PyPI 和官方 MCP Registry。请通过相应的实时公开记录，核实当前软件包版本以及 Registry 条目的启用／最新状态。
1. 安装
python -m pip install agent-memguard
对于桌面治理控制台：
python -m pip install "agent-memguard[gui]"
2. 授权当前项目
memoryguard source add .
3. 连接或修复编码 Agent
全局提供方配置会根据规范用户数据目录中的实际绑定重新构建。此命令可重复执行；成功接管全局配置后，会移除已被取代的 MemoryGuard 项目级覆盖项。
# Repair one provider
memoryguard provider repair claude
memoryguard provider repair codex
memoryguard provider repair cursor
memoryguard provider repair trae
# Repair every detected provider
memoryguard provider repair all
安装后重启宿主程序，然后验证集成：
memoryguard doctor
memoryguard mcp-status
memoryguard hooks status --provider all
启动桌面控制台：
memoryguard gui
memoryguard-gui . 仍可用于桌面快捷方式。单独运行
memoryguard gui 始终会打开规范的用户级控制目录
（Windows 上默认为 %LOCALAPPDATA%\MemoryGuard），因此从项目目录
或 C:\Windows\System32 运行都不会悄然切换数据库。
MEMORYGUARD_WORKSPACE 是显式的操作员覆盖项；显式运行
memoryguard gui <project-path> 或 memoryguard gui --workspace <project-path>
可选择特定工作区。
它不会记住先前选择的项目，也不会打开文件夹选择器。
在 Windows 上，memoryguard gui 会将原生窗口与终端分离，因此
关闭 PowerShell 不会关闭 GUI。
各提供方的设置和行为：
稳定的 Codex / Router 绑定
Codex/Router 会将 MemoryGuard 绑定到稳定的本地 Codex 程序和控制安装。账户配置文件是端点／别名，而非新的记忆所有者：切换配置文件时会自动发现或修复该配置文件，并复用已验证的 Agent 绑定和活动组。请求身份验证遵循失败关闭原则；这不会在不同机器或任意账户之间共享记录。
升级
目前，MemoryGuard 通过 Python 的软件包管理器升级：
python -m pip install --upgrade agent-memguard
memoryguard --version
memoryguard doctor
如果安装了 GUI 扩展，请在升级时保留它：
python -m pip install --upgrade "agent-memguard[gui]"
软件包没有自更新命令。软件包管理器是权威的软件包升级途径；下文的 memoryguard upgrade 是明确的工作区迁移流程，而不是软件包更新程序。
升级现有的 V1 数据主页
升级软件包，然后运行已验证的迁移。对于常规用户级数据主页，无需指定工作区、数据主页、应用或确认参数：
python -m pip install --upgrade agent-memguard
memoryguard --version # confirms installed version
memoryguard upgrade
memoryguard doctor
该命令会准备 V2，验证冻结和实时源证据，迁移 Agent/Group 控制，并仅在所有检查通过后激活，同时仅删除属于本次成功迁移的备份批次。在 V2_ACTIVE 状态下重新运行该命令不会产生额外影响。若要生成零写入报告，请使用：
memoryguard upgrade --preview
面向管理隔离安装的运维人员，仍可使用高级的显式工作区／数据主页选项。检查失败时，系统不会激活，并会保留相关证据；成功激活后不会保留多余的迁移备份。
现有 V2 之前的工作区：显式切换至 V2
v0.6.0 不会自动激活现有工作区。请先升级软件包，然后使用随软件包提供的运维 CLI：
# Read-only manifest status
memoryguard-v2 status -w .
# Build a frozen-source V2 shadow and stop at V2_READY
memoryguard-v2 prepare -w . --apply
# Activate only after the prepare result is V2_READY / ready=true
memoryguard-v2 activate -w . --confirm V2_ACTIVE
准备步骤使用一致的 SQLite 在线备份，保留 V1 和 migration-backups，并在 READY 前重新检查实时源是否发生变更。激活时会再次执行全新的变更检查，然后再更改清单。升级过程中请勿删除旧版 V1 数据或迁移备份。
知识库
桌面控制台可将选定的文件夹或文件集整理为一个受治理的本地知识库。源文件仍保留在原处；MemoryGuard 会将可搜索索引存储在其用户数据主页中，而不是将运行时数据库复制到每个源项目。知识元数据不会成为第二个源正文存储库。
| 能力 | 当前行为 |
|---|---|
| 文件／文件夹导入 | 将文件夹添加为书籍，或将选定文件添加为文档 |
| 结构 | 解析文档、保留章节／小节上下文，并创建可追溯的文本块 |
| 检索 | 全文搜索、可选嵌入，以及分层知识图谱 |
| 自然同步 | 重新导入已更改的文件；扫描不完整或失败时，不会静默移除之前已索引的内容 |
| 生命周期 | 将书籍移至知识库回收站、还原，或明确永久清除其恢复快照 |
| 记忆候选项 | 预览有证据支持的候选项，然后再将其纳入受治理的长期记忆 |
打开桌面控制台并选择 Knowledge Library。远程嵌入或基于模型的索引为可选功能，需明确授权；即使不向远程服务提供商发送源文本，本地全文检索仍可使用。后台导入、重新导入和智能重建都有持久化任务回执：重试相同请求会复用其任务，而将同一键用于不同请求则会被拒绝。若有针对不同请求的任务正在运行，系统会报告繁忙状态，而不会声称已接受该任务。
刷新 CodeGraph
首次构建 CodeGraph 时，必须明确确认并执行完整构建。构建某个范围后，每次成功的受信任文件写入都可触发该范围的增量刷新，但须通过严格的源路径和有效绑定验证。内容哈希未发生变化时不执行任何操作；已删除的文件会被停用；后续上下文会收到一条有界的 affected 回执。对于此路径，MemoryGuard 不会运行守护进程或监视程序，也不会从 Shell 或自由文本中推断路径。没有项目上下文的 MCP 调用方会先构建一个已绑定的目录源，然后传入其 codegraph_source_id，以选择该确切范围进行查询、查看状态、更新和读取图谱。
桌面控制台界面
GUI 有八个可见导航项：七个治理页面，以及单独的 Token 使用量与节省量视图：
- 治理概览
- 数据源与 Agent
- 记忆核心
- CodeGraph
- 规则与习惯
- 对话历史
- 风险信号与治理控制台
- Token 使用量与节省量（独立于七个治理页面）
Agent 列表会显示易读的程序／提供商名称；底层 ID 可在详情视图中查看。没有数据时会明确显示空状态。
写入与治理生命周期
%%{init: {"theme":"base","themeVariables":{"background":"#071521","fontFamily":"Arial, sans-serif","fontSize":"14px","primaryTextColor":"#EEF4F8","lineColor":"#557287","edgeLabelBackground":"#071521","clusterBkg":"#0A1A29","clusterBorder":"#27445A"},"flowchart":{"htmlLabels":true,"curve":"basis","nodeSpacing":30,"rankSpacing":42,"padding":14}}}%%
flowchart TD
subgraph Intake["01 · INTAKE "]
direction LR
Write(["Memory write "]):::entry
Scope["Resolve identity<br/>scope · audience "]:::core
Validate{"Authorized? "}:::decision
Reject["Reject<br/>no persistence "]:::danger
Write --> Scope --> Validate
Validate -- NO --> Reject
end
subgraph Organize["02 · ORGANIZE "]
direction TB
Secret{"Sensitive? "}:::decision
Quarantine["Quarantine<br/>outside active set "]:::danger
Compare["Classify · compare<br/>governed records "]:::active
Relation{"Relationship "}:::decision
New["NEW<br/>create active record "]:::result
Duplicate["DUPLICATE<br/>merge provenance "]:::result
Correction["CORRECTION<br/>supersede old record "]:::rule
Conflict["CONFLICT<br/>preserve both sides "]:::danger
Secret -- YES --> Quarantine
Secret -- NO --> Compare --> Relation
Relation --> New
Relation --> Duplicate
Relation --> Correction
Relation --> Conflict
end
subgraph Govern["03 · GOVERN "]
direction LR
Receipt[("Evidence event<br/>version receipt ")]:::store
Review["CLI or desktop review "]:::surface
Action["Correct · merge<br/>restore · delete "]:::rule
Snapshot["Reversible<br/>snapshot "]:::active
Receipt --> Review --> Action --> Snapshot
end
Validate -- YES --> Secret
Quarantine --> Receipt
New --> Receipt
Duplicate --> Receipt
Correction --> Receipt
Conflict --> Receipt
classDef entry fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.5px;
classDef decision fill:#0D3338,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
classDef active fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:2px;
classDef result fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;
classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
classDef danger fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:1.8px;
classDef store fill:#0B1624,stroke:#7F96A8,color:#EEF4F8,stroke-width:1.4px;
classDef surface fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2px;
style Intake fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
style Organize fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
style Govern fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
linkStyle default stroke:#557287,stroke-width:1.4px;
控制台不是审批队列。Agent 会继续运行。MemoryGuard 会记录结果，并提供所需证据，以便之后进行修正。
可治理的内容
| 信号 | 治理操作 |
|---|---|
| 重复或过时的记忆 | 检查规范记录和替代链；必要时恢复早期版本 |
| 相互冲突的记忆 | 在有意解决冲突之前，保留两者并保持可见 |
| 密钥、令牌或凭据 | 隔离记录，防止其进入活跃的共享记忆 |
| 自动整理有误 | 根据证据进行纠正、合并、锁定、恢复或回滚 |
| 多个编码 Agent | 将 Agent 绑定到同一共享组，同时保留来源身份和范围 |
| 强制规则 | 将规则分配给 Agent、项目、提供方、运行时角色或共享组 |
规则与历史记录彼此独立
MemoryGuard 有意将受治理的长期记忆和原始对话历史记录保留在不同路径中。
| 界面 | 用途 | 上下文行为 |
|---|---|---|
| 规则与习惯 | 偏好、流程、纠正内容、事实、项目和有范围限制的强制规则 | 强制规则在范围、排除项、冲突和语义去重处理后，使用独立的字符数／令牌数预算。有效数量超过 20 是健康状况警告，而非硬性限制；存储数量不设上限。敏感、损坏、单项超限和总量溢出仍会安全失败，不会静默截断。普通记录会在相关时被检索 |
| 对话历史记录 | 受所有者和共享组访问控制的本地原始证据档案 | 不会自动进入启动上下文；只能通过显式历史记录工具读取原始文本 |
| Neuron 图谱 | 对记忆、规则、项目、Agent 和会话进行导航与治理 | 历史记录节点只包含安全的元数据和摘要，不包含原始聊天内容 |
历史记录检索采用渐进方式：先显示搜索结果，再显示有界时间线，最后显示明确选定的轮次或会话。从历史记录中提取内容时，会先创建预览；不会静默写入长期记忆。
%%{init: {"theme":"base","themeVariables":{"background":"#071521","fontFamily":"Arial, sans-serif","fontSize":"14px","primaryTextColor":"#EEF4F8","lineColor":"#557287","edgeLabelBackground":"#071521","clusterBkg":"#0A1A29","clusterBorder":"#27445A"},"flowchart":{"htmlLabels":true,"curve":"basis","nodeSpacing":30,"rankSpacing":42,"padding":14}}}%%
flowchart LR
subgraph HistoryPath["CONVERSATION EVIDENCE "]
direction TB
Archive[("Raw local history ")]:::historyStore
Search["Search summaries "]:::history
Timeline["Bounded timeline "]:::history
Read["Explicit turn or session "]:::history
Preview["Evidence-backed<br/>extraction preview "]:::history
Confirm["Explicit acceptance "]:::surface
Isolation["NO AUTOMATIC<br/>BOOTSTRAP PATH "]:::barrier
Archive --> Search --> Timeline --> Read --> Preview --> Confirm
Archive -.-> Isolation
end
subgraph GovernedMemory["GOVERNED LONG-TERM MEMORY "]
direction TB
Mandatory["Scoped mandatory rules "]:::rule
Assignments["Agent · project<br/>role · group scope "]:::core
RulePack["Mandatory-rule<br/>budget "]:::budget
Ordinary["Facts · preferences<br/>projects · procedures "]:::memory
Recall["Task-relevant<br/>recall budget "]:::budget
Context["BOUNDED CONTEXT PACKET "]:::context
Mandatory --> Assignments --> RulePack --> Context
Ordinary --> Recall --> Context
end
HistoryPath ==>|GOVERNED WRITE | GovernedMemory
classDef rule fill:#3B2C18,stroke:#F3B562,color:#EEF4F8,stroke-width:1.8px;
classDef core fill:#12243A,stroke:#557287,color:#EEF4F8,stroke-width:1.4px;
classDef memory fill:#0D383A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.8px;
classDef budget fill:#12243A,stroke:#38D5C8,color:#EEF4F8,stroke-width:1.6px;
classDef context fill:#EEF4F8,stroke:#38D5C8,color:#071521,stroke-width:2.4px;
classDef history fill:#102F45,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;
classDef historyStore fill:#102436,stroke:#73C7F5,color:#EEF4F8,stroke-width:1.6px;
classDef surface fill:#EEF4F8,stroke:#73C7F5,color:#071521,stroke-width:2px;
classDef barrier fill:#3A2028,stroke:#EA6A6A,color:#EEF4F8,stroke-width:2px;
style GovernedMemory fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
style HistoryPath fill:#081827,stroke:#27445A,stroke-width:1px,color:#EEF4F8
linkStyle default stroke:#557287,stroke-width:1.4px;
支持的宿主
| 宿主 | 集成方式 | 当前边界 |
|---|---|---|
| Claude Code | 全局 MCP 绑定、重定向规则、用户级生命周期 Hook | 已验证的接管路径 |
| Codex | 全局 MCP 绑定、重定向规则、用户级生命周期 Hook | 已验证的接管路径 |
| Cursor | 全局 MCP 绑定、重定向规则、用户级生命周期 Hook | 已验证的接管路径 |
| TRAE | MCP 绑定和重定向规则 | 没有已验证的 Hook 接入点；报告为备用方案，而非完整接管 |
提供方状态会如实报告为已重定向、已观察、可运行或不受支持。如果宿主没有提供可靠的集成点，MemoryGuard 不会声称自己能够禁用该宿主的所有原生记忆功能。
架构
| 层 | 职责 |
|---|---|
| 证据与内容 | 已授权来源、不可变证据、内容寻址的 Blob／出现记录、来源清单和对话档案 |
| 记忆与规则 | 有范围限制的记忆单元、修订版本、绑定、规则定义、决策、证据链接和补偿性治理操作 |
| 运行时与投影 | 有界工作上下文、场景／配置文件投影、CodeGraph、Assets 和 Skills 元数据 |
| 切换与治理 | 四状态清单、原生 MCP／CLI／GUI／Hook 路由、Reference Audit、维护、提供方适配器和回滚证据 |
V2 使用相互独立的权威 SQLite 域，而非一个共享记忆数据库。只有当清单达到 V2_ACTIVE 时，运行时才会读取和写入 V2；V2_BUILDING 和 V2_READY 不会静默回退或双写。证据始终可追溯，但不会被视为自动可信的记忆。
隐私与安全
- MemoryGuard 作为本地 MCP stdio 服务运行。
- 除非你明确授权远程模型或嵌入操作，否则所有受治理的数据都保留在本地。可选的使用遥测仅限本地：测得的宿主令牌事件和确定性转换事件存储在
.memoryguard/usage_telemetry.sqlite中；不会上传数据。令牌节省量是根据 MemoryGuard 确定性单位估算的，并非服务提供商的账单明细。无法报告令牌的宿主在测量列中仍不受支持。 - 知识库数据库使用
MEMORYGUARD_HOME或平台用户数据目录，因此所选源文件夹不会获得自己的知识库数据库。 - V2 权威工作区状态在
.memoryguard/下按 Memory、Rules、Evidence、Content、Runtime、Projection、Assets、CodeGraph、Skills 和 System 域进行隔离；History、Source、Binding 和 Group 控制是 V2 原生界面。切换后，旧版 V1 产物会作为本地回滚／审计证据保留，不再是活动 V2 运行时写入路径；只有memoryguard.migration可以读取它们。 - 默认情况下，源扫描为只读。
- 可变更治理路径会使用验证、明确的范围、来源信息和可逆状态。
- 被隔离的记录不会进入活动共享记忆。
- 原始对话历史绝不会自动注入启动内容。
- 共享组历史访问遵循当前有效成员身份，且不会授予对其他 Agent 源的删除权限。
CLI
安装后的 memoryguard 命令提供以下顶层操作：
| 命令 | 用途 |
|---|---|
audit [path] | 执行只读审计并生成报告 |
open [path] | 打开最新的交互式报告 |
explain <finding_id> | 说明某项发现的证据和风险 |
source <action> | 列出、添加、移除或预览已授权的源 |
scan | 扫描已授权的源并构建覆盖范围账本 |
doctor | 诊断 V2 清单、域可用性和原生覆盖范围 |
mcp-status | 检查 V2 MCP／后端运行状况；租户计数需要绑定 Agent 范围 |
hooks <action> | 安装、检查、暂停、修复或移除宿主 Hooks |
provider <action> | 检查或修复全局服务提供商集成 |
| `storage audit | report` |
| `storage sweep | compact` |
groups <action> | 检查受治理的组状态 |
gui [path] | 启动交互式治理控制台 |
desktop | 启动可信桌面执行器 |
旧版 V1 的 plan、apply、verify、undo、import 和 gc 工作流可能仍可作为明确标记为已弃用的兼容界面解析，但不属于 V1 运行时路径。在 V2_ACTIVE 下，它们会返回稳定的已弃用结果，而不会通过旧版存储写入数据。只有通过明确的 memoryguard.migration 升级流程才会接受旧版数据输入。
运行 memoryguard --help 或 memoryguard <command> --help 查看最新命令参考。
MCP API
默认的 MCP 发现界面有意保持精简。新的 MCP 客户端会通过 tools/list 获取以下 11 个日常工具：
| 工具 | 用途 |
|---|---|
memoryguard_context_bootstrap | 加载有界的强制规则和相关记忆上下文 |
memoryguard_memory_search | 按查询、生命周期状态和有界数量限制搜索受治理的记忆。kind 不是 MCP 搜索筛选条件；语义重复/冲突检查属于单独的高级治理功能。 |
memoryguard_memory_read | 读取一条受治理的记忆 |
memoryguard_memory_write | 写入并整理一条受治理的记忆 |
memoryguard_memory_update | 更新一条已知记忆的正文、类型、召回策略或优先级。不会更改生命周期状态。 |
memoryguard_memory_delete | 软删除一条受治理的记忆 |
memoryguard_memory_status | 检查共享记忆状态 |
memoryguard_audit | 运行只读的本地治理审计 |
memoryguard_explain | 解释一项审计发现及其证据 |
memoryguard_capabilities | 通过有界分页和可选的按需 JSON Schema，发现已注册的 MCP 操作和经审核的无头 GUI 操作 |
memoryguard_invoke | 调用一项已发现的 MCP 操作或经审核的无头 GUI 操作；修改型目标需要确认和幂等键 |
高级治理功能仍可通过 GUI 和 CLI 使用：规则生命周期、绑定和共享组、源代码扫描、CodeGraph、知识和历史记录审查、提供方控制、外部 MCP 导入以及维护操作。已安装的客户端按精确名称调用时，现有高级 MCP 名称仍可调用，以保持兼容性，但这些名称不会由默认的 tools/list 返回。这样可以降低发现和架构开销，同时保留这些治理功能。
memoryguard_capabilities 是发现更广泛兼容性目录的途径。它支持按精确操作查找、英文或中文查询文本、按域筛选以及偏移分页；仅当所选页面请求 include_schema=true 时才会返回架构。该目录通过 memoryguard_invoke 暴露了 162 项经审核的无头 GUI 业务操作。8 项 GUI 操作仍受其现有权限明确限制：仅限桌面的路径/文件夹操作、桌面管理员专用的 CodeGraph 选择/构建，以及 SafeBridge 协议操作。
有界读取响应
MemoryGuard 默认会精简 JSON 文本。可重放的读取响应在完整 MCP 信封中最多为 24,000 个 UTF-8 字节，包括每个 content 块和现有的 structuredContent。较小的响应保留原有结构。超大读取会返回包含 response_ref 和必要标识符的精简回执，不会静默截断原始结果。
发现 memoryguard_response_read（使用 memoryguard_capabilities）后，通过现有 broker 获取页面：
{
"operation": "memoryguard_response_read",
"arguments": {
"response_ref": "opaque-id",
"fields": ["/data/memory_id"],
"offset": 0,
"limit": 3000
}
}
页面是带有 next_offset 的 UTF-8 JSON 片段；按顺序拼接即可。limit 为 4–4096 字节，偏移量必须位于 UTF-8 字符边界。对于单个 JSON 文本负载，fields 用于选择业务字段：使用顶层名称或仅指向对象的 JSON Pointer，例如 /data/memory_id。多内容和非 JSON 结果不接受字段选择，只能以完整信封页面的形式获取。
私有引用仅保存在 MCP 进程中，最长五分钟：最多 16 个快照，每个最多 512,000 字节。它们绑定到确切的可信会话、主体、范围和活动绑定修订。每次读取页面时，都会在当前授权下重新执行原始读取，并比较其摘要。若拒绝访问、输出发生变化、绑定或会话发生变化，或引用过期，则返回稳定的拒绝结果，例如 response_ref_access_denied、response_ref_expired 或 response_ref_result_changed；绝不会使用缓存的旧内容绕过当前读取。公共能力元数据使用现有的偏移分页机制。写入和上下文引导保留其现有的完整回执／强制规则契约，且不能请求响应分页，因此读取页面绝不会重新执行变更操作。如果超大读取无法安全创建引用，其有界回执会报告 delivery.status="unavailable" 和 action="narrow_query"，而不是承诺可以检索完整结果。
使用已发布的架构进行发现和调用示例：
{"operation":"memoryguard_task_list","include_schema":true,"limit":1}
{"operation":"memoryguard_task_list","arguments":{"limit":20}}
对于会变更数据的目标，调用信封还必须包含 "confirmed":true 和非空的 "idempotency_key"；broker 会将这些证明转发给目标现有的权限和范围检查。
底层兼容性目录还涵盖：
- 受治理的记忆读取、搜索、写入、更新、删除和状态查询；
- 带强制规则隔离的有界上下文引导；
- 规则创建、反馈、合并治理、撤销和范围统计；
- Agent 绑定和共享组检查；
- 来源扫描、图投影、导入预览和构建规划；
- 外部 MCP 发现和导入；
- 文档提取预览和候选项接受；
- 对话历史搜索、时间线、显式读取、导出、删除和提取预览；
- 提供方安装和主机 Agent 信息增强。
使用 MCP tools/list 获取精简的默认发现集合。使用 memoryguard_capabilities 获取已注册的兼容性目录及其经过审核的操作元数据。
项目链接
- PyPI 软件包
- GitHub 发布版本
- 更新日志
- v0.7.13 发布说明
- v0.7.12 发布说明
- v0.7.11 发布说明
- v0.7.9 发布记录
- v0.7.8 发布记录
- v0.7.7 发布记录
- v0.7.6 发布记录
- v0.7.5 发布记录
- v0.7.4 发布记录
- v0.7.3 发布记录
- v0.7.2 发布记录
- v0.7.1 发布记录
- v0.7.0 发布门槛
- 记忆连续性与无损存储规范
- 隐私政策
- 使用条款
- 贡献指南
- 贡献者许可协议
- 问题跟踪器
路线图
- 发布历史： v0.7.9 整合了规范治理、本地令牌证据、清晰易读的多 Agent 治理，以及通过 GitHub、PyPI 和官方 MCP Registry 进行公开分发。v0.7.8 记录了此前的治理、遥测和 Codex 运行时工作；v0.7.7 确保在经过验证且唯一绑定的控制主目录中安全修复裸提供方，并使已安装的 Codex MCP/Hook 修复与当前解释器保持一致，同时保留 Agent 和共享组身份。v0.7.6 通过单一不可变快照统一 Codex Hook/MCP 运行时选择，缩短 Hook 状态锁定窗口，并通过显式处理强制溢出时故障关闭，确保引导成功/失败状态准确。更早的发布记录保留了 v0.7.5 冲突审查、v0.7.4 规范治理、v0.7.3 共享历史记录，以及 v0.7.2 写入/读取和 Codex 生命周期变更的详细信息。v0.7.1 仅支持 V2 的迁移和桌面生命周期工作仍作为历史发布背景记录在案。
- 验收边界： Graphify 证据包括重点测试的
3 / 3结果，以及上文所述的真实完整仓库导出/投影。这并不表示上游 Graphify 的完整仓库测试套件已通过。 - 发布后的后续计划： 扩大 CodeGraph/Skills 接入范围，提供更便于运维人员使用的维护报告，并增强迁移可观测性。长期记录不会仅仅因为年代久远而退役。
- 后续： 只有在需求得到验证后，才会推出团队和企业功能。
贡献
欢迎提交问题和拉取请求。提交更改前，请阅读 CONTRIBUTING.md。提交拉取请求须同意 CLA。
许可证
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。