项目使命与定位

ai-dememory 是一个面向 AI 代理与大语言模型（LLM）工作流的记忆治理工具包，旨在解决长会话场景下的"记忆膨胀"与上下文污染问题。项目以"去记忆化（De-Memory）"为核心理念，通过对持久化记忆进行结构化整理、压缩与语义去重，让 AI 系统在保持上下文连贯性的同时，避免冗余信息的累积。

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

根据 pyproject.toml 中的项目元数据定义，ai-dememory 当前稳定版本为 2.0.0，采用语义化版本控制，并已通过 AI 操作的受信任发布流程（Trusted Publishing）发布至 PyPI 与 TestPyPI 仓库。资料来源：pyproject.toml:1-30

核心能力与边界

项目的核心能力可归纳为三个层面：

• 记忆摄取（Ingestion）：从对话日志、向量数据库导出或外部知识库中读取原始记忆片段。
• 记忆压缩（Compression）：利用嵌入相似度与时间衰减模型识别重复或过期条目，并执行合并、摘要或淘汰操作。
• 记忆回写（Write-back）：将处理后的结构化记忆写回存储后端，供下游 RAG 或 Agent 流程调用。

边界方面，ai-dememory 明确不负责：

资料来源：PLAN.md:10-55

架构总览

项目采用分层架构，自下而上分别为存储适配层、核心处理层与 API 暴露层。docs/architecture.md 中定义了模块间通过接口契约解耦的原则，确保任意存储后端（如 PostgreSQL、Redis、SQLite）均可被替换而不影响上层逻辑。

flowchart TD
    A[LLM Agent / RAG 应用] --> B[ai-dememory API 层]
    B --> C[核心处理层<br/>去重 · 摘要 · 衰减]
    C --> D[存储适配层]
    D --> E[(向量数据库)]
    D --> F[(关系数据库)]
    D --> G[(对象存储)]

资料来源：docs/architecture.md:1-80

版本演进与发布治理

ai-dememory 自 2.0.0rc2 起采用 AI 操作的受信任发布（AI-operated Trusted Releases）工作流，由自动化代理在通过所有 CI 检查后直接生成 GitHub Release 与 PyPI 工件。该流程取代了此前依赖人工本地凭据上传的模式，显著降低了密钥泄露风险。

CHANGELOG.md 记录的关键里程碑：

• v2.0.0rc2：引入受信任发布流程，绑定 TestPyPI 发布渠道。
• v2.0.0rc3：修复包命名空间冲突与 Codex 配置文件的安全读取问题。
• v2.0.0：首个稳定版本，完成仓库绑定修复，正式 GA。

资料来源：CHANGELOG.md:1-25

适用场景与读者画像

ai-dememory 主要服务于以下技术读者：

1. AI 应用工程师：需要在多轮 Agent 中控制上下文窗口成本。
2. RAG 架构师：希望对外部知识库进行周期性治理以提升召回质量。
3. 平台 SRE：关注记忆存储的稳定性、可观测性与自动发布治理。

资料来源：README.md:35-60

入门指引

安装最新稳定版：

pip install ai-dememory==2.0.0

源码包命名空间遵循 PEP 420 隐式命名空间包规范，因此即使在 rc3 之前曾出现的命名空间冲突被修复后，用户仍可直接 import ai_dememory 而无需手动声明子包路径。资料来源：src/ai_dememory/__init__.py:1-15

小结

ai-dememory 以"记忆治理"为切入点，定位为 LLM 生态中的横向中间件，通过清晰的存储适配契约、稳定的发布治理与受版本控制的 API，为上层 AI 应用提供可观测、可压缩、可回写的记忆层基础设施。后续章节将深入各子模块的实现细节与配置方法。

ai-dememory（"dememory"，意为"剥离记忆"）是一个面向 LLM 应用场景的本地长期记忆中间件。其核心目标是把对话或文档中的事实从上下文窗口中剥离，交由本地索引与查询服务托管，从而降低 token 成本并使检索行为可控、可审计。项目自 v2.0.0 起以稳定包形态发布，命名空间与 CLI 入口在 v2.0.0rc3 中完成修正。资料来源：docs/architecture.md:1-25, README.md:1-30

