# MemRelay Agent 工作流

在整个任务中把 MemRelay 作为用户规则、项目上下文、开发进度、可复用凭证和共享文件的持久来源。信息一旦明确就记录，不要等到会话结束再凭印象补写。

## 每次会话开始

1. 调用 `capabilities_get`，确认当前可用工具和依赖状态。
2. 使用已知的当前目录、Git remote 和项目名称调用 `project_resolve_or_create`。它会优先解析已有项目，仅在没有匹配项时创建项目，并保留返回的 `created` 结果。
3. 开始实质工作前调用 `context_get` 和 `checkpoint_get`。直接继承已有规则、决定、事实、经验和最新进度，不要求用户重复说明。
- 调用 `capabilities_get` 后，如果客户端支持 MCP Resource，再读取 `memrelay://guide` 和 `memrelay://capabilities`；以它们作为当前工作流和能力来源。AI 整理、记忆 Git、密码库及其他管理工具只有在能力状态显示可用时才调用。

## 工作过程中持续记录

- 明确规则保存为 `rule`，偏好保存为 `preference`，稳定信息保存为 `fact`，已确认选择及原因保存为 `decision`，可复用问题与方案保存为 `experience`，产品需求保存为 `prd`，可执行计划保存为 `task_list`。
- 持久信息确认后立即调用 `memory_save`。每次逻辑写入使用唯一 request ID，更新已有记忆时携带当前 revision。
- 不把猜测、临时信息、未解决冲突、普通闲聊、重复总结、秘密值或一次性签名地址保存为普通记忆。
- 可复用文档、程序、软件包、构建产物和共享资料放入文件仓储。按需创建目录；上传时先调用 `file_upload_prepare`，再向返回的一次性 `upload_url` 直接执行 HTTP PUT 传输准确字节，并用 `file_upload_status` 确认完成。下载时调用 `file_get` 使用其签名 `download_url`，不要让文件正文经 MCP 中转。维护便于后续搜索的文件元数据。

## 保留完整项目进度

- 每完成一个有意义的阶段，以及会话结束前确有修改时，调用 `checkpoint_save`。
- 检查点记录完成内容、原因、关键实现、验证结果、问题与解决方案和明确下一步；没有实质变化时不创建空检查点。
- 会话结束前的最后一个检查点按交接标准书写：“下一步”和“给下个会话”要让零上下文的新会话直接接手——列出未完成线索、会话中的临时约定和需要避开的坑。
- 每个新聊天窗口都先重新解析项目、读取上下文和最新检查点，再开始修改。

## 同步本地项目文档

- 需要本地文档时调用 `project_export_prepare`，直接运行返回的 PowerShell 或 POSIX 下载命令，把压缩包解压到 `aidocs/`；不要逐条读取记忆后手工重写。
- 确保项目 `.gitignore` 包含 `aidocs/`。

## 账号与凭证

- 执行登录、SSH、数据库、API 或远程操作前先搜索密码库；唯一匹配时直接使用，不再询问用户。
- 获得、生成或修改任何可复用账号、密码、Token、API 密钥、自定义秘密字段或 TOTP 种子后，立即调用 `secret_save`；优先更新已有匹配条目，不创建重复项。
- 秘密值只进入密码库。普通记忆只记录密码库条目名称、用途和不含秘密的操作方法。

## 记忆生命周期

- `memory_list` 默认列出待整理来源；`memory_search` 默认使用 `current`，同时搜索稳定整理文档和新的待整理来源，并按结果中的 `read_tool` 调用 `memory_get` 或 `curated_document_get` 读取正文。
- 已整理和已替代的原始 Markdown 仍保留用于追溯。只有需要限定来源或追查历史证据时才使用 `lifecycle=pending`、`covered`、`superseded`、`archived` 或 `all`；需要让旧来源重新参与整理时调用 `memory_mark_pending`。

## 记忆版本历史

- MemRelay 会自动记录记忆变更。需要追溯时使用记忆仓库状态、历史和差异工具。
- 只有用户明确要求时才恢复单个文档或仓库快照；普通项目开发过程中不要修改远程仓库或版本策略。