# https://github.com/GonzaloTorreras/ai-dememory 项目说明书

生成时间：2026-07-12 08:29:47 UTC

## 目录

- [项目概览与核心定位](#page-1)
- [系统架构与数据流](#page-2)
- [MCP v2 服务器与工具配置](#page-3)
- [记忆数据模型与 Vault 布局](#page-4)
- [审查工作流与冲突解决](#page-5)
- [运维调度、Hook 与维护](#page-6)
- [安装、部署与本地分发](#page-7)
- [AI 运维发布与安全模型](#page-8)

<a id='page-1'></a>

## 项目概览与核心定位

### 相关页面

相关主题：[系统架构与数据流](#page-2), [AI 运维发布与安全模型](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/README.md)
- [PLAN.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/PLAN.md)
- [CHANGELOG.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/CHANGELOG.md)
- [docs/architecture.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/architecture.md)
- [pyproject.toml](https://github.com/GonzaloTorreras/ai-dememory/blob/main/pyproject.toml)
- [src/ai_dememory/__init__.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/src/ai_dememory/__init__.py)
</details>

# 项目概览与核心定位

## 项目使命与定位

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 明确不负责：

| 不在范围内 | 说明 |
|------------|------|
| LLM 推理引擎 | 仅作为记忆层中间件 |
| 用户身份认证 | 假定由上层应用托管 |
| 实时对话路由 | 不参与请求分发 |

资料来源：[PLAN.md:10-55]()

## 架构总览

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

```mermaid
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]()

## 入门指引

安装最新稳定版：

```bash
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 应用提供可观测、可压缩、可回写的记忆层基础设施。后续章节将深入各子模块的实现细节与配置方法。

---

<a id='page-2'></a>

## 系统架构与数据流

### 相关页面

相关主题：[项目概览与核心定位](#page-1), [MCP v2 服务器与工具配置](#page-3), [记忆数据模型与 Vault 布局](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/architecture.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/architecture.md)
- [docs/schema.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/schema.md)
- [docs/operations.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/operations.md)
- [docs/local-api.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/local-api.md)
- [scripts/index_memory.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/scripts/index_memory.py)
- [scripts/http_api.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/scripts/http_api.py)
</details>

# 系统架构与数据流

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。

```mermaid
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]()

---

<a id='page-3'></a>

## MCP v2 服务器与工具配置

### 相关页面

相关主题：[系统架构与数据流](#page-2), [AI 运维发布与安全模型](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/mcp-v2.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/mcp-v2.md)
- [docs/mcp-v2-gap-analysis.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/mcp-v2-gap-analysis.md)
- [docs/mcp-tool-profiles.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/mcp-tool-profiles.md)
- [docs/mcp-client-config.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/mcp-client-config.md)
- [ai_dememory_tool/mcp_profiles.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/ai_dememory_tool/mcp_profiles.py)
- [ai_dememory_tool/mcp_server/__init__.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/ai_dememory_tool/mcp_server/__init__.py)
</details>

# MCP v2 服务器与工具配置

## 概述与设计目标

`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 维度。

| 字段 | 用途 | 说明 |
| --- | --- | --- |
| `name` | 工具唯一标识 | 客户端引用此 key 触发调用 |
| `transport` | 传输方式 | 当前支持 `stdio` 与 `http` |
| `requires` | 依赖声明 | 列出运行所需的二进制或环境变量 |
| `safety` | 信任级别 | 影响 Codex 端的二次确认策略 |

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 发布说明](https://github.com/GonzaloTorreras/ai-dememory/releases/tag/v2.0.0rc3)

## 端到端配置流程

```mermaid
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]()

---

<a id='page-4'></a>

## 记忆数据模型与 Vault 布局

### 相关页面

相关主题：[系统架构与数据流](#page-2), [审查工作流与冲突解决](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/schema.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/schema.md)
- [docs/create-memory-repo.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/create-memory-repo.md)
- [docs/obsidian.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/obsidian.md)
- [ai_dememory_tool/templates/vault/.ai-dememory.toml](https://github.com/GonzaloTorreras/ai-dememory/blob/main/ai_dememory_tool/templates/vault/.ai-dememory.toml)
- [vault-template/.ai-dememory.toml](https://github.com/GonzaloTorreras/ai-dememory/blob/main/vault-template/.ai-dememory.toml)
- [vault-template/memories/durable/README.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/vault-template/memories/durable/README.md)
</details>

# 记忆数据模型与 Vault 布局

## 概述与设计目标

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 将记忆按持久性与用途划分为多类，分别存放在 `vault-template/memories/` 下的独立目录中。当前仓库内置的层级包括：

| 目录 | 层级 | 典型用途 |
|------|------|----------|
| `durable/` | 持久型 | 跨会话、跨任务保留的核心事实与约定 |
| `session/` | 会话型 | 单次 agent 运行上下文（结构由模板定义） |
| `episodic/` | 情景型 | 任务事件流与时间戳日志 |

`durable` 层的 README 明确说明了其定位：「稳定、可追溯、面向长期事实」，并要求所有变更通过 Git 提交可审计。

资料来源：[vault-template/memories/durable/README.md:1-25]()
资料来源：[docs/schema.md:31-90]()

### 笔记 Schema

每条记忆本质上是一份带 frontmatter 的 Markdown 文件。schema 文档规定了 frontmatter 的最小字段集，至少包含：

- `id`：由目录路径 + 文件名派生的稳定标识符，确保 AI 重新读取时能定位到同一条记忆。
- `created_at` / `updated_at`：ISO8601 时间戳，用于事件排序。
- `tags`：用于检索与分桶的可选标签数组。
- `source`：标识该记忆由 user、agent 或外部工具写入。

正文部分为自由 Markdown，便于在 Obsidian 中渲染与跨工具共享。

资料来源：[docs/schema.md:40-110]()

### 关系与引用

记忆之间通过 Markdown 链接 `[[wikilink]]` 建立显式引用，AI 在加载 Vault 时会沿链接建立小型图结构，从而支持「回忆关联上下文」的能力。schema 文档建议避免深度嵌套，以保持图扁平可遍历。

资料来源：[docs/schema.md:90-140]()

---

## Vault 布局

### 目录骨架

一个标准 Vault 的根目录如下：

```
vault/
├── .ai-dememory.toml          # Vault 元配置
├── memories/
│   ├── durable/               # 持久型记忆
│   │   └── README.md
│   ├── session/               # 会话型记忆
│   └── episodic/              # 情景型记忆
└── notes/                     # 用户自有笔记（可选）
```

模板配置同时维护在 `vault-template/`（仓库内置示例）与 `ai_dememory_tool/templates/vault/`（CLI 创建 Vault 时复制使用），两者的 `.ai-dememory.toml` 字段命名保持一致。

资料来源：[vault-template/.ai-dememory.toml:1-40]()
资料来源：[ai_dememory_tool/templates/vault/.ai-dememory.toml:1-40]()

### `.ai-dememory.toml` 关键字段

该 TOML 文件位于 Vault 根目录，承担三方面职责：声明 Vault 元信息、配置 agent 行为、指向记忆分类目录。典型字段包括：

- `[vault]`：`name`、`owner`、`version`。
- `[memories]`：`durable_dir`、`session_dir`、`episodic_dir`，以相对路径形式指定各层级位置。
- `[agent]`：`default_model`、`max_context_tokens` 等运行参数。
- `[sync]`：Git 远程、上游分支与冲突处理策略。

CLI 在 `create-memory-repo` 流程中读取该文件并据此生成缺失目录，从而保证任何 Vault 实例都拥有相同的最小布局契约。

资料来源：[ai_dememory_tool/templates/vault/.ai-dememory.toml:5-60]()
资料来源：[docs/create-memory-repo.md:1-60]()

---

## 与 Obsidian 的协作

由于 Vault 本身就是合法 Markdown 仓库，ai-dememory 提供了 Obsidian 适配层：

- 在 `.obsidian/` 中预设 `app.json`，关闭会破坏 frontmatter 的渲染行为。
- 启用「Markdown links」而非 Wiki-links 选项，使 agent 生成的 `[[id]]` 与 `(` 链接在双端都可解析。
- 文档 `docs/obsidian.md` 给出了从 Obsidian 新建 Vault、`Symlink` 到 ai-dememory 工作区、以及启用 Dataview 插件进行检索的步骤。

```mermaid
flowchart LR
  A[用户] --> B[Obsidian Vault]
  B --> C[.ai-dememory.toml]
  B --> D[memories/durable]
  B --> E[memories/session]
  B --> F[memories/episodic]
  C --> G[ai-dememory CLI]
  D --> G
  E --> G
  F --> G
  G --> H[Git Remote]
```

资料来源：[docs/obsidian.md:1-80]()
资料来源：[docs/create-memory-repo.md:20-70]()

---

## 实践约束

- **只追加优于就地编辑**：`durable` 层建议仅通过 PR/提交新增，避免覆盖历史事实。
- **目录即命名空间**：相同 `id` 在不同层级语义不同，禁止跨层级同名而无前缀。
- **Git 作为审计通道**：所有 `episodic` 与 `session` 层在合并前应通过 diff 复核。

资料来源：[docs/schema.md:140-180]()
资料来源：[vault-template/memories/durable/README.md:10-30]()

---

<a id='page-5'></a>

## 审查工作流与冲突解决

### 相关页面

相关主题：[记忆数据模型与 Vault 布局](#page-4), [运维调度、Hook 与维护](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/review-workflows.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/review-workflows.md)
- [scripts/review_memory.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/scripts/review_memory.py)
- [docs/adr/0001-review-and-conflict-workflows.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/adr/0001-review-and-conflict-workflows.md)
- [docs/adr/0027-canonical-review-mode-names.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/adr/0027-canonical-review-mode-names.md)
- [docs/adr/0082-mcp-review-mode-configuration.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/adr/0082-mcp-review-mode-configuration.md)
- [scripts/maintenance.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/scripts/maintenance.py)
</details>

# 审查工作流与冲突解决

## 概述与适用范围

`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 命名规范**：

| 模式名 | 触发条件 | 适用场景 |
| --- | --- | --- |
| `trusted` | Codex 配置通过安全校验 | 受信任代理的自动落地 |
| `interactive` | 检测到 MCP 客户端在线 | 通过 MCP 进行交互式复核 |
| `offline` | 无外部代理可达 | 单机/沙箱环境的人工审查 |
| `locked` | 存在未解决的冲突条目 | 阻塞进一步写入 |

模式名称由 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` 中构成了一个 **从单条记忆到整次发布** 的闭环护栏，是项目"可信去记忆"承诺的工程基础。

---

<a id='page-6'></a>

## 运维调度、Hook 与维护

### 相关页面

相关主题：[记忆数据模型与 Vault 布局](#page-4), [审查工作流与冲突解决](#page-5), [安装、部署与本地分发](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/scheduler.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/scheduler.md)
- [docs/scheduler-plugin-blueprint.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/scheduler-plugin-blueprint.md)
- [docs/hooks.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/hooks.md)
- [docs/sleep-consolidation.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/sleep-consolidation.md)
- [docs/memory-quality.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/memory-quality.md)
- [scripts/schedule_memory.py](https://github.com/GonzaloTorreras/ai-dememory/blob/main/scripts/schedule_memory.py)
- [README.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/README.md)
</details>

# 运维调度、Hook 与维护

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 (`schedule_memory.py`) | 节拍与任务编排 | Cron / CI / 守护进程 | Hooks、Consolidation |
| Hooks (`docs/hooks.md`) | 生命周期扩展点 | Scheduler、业务写入路径 | Consolidation、Quality 评估 |
| Sleep Consolidation | 去重/合并/分层 | Hook（由 Scheduler 调度） | Memory Quality |
| Memory Quality | 评估与回收决策 | Consolidation 完成事件 | 写入路径反馈 |

运行时序大致是：**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]()

---

<a id='page-7'></a>

## 安装、部署与本地分发

### 相关页面

相关主题：[项目概览与核心定位](#page-1), [MCP v2 服务器与工具配置](#page-3), [AI 运维发布与安全模型](#page-8)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/install.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/install.md)
- [docs/distribution.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/distribution.md)
- [docs/local-mcp.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/local-mcp.md)
- [docs/create-memory-repo.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/create-memory-repo.md)
- [docs/codex-plugin.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/codex-plugin.md)
- [Dockerfile](https://github.com/GonzaloTorreras/ai-dememory/blob/main/Dockerfile)
</details>

# 安装、部署与本地分发

## 范围与目标

本页覆盖 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 环境。其典型部署拓扑如下：

```mermaid
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]()。

---

<a id='page-8'></a>

## AI 运维发布与安全模型

### 相关页面

相关主题：[项目概览与核心定位](#page-1), [运维调度、Hook 与维护](#page-6), [安装、部署与本地分发](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [docs/ai-operated-releases.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/ai-operated-releases.md)
- [docs/auto-approval.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/auto-approval.md)
- [docs/release-v2-checklist.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/release-v2-checklist.md)
- [docs/pr-draft.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/pr-draft.md)
- [PUBLIC_RELEASE.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/PUBLIC_RELEASE.md)
- [docs/adr/0247-ai-operated-tag-releases.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/adr/0247-ai-operated-tag-releases.md)
</details>

# AI 运维发布与安全模型

## 概述与设计目标

`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` 正式发布。

```mermaid
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](https://github.com/GonzaloTorreras/ai-dememory/blob/main/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](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/adr/0247-ai-operated-tag-releases.md)，作为该运维模型决策的 ADR（架构决策记录）。资料来源：[docs/adr/0247-ai-operated-tag-releases.md:1-60]()

## 发布执行与验证

每一次实际发布都遵循 [docs/release-v2-checklist.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/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](https://github.com/GonzaloTorreras/ai-dememory/blob/main/docs/pr-draft.md) 中固化，AI 代理生成 PR 文案时必须遵循模板，避免自由发挥引入噪音；面向最终用户的发布说明则存放于仓库根目录的 [PUBLIC_RELEASE.md](https://github.com/GonzaloTorreras/ai-dememory/blob/main/PUBLIC_RELEASE.md)，供下游使用者核对公开行为差异。资料来源：[docs/release-v2-checklist.md:1-50]() [docs/pr-draft.md:1-40]() [PUBLIC_RELEASE.md:1-30]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: GonzaloTorreras/ai-dememory; human_manual_source: deepwiki_human_wiki -->