MemoryCustodian

1) 安装 MemoryCustodian（选择与您的代理/工作流匹配的路径）: 选择一种安装方法： - 要求您的编码代理从存储库安装技能：https://github.com/waittim/MemoryCustodian - Codex（本地市场）：从检出运行 `codex plugin marketplace add .`，然后运行 `codex plugin add memory-custodian@memory-custodian-dev`。 - Claude Code（插件）：对于本地测试，运行 `claude --plugin-dir .`，或使用 `./install.sh claude` 安装到个人技能中。 - Gemini 风格的代理：使用 `./install.sh gemini` 或 `gemini skills link ./skills/memory-custodian` 安装。 - CLI/源检出：通过 `scripts/memory-custodian ...` 从存储库运行，或使用 `python3 -m pip install -e .` 可编辑安装以获取 `memory-custodian` 命令。

2) 在项目中初始化 MemoryCustodian（每个存储库一次）: 为每个目标项目运行一次初始化： - 如果作为控制台脚本安装：`memory-custodian init --project-root /path/to/project --agent all` - 从源检出：`scripts/memory-custodian init --project-root /path/to/project --agent all` 使用 `--agent codex`、`--agent claude`、`--agent gemini` 或 `--agent all` 来生成您的代理读取的精简引导文件。

3) 了解初始化创建了什么（内存所在的位置）: 初始化在 `docs/memory/` 下创建默认的持久内存集： - `manifest.md`（路由要加载的内容） - `brief.md`（当前项目形态） - `decisions.md`（关键决策） - `constraints.md`（硬性要求） - `do-not-use.md`（被拒绝的路径/墓碑） - `inbox.md`（暂存区） 平台引导文件（例如，`AGENTS.md`、`CLAUDE.md`、`GEMINI.md`）保持精简并指向 `docs/memory/`。

4) 在依赖之前整理生成的摘要: 在 `init` 之后，`brief.md` 以带有 TODO 的脚手架开始。在将内存视为就绪之前，从权威项目源（README、代码、文档）填充它。使用 `memory-custodian status --project-root /path/to/project`（或 `scripts/memory-custodian status ...`）查看摘要是否仍未整理；`status` 和 `check` 报告未整理的摘要。

5) 为任务加载正确的内存（清单优先读取）: 代理的预期工作流程是： 1) 读取 `docs/memory/manifest.md`。 2) 读取 `docs/memory/brief.md`。 3) 仅加载清单标记为与当前任务相关的任务相关文件。 对于手动检查，生成一个上下文包： - `memory-custodian read --project-root /path/to/project --task planning` - `memory-custodian read --project-root /path/to/project --task implementation` - `memory-custodian read --project-root /path/to/project --task artifact`

6) 当某些内容应该在当前聊天中保留时添加持久内存: 使用 CLI 记录决策/约束/偏好/被拒绝的方法： - `memory-custodian add "我们选择了清单优先加载。" --type decision` - `memory-custodian add "持久化同步重试退避。" --type decision --area sync --reason "在启动之间保持重试有界。"` 保持决策条目简短（该工具强制执行令牌指南，并拒绝过长的写入，除非您明确允许长条目）。

7) 仅在相关时启用可选内存模块: 可选模块（例如，规则、配置文件、区域）是选择加入的，除非通过清单启用和路由，否则不会加载。根据需要启用它们： - `memory-custodian enable preferences` - `memory-custodian enable rules/output` - `memory-custodian enable profile/git` - `memory-custodian enable area/frontend` 启用永远不会覆盖现有的模块文件。

8) 使用“do-not-use”保留被拒绝的方法并避免回归: 当您有意拒绝某种方法（例如，存储后端或架构）时，将其记录在 `docs/memory/do-not-use.md` 中（通过编辑或适当的添加/遗忘工作流），以便未来的会话不会重新提出它。

9) 定期检查健康状况和协议兼容性: 运行确定性验证以确保结构、预算和协议元数据正确： - `memory-custodian check --project-root /path/to/project` 使用 `memory-custodian status` 获取快速概览并检测未整理的摘要。

10) 压缩和维护内存（预览优先，安全修改）: 使用维护命令保持内存小而最新： - `memory-custodian compact --project-root /path/to/project` 压缩受到保护且预览优先；仅在审查计划后才应用更改。收件箱压缩是保守的（例如，精确重复的顶级项目符号单元删除和墓碑过滤），并期望代理/人类进行语义提升到决策/约束中。

11) 安全地忘记过时的信息（预览优先）: 使用预览优先的遗忘功能删除或编辑过时的主题： - 预览：`memory-custodian forget "旧部署说明" --mode soft --project-root /path/to/project` - 审查后应用：`memory-custodian forget "旧部署说明" --mode soft --apply --project-root /path/to/project` 广泛匹配需要明确确认（例如，`--allow-broad-match`）。某些情况需要手动重写；该工具将拒绝不安全的整体删除。

12) 在需要时修复或替换现有设置: 如果文件丢失或元数据需要更新而无需覆盖已整理的内容： - 修复：`memory-custodian init --project-root /path/to/project --repair` 如果您有意进行完全替换，请使用预览优先替换，并且仅在正确时才应用： - `memory-custodian init --project-root /path/to/project --replace-existing` - 然后仅当列出的文件应该被替换时才添加 `--apply`。

13) 当工具更新时迁移协议/项目内存版本: 当 `check` 报告旧的或缺失的协议元数据时，离线迁移项目清单： - 预览：`memory-custodian migrate --project-root /path/to/project` - 审查后应用：`memory-custodian migrate --apply --project-root /path/to/project`

14) 在 Windows 与源检出上使用正确的调用: 在 Windows 上，安装控制台命令并使用 `memory-custodian ...`。在任何平台上的存储库检出中，您可以运行 `scripts/memory-custodian ...` 作为包装器。