让 AI 记住你的研发习惯，以及每个项目自己的规则。
Dev Memory 是用于 AI 辅助开发的 Skill 和本地 Python 程序。它帮助 AI 召回相关研发习惯与项目规则，并根据真实要求或证据保存长期知识。AI 判断含义，程序负责校验并将记录存入 SQLite。
已有 Node.js 22+（含 npm/npx）和 Git 即可。Windows x64 与 macOS（Apple Silicon / Intel）会自动准备专用 Python 3.12，无需安装或升级系统 Python。macOS 本地向量要求系统版本 13+。
Linux 或直接使用 Python 安装入口时，仍需 Python 3.10+（含 sqlite3）。其他要求与故障排查见安装说明。
在开发项目的根目录执行：
npx -y --prefer-online chrisstarr7/dev-memory codex使用其他 AI 宿主时，将 codex 换成对应参数：
| 宿主 | 参数 | 项目引导文件 |
|---|---|---|
| Codex | codex |
AGENTS.md，或已有的非空 AGENTS.override.md |
| Claude Code | claude |
CLAUDE.local.md |
| Cursor | cursor |
.cursor/rules/dev-memory.mdc |
| Gemini CLI | gemini |
GEMINI.md |
| GitHub Copilot | copilot |
.github/copilot-instructions.md |
| OpenCode | opencode |
AGENTS.md |
| DeepSeek Harness | deepseek |
AGENTS.md |
基础记忆运行时只依赖 Python 标准库。向量依赖与模型在独立环境中准备；失败时保留基础功能，并说明失败原因。添加 --without-vectors 可跳过向量依赖与模型下载；首次准备专用 Python 仍需联网。参数应对应实际运行 AI 的宿主：通过 OpenCode 使用 DeepSeek 模型时，选择 opencode。
Codex 安装会同时启用用户级全局习惯和当前项目记忆。在未初始化的其他项目中，用户级引导只召回全局习惯。需要项目记忆时，在该项目再次运行安装命令。其他宿主目前仅使用项目引导。安装或升级后，在项目中开启新的 AI 会话；之后正常提出需求即可，不必每轮调用 Skill 或说“记住”。新建记忆库从空库开始，已有记录会保留。
安装时自动为 dev-memory 准备独立 CPython 和向量依赖，放在 ~/.dev-memory/python-runtime 与 ~/.dev-memory/vector-runtime（DEV_MEMORY_HOME 可更改根目录）。它们只供 dev-memory 使用，可由同一用户的多个项目共用；不会安装进系统 Python、全局 site-packages，也不修改 PATH、注册表或 Shell 配置。依赖和下载缓存都在该目录内。依赖默认从 PyPI 下载，不受其他 Python 项目的 pip 镜像配置影响；企业环境可用 DEV_MEMORY_PIP_INDEX_URL 指定获准的镜像。升级或卸载 Skill 均保留该运行环境及已有记忆。
其他安装方式、权限和宿主细节见安装与卸载说明。
Dev Memory 只有两层持久记忆：
| 范围 | 适合保存的信息 | 示例 |
|---|---|---|
| 全局 | 脱离具体项目后仍可复用的研发习惯 | 新增实现前先检查是否已有合适代码 |
| 当前项目 | 长期有效的规则、契约、决策和有依据的事实 | API 要求、安全边界、代码规范 |
一次性要求、任务进度和未确认猜测留在当前对话中。Dev Memory 不保存对话正文或任务检查点。开启新会话后，可能需要重新检查代码来确认进度。两个范围都不能保存凭证。
项目知识也可以包括验收规则、兼容要求、部署约束、迁移和经过验证的故障经验。代码现状只有在长期有效、不易重新发现且可能影响后续工作时才值得记录；它只说明观察到了什么，不能代替用户期望。写入前，AI 应保持原有适用范围，并检查是否已有等价记录。即使审查后无需改代码，新提出的长期规则仍可能值得保存。
保存时应保留原意中的范围、条件、例外和语气强度；示例、未采纳方案和临时要求不能扩写为长期规则。纠正已有记忆时，未提及的字段保持原值，明确清空才删除，并读回当前正文核对；历史版本仅用于审计。程序校验来源和修订边界，语义是否准确仍由 AI 对照实际来源判断，不能用“保存成功”代替。
全局习惯有两种证据路径：明确要求长期适用于所有项目时，可以立即保存为有效规则；没有明确跨项目声明的可复用要求、选择或纠错，首次先保存为未生效候选，取得两个独立任务的证据后才晋升为软偏好。AI 的总结和重复召回不算新证据。
新项目默认使用 full-project 模式，允许自动保存合格的项目知识。可选的 developer-first 模式会阻止新增项目记录。升级保留原有模式，以及暂停、禁用和只读设置；旧项目切换到 full-project 需要明确操作。
在已启用 Dev Memory 的会话中，可以直接说：
- “把项目记忆里的默认表名改成‘核验登记’，其他条件不变。”
- “旧记忆里‘所有改动都先写方案’不对，我指的是复杂改动。”
AI 会定位原记录、核对范围和当前内容，再修订并读回确认；用户无需提供 ID、SQL 或 JSON。目标有实质歧义时会先澄清，查找不到不会直接新建一条冒充纠正成功。“这次临时不跑测试”只适用于本轮；暂停、禁用或只读导致无法保存时，会明确说明。候选记忆不会因普通编辑自动生效，历史修订仍可在看板查看。
已初始化项目的 Mermaid 流程图如下。召回用于指导任务，新信息在工作过程中持续评估：
flowchart TD
S([任务开始或切换主题]) --> R[召回全局与当前项目记忆]
R --> A[把适用的有效记忆转成任务决策与检查项]
A --> W[执行任务；及时识别新信息]
W --> E[评估未来用途、证据、长期性、范围、控制和现有记录]
E --> G{有合格的内容需要保存？}
G -->|否| F([交付结果])
G -->|是| P[新增或修订所属记忆库；核对回执]
P --> F
记录判断适用于要求、选择、规范、决策、有依据的事实、方法和纠错，不限于发现错误。新信息出现时及每轮结束前都应评估，纯审查任务也一样。重要纠错在受影响修改前保存；其他合格增量在交付前保存。
全局与项目分别提交，失败或部分成功都应如实说明；没有合格增量就不做空写入。
复杂的记忆评估可与独立开发工作并行。宿主须能隔离上下文、限制记忆库访问、返回结果并停止评审；不满足时由主智能体直接评估。主智能体收到建议后先核对原始依据，再保存并确认回执；评审未返回时，收尾最多等待一次、总计不超过 5 秒，宿主无法限时等待则立即停止评审并接管。超时后先作废提案，再停止评审，由主智能体自行判断；迟到结果不得追加或修改本轮记忆。主任务已完成但记忆仍在收尾时，AI 会先给出进度提示。
召回根据当前任务检索少量相关记忆，不会把整个记忆库交给 AI，也不会搜索其他项目。任务开始、恢复、压缩、上下文丢失，或项目、模块、主题发生实质变化时，AI 执行一次聚焦的 context 查询；同一段未中断上下文内，结果仍有效时直接复用，不必每轮重复查询。
- 使用任务关键词和可选的开发意图寻找相关记录。关键词检索独立可用；本地向量索引就绪时，同时利用语义匹配。
- 在数量与字符预算内返回选中的记忆正文。默认联合预算为 5 条／4000 字符，先为全局预留最多 3 条／2400 字符，未使用额度交给项目。当有界词项检索确认项目相关记录超出预留槽位时，全局未匹配的软偏好只保留未加载导航，释放正文额度；全局强约束以及关键词、任务意图或向量命中的记忆仍正常参与选择。例如，全局实际返回 1 条且字符预算允许时，项目可返回最多 4 条。全局单独召回、空查询、空项目或项目召回关闭时保留原有分配；各库上限和总预算始终生效。
- AI 核对适用范围、条件、例外及来源时效，再转成当前任务的决策与检查项。当前要求始终优先；旧代码观察和测试结果不能直接当作当前事实。
新会话首次召回，以及恢复、压缩或上下文丢失后，使用 context --force 重新读取当前正文；即使任务没变、恢复的历史里仍能看到旧正文，也要执行这一次召回。工作区文件意外偏离此前会话状态时，也先刷新相关记忆再修改。cached 只表示相同查询曾返回过，不包含记忆正文。Codex 提供真实会话 ID 时，缓存会按该 ID 隔离，避免 AI 重复填写会话标签导致新会话漏读。候选、暂停、禁用和只读边界保持不变。
预算不足时，结果会明确标出未返回的相关记录，AI 只补取当前必需的内容。返回了一条记忆，不代表 AI 一定采用，也不证明其中引用的代码仍然保持原行为。
可选 context --disclosure auto 会对短正文省略空字段，对超过 1000 个序列化字符的正文先给导航预览；--disclosure index 只返回索引预览。预览不作为有效规则使用，AI 需要时按范围批量执行 show --scope project|global --ids ID ... --current 读取完整条件、例外和禁止项。默认仍直接返回正文，不强制增加调用，也不调用另一个模型生成摘要。长正文的 1000 字符阈值与正文预算都是字符口径，不等于 Token。
| 记录状态 | 普通召回 | 自动整理队列 |
|---|---|---|
active，非假设 |
按相关性和预算选取 | 发生变更的当前版本入队 |
candidate，非假设 |
不返回为有效指令 | 可以整理，但保持未生效 |
candidate + hypothesis |
不参与 | 不进入，仍属未确认内容 |
conflicted |
可能作为冲突上下文返回，采用前须解决冲突 | 不进入常规队列，需明确的冲突处理 |
stale、archived、superseded |
不参与 | 不进入 |
历史 active + hypothesis |
不参与 | 作为异常纳入；有效时应有来源地修订，只有符合归档条件时才归档 |
月度召回次数表示完整记忆正文曾返回给 AI，不表示已实际采用。缓存命中、只读查询和暂停采集时不增加计数。召回统计与整理队列独立：重复召回不会重新触发整理；新记忆即使从未召回，也可能需要质量审查。
安装成功表示程序和引导已配置；实际生效需要宿主加载引导，AI 读取记忆正文并落实到产物。可在源码仓库中按需执行 python3 evals/check_host_delivery.py --model EXACT_MODEL --reasoning high --output "仓库外的绝对路径/result.json"，使用已有 Codex 登录进行隔离验收。它真实执行新会话、重启进程后恢复、上下文压缩三个阶段，分别更新测试规则，再检查新版本正文送达及实际文件结果；不会作为日常开发步骤运行。
| 接入范围 | 已有证据 |
|---|---|
| 本机 Codex CLI／app-server | 新会话、恢复、压缩后的正文送达与产物行为均已实测 |
| OpenCode 2.2.1 | 普通提示采集、新会话召回及实际产物已实测；采用主智能体回退路径，未认证原生取消能力 |
| 可选 Codex hooks | 配置与程序测试覆盖，真实信任执行单独验收 |
| 其他宿主 | 引导适配与程序测试覆盖，本轮未进行真实模型会话验收 |
特定宿主／模型通过一次验收，不代表所有后续会话都能强制执行规则。模型和版本、检查方法及限制见宿主验收记录。
--assessment 默认检查普通提示下的采集和协作路由；强制委派的测试探针需显式指定 --behavior-probe，不能当作自动生效的证据。召回分配、OpenCode 普通会话及本地向量启动测量见本轮审查记录。向量阶段诊断按需执行 python evals/vector_startup.py --runtime-root PATH，只读取已有运行环境，不作为日常召回步骤。
可选 hooks 在收到带稳定会话／轮次 ID 的明确纠错、长期要求或已验证陈述时，会提醒主 AI 复核采集资格；它不会直接保存原始消息或自动认定结论已被工具验证。宿主支持、实际事件交付和正常信任审查缺一不可；不支持或未启用时继续使用 Skill。正式用户配置不会因安装自动信任 hooks，详见 hooks 说明。
源码仓库提供记忆效果基线：
python3 evals/check_memory_quality.py --model EXACT_MODEL --reasoning high --output /仓库外绝对路径/result.json命令会调用真实模型并消耗额度，默认对三个隔离任务各重复两次，比较有无记忆；报告正确正文召回率、规则落实、可观察的错误采用、Token 增量和完整任务耗时。--runtime-ref COMMIT 用于复现旧版本，--disclosure auto 验证分层读取，--cases long 补测长正文及末尾例外。失败、超时和缺失用量不会被排除，小样本结果不作为通用提速承诺。方法与本轮证据见记忆效果基线。
自动整理针对发生变化的知识，检查长期价值、来源依据、时效和重复情况。处理结果可以是保留、精简、调整标签、合并真正等价的记录或修订内容。只有用户明确要求、可靠证据证实记忆错误，或明确有效期已过且存在同范围且最新的有效替代记忆时才归档；过期归档会在原记录中注明替代记忆。不会仅因记忆较旧、未被召回、标记为假设或内容相似而归档。
全局库和各项目库分别维护待审版本队列，满足以下任一条件时提示到期：
| 触发条件 | 准确含义 |
|---|---|
| 积压达到 5 条 | 5 个不同的合格记录 ID；同一条修改 5 次仍只算 1 条 |
| 某条待审正文达到 1200 字符 | 长记录无需等待凑足 5 条 |
| 某项待审修改满 7 天 | 默认时间阈值，在下一次获准的交互中判断 |
达到阈值表示需要审阅，不表示后台已经改写记忆。 普通召回和保存只返回到期提示，不加载历史整理正文。AI 在合适的任务边界获取一组相关记录，判断后按修订版本提交，并检查回执；任务紧急或证据不足时保留待审。整理周期开始后，后续轮次可以继续处理不足 5 条的尾批，无需重新等待凑数。
flowchart TD
S([合格记录发生变化]) --> Q[在所属库排队当前版本]
Q --> D{达到审阅条件？}
D -->|否| L([留待后续交互])
D -->|是| M[返回到期元数据]
M --> B{处于合适的任务边界？}
B -->|否| L
B -->|是| R[读取一组相关记录]
R --> C{来源和含义已充分核对？}
C -->|否| L
C -->|是| A[保留、精简、改标签、合并或纠正]
A --> F[按版本提交并检查回执]
F --> E([结束；剩余工作留待以后])
每轮、每个库最多处理一组相关记录：8 条／12000 字符，包含随附的来源证据。每条最多附带 3 条近期证据摘要，并标明是否省略更早证据；缺少上下文时应定向核对来源，不能仅凭脱离原方案的简短确认推导出更多详细约束。
整理必须保留有效条件、例外、否定要求和作用域，区分业务要求与代码事实；核对观察记录引用的当前代码，优先保留简明约束和权威文档入口，避免复制整份实施方案。历史 active 假设须解决后才能标记已审。未读完、超长或尚未确认的记录留在队列中，不能为了清空积压删减约束。
整理协议升级时，可能将已有合格记录重新排队一次，但不会因此改变正文。暂停、禁用、排除和只读控制继续有效。系统没有常驻整理进程或持续对话监听，也不强制额外调用模型；自动执行依赖宿主加载规则并由 AI 落实。普通召回不读取整理证据。整理后仍保留原始证据与修订历史，因此有效记录变少不等于磁盘占用同比减少。操作和保护机制见操作协议。
| 位置 | 内容 |
|---|---|
~/.dev-memory/global/ |
全局 SQLite 库、配置、可选视图和备份 |
<项目根目录>/.dev-memory/ |
当前项目的 SQLite 库与激活绑定 |
一次项目召回只打开全局库和当前项目库，不搜索其他项目。不同克隆和工作树默认各有自己的项目库。SQLite 是权威数据，可选的 Markdown 阅读视图可以重建。会话和轮次 ID 用于重试去重、隐私跳过与召回缓存，属于运行元数据，不是第三层记忆。
核心程序没有遥测，也不会自动上传记忆。召回内容若提交给托管 AI，仍受该宿主的数据政策约束。全局记录及证据必须去除项目名、业务细节、代码、路径、客户数据、原始对话、日志和密钥。备份也包含私有数据。
旧数据库可能仍有任务/检查点记录。当前版本不再创建、召回、整理或导出它们，但保留旧记录供显式审查和删除：先用 list --scope project --status all 查看，再走 forget preview / forget apply 流程。reports/ 中的历史文件可能描述旧版行为。
每个记忆库继续使用现有 SQLite 文件：中文原文是权威数据，向量索引是可选的检索辅助。安装或更新时会尝试准备本地模型；模型不可用时，原文和关键词检索仍可使用。普通开发不会下载模型。向量检索只帮助找候选，不会改变记忆的有效状态。
未完成的向量计算不会影响已保存的原文。看板可查看索引状态；浏览看板不会启动模型推理。平台要求、恢复方法和诊断命令见向量运行说明。
已有 Node.js 22+ 和 Git 后，在项目目录运行（Linux 另需 Python 3.10+）：
npx -y --prefer-online chrisstarr7/dev-memory dashboard命令会在本机启动看板并尝试打开浏览器。若浏览器没有打开，复制终端打印的地址到浏览器；保持终端运行，按 Ctrl+C 停止服务。看板只监听本机地址，不会上传记忆；地址含临时访问凭据，不要分享。
看板支持查看原文、依据、修订历史和向量数据，搜索及筛选记录，预览召回，管理项目和备份。月度召回次数表示完整记忆曾返回给 AI，不代表 AI 一定采用；启用统计前的历史无法补算。
在记忆列表下展开“模拟日常召回”，输入任务关键词，可选任务类型，再点击“执行预览”。默认使用日常首次召回的 5 条／4000 字符联合额度，显示各范围实际用量、记忆修订、关键词／语义／任务类型／兜底匹配，以及因条数、字符或候选额度未加载的结果。向量不可用时会显示降级原因，原文检索仍可使用。选择“扩大检索”可提高请求额度，但结果不代表日常默认调用；两种模式都受各库配置约束。
预览不保存查询、不增加召回次数，也不证明 AI 已执行规则。打开页面不启动检索；主动执行预览时可能使用本地向量模型。CLI 可在 context 或 recall 后添加 --explain 获取同样的选择依据，配合 --readonly --force 可检查首次召回而不写入统计或缓存。
若 Windows 页面提示项目列表权限错误，看板仍可显示全局记忆。按Windows 看板权限修复修复后重启看板。
可以直接告诉 AI：
- “暂停全局记忆写入，但继续读取已有记录。”
- “这一轮不要保存记忆。”
- “查看相关记忆。”
- “删除前先预览影响范围。”
当前要求始终优先于记忆。若记忆没有保存或无法读取，让 AI 对已安装程序运行一次 doctor，并核对实际回执；口头确认不等于写入成功。
在项目目录运行更新命令，并在完成后开启新会话：
npx -y --prefer-online chrisstarr7/dev-memory update codex更新会刷新当前已绑定项目的引导，并保留现有记忆库、控制设置和无关引导内容；在未绑定目录运行更新不会初始化该目录。需要在其他项目启用项目记忆时，在该项目中单独执行安装命令。
请通过 GitHub Issues 提交脱敏问题，不要附上数据库、凭证或原始对话。
使用安装绑定中的 Python 和 Skill 路径运行 CLI：
npx -y --prefer-online chrisstarr7/dev-memory uninstall codex将 codex 替换为实际宿主；自定义 Skill 目录可添加 --target <Skill目录>。卸载会移除受管理的程序，以及 Codex 用户级引导和本 Skill 的 hooks；项目引导与记忆库会保留。如需移除项目引导，只删除其中 dev-memory:managed:start/end 管理块。删除记忆请使用 CLI 的 forget 预览与确认流程。详见安装与卸载说明。
若对应宿主的 Skill 未安装，卸载命令会提示“无需卸载”并正常结束，不创建安装目录，也不改动记忆数据。若目录存在但不是 dev-memory 管理的安装，命令会拒绝删除。