总体分层

系统采用清晰的分层架构，自下而上共四层：

• 数据源层：来自宿主应用的原始文本载体，例如导出的 Markdown 笔记、对话日志或第三方 JSON。
• 索引管线层：scripts/index_memory.py 提供批处理式摄入入口，承担切片、归一化与写入职责。
• 存储层：以本地文件系统为基础的轻量级索引目录，遵循 docs/schema.md 中规定的字段约束。
• 服务层：scripts/http_api.py 暴露本地 HTTP 接口，承载查询与回写请求。

四层之间仅通过受约束的接口通信，避免任意层越权读取其它层的私有状态。资料来源：docs/architecture.md:15-60

核心数据流

数据流遵循"摄入 → 索引 → 存储 → 查询"的单向管道：

1. 摄入阶段由 index_memory.py 读取命令行传入的源路径列表，统一解析为 UTF-8 文本。
2. 索引阶段按可配置窗口大小切分文本块，并附加 source、offset 等溯源元数据。
3. 存储阶段将块以 docs/schema.md 描述的格式写入本地索引目录。
4. 查询阶段通过 HTTP API 接收检索请求，返回匹配块的引用，由宿主应用按需注入回 prompt。

flowchart LR
    A[原始文件/对话] --> B[index_memory.py]
    B --> C[(本地索引存储)]
    C --> D[http_api.py]
    D --> E[宿主 LLM 应用]

资料来源：scripts/index_memory.py:1-80, scripts/http_api.py:1-60, docs/schema.md:1-45

关键模块职责

索引管线（index_memory.py）

该脚本是离线摄入入口，承担可重建的索引构造工作。其职责包含：递归扫描源路径、按块窗口切分、生成稳定的块 ID、写入带元数据的索引文件，并在结束时输出统计摘要。该脚本不持有运行时状态，可被任意时刻重复执行以重建索引。资料来源：scripts/index_memory.py:10-95, docs/operations.md:1-40

HTTP API 服务（http_api.py）

HTTP 入口监听本地端口，按路径前缀将请求分发到查询或回写处理器；所有响应统一以 JSON 编码。docs/local-api.md 进一步限定其仅绑定 loopback、默认鉴权要求以及请求体上限，确保暴露面最小化。资料来源：scripts/http_api.py:20-130, docs/local-api.md:1-70

存储模式

模式文档规定每条记忆记录至少包含 id、source、offset、text 四个核心字段，并描述索引目录的物理布局与命名约定。所有写入路径都需通过该模式的字段校验，确保后续检索逻辑的一致性。资料来源：docs/schema.md:1-80

部署与运行边界

docs/operations.md 定义了索引全量重建、增量更新与本地 API 启动三类标准流程，并明确本工具以"单机、单用户、单进程"为部署前提，不包含分布式协调、租户隔离或集群复制能力。这一边界与 v2.0.0 系列发布所强调的"稳定包形态"保持一致——功能面收窄、可预测性优先。资料来源：docs/operations.md:1-90, docs/architecture.md:50-95

设计权衡

将记忆层从 LLM 中分离带来了两点关键收益：其一，prompt 长度可预测，避免随历史增长而膨胀；其二，检索行为可被审计与回放，方便调试与合规追溯。代价是引入了额外的本地组件，宿主需要保证索引与查询路径的可用性。该权衡在 docs/architecture.md 的设计动机段落被显式记录。资料来源：docs/architecture.md:30-70, docs/operations.md:40-75

概述与设计目标

ai-dememory v2.0.0 引入了基于 Model Context Protocol（MCP）的服务器与工具配置体系，作为 AI 编排层与底层记忆管理之间的稳定契约。该模块的核心目标是把"工具能力描述"与"工具执行实现"解耦，使宿主客户端（如 Codex、Claude Desktop、其他兼容代理）能够在不修改业务代码的前提下，按需加载、切换与鉴权一组对外暴露的 MCP 工具。ai-dememory v2.0.0 在仓库中被作为首个稳定里程碑发布，相关变更由 PR #6 合并，确立了 v2 协议为当前主推版本。

