lavkumarv/memory-blackbox

**memory-blackbox** 是用于 AI agent 记忆的 DFIR（数字取证与事件响应）层。 它拦截 agent 执行的每一次内存**读取**和**写入**，为每次操作盖上经过加密签名、防篡改的来源印章，并将它们存储在仅追加的账本和来源 DAG 中。在发生事件后，它能准确还原发生的一切：是哪段记忆导致 了某个操作，这段记忆来自哪里，它还感染了什么，以及如何撤销它 —— 而这一切都无需删除任何历史记录。 ``` $ memory-blackbox demo === memory-blackbox incident replay === Poison planted: 019f14b7-2ba6-7e2b-aa6c-ea5e727dd9a8 Harmful action taken: 019f14b7-2ba8-718f-92d9-c917790cb7fa (HARMFUL) trace -> root cause: 019f14b7-2ba6-7e2b-aa6c-ea5e727dd9a8 (correct) blast radius: 3 record(s) rollback affected: 3 record(s) Re-run after rollback: no longer harmful Ledger integrity: VERIFIED ``` ## 目录 - [为什么需要](#why) - [安装](#install) - [它能做什么](#what-it-does) - [集成](#integrations) - [Library wrapper](#1-library-wrapper) · [支持的 backends](#supported-backends) - [MCP gateway](#2-mcp-gateway) - [Sidecar](#3-sidecar) - [架构](#architecture) - [CLI](#cli) - [完整性模型](#integrity-model) - [定位](#positioning) - [文档](#documentation) - [贡献](#contributing) · [License](#license) ## 为什么需要 Agent 记忆是一个攻击面。在 2 月份摄入的投毒文档可能会植入一条指令，而该指令只在 4 月份触发 —— 此时来源早已被遗忘，攻击者也已离开。运行时的防护机制能*拦截*实时攻击；但事后却没有东西能*还原*事件经过。 memory-blackbox 就是那个黑匣子记录仪：它观察每一次内存读取和写入，为每次操作盖上防篡改的来源印章，让你能够重放并分析到底发生了什么 —— 即使攻击者试图抹除痕迹。 ## 安装 ``` pipx install memory-blackbox # or: uv tool install memory-blackbox memory-blackbox init # create the ledger, signing key, and profile memory-blackbox demo # plant a poison, then trace it and roll it back ``` `demo` 会以零配置端到端运行完整的事件重放。 ## 它能做什么 | 命令 | 回答的问题 | |---------|-----------------| | 🔎 **trace** | 将任何 agent 操作追溯到导致该操作的内存写入和来源。 | | 💥 **blast-radius** | 投毒来源可能影响到的所有内容（前向闭包）。 | | 🌊 **drift** | 当某次写入与其语义集群中受信任的大多数发生矛盾时。 | | 🔐 **verify** | 证明账本未被编辑、未被产生间隙、或未被删除行。 | | ↩️ **rollback** | 隔离投毒内容及其闭包 —— 通过追加，永不删除。 | 它还提供了一个 **detector pack**（缺失来源、prompt 注入、unicode 走私、secrets/PII、写入速率突增、信任评分、语义漂移）以及一个 `reconcile` 命令，用于标记没有账本记录的后端条目（绕过了捕获机制的写入）。每个检测器都映射到一个命名的威胁类别 —— 参见 [docs/threat-mapping.md](docs/threat-mapping.md)。 ## 集成 三种捕获路径，均由相同的仅追加账本支持。选择适合你技术栈的任意一种 —— 它们底层的账本、DAG 和查询是完全相同的。 ### 1. Library wrapper 在进程内包装你的内存客户端；调用将被捕获并原样转发。 ``` from memory_blackbox.capture.engine import Forensics from memory_blackbox.crypto import keys from memory_blackbox.adapters.mem0_ import mem0_adapter from memory_blackbox.model.records import Source, SourceType, TrustLevel from mem0 import Memory # your real client forensics = Forensics.open("forensics.db", keys.generate()) source = Source(source_type=SourceType.document_ingest, trust_level=TrustLevel.untrusted) memory = forensics.wrap_adapter( Memory(), mem0_adapter(), namespace="agent", default_source=source, ) memory.add("the user prefers dark mode") # captured as a provenance write, then forwarded memory.search("user preferences") # captured as a retrieval, then forwarded ``` #### 支持的 backends | Backend | Adapter | Write intercept | Read intercept | |---------|---------|-----------------|----------------| | **Mem0** | `mem0_adapter()` | `Memory.add` | `Memory.search` / `get_all` | | **Chroma** | `chroma_adapter()` | `collection.add` | `collection.query` | | **Letta** | `letta_adapter()` | archival insert | archival / recall search | | **pgvector** | `PgVectorCapture` | `INSERT … embedding` (explicit helpers) | `SELECT … ORDER BY embedding <=> q` | | **memory.md** | `MemoryMdAdapter` | file write/diff on `MEMORY.md` · `CLAUDE.md` · `AGENTS.md` | file reads | | *Anything via MCP* | [MCP gateway](#2-mcp-gateway) | any memory tool call | any memory tool call | | *Hosted vector DBs* | [Sidecar](#3-sidecar) | upsert | query | ### 2. MCP gateway 与 Backend 无关：将你的 agent 指向 gateway，而不是真实的 memory MCP server。每个 `tools/call` 都会**逐字节一致地**向上游转发，同时带有来源信息的写入和读取会被记录下来。 → [完整示例](examples/mcp_gateway/run.py) ``` from memory_blackbox.capture.gateway import McpGateway from memory_blackbox.capture.wrapper import WriteMap, ReadMap gateway = McpGateway( forensics, forward=mcp_server.call, # (tool_name, arguments) -> result, your real MCP server namespace="agent", default_source=source, write_tools={ "create_memory": WriteMap( content=lambda c: c.kwargs["content"], memory_id=lambda c: c.result["id"], ), }, read_tools={ "search_memory": ReadMap( query=lambda c: c.kwargs["query"], returned=lambda c: [m["id"] for m in c.result["matches"]], ), }, ) result = gateway.call_tool("create_memory", {"content": "..."}) # logged + forwarded unchanged ``` ### 3. Sidecar 一个位于托管型 vector DB（**Pinecone, Qdrant Cloud, Weaviate, Mongo Atlas**）前面的反向代理。它 拦截 upsert/query，记录来源，用其账本记录 ID 标记每次 upsert，并将请求转发到上游。可作为进程或 Kubernetes sidecar 部署。 → [完整示例](examples/sidecar/run.py) ``` from memory_blackbox.capture.sidecar import Sidecar from memory_blackbox.capture.wrapper import WriteMap, ReadMap sidecar = Sidecar( forensics, forward=vector_db.call, # (op, payload) -> result, your hosted DB's HTTP/gRPC API namespace="agent", default_source=source, upsert_ops={"upsert": WriteMap(content=lambda c: c.kwargs["text"])}, query_ops={ "query": ReadMap( query=lambda c: c.kwargs["q"], returned=lambda c: [m["id"] for m in c.result["matches"]], ), }, ) sidecar.handle("upsert", {"text": "...", "id": "vec-1"}) # logged + tagged + forwarded ``` ## 架构 ``` flowchart LR A([AI agent]) -- read / write --> C{Capture} C -- library wrapper --> B1[(Mem0 · Chroma · Letta
pgvector · memory.md)] C -- MCP gateway --> B2[(any MCP
memory server)] C -- sidecar --> B3[(Pinecone · Qdrant
Weaviate · Mongo)] C --> L[[Append-only ledger
BLAKE3 chain · Merkle root · Ed25519]] C --> D[[Provenance DAG]] L & D --> Q{{trace · blast-radius · drift · verify · rollback}} ``` 签名密钥保存在 engine 中，agent 永远无法访问它。来源捕获在写入路径上增加的耗时不到 1 毫秒。完整模型请参见 [`ARCHITECTURE.md`](ARCHITECTURE.md)。 ## CLI ``` memory-blackbox init create ledger, keys, config memory-blackbox demo run the incident replay memory-blackbox trace --action [--format ...] action → root cause memory-blackbox blast-radius --source forward closure of a source memory-blackbox drift --topic consensus-flip events memory-blackbox timeline --topic ordered narrative memory-blackbox verify integrity check (nonzero exit on tamper) memory-blackbox rollback --to [--apply] dry-run or apply a rollback memory-blackbox report --incident --format ... md | json | sarif report memory-blackbox reconcile --ids-file flag store entries with no ledger record ``` ## 完整性模型 账本是**仅追加的**：回滚会追加新事件，绝不进行编辑或删除。BLAKE3 哈希链证明没有任何行被编辑过；定期检查点的签名 Merkle root 证明没有任何行被移除过（包括尾部截断）。每个条目都由 agent 永远看不到的密钥进行 Ed25519 签名。`verify` 会检查这三者。路线图计划为高可靠性部署添加外部透明日志锚定（Rekor 风格） —— 参见 [`docs/threat-model.md`](docs/threat-model.md)。 ## 定位 这是**事后还原** —— 专注于来源、爆炸半径和回滚。它**不会**在运行时 阻止攻击；请在你的运行时防护机制之下运行它。你的运行时防护机制负责阻止攻击；而它负责告诉你*是哪段记忆导致了攻击，以及需要回滚什么。* **本地优先。** 无遥测；默认情况下不会有任何数据离开你的机器。账本映射了 agent 知道的所有信息，因此它在磁盘上将始终保持本地化和仅限所有者访问。 **合规证据。** 一份防篡改、经过签名的*关于 agent 在何时知道什么*的记录，正是 EU AI Act（第 12 条日志记录）、Colorado AI Act 和 HIPAA 审计追踪所要求的。参见 [docs/threat-mapping.md](docs/threat-mapping.md)。 ## 文档 - [ARCHITECTURE.md](ARCHITECTURE.md) — 概念模型、数据模型和算法 - [docs/spec.md](docs/spec.md) — 版本化的 ProvenanceRecord schema - [docs/threat-model.md](docs/threat-model.md) — 资产、对手和缓解措施 - [docs/threat-mapping.md](docs/threat-mapping.md) — 映射到 OWASP ASI / MITRE ATLAS / CoSAI 的检测器 - [ROADMAP.md](ROADMAP.md) — 已完成的功能和计划中的功能 - [examples/](examples/) — 可运行的事件重放、MCP gateway、sidecar 和扩展模板 - [SECURITY.md](SECURITY.md) — 披露政策和工具自身的完整性姿态 ## License Apache-2.0 — 参见 [LICENSE](LICENSE)。我们在 Apache-2.0 下接受贡献，并要求 DCO 签署 (`git commit -s`)。

标签：AI智能体, Blue Team, 人工智能, 内存审计, 子域名突变, 异常检测, 数据溯源, 用户模式Hook绕过, 逆向工具