项目定位与设计目标

mnemo 是一个面向"可验证记忆"(verifiable memory) 的 Python 库，专注于为 AI 系统提供带治理能力的记忆层。根据 README.md 的描述，仓库将自己定位为内存管理与合规审计并重的工具，强调在 写入、读取与遗忘 三个维度上同时提供可被独立验证的能力，从而区别于普通缓存或向量存储。

项目的核心设计目标围绕三大支柱(三大支柱具体取自社区上下文的描述)：

• 可证明遗忘(Pillar 2)，由 ErasureAuditor 提供的 compliance_receipt 承担，对应 GDPR Art. 17 / EU AI Act 的留存与可删除性义务
• 双时态审计(bitemporal audit)，保证事务时间与有效时间均可回溯
• 签名化凭证，使任何记忆操作的产物都能作为一份可独立出示的合规证据

资料来源：README.md:1-40

顶层包结构

mnemo 采用单包、单入口的简洁结构。mnemo/__init__.py 负责将主要公共对象重新导出，方便使用者 import mnemo; mnemo.X 而无需关心内部子模块。

核心的 Mnemo 类位于 mnemo/mnemo.py，是用户实际打交道的主要入口；与之并列的还有面向治理的 ErasureAuditor 以及若干与时间、签名相关的辅助类（暴露在 __init__.py 中）。版本号与最小依赖声明在 pyproject.toml 中给出，并通过 CHANGELOG.md 按发行节奏维护。

资料来源：mnemo/__init__.py:1-30, mnemo/mnemo.py:1-60, pyproject.toml:1-40, CHANGELOG.md:1-40, README.md:40-80

核心架构：四大支柱

mnemo 的运行时由四个可独立演化的支柱组成，它们通过 Mnemo 这一聚合对象对外提供服务：

flowchart LR
    A[写入层<br/>Store Adapters] --> B[Mnemo 核心<br/>记忆账本]
    C[双时态层<br/>Bitemporal Index] --> B
    D[ErasureAuditor<br/>合规审计] --> B
    E[签名 / 凭证层<br/>proof-of-erasure] --> D
    B --> F[查询 / 检索 API]
    D --> F

• 存储适配层：覆盖常见的记忆后端，向 Mnemo 上报增删改查事件，用于跨存储做一致性核对
• 双时态索引：为每条记录同时维护事务时间与有效时间，使历史版本可被独立回放
• ErasureAuditor：在收到遗忘请求后对所有相关存储执行审计，并将结果封签为 compliance_receipt
• 签名凭证层：对 compliance_receipt 等关键产物进行签名，使其在不依赖 mnemo 在线服务的情况下也能被验证

资料来源：mnemo/mnemo.py:60-160, README.md:80-140

合规与遗忘模型

ErasureAuditor.compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=) 是当前发行版中最关键的公共 API。该方法：

• 以 subject（数据主体）与 values（被请求遗忘的值集合）为输入，遍历所有相关存储
• 接收可选的 sign、pubkey、request_id 参数，决定是否对产出进行签名以及签名的上下文
• 通过 basis 参数指明法理依据（如 GDPR Art. 17），并把该依据写入凭证
• 最终返回一份独立可验证的 proof-of-erasure 凭证，可在 DPO 向监管机构出示时使用

CHANGELOG 显示，这一能力是在 1.5.0 中作为"治理 / 时间支柱"被显式公布的，与双时态审计能力同期发布，社区讨论也围绕"如何让遗忘在多存储场景下仍可被证明"这一主线展开。

资料来源：mnemo/mnemo.py:160-240, CHANGELOG.md:1-20, README.md:140-200

版本与依赖约束

pyproject.toml 同时声明了 mnemo 的最小 Python 版本与外部依赖；CHANGELOG.md 中 1.5.0 条目确认了"可证明遗忘 + 双时态审计"是当前的主线交付。读者在落地集成时应：

• 核对 pyproject.toml 中的 requires-python 与依赖版本
• 通过 mnemo.__version__（定义于 mnemo/__init__.py）确认运行时版本
• 升级到 1.5.0 之后方可使用 ErasureAuditor.compliance_receipt 的签名化凭证输出

资料来源：pyproject.toml:1-40, mnemo/__init__.py:1-20, CHANGELOG.md:1-20

总结

mnemo 通过"存储适配 + 双时态账本 + ErasureAuditor + 签名凭证"四层结构，把 AI 系统的记忆从黑盒变成可被独立审计、可被监管接受的治理对象。其入口类 Mnemo 与审计方法 ErasureAuditor.compliance_receipt 共同构成 1.5.0 之后用户接触最多的两个 API 面，建议阅读代码时优先从这两个对象入手，再向各自依赖的子模块延伸。

1. 概述与定位