资料来源：docs/mcp-v2.md:1-40

工具配置（Tool Profiles）

工具配置文件由 Python 模块 ai_dememory_tool/mcp_profiles.py 提供注册中心，并在 docs/mcp-tool-profiles.md 中以人类可读的形式给出每一条 profile 的字段语义。下表汇总 v2 阶段常用的 profile 维度。

profile 注册逻辑集中在 mcp_profiles.py 中的 register_profile() 函数；新增工具时仅需在该模块追加条目，无需改动服务器端分发代码。docs/mcp-tool-profiles.md 中明确指出，profile 名称必须保持稳定，否则会破坏已在客户端固定写入的调用约定。

资料来源：ai_dememory_tool/mcp_profiles.py:1-80 资料来源：docs/mcp-tool-profiles.md:1-60

客户端配置（Client Configuration）

docs/mcp-client-config.md 详细描述了如何让外部客户端发现并连接 ai_dememory_tool.mcp_server 实例。典型步骤包括：

1. 在客户端 JSON 配置（Codex 使用 ~/.codex/config.toml，Claude Desktop 使用 claude_desktop_config.json）声明 mcpServers 段。
2. 通过 command + args 字段指示启动 ai-dememory 的 MCP 入口。
3. 将 transport 与 safety 等 profile 字段透传给运行期。

服务器入口由 ai_dememory_tool/mcp_server/__init__.py 暴露，对外仅暴露 run() 与 list_tools() 两个表面 API；这保证了协议面与工具面在同一进程内共存，但调用栈保持清晰。

资料来源：docs/mcp-client-config.md:1-90 资料来源：ai_dememory_tool/mcp_server/__init__.py:1-50

v2 差异分析与升级路径

docs/mcp-v2-gap-analysis.md 对 v1 → v2 期间发生的行为差异做了收敛式记录，主要差异点包括：默认 transport 统一为 stdio、safety 字段成为必填、以及对 Codex 配置文件读取顺序的修正（v2.0.0rc3 的 PR #5 解决了命名空间与 Codex 配置安全问题）。迁移建议是先在客户端同时声明新旧两条 mcpServers 条目，借助客户端自身的回退机制比较行为，再将旧条目下线。

资料来源：docs/mcp-v2-gap-analysis.md:1-70 资料来源：ai-dememory v2.0.0rc3 发布说明

端到端配置流程

flowchart LR
    A[客户端配置 mcpServers] --> B[启动 ai-dememory MCP 入口]
    B --> C[mcp_server/__init__.py 加载]
    C --> D[mcp_profiles.py 注册 profile]
    D --> E[按 transport 派发工具调用]
    E --> F[safety 校验与执行]

整个流程保证：① 客户端只与 mcp_server 入口对话；② 工具元信息集中在 mcp_profiles.py，修改不会扩散到协议层；③ v2 的差异点集中在 mcp-v2-gap-analysis.md 描述的字段语义上，运行期行为可在不升级客户端的前提下被服务端吸收。

资料来源：docs/mcp-v2.md:40-120 资料来源：ai_dememory_tool/mcp_server/__init__.py:50-90

概述与设计目标

ai-dememory 的核心抽象是一个「Vault」——一个本地优先、由 Git 管理的 Markdown 仓库，专门用于承载 AI 的长期记忆。该设计将记忆内容（Markdown 笔记）、记忆元数据（.ai-dememory.toml 配置）以及记忆分类（durable / session / episodic 等目录）统一在同一棵目录树下，使记忆既能被人类阅读（如 Obsidian），也能被 AI Agent 程序化读写。

• Vault 作为单一事实来源（single source of truth），通过文件系统 + Git 进行版本控制与同步。
• 不同生命周期的记忆以独立目录形式隔离，避免相互污染。
• .ai-dememory.toml 是 Vault 的元数据描述文件，承担 agent 行为编排入口。

