内容
# MemoryGuard
> 本地优先的 MCP 记忆后端与治理台，面向编程 Agent。
MemoryGuard 让多个编程 Agent 可以写入同一个共享的记忆层，然后自动组织、隔离、取代和回滚记忆 —— 而无需将 GUI 变成审批队列。
## 功能特点
- **MCP 记忆后端** — 6 个核心工具：读取 / 搜索 / 写入 / 更新 / 删除 / 状态
- **自动组织** — 分类 / 去重 / 取代 / 冲突 / 隔离 / 派生 / 压缩
- **多 Agent 共享记忆组** — 多个 Agent 写入同一个受管理的记忆
- **GUI 治理控制台** — 观察、编辑、合并、锁定、恢复、回滚（不是审批队列）
- **提供者适配器** — 一键设置适用于 Claude Code / Codex / Cursor
- **回滚和版本历史** — 所有治理操作都有版本记录且可逆
- **无需账户，无需服务器，无需遥测** — 所有内容都保留在本地
## 快速开始
### 安装
**一键安装（推荐）：**
```bash
pip install agent-memguard
```
启用 GUI 支持（可选，用于桌面窗口）：
```bash
pip install "agent-memguard[gui]"
```
**或从源代码安装：**
```bash
git clone https://github.com/irisxc4/memoryguard.git
cd memoryguard
pip install -e .
```
验证安装：
```bash
memoryguard doctor
```
### 配置您的 Agent
**一键设置（自动写入 MCP 配置 + 说明文件）：**
```bash
# Claude Code
memoryguard source add . && python -m memoryguard.provider_adapters install claude
# Codex
memoryguard source add . && python -m memoryguard.provider_adapters install codex
# Cursor
memoryguard source add . && python -m memoryguard.provider_adapters install cursor
```
或直接在您的 Agent 中使用 MCP 工具：
```bash
memoryguard_provider_install(provider="claude")
```
**手动配置** - 参见安装指南以获取详细信息：
- [Claude Code](docs/install-claude-code.md)
- [Codex](docs/install-codex.md)
- [Cursor](docs/install-cursor.md)
<details>
<summary>手动 MCP 配置（所有 Agent 使用相同的服务器）</summary>
**Claude Code** — `.mcp.json`（项目根目录）：
```json
{
"mcpServers": {
"memoryguard": {
"command": "python",
"args": ["-m", "memoryguard.mcp_server"]
}
}
}
```
**Codex** — `~/.codex/config.toml`:
```toml
[mcp_servers.memoryguard]
command = "python"
args = ["-m", "memoryguard.mcp_server"]
```
**Cursor** — `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"memoryguard": {
"command": "python",
"args": ["-m", "memoryguard.mcp_server"]
}
}
}
```
</details>
### 使用
```bash
memoryguard doctor # 诊断安装和环境
memoryguard mcp-status # 查询 MCP 记忆后端状态
python -m memoryguard.mcp_server # 启动 MCP stdio 服务器（由您的 Agent 运行）
memoryguard audit . # 只读工作区扫描，生成报告
memoryguard open . # 打开最新报告
```
一旦您的 Agent 配置完成，它就会通过 `memoryguard_memory_write` MCP 工具写入记忆。MemoryGuard 会自动组织每次写入。
打开 GUI 以观察和治理结果。
## 工作原理
MemoryGuard 有三个层次：
| 层次 | 角色 |
|---|---|
| **数据层** | Agent 原生记忆、文件、外部 MCP、文档 — 提供原始证据，无治理 |
| **记忆层** | MemoryGuard MCP 共享记忆后端 — 唯一的共享真实来源；Agent 在此处写入；自动组织在每次写入时运行 |
| **治理层** | GUI + CLI — 观察、编辑、合并、锁定、恢复、回滚事后 |
```
Agent 写入记忆
→ memoryguard_memory_write（MCP 工具）
→ 原始事件
→ 自动组织（分类 / 去重 / 取代 / 冲突 / 隔离 / 派生 / 压缩）
→ 活动共享记忆
→ GUI 治理（观察 / 修正 / 覆盖 / 回滚）
```
## 命令
| 命令 | 描述 |
|---|---|
| `audit [path]` | 只读扫描，生成报告 |
| `open [path]` | 在窗口中打开最新报告 |
| `explain <finding_id>` | 解释发现的证据和风险 |
| `plan <finding_ids...>` | 生成最小修复计划（无写入） |
| `apply <plan_id>` | 应用计划：备份 + 补丁 + 重新扫描 |
| `verify` | 重新扫描并比较前后 |
| `undo <change_id>` | 从备份恢复并重新验证 |
| `source <action>` | 管理授权来源（列表 / 添加 / 删除 / 预览） |
| `scan` | 只读扫描，构建覆盖率账本 |
| `import <action> <bundle>` | 离线导入包（预览 / 创建） |
| `memory <action>` | 记忆构建和发布（构建计划 / 构建应用 / 验证 / 回滚） |
| `doctor` | 诊断安装和环境 |
| `mcp-status` | 查询 MCP 记忆后端状态 |
## MCP 工具
### 记忆后端（6 个核心工具）
| 工具 | 描述 |
|---|---|
| `memoryguard_memory_read` | 按 ID 读取单个记忆记录 |
| `memoryguard_memory_search` | 按查询、类型或状态搜索记忆 |
| `memoryguard_memory_write` | 写入新记忆；写入时自动组织 |
| `memoryguard_memory_update` | 更新记忆（正文 / 类型 / 状态） |
| `memoryguard_memory_delete` | 软删除记忆 |
| `memoryguard_memory_status` | 获取共享记忆组状态 |
### 审计和扫描
| 工具 | 描述 |
|---|---|
| `memoryguard_audit` | 只读工作区扫描 |
| `memoryguard_explain` | 解释发现的证据和风险 |
| `memoryguard_list_sources` | 列出授权来源 |
| `memoryguard_scan_summary` | 扫描 + 覆盖率账本 |
| `memoryguard_neuron_graph` | 读取神经元图投影 |
| `memoryguard_import_preview` | 预览导入包 |
| `memoryguard_build_plan` | 生成记忆构建计划（无写入） |
### Agent 绑定
| 工具 | 描述 |
|---|---|
| `memoryguard_binding_create` | 将 Agent 绑定到共享组 |
| `memoryguard_binding_list` | 列出 Agent 绑定 |
### 外部 MCP
| 工具 | 描述 |
|---|---|
| `memoryguard_external_mcp_list` | 列出导入的外部 MCP 描述符 |
| `memoryguard_external_mcp_import` | 导入外部 MCP 描述符（L0–L4 分类） |
### 文档和发现
| 工具 | 描述 |
|---|---|
| `memoryguard_extract_memories` | 从源文件提取记忆片段（只读预览） |
| `memoryguard_accept_candidates` | 接受提取的候选并写入共享记忆 |
### 语义和提供者
| 工具 | 描述 |
|---|---|
| `memoryguard_semantic_check` | 检查文本的语义重复 / 冲突 |
| `memoryguard_provider_install` | 安装提供者适配器（Claude / Codex / Cursor） |
## 治理 GUI
GUI 是一个 **治理控制台，而不是审批队列**。Agent 通过 MCP 写入记忆；MemoryGuard 自动组织它们。然后 GUI 显示给您：
- Agent 的原始写入
- 自动组织结果（分类 / 去重 / 压缩）
- 取代链（涉及的内容及原因）
- 冲突队列（需要人工仲裁的记忆）
- 隔离队列（自动隔离的秘密 / 令牌 / 凭证）
- 派生记忆（通过重复行为得出的程序 / 首选项）
治理操作：**编辑、合并、分割、锁定、恢复、删除、回滚**。每个操作都有版本记录且可逆。
## 常见问题
**MemoryGuard 是否需要服务器或账户？**
不。它作为本地 MCP stdio 服务器运行。无需账户，无需云服务，无需遥测。
**它是否完全取代我的 Agent 的原生记忆？**
MemoryGuard 将写入重定向到 MCP 后端，如果 Agent 支持的话。某些 Agent 无法完全禁用原生记忆 — MemoryGuard 使用重定向 / 观察 / 不支持的分类，而不是假装一切都可以关闭。
**GUI 是否审批每次写入？**
不。MCP 后端接受写入并自动组织它们。GUI 只在之后治理结果。
**我的记忆是否被上传到任何地方？**
不。所有数据都保留在 `.memoryguard/` 下的本地 SQLite 数据库中。
**我可以回滚更改吗？**
是的。所有治理操作都有版本记录。您可以恢复、取消取代并回滚到任何以前的版本。
## 路线图
- **现在（开源核心）：** 本地 MCP 记忆后端 + 自动组织 + GUI 治理 + 提供者适配器 + 回滚。本仓库。
- **稍后：** 增强的治理功能（衰减、派生、治理报告）。无承诺时间表。
- **稍后：** 团队和企业功能。无承诺时间表。
我们不承诺未来功能的日期。开源核心设计为单独使用。
## 许可证
MIT — 参见 [LICENSE](LICENSE)。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。通过提交 PR，您同意 [CLA](CLA.md)。