mnemo 是一个面向 AI 代理的可验证记忆库（verifiable memory store），其核心目标是在多主体、多后端（向量库、KV、日志、模型权重等）环境下，对"写入、读取、遗忘"三类记忆操作提供可审计、可重放、不可事后篡改的治理能力。mnemo.py 作为顶层入口模块，封装了记忆读写接口与跨存储后端的统一抽象，并在 1.5.0 版本中正式引入"可证明遗忘（Provable Forget）+ 双时态审计（Bitemporal Audit）"作为治理支柱。

资料来源：mnemo/mnemo.py:1-40

2. 记忆操作的语义模型

记忆操作在 mnemo 中被划分为三类原子动作，每一类都会生成可挂载签名的审计事件：

• 写入（Write）：将 subject → values 的映射持久化到对应后端，并写入 valid_time（事件时间）与 transaction_time（系统时间）两条时态轴。
• 读取（Read）：按 subject 与时间窗口检索，强制返回带签名的引用令牌，禁止静默拼接未审计数据。
• 遗忘（Forget）：触发跨存储扫描，并准备后续的 compliance_receipt 产物。

资料来源：mnemo/mnemo.py:42-120

3. 防篡改机制

3.1 可证明遗忘与 ErasureAuditor

ErasureAuditor.compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=) 是 1.5.0 引入的核心治理 API。它对一次遗忘请求执行多后端扫描，并打包为可分发的签名式遗忘证明（proof-of-erasure receipt），可作为 DPO 在 GDPR Art. 17 与 EU AI Act 记录保存要求下提交给监管方的物证。返回的 receipt 至少包含：被检查的存储列表、各存储的逐项扫描结果、签名、签名公钥指纹、请求 ID 与判定依据（basis）。

资料来源：mnemo/mnemo.py:180-260

3.2 完整性基准

probes/INTEGRITY_BENCHMARK.md 定义了一组对抗记忆库完整性攻击的标准化探针，涵盖：(a) 写入覆盖后旧值是否仍可被检索；(b) 跨后端检索是否会出现幽灵条目；(c) 时态窗口是否可被回拨。

资料来源：probes/INTEGRITY_BENCHMARK.md:1-60

3.3 影响门控与中毒防御

agentpoison_influence_gate.py 实现在写入侧对单条记录可施加的影响施加上限，防止攻击者通过大量近似条目污染代理的检索结果；triad_attacker_split.py 模拟"三方分裂攻击"，验证审计路径在三方串通伪造场景下仍能定位冲突来源。

资料来源：probes/agentpoison_influence_gate.py:1-80

资料来源：probes/triad_attacker_split.py:1-80

3.4 生命周期预算与归因下界

lifetime_budget_bound.py 为每条记忆设定最大存活窗口与影响预算，避免陈旧信息无限期地主导检索；attribution_floor.py 定义任意单次决策可归因到某条记忆的最小置信度，防止"幽灵归因"被构造。

资料来源：probes/lifetime_budget_bound.py:1-60

资料来源：probes/attribution_floor.py:1-60

4. 工作流程

flowchart LR
    A[客户端写入/读取/遗忘请求] --> B[mnemo.py 统一接口]
    B --> C{操作类型}
    C -- 写入 --> D[Influence Gate + 签名事件]
    C -- 读取 --> E[时态窗口检索 + 引用令牌]
    C -- 遗忘 --> F[ErasureAuditor 跨存储扫描]
    F --> G[compliance_receipt<br/>proof-of-erasure]
    D --> H[(双时态审计日志)]
    E --> H
    F --> H
    H --> I[监管方 / DPO 验证签名]

资料来源：mnemo/mnemo.py:120-260

5. 关键产物与外部契约

资料来源：mnemo/mnemo.py:200-260

资料来源：probes/INTEGRITY_BENCHMARK.md:20-60

6. 与社区关注点的对应

mnemo 1.5.0 将"可证明遗忘 + 双时态审计"明确为治理支柱（governance / temporal pillar），社区中关于 GDPR 合规、EU AI Act 留痕、Agent Poisoning 防护等讨论均围绕上述 API 与探针展开；本页面所述的记忆操作语义与防篡改产物，正是这些合规与安全诉求在代码层的落点。

mnemo 1.5.0 引入了"可证明的擦除 (provable forget)"作为其治理 / 时间维度的第二支柱 (Pillar 2)。该能力通过 ErasureAuditor 在多存储后端中验证主体 (subject) 的数据是否真正被遗忘,并将结果打包为可签名、可审计、可在跨组织流转的擦除证明 (proof-of-erasure),以满足 GDPR 第 17 条与 EU AI Act 记录保存等监管要求。资料来源：mnemo/erasure_auditor.py:1-60

设计目标与作用范围

可证明的擦除面向的是跨多个异构存储后端的遗忘请求,这些后端可能包括向量索引、结构化数据库、对象存储、缓存层以及外部归档。ErasureAuditor 的核心职责是:

1. 对给定主体 (subject) 及其关联值 (values) 进行全面的存在性扫描;
2. 收集每个存储的执行结果,生成逐存储的擦除报告;
3. 将报告聚合为可签名的合规收据 (compliance_receipt),供 DPO (Data Protection Officer) 提交给监管机构。资料来源：mnemo/erasure_auditor.py:10-90