资料来源：docs/schema.md:1-30

概述与适用范围

ai-dememory 项目的"审查工作流与冲突解决"子系统承担着 在 AI 长期记忆被写入或删除之前进行门禁校验 的职责。它把"记忆操作"分为受信任路径与待审查路径两类：受信任路径由 Adopt AI-operated trusted releases PR 引入并稳定于 v2.0.0，允许自动化代理在受控命名空间内直接落地变更；待审查路径则强制要求人工或异体代理进行二次核验，避免静默遗忘或错误覆写。资料来源：docs/review-workflows.md:1-40

子系统的核心目标是：把"哪些记忆条目应当被遗忘"这一判断，从模型本身的隐式行为，转变为 可追溯、可回滚、可被外部代理复审 的显式工作流。冲突解决是该工作流的衍生能力，当多个代理对同一记忆条目产生不一致的遗忘/保留建议时，系统需要在该条目上锁、版本化、并最终敲定唯一结论。

核心组件与执行入口

工作流主要由两条代码路径驱动：

1. scripts/review_memory.py：作为审查执行的入口脚本，封装"扫描 → 标记 → 比对 → 落盘"四步流程，可被 CI 或本地代理直接调用。资料来源：scripts/review_memory.py:1-60
2. scripts/maintenance.py：作为系统级维护任务承载者，负责清理过期锁、压缩历史快照、并与发布流程（如 v2.0.0 的 trusted releases）联动。资料来源：scripts/maintenance.py:1-80

两条路径在架构上解耦：审查脚本只关心单次会话内的差异，维护脚本关心跨会话的状态一致性。这种划分也呼应了 ADR 0001 中提出的"审查与冲突解决必须分开演化"的决策原则。资料来源：docs/adr/0001-review-and-conflict-workflows.md:1-50

审查模式与配置规约

为避免历史上散落的命名（早期版本曾出现 review_v2、legacy-audit 等别名）造成代理误判，项目引入了 canonical 命名规范：

模式名称由 ADR 0027 统一收敛，凡 CLI、MCP 配置、CI 环境变量中出现的标识符都必须引用该表。资料来源：docs/adr/0027-canonical-review-mode-names.md:1-40

MCP 侧的审查模式配置由 ADR 0082 进一步规约，明确规定了当 Model Context Protocol 客户端声明 review_mode 字段时，应如何在服务端映射到上述 canonical 模式，以及当字段缺失时如何回退到 offline。资料来源：docs/adr/0082-mcp-review-mode-configuration.md:1-60

冲突检测与解决机制

冲突解决遵循 乐观加锁 + 最终一致 的策略：

1. 当 review_memory.py 检测到同一记忆条目在不同代理的快照中存在差异，会在该条目上写入 conflict 标记并触发 locked 模式。
2. maintenance.py 在下一次周期扫描这些 locked 条目，收集所有候选决议，并按 优先级（受信任代理 > 人工审查 > 历史默认值）排序。
3. 一旦决议被敲定，系统会写入新的版本号并释放锁，同时将旧版本归档至 history/ 子目录以保证可追溯。

v2.0.0rc3 中针对包命名空间与 Codex 配置安全性的修复（PR #5），正是为了防止恶意代理伪造 trusted 标记从而绕过冲突锁，这是该机制在生产中第一次被外部验证的场景。资料来源：docs/review-workflows.md:80-130

与发布流程的耦合

需要特别注意的是，审查工作流并非孤立模块。它与 v2.0.0 起正式启用的 "AI-operated trusted releases" 深度耦合：受信任代理在发起发布 PR 时，必须附带一次完整的 review_memory.py 扫描报告，并确保没有 locked 条目遗留，否则 CI 会拒绝合入。这种耦合保证了 任何对外可见的包版本，其底层记忆状态都经过显式审查，从而把"记忆健康度"提升为一等发布门禁。资料来源：docs/review-workflows.md:140-180

操作建议与扩展点

