内容
# memwall
**人工智能代理内存的防病毒软件**
持久内存是代理式人工智能的新攻击面。一旦被植入的恶意内存——通过电子邮件、网页或代理读取的文档——就会在会话之间存活并在数天或数周后触发。OWASP 将 *内存和上下文中毒* 添加到其 2026 年代理式人工智能十大安全风险中（ASI06）；已发布的 研究显示针对真实代理栈的攻击成功率在 80-99% 之间。
memwall 扫描代理内存存储，以检测注入的指令、数据外泄向量、隐藏的恶意 payload 和卫生问题，如保留的个人可识别信息（PII）。核心扫描功能零依赖。
## 快速入门
```bash
pip install -e .
memwall scan path/to/memory.json # 扫描单个存储或导出
memwall scan . # 扫描项目：CLAUDE.md、AGENTS.md、内存文件
memwall scan memory.json --judge # 添加 Claude 语义判断（需要 ANTHROPIC_API_KEY）
memwall rules # 列出检测规则
```
60 秒演示 - 扫描捆绑的示例存储并观察它捕获发票外泄植入和支付重定向：
```bash
git clone https://github.com/gbayerv26/memwall && cd memwall
pip install -e .
memwall scan examples/
```
目录扫描是内存感知的：`package.json`、`tsconfig.json` 和其他非内存 JSON 文件自动跳过，超过 5 MB 的文件也是如此。
## 支持的存储（v0.1）
- **MCP 参考内存服务器** - `memory.json` / `.jsonl` 实体和观察
- **mem0 样式导出** - JSON 内存对象列表
- **代理指令文件** - `CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`.cursorrules`、`.mdc`
- **笔记/ markdown 内存文件** 和通用 JSON 转储
## 工作原理
**第一阶段 - 启发式（免费，立即）。** 规则 MW001-MW013 捕获已知的内存中毒形状：指令覆盖、保密压力（“不要告诉用户”）、权限声明（“系统注释：”，“开发者模式”）、支付重定向、加密钱包、编码有效载荷、零宽度/双向隐藏字符和需要过期策略的个人可识别信息（PII）。当指令和出站目的地出现在同一内存中时，会触发组合规则（MW000）升级为严重 - 经典的数据外泄形状。
指令文件获得校准的规则集：CLAUDE.md 中的指令是正常的，因此只有真正可疑的规则才适用。
**第二阶段 - 判断（可选）。** `--judge` 将标记的记录发送到 Claude 进行语义分类（`benign_fact` / `preference` / `task_context` / `suspicious_instruction` / `likely_injection`）。判断器将内存内容视为不受信任的数据，并且永远不会遵循其中的指令。
```bash
pip install -e ".[judge]"
export ANTHROPIC_API_KEY=sk-ant-...
memwall scan memory.json --judge
```
## CI 门控
```bash
memwall scan ./agent-memory --fail-on high --json memwall-report.json
```
当任何发现达到 `--fail-on` 阈值时，退出代码为 1，因此您可以阻止部署在中毒存储上。
接受的发现可以基线化，以便 CI 仅在新的发现上失败 - 基线化发现保持抑制，直到内存内容本身发生变化：
```bash
memwall scan ./agent-memory --baseline .memwall-baseline.json --update-baseline # 接受当前状态
memwall scan ./agent-memory --baseline .memwall-baseline.json --fail-on high -q # 门控新发现
```
## 网关 - 提交前隔离
`memwall gateway` 是一个透明的 MCP 代理，您可以将其置于任何 stdio 内存服务器前面。每个内存写入在到达存储之前都会被扫描；任何达到阻止阈值或以上的写入都会被隔离，而不是写入，代理会向代理返回明确的“阻止，请勿重试”工具响应。读取和其他流量会不受影响地通过。
```bash
memwall gateway --state-dir ~/.memwall -- npx -y @modelcontextprotocol/server-memory
```
Claude Desktop / Claude Code 配置 - 包装您的现有内存服务器：
```json
{
"mcpServers": {
"memory": {
"command": "memwall",
"args": ["gateway", "--state-dir", "/home/you/.memwall", "--",
"npx", "-y", "@modelcontextprotocol/server-memory"]
}
}
}
```
写入（工具名称匹配 create/add/store/save/write/update/remember...）会使用与 `memwall scan` 相同的规则引擎进行扫描。网关在内部错误时打开失败，并将协议流量保留在 stdout 上，将诊断信息保留在 stderr 上，因此它永远不会使您的内存服务器宕机。
查看发生了什么 - 每个写入都记录在仅追加的审计跟踪中，并带有 payload 哈希，因此您可以回答“此信念何时进入内存”：
```bash
memwall log --state-dir ~/.memwall # 法医事件日志
memwall quarantine --state-dir ~/.memwall list # 保存的写入
memwall quarantine --state-dir ~/.memwall show q1a2b3c4
memwall quarantine --state-dir ~/.memwall release q1a2b3c4 -- npx -y @modelcontextprotocol/server-memory
memwall quarantine --state-dir ~/.memwall drop q1a2b3c4
```
`release` 在人工审查后重放原始写入到后端；`drop` 丢弃它。两种决定都追加到审计跟踪中，永远不会被覆盖。
## 可信度感知的策略 - 源头握手
代理（或其线束）可以通过将 MCP 元数据附加到写入调用来声明内存内容来自哪里：
```json
{"method": "tools/call",
"params": {"name": "add_observations",
"_meta": {"memwall": {"origin": "web"}},
"arguments": {"...": "..."}}}
```
每个源都映射到一个阻止阈值 - 来自开放网络的内容受到比用户输入更严格的约束：
| 源头 | 阻止级别 |
|---|---|
| `user` | 严重 |
| `agent` | 高 |
| `tool` / `web` / `email` / `document` | 中等 |
| 未声明 | `--block-at` （默认为高） |
使用 `--policy policy.json` 覆盖：
```json
{"default_block_at": "high", "origins": {"web": "low", "voicemail": "low"}}
```
未列出的源头保留内置表格。声明的源头记录在每个事件和隔离条目中，因此审计跟踪带有出处。`memwall` 元键在调用到达后端之前被剥离。
## 循环中的判断
```bash
memwall gateway --judge -- npx -y @modelcontextprotocol/server-memory
```
使用 `--judge` 时，标记的写入会从 Claude 判断中获得第二个意见，然后再隔离。清除判决（事实/偏好/任务上下文）允许写入通过 - 减少启发式误报，同时阻止真正的注入。如果判断不可用或不确定，则写入保持隔离（故障安全）。需要 `pip install "memwall[judge]"` 和 `ANTHROPIC_API_KEY`；仅为已标记启发式的写入添加一个 API 调用，因此正常流量不会产生延迟。
## 路线图
- **第三阶段 - 主机监控。** 持续扫描、警报和合规导出（欧盟 AI 法日志，GDPR 删除验证）。
- 更多存储：Zep、Letta、LangGraph 检查点、矢量数据库。
- 策略包：可共享的、版本化的行业/风险偏好策略。
## 诚实的局限性
启发式方法根据设计会有误报和漏报 - 它们是分诊层，而不是判决。在删除内存之前，请审查发现的内容。判断阶段提高了精度，但仅限于其背后的模型。
## 许可证
MIT