合规收据是 Pillar 2 区别于普通"删除"的关键——它不仅仅是"调用了删除 API",而是可以被第三方独立验证的证据。

核心 API: `compliance_receipt`

ErasureAuditor.compliance_receipt 是页面主题的核心入口。其签名如下:

ErasureAuditor.compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=)

参数说明:

• subject / values:需要被遗忘的数据标识及待校验的取值;
• sign:可选的数字签名算法标识,用于对收据内容签名;
• pubkey:签名使用的公钥,接收方可验证完整性;
• request_id:原始遗忘请求的全局唯一 ID,用于审计追踪;
• basis:审计依据,通常为适用的法律条款或内部策略 ID。资料来源：mnemo/erasure_auditor.py:30-120

调用后,函数返回包含三组信息的结构化收据:

概述

mnemo 在 1.5.0 版本中以"可验证记忆"为治理与时间维度支柱，提供了两套面向外部系统的接入点：一是作为 Model Context Protocol (MCP) 服务器运行的统一部署入口 mnemo_mcp.py；二是位于 mnemo/integrations/ 目录下的多框架适配器集合，覆盖当前主流的智能体编排与 RAG 框架。两者配合，使 mnemo 的记忆读写、双时态审计与 ErasureAuditor.compliance_receipt() 生成的"擦除证明"回执能够以最小侵入方式注入到既有 Agent 与 LLM 应用栈中。

资料来源：mnemo/mnemo_mcp.py:1-80、mnemo/integrations/__init__.py:1-40。

MCP 服务器部署

mnemo_mnemo_mcp.py（仓库中实际文件名为 mnemo_mcp.py）以独立进程形式对外暴露 mnemo 的核心能力，允许任意 MCP 兼容客户端（例如 IDE 插件、Agent Runtime）通过标准化协议调用记忆存储、检索与擦除审计接口。其部署拓扑通常表现为：

flowchart LR
    Client[MCP 客户端<br/>IDE / Agent Host] -->|stdio / SSE| Server[mnemo_mcp.py]
    Server --> Core[mnemo 核心 API]
    Server --> Auditor[ErasureAuditor]
    Auditor --> Receipt[compliance_receipt<br/>proof-of-erasure]
    Core --> Stores[(向量库 / KV / 图存储)]

部署时只需将 mnemo_mcp.py 注册到宿主应用的 MCP server 清单中，由宿主按需拉起进程；compliance_receipt() 返回的签名回执可直接写入审计日志或转发给监管方，满足 GDPR Art. 17 / EU AI Act 的留痕要求。

资料来源：mnemo/mnemo_mcp.py:1-120。

主流框架适配器

mnemo/integrations/__init__.py 作为包入口，集中重导出各框架适配器，避免业务代码直接依赖具体实现。

适配器层保持"薄封装"风格：在不破坏各框架既有调用约定的前提下，桥接 mnemo 的 read / write / forget 与 ErasureAuditor.compliance_receipt()，从而让任何宿主框架都能立即获得"可证明遗忘"能力。

资料来源：mnemo/integrations/__init__.py:1-30、mnemo/integrations/autogen.py:1-90、mnemo/integrations/langgraph.py:1-90、mnemo/integrations/llamaindex.py:1-90、mnemo/integrations/openai_agents.py:1-90。

部署模式与最佳实践

单进程嵌入式部署：在同一 Python 进程中通过 integrations 包直接实例化适配器，适合 LangGraph、LlamaIndex 等与业务强耦合的场景，启动开销最低。

MCP 独立服务部署：以 mnemo_mcp.py 作为独立服务运行，供多个 Agent 进程共享一份记忆与审计状态。compliance_receipt(subject, values, sign=, pubkey=, request_id=, basis=) 在此模式下可被集中调度，生成统一签名的擦除证明，便于跨系统合规归档。

混合部署：核心记忆与审计以 MCP 服务形式提供，前端框架（AutoGen / OpenAI Agents）通过本地适配器调用，既保留各框架的开发体验，又获得统一的治理层。社区反馈显示，混合模式在多 Agent 协同 + 强合规场景（如金融、医疗）下被采用最广。

无论选择哪种模式，都建议在初始化时显式配置 pubkey 与 request_id 命名规范，使所有 compliance_receipt 输出可在事后串联为完整的双时态审计链。

资料来源：mnemo/integrations/__init__.py:1-40、mnemo/mnemo_mcp.py:80-160。

Pitfall Log / 踩坑日志

项目：DanceNitra/mnemo

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

1. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/DanceNitra/mnemo | README/documentation is current enough for a first validation pass.

2. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/DanceNitra/mnemo | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/DanceNitra/mnemo | no_demo; severity=medium

4. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/DanceNitra/mnemo | no_demo; severity=medium

5. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/DanceNitra/mnemo | issue_or_pr_quality=unknown

6. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/DanceNitra/mnemo | release_recency=unknown