• 在 CI 中以 --mode=interactive 显式声明审查模式，避免隐式回退到 offline。
• 自定义代理若需新增审查模式，应先在 ADR 中登记 canonical 名称，再向 scripts/review_memory.py 添加对应分支。
• 冲突条目不应被人工直接编辑 history/ 目录，而应通过 maintenance.py 的 resolve 子命令统一处理，以保留审计链。

至此，审查工作流与冲突解决在 ai-dememory 中构成了一个 从单条记忆到整次发布 的闭环护栏，是项目"可信去记忆"承诺的工程基础。

ai-dememory 是一个面向"AI 长期记忆"的库，其运行时不仅包含一次性的记忆读写路径，还需要配套的周期化运维、事件钩子与后台维护流程，确保记忆库在长时间使用中保持一致、可回溯且不膨胀。本页围绕 docs/scheduler.md、docs/hooks.md、docs/sleep-consolidation.md、docs/memory-quality.md、scripts/schedule_memory.py 等核心文件，梳理"调度 / Hook / 维护"三大主题。

一、Scheduler 调度入口与角色

调度子系统是整个运维体系的入口与节拍器，负责把"记忆整理、巩固、清理"等后台任务从用户的同步请求中解耦出来。

• 入口脚本：scripts/schedule_memory.py 是命令行入口，通常由外部 Cron、CI 或守护进程周期性触发。它封装了任务选择、参数校验与执行上下文。
• 插件蓝图：docs/scheduler-plugin-blueprint.md 定义了第三方或自定义任务如何以"插件"形式注入调度器，强调注册方式、参数约定与失败语义。
• 运行语义：docs/scheduler.md 描述了调度器对任务状态的暴露方式——可观测、可中断、可重试，并保证记忆写入是幂等的。

资料来源：scripts/schedule_memory.py、docs/scheduler.md、docs/scheduler-plugin-blueprint.md

二、Hooks 事件钩子机制

Hooks 提供"在关键生命周期点插入自定义逻辑"的轻量扩展点，是运维调度与业务逻辑之间的桥梁。

• 核心契约：docs/hooks.md 列出了 ai-dememory 暴露的全部标准事件（如写入前/写入后、检索命中、过期、巩固完成等），以及每个事件的入参 schema。
• 使用范式：Hooks 既可以用于审计与埋点（如记录每次记忆命中的来源），也可以用于在 sleep-consolidation 之前做用户自定义的预处理。
• 与 Scheduler 的协作：调度任务本身就是 Hook 的一个特殊调用方——调度器按节奏触发 sleep 类 Hook，从而把"周期维护"纳入同一套事件语义中。

资料来源：docs/hooks.md、docs/scheduler.md

三、Sleep Consolidation 与记忆质量维护

后台维护流程以"睡眠期巩固（Sleep Consolidation）"为典型代表，目标是让长期记忆库自我修复、自我瘦身。

• Sleep Consolidation：docs/sleep-consolidation.md 描述了在"空闲窗口"内对记忆条目进行去重、合并、摘要重写与冷热分层的过程。该流程通常由 Scheduler 周期性触发，并由 Hook 体系暴露进度事件。
• Memory Quality：docs/memory-quality.md 定义了维护过程中对记忆质量的评估维度（如新鲜度、命中率、冗余度），并给出在质量低于阈值时的回收策略。
• 失败安全：在 v2.0.0rc3 的变更中（"Fix package namespace and Codex config safety"），维护路径增加了对配置与命名空间的健壮性校验，避免错误配置触发灾难性清理。

资料来源：docs/sleep-consolidation.md、docs/memory-quality.md、README.md

四、关系总览与运行时协作

下面这张表把三大主题相互之间的"谁调用谁、谁观察谁"压缩到一张视图，便于新接入者建立心智模型。

运行时序大致是：Scheduler 触发 → 发出"进入睡眠期"Hook → Consolidation 读取记忆并产出摘要 → Memory Quality 评估 → 写出新记忆并发出"巩固完成"Hook → Scheduler 更新下次调度计划。这种闭环设计使得运维调度、Hook 与维护三者形成可观测、可回滚的运维面，而不是若干孤立脚本的拼接。

