Persist OS 完全指南：给 AI 编程 Agent 装上「持久记忆」，让每次编码都有据可查
你是否有过这样的经历：AI 编程 Agent（Claude Code、Cursor、Codex）帮你飞快地写了一大段代码，但你问它”为什么要这样设计””之前考虑过哪些方案”，它完全答不上来——因为它的上下文只存在于当前的聊天窗口，上次会话的决策早已被清空。
Git 记录了什么发生了变化，但记不住为什么要这样改。这是 AI 辅助编程时代一个越来越明显的痛点：代码写得快了，但架构决策、设计理由、技术选型的上下文全散落在对话记录里，根本无法追溯。
今天要介绍的 Persist OS 就是专门解决这个问题的——一个本地优先的开源 CLI 工具，为你的仓库建立结构化的、可审计的工程记忆，然后用一个确定性检查器（persist doctor）确保这些记忆始终有效。
什么是 Persist OS
Persist OS 是一个 TypeScript 编写的 CLI 工具（MIT 许可证），它的核心理念可以用一句话概括：把”为什么这么写”沉淀到仓库里，让它像代码一样可审计、可回溯。
具体来说，它会创建一个结构化记忆层，包含以下内容：
- 产品意图：当前版本的目标是什么，解决了什么问题
- 架构决策（ADR）：每个技术选型的背景、选项、理由
- 模块所有权：每个模块是谁负责的，边界在哪里
- 测试和安全期望：每个功能有哪些已知约束
- AI Agent 规则：告诉 AI 工具这个仓库有哪些约定不能违背
所有这些记忆都存放在 docs/ 目录下的 Markdown 文件中，可以正常提交到 Git，可以在 Pull Request 中被审查，可以被任何 AI Agent 重新读取。
Persist OS 不是向量记忆引擎。类似 supermemory、mem0 的工具用嵌入向量做相似度检索；Persist OS 写的是人类和 Agent 都能直接阅读的结构化文件——它们是互补关系，而非竞争关系。
安装与初始化
安装方式有两种。最快的尝试方式是用 npx：
npx persist-os@latest init
如果打算长期使用，建议全局安装：
npm install -g persist-os persist --help
环境要求：Node.js >= 20。persist-os 包已发布在 npm 上，目前最新版本为 0.6.1。
初始化一个项目
在你的项目根目录中运行：
cd /path/to/your-project persist init
这会自动创建：
docs/目录：存放架构文档、ADR、功能规划等.persist/config.json：配置文件，记录当前仓库的决策树状态- 针对你使用的 AI 工具的集成文件（
CLAUDE.md、.cursor/rules/、AGENTS.md等）
初始化的过程是交互式的——每个文件创建时都会提示你做了什么、文件放在哪里、下一步可以做什么。如果你用 --ai-tools 指定工具，则只生成特定工具的规则：
persist init --ai-tools claude,cursor
默认会为 Claude Code、Cursor、Codex 都生成规则，AGENTS.md 则始终生成。
使用 Preset 初始化
如果你想针对特定技术栈生成更丰富的预设决策记录，可以用 --preset 参数：
persist init --preset python-fastapi persist init --preset nextjs persist init --preset kotlin-android persist init --preset laravel-react
目前内置了 9 个 Preset（含 generic），覆盖了 Python/FastAPI、Next.js、Kotlin/Android、iOS/Swift、Laravel、Flutter 等主流技术栈。每个 Preset 会提出预设的架构决策（以 Proposed ADR 形式），但不会自动接受任何选择——你需要手动用 persist adr accept 决定是否采纳。
查看可用 Preset：
persist preset list
日常使用命令
Persist OS 提供了一套完整的 CLI 命令来管理工程记忆：
记录功能意图
当你要开始一个新功能时，先创建一个功能记忆：
persist feature create checkout
这会创建一个 PRD（产品需求文档）骨架，包含功能描述、验收标准、测试要求和审查清单。这些内容会存放在 docs/features/checkout/ 目录下。
管理架构决策（ADR）
ADR（Architecture Decision Record）是 Persist OS 的核心能力。每个 ADR 包含：背景、选项、决策理由和预期后果。
创建新 ADR：
persist adr create payment-provider
此时 ADR 状态为 Proposed（草稿）。你需要审查内容后接受它：
persist adr accept payment-provider
如果后续决策发生了变化，不要直接修改旧的 ADR——用 supersede 替换：
persist adr supersede payment-provider stripe-vs-adyen
这会标记旧 ADR 为”已被替代”，新 ADR 会链接回旧版本，形成完整的决策链条。persist doctor 会自动检查是否还有内容引用了已过期的 ADR。
记录模块
定义模块的边界和所有权：
persist module create auth
每条模块记录会包含：模块范围、负责人、依赖关系、测试策略和安全约束。
导入 MCP 服务端上下文
如果你使用了 MCP（Model Context Protocol）服务端（如 Figma、数据库等），可以将其上下文离线导入：
persist mcp add figma
这会读取 MCP 服务端的能力描述，生成结构化的备用记忆，供 Agent 在离线时查阅。
生成可复用的 Agent 技能
Persist OS 还支持生成可移植的 Agent 技能文件：
persist skill create data-query
生成的技能文件位于 .agents/skills/ 目录下，可以被 Claude Code 的 Agent Skills 机制加载。
Doctor：最独特的验证机制
persist doctor 是 Persist OS 区别于其他文档工具的关键功能。它是一个确定性的、本地运行的检查器，会验证工程记忆的完整性和一致性：
persist doctor
它会检查以下方面：
| 检查类别 | 检测内容 | 严重级别 |
|---|---|---|
| 结构完整性 | 缺少配置、必需文档、功能/模块/ADR 节 | error |
| 完成证据 | 标记完成但无测试/结果证据的功能 | error |
| ADR 质量 | 已接受的 ADR 无实质性后果描述 | error / warn |
| 安全性 | 安全敏感功能缺少安全影响文档 | error / warn |
| 漂移检测 | 引用了已不存在或未接受的 ADR | error / warn |
| 过期引用 | 仍引用已被替代的旧决策 | warning |
| 陈旧性 | 记忆引用的 src/ 代码已发生重大变化 | warning |
| 上下文预算 | Agent 规则文件超长（超过上下文预算） | warning |
| 内容完整 | 功能 PRD、模块文档留有空模板 | warning |
退出码含义：0=健康，1=有警告，2=有错误。
你可以将它加入 pre-commit hook：
git config core.hooksPath .persist/hooks
或者在 CI 中运行：
pnpm test:run && pnpm typecheck && persist doctor
因为它是确定性的（相同的仓库状态总是产生相同的输出），它可以可靠地作为 CI gate。
Guard：代码变更与测试的关联检查
persist guard 是一个辅助命令，它会检查即将提交的代码变更是否关联了测试：
persist guard --source src/
如果 src/ 目录中的代码有变更但没有对应的测试文件变更，它会返回非零退出码。这可以防止”改代码不补测试”的情况。
AI Agent 如何加载工程记忆
Persist OS 为每个 AI 工具生成了对应的记忆加载机制：
- Claude Code：
CLAUDE.md自动导入AGENTS.md，SessionStart hook 在每个会话中注入最新的 ADR 和模块地图 - Cursor：
.cursor/rules/persist-memory.mdc作为 always-apply 规则，每次请求都加载记忆规则 - Codex：
AGENTS.md自动发现并加载
生成的 AGENTS.md 包含一个简短的 Rules 块：先读取记忆、复用约定、记录教训、不违背已接受的 ADR、在声称”完成”前运行 persist doctor。
最重要的一点是：Agent 被要求在运行过程中自己维护 CONVENTIONS.md 和 LESSONS.md。这意味着你不用手动写——Agent 在编码过程中会自动记录学到的东西，你只需要在 PR 中审查它的修改即可。
Local-First 与隐私保障
Persist OS 有明确的无网络承诺：
- 运行时不做任何网络调用
- 不收集遥测数据
- 不连接 MCP 服务端
- 不调用 AI API
- 不生成生产代码
- 默认不覆盖已有文件
所有的记忆、决策记录、检查逻辑全部在本地运行，适用于离线环境和有严格合规要求的项目。
适用场景
Persist OS 最适合以下情况：
- 同时使用多个 AI 编码 Agent 的项目：Claude Code 写后端、Cursor 写前端、Codex 做测试——需要一个统一的记忆层确保所有 Agent 一致性
- 对架构决策有审计要求的团队：每个 ADR 有完整的生命周期（Proposed → Accepted → Superseded），可追溯
- Vibe Coding 后的重构项目：快速原型完成后，用
persist adopt检查现有代码，生成记忆层，让后续的 Agent 维护有据可依 - 需要 CI 门禁的项目：
persist doctor的确定性退出码可以嵌入任何 CI 流程
不太适合的场景：单 Agent 且无文档需求的个人项目、已有成熟知识管理系统的团队。
结语
Persist OS 解决的是一个微妙但越来越重要的痛点：AI 代码生成的速度远超人类记录决策的速度，导致架构知识大量流失。它用一套轻量级的 CLI 命令，把”为什么”沉淀为仓库中的结构化文件——既不会像向量数据库那样黑盒，也不会像 Wiki 那样与代码脱节。
如果你正在使用 AI 编码 Agent 开发项目，且希望每次编码迭代都有据可查，不妨试试。用 npx persist-os@latest init 在你的项目中初始化，几分钟就能给仓库装上”工程记忆”。
相关链接