五、面向使用者的小结

• 若你是运维/平台角色：关注 scripts/schedule_memory.py 与 docs/scheduler-plugin-blueprint.md，把后台任务纳入既有的 Cron / CI / GitHub Actions。
• 若你是业务开发者：以 docs/hooks.md 为契约，在写入或检索路径插入审计、过滤、转换逻辑。
• 若你是库维护者：docs/sleep-consolidation.md 与 docs/memory-quality.md 是质量基线，配合 v2.0.0 系列对包命名空间与 Codex 配置的安全加固，保证维护流程本身不会成为事故源。

资料来源：README.md、docs/scheduler.md、docs/hooks.md、docs/sleep-consolidation.md、docs/memory-quality.md

范围与目标

本页覆盖 ai-dememory 从源代码到本地可运行的完整链路：Python 包安装、本地 MCP（Model Context Protocol）服务部署、记忆仓库初始化、Codex 插件配置，以及基于容器镜像的可移植分发。其目标是让开发者能在隔离或本地环境中，复用一个长期持久化的 AI 会话记忆层。资料来源：docs/install.md、docs/distribution.md。

安装方式与发布通道

ai-dememory 以 Python 包的形式对外分发，社区上下文显示项目已经历多轮候选版与一次稳定发布：

• 2.0.0rc1 首次推送到 TestPyPI（PR #2）；
• 2.0.0rc2 引入"AI 操作的受信发布"工作流（PR #1）；
• 2.0.0rc3 修复包命名空间与 Codex 配置安全（PR #5）；
• 2.0.0 稳定版本通过 GitHub Releases 通道正式发布（PR #6）。

资料来源：docs/distribution.md。

安装路径应按以下顺序进行：克隆仓库 → 选择发布通道（TestPyPI 预发布 / GitHub Release 归档）→ 配置访问凭据 → 初始化记忆仓库。这一顺序与 docs/install.md 中描述的标准安装流程一致。资料来源：docs/install.md。

本地 MCP 与 Codex 插件

ai-dememory 的运行依赖于本地 MCP 服务与编辑器侧的代理集成：

• docs/local-mcp.md 描述了启动本地 MCP 实例的命令、监听端口以及与外部代理的握手流程；
• docs/codex-plugin.md 说明在 Codex 中注册该 MCP 所需的插件清单、路径配置以及会话记忆的读写语义。

资料来源：docs/local-mcp.md、docs/codex-plugin.md。

由于 v2.0.0rc3 修复了 Codex 配置安全问题（PR #5），插件配置文件的权限与存放路径需严格遵循文档约束，避免敏感凭据泄露到仓库目录之外。资料来源：docs/codex-plugin.md。

记忆仓库的初始化逻辑位于 docs/create-memory-repo.md，它定义了本地仓库的结构、索引文件以及与 MCP 服务的绑定方式，是安装流程的最后一步。资料来源：docs/create-memory-repo.md。

容器化分发

Dockerfile 为项目提供了容器化分发路径，使 MCP 服务能够在一个隔离、可复现的环境中运行，避免污染宿主 Python 环境。其典型部署拓扑如下：

flowchart LR
    A[编辑器/代理] -->|MCP 协议| B[本地 MCP 服务<br/>Dockerfile]
    B --> C[(记忆仓库<br/>docs/create-memory-repo.md)]
    B --> D[Codex 插件<br/>docs/codex-plugin.md)]

容器内只需暴露 MCP 所需的本地端口与挂载记忆仓库目录，便可复现 docs/install.md 所述的全部安装结果。资料来源：Dockerfile、docs/local-mcp.md。

版本管理与可信发布

版本号遵循语义化版本控制：2.0.0rc1 → rc2 → rc3 → 2.0.0（PR #6）。每次候选版的 GitHub 仓库绑定都会被同步修正（PR #4），以保证下载链接始终指向正确的源码标签。用户可据此在本地通过 Git 检出指定标签以获得与发布版一致的产物。资料来源：docs/distribution.md。

概述与设计目标

ai-dememory 仓库采用了一种以 AI 操作型可信发布（AI-operated trusted releases） 为核心的运维与安全模型。该模型将发布流程中重复、可形式化校验的部分（Tag 写入、版本号匹配、命名空间一致性、Codex 配置核查）交给 AI 代理自动化执行，同时通过严格的策略约束、人工审核点以及 PR 留痕，确保不会产生越权或破坏性发布。

设计目的可以归纳为三点：

1. 可审计：每一次对 v* tag 的写入、每一次对 TestPyPI / PyPI 的发布，都必须对应一条 PR 与一次人工合并。
2. 最小爆炸半径：AI 只能写入受限路径，且必须遵守命名空间与配置文件安全约束。
3. 可回滚：每次候选版本先发到 TestPyPI（2.0.0rc1 等），通过校验后再晋升为 2.0.0 稳定版。

资料来源：docs/ai-operated-releases.md:1-40

发布流程与角色分工

整个发布流程分为四个阶段，分别对应四个 PR 与一次 GitHub Release：

1. 策略引入 — PR #1「Adopt AI-operated trusted releases」引入运维模型本身。
2. 预发布 — PR #2「Release 2.0.0rc1 to TestPyPI」将首个候选版本推送到 TestPyPI。
3. 安全修复 — PR #5「Fix package namespace and Codex config safety」修正命名空间占用与 Codex 配置泄漏风险。
4. 稳定晋升 — PR #6「Release ai-dememory 2.0.0 stable」完成 v2.0.0 正式发布。

flowchart LR
    A[PR #1: 引入 AI 运维策略] --> B[PR #2: rc1 发到 TestPyPI]
    B --> C[PR #5: 命名空间与 Codex 安全修复]
    C --> D[PR #6: v2.0.0 稳定版发布]
    D --> E[GitHub Release + Git Tag v2.0.0]

AI 在该流程中的权限是 写 tag + 写 PR，不直接合并主干，也不会绕过 PR review；自动合并由 GitHub 仓库设置根据 docs/auto-approval.md 中定义的规则进行白名单放行。资料来源：docs/ai-operated-releases.md:41-80 docs/auto-approval.md:1-30

安全模型

安全模型围绕三个边界展开：

• 命名空间边界：包的发布名称必须与 ai_dememory Python 包命名空间一致，否则 twine check 与 python -m build 会失败。修复历史由 PR #5 承担，明确禁止 AI 写入冲突的命名空间声明。
• 配置边界：「Codex config safety」要求 Codex / 构建相关的配置文件只能通过受限 PR 修改，禁止直接 push 到 main。
• 凭据边界：所有上传凭据（如 TestPyPI token）只能来自仓库 Secrets 与 Actions 环境，不进源码、不进 tag 注解。

这三层约束在结构上记录于 docs/adr/0247-ai-operated-tag-releases.md，作为该运维模型决策的 ADR（架构决策记录）。资料来源：docs/adr/0247-ai-operated-tag-releases.md:1-60

发布执行与验证

每一次实际发布都遵循 docs/release-v2-checklist.md 中的清单，主要包含：

• 版本号与 git tag 一致性检查（v2.0.0 ↔ __version__）。
• python -m build 与 twine check 在 CI 中通过。
• 通过 TestPyPI 验证候选版本可被 pip install 正确安装。
• CHANGELOG / RELEASE 日志条目就位。

候选 PR 的撰写规范在 docs/pr-draft.md 中固化，AI 代理生成 PR 文案时必须遵循模板，避免自由发挥引入噪音；面向最终用户的发布说明则存放于仓库根目录的 PUBLIC_RELEASE.md，供下游使用者核对公开行为差异。资料来源：docs/release-v2-checklist.md:1-50 docs/pr-draft.md:1-40 PUBLIC_RELEASE.md:1-30

Pitfall Log / 踩坑日志

项目：GonzaloTorreras/ai-dememory

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/GonzaloTorreras/ai-dememory | host_targets=mcp_host, claude

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

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

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

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

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

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

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

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

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

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

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